NIM Users Guide - ccasoftware.com

CCA Software Pty Ltd

NIM Users Guide

Version

5.00a

I N T R O D U C T I O N

NIM is a product of CCA Software Pty Ltd., and:

NIM is distributed by CCA Software Pty Ltd. of Suite 3, 10 – 12 Blackburn Rd, Blackburn Vic 3130, Australia.

Copyright Notice

Copyright 1994 - 2011 CCA Software Pty Ltd.

All rights Reserved.

Trademark Acknowledgments

ADABAS and NATURAL are trademarks of SOFTWARE AG of Germany and North America MVS/ESA, OS390, z/OS, VTAM and JES are products of IBM Corp. USA. MSP, MSP/AE and MSP/EX are products of FUJITSU Japan. SPACEMAN & APAS/INSIGHT

are products of CA Corporation of USA.

Requirements for Confidentiality

This document contains trade secrets and proprietary information of CCA Software Pty Ltd. Reproduction of this document without the written approval of CCA Software Pty Ltd. is

prohibited. Use of this document is limited to licensed users of NIM or those given specific written permission by CCA Software Pty Ltd.

THE SOFTWARE, WHICH IS DESCRIBED IN THIS DOCUMENT, IS SUBJECT TO LIMITATIONS ON USE, RELEASE, DISCLOSURE AND DUPLICATION AND TO REQUIREMENTS FOR CONFIDENTIALITY, PROTECTION AND SECURITY WHICH ARE SET OUT IN THE SOFTWARE LICENCE AND MAINTENANCE

AGREEMENTS.

CCA Software Pty Ltd. PO Box 423,

Blackburn , Victoria 3130 Australia

ABN: 35 060 664 057

[email protected]

http://www.ccasoftware.com.au/

Tel: +61-3-9890 9500 or Fax: +61-3-9890 1344

This edition applies to NIM V 5.00b with the NIM

VTAM & ATP Servers.

Table of Contents

INTRODUCTION......................................1

Internal Efficiency .................................1 Flexible Configuration ..........................1 Powerful DBA and Operator Interfaces 2 Complete NATURAL Environment Support ..................................................2 Complete TP Monitor Facilities ............3

OPERATIONS & GUIDELINES.............5

NIM ARCHITECTURE.................................5 MEMORY USAGE AND 31-BIT ADDRESSING

CONSIDERATIONS......................................6 RUNNING MULTIPLE NIM VTAM- SERVER

ADDRESS SPACES......................................6 SECURITY CONSIDERATIONS.....................7 AUTOMATED LOGON TO OTHER VTAM

APPLICATIONS...........................................9 LOG RECORD FUNCTIONS AND FORMATS..9 THE NIM VTAM- SERVER SESSION

SUMMARY SCREEN..................................10

PARAMETERS AND USER EXITS .....11

NIM PARAMETERS..................................11 Parameter Specification Overview......11 Global Parameters ..............................12 Logical Driver Parameters..................21 Default Logical Driver Parameter ......36 File Parameters ...................................37 NIM Asynchronous Session Parameters.............................................................38

USING NIM’ S FLEXPARM FACILITY .....38 NIM USER EXITS.....................................39

Address Space Control Program Exits 39 Server Exits..........................................41 NATURAL Subtask Exits .....................42

NIM USER SUBTASK ...............................45 MODIFYING NIM OPERATIONAL DEFAULTS

................................................................45

CONFIGURATION.................................46

CONFIGURING THE NIM-NATURAL-ADABAS-DB2 INTERFACE.......................46 ADABAS LINKAGE – ADALNK

SPECIFICATION........................................47 SUPPORTING THE BASIC NATURAL

ENVIRONMENT ........................................48 Using a Common NATURAL Nucleus .48 Using NATURAL Dynamic Parameters.............................................................48 Using the NATURAL “PARM=” Parameter ............................................49 NATURAL Buffer Pools.......................49

SUPPORTING NATURAL ADD-ONS........ 49 NATURAL DB2 Support...................... 50 NATURAL VSAM Support................... 50 Other Products .................................... 51

ONLINE PRINT AND WORK FILES ............ 51 Dynamic Print File Allocation Using NIMDRPWM....................................... 52 Dynamic Work File Allocation Using NIMDRPWM....................................... 53 Dynamic Print/Work Free Using NIMDRPWM....................................... 53

3GL AND ASSEMBLER SUBROUTINE

SUPPORT................................................. 54 Calling Subroutines............................. 54 Subroutine Parameter Lists and AMODE............................................................. 55 Subroutines Which Load Below 16MB 55 Non-Reentrant Subroutines ................. 55 Subroutines Imported from Other Environments.......................................56 Subroutines Which Call ADABAS ....... 56 Subroutines Written in the PL1 Language............................................. 56 Subroutines Written in the COBOL 2 Language............................................. 56 Subroutines Which Access NIM Control Blocks.................................................. 57 Special Considerations for FUJITSU Operating Systems............................... 57

BATCH JOB SUBMISSION......................... 58

CONSOLE OPERATOR INTERFACE 61

OPERATOR COMMANDS .......................... 61 Termination Commands ...................... 62 User Cancellation Commands............. 63 Message Related Commands............... 64 File Related Commands ...................... 65 Status Display Commands................... 67 Miscellaneous Commands................... 70

NIM'S NATURAL BASED COMPONENTS & TOOLS ................... 73

NIM ON-LINE SERVICES/NIMBLE......... 73 Security Issues..................................... 74 Users (Option ‘U’ in Menu) ................ 74 Logical Drivers (Option ‘L’ in Menu).74 Files (Option ‘F’ in Menu).................. 74 Address Space Summary (Option ‘S’ in Menu) .................................................. 74 Messages (Option ‘M’ in Menu) ......... 75 Utilities (Option ‘T’ in Menu) ............. 75

NIM ON-LINE SERVICES/NIMOS ........... 75 Security Issues..................................... 75 Use of the NATURAL System (FUSER) File ...................................................... 76 User Profiles (Option ‘P’ in OSmenu) 76


Editing and Browsing Datasets (Option ‘E’ in OSmenu) ....................................76 Listing the Catalog (Option ‘L’ in OSmenu) ..............................................77 Data Manipulation (Option ‘D’ in OSmenu) ..............................................77 NATURAL Print/Work File Allocation (Option ‘N’ in OSmenu).......................77 Utilities (Option ‘U’ in OSmenu).........77

NIM ON-LINE SERVICES/UTILITY

PROGRAMS..............................................77 NATGET and NATSET Subroutines ....77

NATSET OPERATIONS............................78 NIMTPHCP Subroutine.......................80

INSTALLATION.....................................81

RELEASE CONTENTS .............................82 UPLOADING THE RELEASE DATASETS.....83 DEFINING A NIM VTAM- SERVER

APPLICATION...........................................85 CONFIGURING THE NATURAL

ENVIRONMENT ........................................86 CREATING THE NIM NATURAL

ENVIRONMENT ........................................88 PROVIDING THE ADABAS INTERFACE....89 INTRODUCTION TO LOGICAL DRIVERS.....89

The above logon string requests a logon to VTAM application NIMTEST with logon data of "DEV". The NIM logon data can contain a logical driver name and "FLEXPARMs" (refer to the section "NIM Asynchronous Session Parameters.............................................................90

SETTING UP NIM PARAMETERS...............91 Changing the Sample Test Parameters93

CREATING JCL TO EXECUTE NIM...........94 JCL Component – the EXEC card .......94 JCL Components – the STEPLIB.........94 JCL Components – the DD Definitions95 Running the Job ...................................96

INSTALLING THE NIM NATURAL OBJECTS

................................................................97 INPL Dataset Details...........................98

VERIFYING THE INSTALLATION ...............99

PROBLEM DETERMINATION GUIDE.................................................................101

MESSAGES............................................103

MESSAGES.............................................105

RETURN CODES FROM THE DYNAMIC PRINT & WORK FILE ROUTINES.............................................143

LOG RECORD LAYOUT ....................145

GENERAL DESCRIPTION........................145 HEADER LAYOUT ..................................145 SESSION END LAYOUT ..........................146 SNAPSHOT AREA LAYOUT.....................148 TRAILER LAYOUT..................................149

ZAPPING OPERATIONAL DEFAULTS.................................................................151

NIM VERSION 4 RELEASE NOTES.153

ADABAS and NATURAL ...................153 ABOVE THE LINE ADDRESSING.............154 LINK PACK ELIGIBILITY ........................154 PHYSICAL DRIVER SPLITTING ...............155 NATURAL DB2 SUPPORT...................155 PARAMETER CHANGES..........................156 CONFIGURABLE MESSAGES...................157 CONFIGURABLE TABLES SIZES..............157 NIMBLE ENHANCED............................157 “TSOPAK” RENAMED “OS

FUNCTIONALITY ” AND GREATLY

ENHANCED............................................158 STANDARD BATCH JOB SUBMISSION

SUPPORT...............................................158 ONLINE PRINT AND WORK FILE SUPPORT

..............................................................158 SUPPORT FOR 24-BIT ADDRESSING MODE

EXTERNAL SUBROUTINES.....................158 USER EXITS REORGANIZED...................159 NATGET/ NATSET ENHANCED ..........159 OPERATOR INTERFACE..........................160 LOGGING...............................................160 INCOMPATIBILITIES WITH NIM V5.00 AND

V4.40....................................................161 Data Structures .................................161 Log Records ......................................161 WTO Messages..................................161 Miscellaneous Service Routines ........161 The only job submission interface supported is the "NATRJE" interface. User Exits ..........................................162

INDEX ....................................................163

N I M U S E R S G U I D E P A G E 1

INTRODUCTION

NIM is an efficient, flexible and highly functional TP monitor designed specifically to support the NATURAL environment running under MVS style operating systems. Because it was designed specifically to efficiently support NATURAL, it has many significant advantages over other TP monitors:

Internal Efficiency

The entire architecture of NIM is tuned for supporting the NATURAL environment. The generalizations and compromises made by other TP systems that support applications of widely varying characteristics are not required in NIM.

Extensive use of two powerful operating system facilities characterizes the simple and efficient NIM design:

Independent sub-tasking.

NIM runs each TP user in a independent operating system sub-task, dramatically reducing the overhead required to schedule and dispatch users, and isolating each user into their own operating environment with minimal overhead.

This approach provides particular benefits to NATURAL-DB2 users, as the CAF interface employed by NIM allows NATURAL users extremely efficient and unconstrained access to all the facilities of DB2.

MVS virtual storage management.

NIM relies on the operating system demand paging mechanisms rather than older rolling techniques whose performance quickly deteriorates under heavy load.

In contrast to most TP systems that impose a heavy load on the CPU and I/O systems in shuffling user memory often needlessly between main memory, expanded memory and disk roll files. NIM allows the operating system to efficiently perform the jobs for which it has been designed and automatically and optimally adapt to varying load conditions.

Flexible Configuration

NIM supports the definition of different operating environments, including NATURAL nucleus options and parameters, operating system dispatching priorities and processing exits into an entity called a "logical driver". The DBA can define a logical driver for each required class of service. Logical drivers can be dynamically added and modified "on the fly" to allow instant re-configuration of the entire operating environment.

Chapter

1


P A G E 2 N I M U S E R S G U I D E

NIM V5.00 logical drivers can be configured to support any version of NATURAL from V3.1.x onwards. This allows sites to transition applications from NATURAL older versions to the latest version of NATURAL all within the NIM environment.

Powerful DBA and Operator Interfaces

NIM provides a highly functional interactive full-screen monitoring and control interface ("NIMBLE"), that allows the DBA to monitor the performance of the TP system and individual sessions. Most NIM parameters can be dynamically changed, and powerful diagnostic and user control mechanisms allow the DBA to be in full control of the TP system at all times.

The NIM console operator interface supports basic monitoring and control operations from the MVS, OS/390, z/OS console.

Complete NATURAL Environment Support

NIM provides complete support for the NATURAL "add-on" products such as NATURAL-DB2, NATURAL-VSAM, CON-NECT, NATURAL CONNECTION, SUPER NATURAL, TRS, CON-STRUCT, etc.

When used in a 31 bit-addressing environment, NIM utilizes virtual addressing above the 16MB line.

NIM fully supports on-line print and work file usage by allowing NATURAL applications to dynamically allocate sysout streams and datasets, subject to the user's RACF/ACF2 profile.

The NIM "OS functionality" package allows users under NIM to edit or browse operating system datasets, allocate, and delete datasets, and rename, delete, print and submit as jobs member of partitioned datasets. When used in conjunction with the NIM-SPOOL sysout browse and printing control program, NIM provides the complete development environment for building NATURAL applications as well as providing the most efficient execution environment.



Complete TP Monitor Facilities

NIM provides all the facilities expected in a modern TP monitor, all tuned to the requirements of the NATURAL environment:

Comprehensive logging;

Security interface;

User exit processing;

Comprehensive monitoring and dynamic control;

Comprehensive diagnostic support.

All functions have been reviewed to achieve major functionality and reliability gains over the previous releases. The results of user comments and suggestions and operational experiences in a variety of high volume environments have formed the basis for this release. NIM Version 4.30 supports the following environments:

NATURAL All versions from 3.1.3 and above

Database ADABAS V7.x, V8.1 and above; DB2 (with NATURAL-DB2); VSAM (with NATURAL-VSAM).

Operating system IBM - OS/390, z/OS.

Fujitsu - MSP/EX

This manual forms the documentation for the NIM system. It contains all the information required to:

� Perform basic installation and verification;

� Perform customization of operating parameters and understand the relationship between NIM and NATURAL components;

� Use the operator interface, the NIMBLE control and monitoring facility;

� Perform ongoing operational procedures and requirements in a production environment;

� Perform tuning, configuration and problem diagnosis.


Operations & Guidelines

NIM Architecture

NIM is a "TP monitor" dedicated to supporting a large number of NATURAL terminal users. It is designed to have a linear load curve - so that system resource consumption per user is constant, even when very large numbers of users are logged on.

NIM VTAM-server is the primary telecommunications server, which uses a direct interface to VTAM to provide terminal screen and related services such as logon processing, logon redirection, and error handling and session cleanup.

NIM runs many users per region using MVS sub-tasks. Each sub-task runs NATURAL and shares a small NIM interface to MVS. One control task performs session housekeeping, logging and console interfacing.

The benefits of this sub-tasking architecture are:

MVS can optimize its scheduling and memory paging;

Concurrent use of multi-CPU processors is possible;

Future new NATURAL services can easily be added in.

Extended memory addressing features are fully utilized in order to minimize virtual storage constraints. Extensive use is made of re-entrant code. Most NIM modules are globally shareable and ELPA eligible.

Released with NIM V5.00 is the ability to protect the core NIM control blocks from accidental corruption by users and end user programs. A z/OS facility called sub-spaces has been utilized to provide this level of protection. This has led to the requirement for NIM to start as an authorized program to allow the creation of the subspaces. In normal operational mode NIM is still running as a non-authorized program (i.e. after startup).

NIM is usually run as multiple address spaces. This is very useful for separating sensitive user applications from each other and to offer different service levels.

NIM VTAM-server address spaces are loosely coupled by VTAM, allowing users to see one "seamless" NIM environment.

Chapter

2

O P E R A T I O N S & G U I D E L I N E S


NIM uses a concept of a "Logical Driver", which is a named set of NATURAL and NIM parameters and definitions. Users specify a "logical driver" name in their LOGON to obtain the required NATURAL and server environment. The DBA will have mapped each possible logical driver onto one (or more) NIM address spaces. If needed, the DBA can change the underlying parameters without disturbing the user. This can even be done dynamically, while NIM is active.

NIM is designed to be flexible. It is easy for NIM jobs to be started, modified or stopped. The console operator can accomplish many dynamic control functions, while an extensive and easy to use interface is available to the DBA through special NATURAL programs.

NIM provides a central logging facility. Logging user exits to make it easy for historical data to be gathered for management and accounting purposes.

NIM can augment NATURAL and ADABAS security if needed. User exits are provided for this purpose. For example, the main security exit is able to establish an individual RACF/ACF2 profile for each logged on user, based on a user-id/password supplied at the first terminal interaction.

Memory Usage and 31-Bit Addressing Considerations

NIM runs in AMODE 31 nearly full time, and all-important modules are resident above the line (RMODE ANY). The only time NIM goes into AMODE 24 is for QSAM I/O.

If you have any large subroutines or memory hungry subroutines that are frequently used, it is highly recommended that they be rewritten to use memory above the 16MB line. Small subroutines aren't really a problem, but any new subroutines should be 31-bit aware, even if small and seldom used (see the section "3GL and Assembler Subroutine Support" on page 54).

User exits MUST be written in Assembler, MUST be able to handle parameters above the line, and MUST be re-entrant (see the section "NIM User Exits" on page 39).

We strongly recommend that an independent NATURAL nucleus should be created and placed in the link pack area (ELPA for OS390 & z/OS). The NATURAL nucleus can be quite large and can be shared by NIM, batch and TSO. This is a major saving of both real memory and page dataset space.

Most NIM modules are eligible for the ELPA. If you run several NIM address spaces, there would be some savings in placing them there.

Running Multiple NIM VTAM-server Address Spaces

Most installations need to run at least two NIM VTAM-server address spaces - one for programmers and one for users. Many will run more. Different classes of users may have different security requirements, different times of day for operation and so on - this can be a basis for partitioning the NIM VTAM-server workload into multiple jobs. If you are not running OS/390 or similar, you may be forced to run multiple address spaces due to virtual storage constraint (because of 24 bit addressing). Multiple address spaces can limit the impact of a (rare) NIM system ABEND.



As an example of multiple NIM VTAM-servers, let's suppose that we have 2 NIM jobs active - one for production, which recognizes logical drivers PROD1, and PROD2 and one for development, which recognizes logical driver DEV. Suppose also that the two NIM jobs use VTAM IDs of NAT and NATDEV. There are now three valid ways to logon:

(1) LOGON NAT,PROD1 (2) LOGON NAT,PROD2 (3) LOGON NATDEV,DEV

The above case represents two totally independent NIM jobs. By adding a logical driver of DEV to the 1st NIM, we can have a 4th possibility:

(4) LOGON NAT,DEV

This could make the NATDEV NIM job redundant as all logical drivers can be logged on to via NAT. However by adding 2 special parameters to the DEV logical driver in the NAT job, it can be made into a dummy driver which gives the illusion to the user that they have logged on to NAT, whereas in fact NAT simply passes the user on to NATDEV. The direct method of logging on to NATDEV then would not need to be made public - this gives the DBA the flexibility to change the underlying NIM job structure without changing the user's view of the system. The parameters needed are documented in the section "NIM Parameters" on page 11, (in this example they would be "DRIVER DEV UMAX=0" and "DRIVER DEV XFER=NATDEV").

When using multiple NIM address spaces, you will obviously need multiple NIM parameters. A useful trick is to keep your parameters in files and to concatenate 2 files to each PARM DD - one file should contain parameters applicable to all NIM jobs and the next one should contain those few parameters specific to each job. In conjunction with use of the DEFAULT parameter, you will be able to keep your parameters concise and manageable, even with many logical drivers in many NIM address spaces. When concatenating parameters, remember that if a parameter is doubly specified, the second specification will override the first (the sole exception is the DYNPARM parameter that concatenates to form a longer dynamic parameter string).

If there is a need for the DBA to be able to always logon to a NIM job (e.g. to run NIMBLE functions to investigate user problems), then you should consider setting up a special logical driver with a non-publicized name for DBA use only. Make sure that the GLOBAL UMAX parameter is sufficiently high to allow you to logon, even when the various DRIVER UMAX values are causing "normal" users to be transferred to another address space.

Security Considerations

Security for NATURAL applications is usually done by some combination of NATURAL security, ADABAS security and security features built into the NATURAL programs. NIM user exits are able to augment this security if needed.



Most sites use RACF or ACF2 to implement security policies would like to include NATURAL into this environment. This can be done by ensuring that a special NATURAL program is always given control first. The program then sets up a screen to obtain User-id and password and then call a subroutine to have RACF verify the combination.

Alternatively, NIM user exit 1 can be used - this has the advantage that bonafide's are checked before NATURAL is invoked but has the disadvantage that low level 3270 screen orders must be generated from assembler. A sample user exit 1 is provided on the installation tape. Note that NIM user exit 1 must run authorized in order to communicate with RACF or ACF2 via the SAF interface (RACROUTE).

Note: that NATURAL also has a user exit 1 (NATUEX1) which is almost identical in function to NIM's user exit 1. You may wish to use it instead of NIM's exit (an advantage here is Natural rather than assembler is coded).

In a NIM environment, a user has access to system resources via on-line print and work files as well as ADABAS resources. If the NATURAL environment allows users to write programs, or to run a general purpose NATURAL program that might allow the user to read a work file of any name, then the NIM on-line work file feature represents a potential security exposure. However, in many production environments this will be of no concern, because the higher-level security imposed on NATURAL programs will mean that it is impossible for a user to write or use a NATURAL program, which reads the "wrong" work file.

If RACF is being used, the lowest level of dataset protection is given by the User-id associated with the NIM job or started task, if the job cannot access a dataset then neither will any NATURAL user (unless they have a special task related RACF profile).

If user exit 1 is used, it is possible to arrange that different users have different RACF profiles. This is done by issuing a RACINIT macro in the user exit (NIM Uex1 or NATUEX1) and specifying that the ACEE RACF control block is to be in a task related sub pool and is not freed (except at end of task, automatically). Therefore, certain users can have dataset access privileges over and above the default given by the ACEE associated with the whole NIM address space.

RACF profiles are inherited by batch jobs that are submitted by NATURAL users calling Natural’s NATRJE facility. Therefore, the same considerations mentioned above apply. In a controlled production environment you may have a system where it is only possible for users to submit 'canned' run-streams indirectly. In this case you do not have to worry about limiting users dataset access but, you do have to ensure that any user who may submit a canned job has either a special or default profile which provides at least the access privileges needed by that canned job.

If you allow users access to NIM's "TSO Functionality" suite, then RACF security is an important issue because the TSO functionality allows users to delete members of partitioned datasets etc.

For DB2 users, NIM provides extra security in the form of user exit 6, which is called, from the DB2SERV front end at the time of a dynamic plan switch. The exit is able to reject the plan switch based on user id if necessary.



As most security is based on an authenticated user id, we will discuss the NATURAL user ids. The most visible user id is the NATURAL system variable *init-user which is set up by the TP monitor as CMUSERID in the IOCB area described by NATURAL source member NAMIOCB (NATURAL V2.3+). If no user exit sets this up, it will default to the VTAM terminal id under NIM. Another important user id is the ET id (transaction id) reflected in the NATURAL system variable *etid - defined as ETID in the BB area described by NAMBB (NATURAL V2.3+). This is initialized by the ETID dynamic parameter or failing that, defaults to *init-user value. A third user id is the ADABAS id used in ADABAS calls. This user id is set up by NIM as 'DB2T' followed by a time based 4 bytes to make it unique.

It is defined in field UBUID in the ADABAS UB DSECT. The UB is pointed to by the NIM field TRM@UB in the DSECT TERMMAP.

Natural’s user exit 1 gives direct access to CMUSERID and ETID. If needed, special code could be included so that this exit could gain access to NIM control blocks (which are not in the formal interface provided by NATUEX1).

NIM's user exit 1 gives direct access to CMUSERID, plus indirect access to UBUID and access to the dynamic parameter string, which will contain an ETID if it is specified. The dynamic parameter string is pointed to by TRM@DYNP in the TERMMAP NIM DSECT and is up to 256 bytes long and is modifiable. The full word length of the used part of the string is contained in TRMLDYNP.

Some sites may wish to modify the *init-user value by calling a special assembler subroutine from the first NATURAL program. You should be aware that an ADABAS open command has probably been done at this stage and may cause problems if *init-user was not initially blank (it will not be initially blank unless user exit 1 specially made it blank). Also, be aware that such subroutines may be a security risk (although any underlying RACF profile can not be affected).

Automated Logon to Other VTAM Applications

The same VTAM session passing techniques used by NIM VTAM-server to route user logons to the appropriate NIM job before starting a NATURAL session can also be employed to route a user to another VTAM session at the end of a NATURAL session. This can be done under NATURAL program control by a call to a special NIM subroutine called NIMSET. Just call NIMSET with appropriate parameters (see the section "NIM ON-line Services/Utility Programs" on page 77) and then use the TERMINATE statement to cause immediate one-way transfer to another VTAM environment from the middle of a NATURAL session.

Log Record Functions and Formats

The log record layout is detailed in appendix C. The log has 2 functions:

� To detail statistics at a terminal user level each time a NATURAL session ends, and

� To provide a cumulative workload summary at a specified interval (e.g. total sessions, CPU etc.).


P A G E 1 0 N I M U S E R S G U I D E

By default, log records are written to the DD name DB2TPLOG as a 160-byte FB format record, with the interval for cumulative summaries (snapshots) being 15 minutes. The snapshot interval is synchronized with the wall clock time so that if the interval is a divisor of 60, a snapshot record will coincide with each hour.

Logging can be "turned" off by supplying a dummy dataset or by omitting the DD record in the JCL (which will cause a warning message) or by zapping modifying the NIMTOC (see the section "Modifying NIM Operational Defaults" on page 45 and appendix D).

The frequency of snapshot log records can be modified by the GLOBAL parameter SNAPINT.

User exit E can be defined in GLOBAL parameters to be given control after the log record has been written (or after the log record has been built if logging is turned off). The log image may not be modified but it may be inspected and perhaps some action taken (e.g. an installation formatted SMF record could be written).

The NIM VTAM-server Session Summary Screen

At end of each NIM VTAM-server user session, a summary statistics screen is shown. This contains such details as connect time, CPU use, ADABAS use and DB2 use. It will remain on the user’s screen for sufficient time for the user to be able to digest the information or until they press the enter key. Only when this screen disappears will the session final cleanup begin for that user. The statistical details will be the same as the figures given to the end of session log record - with the exception of the connect time (which will vary according to the viewing time for this screen).

The DBA can suppress this screen or adjust the time it will stay on the screen by using the ENDMT parameter, e.g. ENDMT=0.

N I M U S E R S G U I D E P A G E 1 1

Parameters and User Exits

This chapter presents a variety of ways to configure the NIM and NATURAL interface. Normally only a small subset of these will be used. A Typical site may define 3 or 4 logical drivers, mostly with default settings and will probably use some form of security exit.

NIM Parameters

During initialization, the NIM address space control program reads a dataset describing the operating parameters to be used. The parameters describe "global" attributes of the address space (such as the VTAM-server application name to be used), logical driver definitions and file definitions for datasets to be controlled by NIM (usually only applicable to NATURAL-VSAM users).

Most of the global and all of the file and logical driver parameters can be modified by authorized users of the NIMBLE NATURAL application. Changes made via NIMBLE will remain for the life of the NIM address space, or until changed again using NIMBLE (i.e., changes made using NIMBLE will not effect subsequent executions of NIM, as such changes do not update the dataset containing NIM parameters read during initialization).

Several global parameters and other operating parameters can also be changed by the NIM console operator interface. As with NIMBLE, such changes have effect only for the life of the NIM address space.

Besides the NIM parameters discussed here, there are several other classes of site accessible operating environment definitions that can be made:

Zaps to module NIMTPINI, which determine relatively static, site independent parameters such as internal table sizes (refer to the section "Modifying NIM Operational Defaults" on page 45);

User exits (refer to the section "NIM User Exits" on page 39);

User subtask (refer to the section "NIM User Subtask" on page 45);

Parameter Specification Overview

The parameters described here are supplied to NIM in the //PARM DD JCL statement. The dataset associated with the //PARM DD definition must have the following attributes:

Record format: Fixed Blocked (FB) or Fixed (F) Record length: 80 bytes

Chapter

3

C O N F I G U R A T I O N


The dataset may be either a sequential dataset, a member of a partitioned dataset or a JES sysin dataset.

All 80 columns of each record are parsed. Any record beginning with an asterisk ("*") in column 1 is treated as a comment, and ignored. Ensure that the profile for the dataset has NUM=OFF, otherwise NIM may interpret the appended numbers as data and cause syntax errors at startup in the parameter parser.

All records in the PARM file are of one of the following 5 types:

* Comments.

GLOBAL address space global parameters.

DRIVER logical driver definitions.

DEFAULT default values for logical driver parameters not explicitly overridden on a logical driver definition.

FILE definitions of files to be controlled by NIM and its operator and NIMBLE interface (usually only applicable to NATURAL-VSAM users).

SESSION definitions of specific NIM ATP parameters.

Each statement type is identified by the presence of one of the highlighted literal string (*, GLOBAL, DRIVER, DEFAULT, FILE and SESSION) starting in column 1 of the record. The order of parameter definitions is not significant except in the case of the DEFAULT parameters, which provide default values only for logical drivers defined subsequently in the //PARM file.

Global Parameters

The NIM global parameters apply across all logical drivers, and describe parameters pertaining to address space operation. The syntax of the global parameter record is:

GLOBAL <global parameter> = <global parameter value >

The literal "GLOBAL" must begin in column 1. An arbitrary number of blanks may separate the parameter operands.

The GLOBAL parameters are:

APPL VTAM Application Name

Purpose Defines the VTAM application name to be used by NIM VTAM-server when attempting to establish a connection to VTAM. The VTAM application name must have been defined to VTAM and must be active when NIM VTAM-server initializes. Refer to the section "Defining a NIM VTAM-server Application" on page 85, for details on the characteristics required for the NIM VTAM-server application.



Default None. This parameter is mandatory for NIM VTAM-server

Range VTAM application names must be 1 to 8 alphanumeric characters

Considerations The VTAM application name to be used by NIM VTAM-server must have been defined to VTAM and be active before NIM VTAM-server initializes. If several NIM VTAM-server address spaces are being run concurrently, they must all have unique VTAM application names. The VTAM application name is often the name used by the end user to log on to NIM. E.g., if the VTAM application name "NIMPROD" was used, then the user may enter "LOGON NIMPROD" at the system logon prompt to start a session with the NIM VTAM-server running as VTAM application "NIMPROD". However, many sites run session managers and logon string translation programs, which can mean that the user never needs to know the VTAM application name of the service they require (e.g., they may select an option from a logon menu).

Example "GLOBAL APPL=NIMPROD"

Defines NIMPROD to be the VTAM application name to be used.

ATPREFIX Optional, used as the default prefix for ATP ‘terminal’ lu-names.

Purpose Defines the prefix by which ATP logical terminals are named. This will distinguish ATP sessions from normal NIM user sessions.

Default ASYN

Range pppp, four byte alphanumeric prefix.

Considerations Must be 4 byte alpha numeric. This should be used to clearly define non-terminals tasks for normal online users.

Example ATPREFIX=ASYT

All asynchronous tasks started will be named in the from ATSTnnnn, where nnn is 0001 – 9999 as generated by NIM.

ATTACH User subtask name

Purpose Defines the name of a user written module to be attached as a subtask of the NIM control program.

Default None. If not supplied, no user subtask will be attached.

Range Any valid load module name.

Considerations Most sites will not use this parameter. Refer to the section "NIM User Subtask" on page 45 for details on the use of the ATTACH parameter.



Example "GLOBAL ATTACH=NIMUTASK"

Defines NIMUTASK to be the name of the user subtask load module.

CONSMSG Sets the default verbosity level for NIM console messages

Purpose Messages with the specified importance level and above will be written to the operator’s console. Note: All messages are always written to NIM’s joblog. Some messages, eg. those produced during NIM startup, are always written to the joblog and the operator’s console. I - messages of type information, W – messages of type warning,, E – messages of type error and S – Serious error messages.

Default CONSMSG=I means write I+W+E+S messages to the console. CONSMSG=W means write W+E+S messages to the console. CONSMSG=E means write E+S messages to the console. CONSMSG=S (the default) means write only S messages to the console.

DRIVER Default logical driver name

Purpose Defines the default logical driver name to be assigned to a user session if either no logical driver or an invalid logical driver name is specified by the user when they log on to NIM.

Default None. This parameter must always be specified.

Range Must match one of the logical driver names specified in the //PARM file by the DRIVER parameter.

Considerations The default logical driver name should be set to the logical driver providing the default or most common session characteristics required. If it is mandatory that a correct logical driver name be specified by the user as part of their logon string. Then this parameter should be set to point to a special logical driver that invokes NATURAL with a stacked program which will inform the user of their error and always terminate the session.

Example "GLOBAL DRIVER=PROD"

Defines PROD to be the name of the default logical driver.

MEMTESTH/MEMTESTL

Memory test amounts, high (above the line) and low (below the line)

Purpose Defines the amount of memory that must be available above and/or below the line (i.e., with virtual addresses above and below 16MB) in the NIM address space before NIM will accept a logon request. If the memory is not available, NIM will attempt to transfer the logon request to another address space.



Default None. If the MEMTESTH parameter is not supplied, no test of available above the line memory will be made, If the MEMTESTL parameter is not supplied, no test of available below the line memory will be made.

Range The value specified is in units of kilobytes (i.e., 1024 bytes). Appropriate values will depend on the amount of memory required to run each user session, which will include the memory acquired by NATURAL and memory needed to load and run any subroutines called from NATURAL.

Considerations NIM tests to see if the specified memory is available by trying to acquire the memory. The memory is held whilst the NATURAL sub-task is started and initialized, and released just prior to passing control to NATURAL.

The purpose of these parameters is to allow a site to specify the point at which users are transferred to another NIM address space. The amount of virtual memory required to run a NATURAL session varies greatly on NATURAL options in use (such as CON-NECT, TRS, NATURAL- VSAM, etc), buffer sizes (such as ESIZE, FSIZE, DSIZE, etc), terminal buffer sizes effected by NATURAL parameters such as LS, PS, AVERIO, and by the number of on-line print and work files defined. COBOL, ASSEMBLER, PL/1 etc. Modules must also be loaded into virtual memory, and the size of their code and work areas and reentrancy attribute will also affect the virtual memory requirements. Typically, 31 bit addressing mode users should allow for 8K per user below the line and between 100K - 250K per user above the line.

The NIM control program will attempt to acquire the specified memory test amount in 1 "lump" above and 1 "lump" below the line. NATURAL actually acquires memory in several smaller requests, and so can take advantage (and result in) memory fragmentation within the address space. Hence, application of the MEMTESTH/MEMTESTL tests for the exact amount or storage required by NATURAL and can result in NIM transferring a user. However, this outcome is by far preferable to operating the address space at very close to its theoretical maximum, when an unanticipated storage request (as may be made by a 3GL subroutine) may be impossible to satisfy.

To determine typical values of memory used by NATURAL subtasks, select the NIMBLE utility program "DISPLAY ALLOCATED MEMORY SUMMARY" - NIMBLE option T, sub-option M (or execute program NIMREG directly). Observe the values for allocated memory above and below the line reported against NATURAL subtasks (those with valid terminal ID's).



Example: "GLOBAL MEMTESTH=160 GLOBAL MEMTESTL=32"

Specifies that at least 160K must be available above the line and 32K must be available below the line before a logon request will be accepted.

MESSAGE or M Logon ("Greeting") message specification

Purpose Defines up to 5 lines of a Logon (or "Greeting") message to be sent to each user when they logon to NIM. This message will be sent prior to the user receiving any screens from NATURAL, but after any screens generated by a site-specific logon exit routine.

Default None. No logon message will be sent.

Range The syntax in the above specification must be replaced by a digit from 1 to 5. The message text may take the remainder of the input parameter line following the '='.

Considerations Users logging on to logical drivers which have the ACCPTMSG parameter set to "N" will not receive the logon message, or any other "broadcast" (i.e., unsolicited) messages. Although each line of the logon message can be up to 80 characters long, it is impossible to specify more than 70 characters using a specification of the type: GLOBAL M1=..... The operator interface allows specification of a single line logon message of up to 80 characters. The NIMBLE interface allows specification of a 5-line logon message, with each line being up to 73 characters long.

Example "GLOBAL M1= Welcome to NIM V5.00a !! GLOBAL M2= GLOBAL M3=NIM address space NIMPROD, running GLOBAL M4=NATURAL V3.1 SM06 - please report GLOBAL M5=problems to the DBA on ext 1234"

Defines a 5-line logon message.

NONSWAP NIM is started as a non-swappable address space

Purpose Y sets the NIM address space non-swappable. This parameter replaces the need to run NIM with the NONSWAP program.

Default The default is N.

PRELOAD Pre-load a reentrant load module

Purpose Defines a load module to be preloaded into the NIM address space. The purpose of pre-loading a module is to reduce the system overhead when a (typically) 3GL or assembler reentrant routine is called, as no DASD access to search the steplibs and load the module are required.



Default None. No user specified load modules will be preloaded.

Range Any valid load module name.

Considerations Only reentrant and commonly used load modules should be preloaded. Any number of PRELOAD parameter lines may be present.

Use of the NIM PRELOAD facility can be seen as an flexible alternative to use of the NATURAL CSTATIC parameter. While not reducing the call overhead as completely as CSTATIC, it has some advantages:

PRELOAD is more flexible - the NATURAL parameter module and nucleus does not need to be reassembled and linked when a module or the CSTATIC list changes;

as the tendency increases to place NATURAL components in the LPA/ELPA, changing modules in the CSTATIC list will require an IPL;

• The NIM UNLOAD and LOAD commands can be used to dynamically delete from memory and reload a module into memory if that module is not currently in use, without needing to stop NIM;

• Preloaded modules may be subroutines called from either NATURAL or from 3GL/assembler subroutines called from NATURAL, whereas CSTATIC modules are only directly available to NATURAL;

• Preloaded modules running in AMODE 24 will automatically have their parameters moved below the line when called (by the NIM NATURAL driver);

• The NIM call interface is very efficient and the overhead saved by the CSTATIC method is extremely small when reentrant preloaded modules are being invoked.

Extremely static, AMODE 31 bit reentrant modules are still good candidates for Natural’s CSTATIC list. The NIM PRELOAD facility adds some flexibility in system tuning.

Example GLOBAL PRELOAD=DATECONV1 GLOBAL PRELOAD=DATECONV2 GLOBAL PRELOAD=TRIGFUN1

Modules DATECONV1, DATECONV2 and TRIGFUN1 are to be preloaded.



SHOWGADR Show addresses of NIM major control blocks

Purpose Y turns on the display of the addresses of NIM’s major areas and control blocks during NIM initialisation. The default is N with the exception of the Global Subspace storage area whose address is always displayed.

This display is useful when debugging. It is normally turned off but NIM support may ask you to turn it on to assist with problem resolution.

Default N, possible values [Y/N]

SHOWSADR Show addresses of NIM major session control blocks

Purpose Y turns on the display of the addresses of every session’s major areas and control blocks during session initialisation. The default is N.

This display is useful when debugging. It is normally turned off but NIM support may ask you to turn it on to assist with problem resolution.

Default N, possible values [Y/N]

SERVER NIM server definition

Purpose Defines a NIM server to start at NIM Address Space startup.

Default None

Range VTAM [required] or ATP [optional]

Considerations NIM requires the VTAM value to be supplied, if asynchronous non-terminal tasks are to be used then the ATP server must be defined as well.

Example GLOBAL SERVER=VTAM GLOBAL SERVER=ATP

Both VTAM and ATP servers will be loaded at NIM startup.

SNAPINT Log Snapshot record generation interval

Purpose Defines an interval between generations of NIM log snapshot records.

Default 15 minutes.

Range 1 to 999 minutes.

Considerations NIM attempts to synchronize snapshot log records with the wall-clock hour. E.g., if SNAPINT is set to 20, records will be written on the



hour, 20 past and 20 to the hour.

If the snapshot interval is not an even divisor of 60, snapshot log records cannot be synchronized with the hour.

Example GLOBAL SNAPINT=60

Log snapshot records are to be written every 60 minutes (i.e., on the hour).

SSID or SUBSYS Define DB2 subsystem to be connected

Purpose NIM supports NATURAL-DB2 by using the DB2 Call Attach Facility (CAF) interface. The main NIM address space control program establishes the connection with DB2, greatly reducing the resources required by NATURAL subtasks to initialize their DB2 connections. This parameter supplies the name of the DB2 subsystem to be connected.

Default None. No DB2 connection will be made.

Range A valid DB2 subsystem.

Considerations DB2 permits an address space to be connected to only one DB2 subsystem at time. Hence, DBAs must ensure that only one subsystem is used by any particular NIM address space.

NIM monitors all attempts to open DB2 connections from NATURAL subtasks, and will report any attempts to connect to a DB2 subsystem other than that specified with this parameter.

Refer to the section "NATURAL DB2 Support" on page 50 for full details.

Example GLOBAL SUBSYS=DB2P

The DB2P DB2 subsystem is to be accessed from the address space.

SZERO Share sub pool zero between subtasks and control program.

Purpose Allows memory obtained by a NATURAL subtask in sub pool zero to be shared by other subtasks and the NIM address space control task.

Default N. Sub pool zero is not to be shared.

Range Y or N.

Considerations This parameter should not be changed unless specifically advised to do so by your NIM distributor. It may be required in some very rare circumstances associated with use of particular COBOL or VSAM processing options. General use may degrade performance.



Example: GLOBAL SZERO=Y

Sub pool zero is to be shared.

UEXn Specify address space control program user exit.

Purpose Defines the name of a user written exits to be called from a user exit processing point in the NIM address space control program.

Default None. If not supplied, no user exit processing will be performed

Range In the above specification n should be an uppercase letter in the range A to G. The user exit load module must be a valid load module name, performing the required processing and adhering to the user exit interface.

Considerations Refer to the section "NIM User Exits" on page 39 for details on the use of the GLOBAL UEX parameter.

Example: GLOBAL UEXA=STRTEXIT GLOBAL UEXB=SHUTEXIT LOBAL UEXE=SITELOG

Defines 3 user exits: - UEXA (Startup exit) is STRTERXIT; - UEXB (Shutdown exit) is SHUTEXIT; - UEXE (Logging exit) is SITELOG.

UMAX or USERMAX

specify address space user max

Purpose Defines an address space wide limit on the number of concurrent users. When a user attempts to log on and the number of users is already at the usermax, the NIM will attempt to transfer the logon request to another address space.

Default 500

Range 0 to 1000. If set to 0, NIM will always attempt to transfer users to another address space.

Considerations The GLOBAL usermax is checked before logical driver usermax limits. Hence, a user may be transferred even if the logical driver usermax has not yet been reached. The GLOBAL usermax is a way of limiting the total number of subtasks in the NIM address space, and a coarse regulator of virtual memory usage per address space (the REGION= and MEMTESTH/L parameters provide more accurate control).

Example: GLOBAL USERMAX=250

Specifies that at most 250 concurrent users may be logged on to the



NIM address space

WTOHEAD specify console message prefix

Purpose Defines string to appear as the prefix to all console (write-to-operator, "WTO") messages generated by NIM.

Default For NIM VTAM-server - VTAM application name.

Range An 8 character string

Considerations When running multiple NIM address spaces, this parameter may be used to allow for easy identification of the source address space of a message. The default value will often prove suitable for this purpose.

Example: GLOBAL WTOHEAD='TP PROD'

Specifies that at the string "TP PROD" will prefix all NIM messages from the address space.

XFER specify GLOBAL (default) transfer VTAM application name

Purpose Defines the name of the VTAM application to which GLOBAL transfer attempts will be made.

Default None. No global transfer will be attempted.

Range An active NIM VTAM-server application name. The VTAM application name (APPL) must be different from the transfer application name (XFER).

Considerations The GLOBAL XFER is only used if the logical driver XFER specification has been omitted for the logical driver being used.

When NIM VTAM-server decides that it must transfer a user requesting to logon to another address space (due to global or driver usermax, or memory tests), it determines if a transfer application has been defined in the logical driver used by the user (either an explicit logical driver or the default logical driver). If none has been specified at the logical driver level, then the value of this (Global) parameter is used.

Example: GLOBAL XFER=NIMPROD2

Specifies that the global transfer application is NIMPROD2.

Logical Driver Parameters

One of more logical drivers must be defined in each NIM address space. A logical driver is a collection of parameters and names of load modules that defines an execution environment for a class of service. Refer to the section "Introduction to Logical Drivers" on page 89 for a description of the purpose and use of logical drivers.



A logical driver is defined by the presence of at least one, and usually more logical driver definitions in the //PARMS file. The syntax of the logical driver parameter record is:

DRIVER <logical driver name> <parm> = <parm value>

The literal "DRIVER" must begin in column 1. An arbitrary number of blanks may separate the parameter operands.

The logical driver name must always be present, consisting of between 1 and 8 alphanumeric characters.

Normally, several different parameters will be defined for a logical driver. Although it is convenient to group definitions for a particular logical driver together in sequence in the //PARMS file it is not mandatory.

If a logical driver parameter is omitted for a particular logical driver, it will default. The default value may have been defined by the DEFAULT record, described in the next section, or may default to have no value or a specific NIM default described below.

New logical drivers can be defined, and logical drivers can be modified and deleted dynamically whilst the address space is running by using the NIMBLE interface.

The logical DRIVER parameters are:

ABMAX maximum number of abend recoveries to be performed

Purpose Defines the maximum number of times that the abend recovery routines in the NIM driver will attempt to recover the abend and pass control to the retry routine.

Default 20

Range 0 – 9999

Considerations The main purpose of this parameter is to prevent a runaway or recursive abend retry situation. All program checks and abends contribute to this count, including program checks within NATURAL (S0C7 from bad packed fields, invalid addresses in DUMP, etc) and most external subroutines.

When the ABMAX limit is exceeded, the user NATURAL session is terminated and message 210 is generated.

If the DUMP parameter is set to Y, then the user session will be terminated at the first abend, regardless of the setting of ABMAX.

Example DRIVER TESTD ABMAX=10

ACCPTMSG "Accept unsolicited messages" flag



Purpose Defines whether by default, users of this logical driver should receive unsolicited messages such as the logon ("greeting") and broadcast messages.

Default Y

Range Y or N

Considerations Sessions used for file transfers or running against prepared scripts will probably not want unsolicited and unpredictable messages from interfering with session data flow, and so may wish to be run under a logical driver with this flag set to N.

Regardless of logical driver settings, the receipt of unsolicited messages can also be disabled (or enabled) by a call to the NATSET utility (refer to the section "NIM ON-line Services/Utility Programs" on page 77).

Example DRIVER TESTD ACCPTMSG=N

ADALINK or ADALNK

Specify ADABAS link module

Purpose Defines the name of the ADABAS call linkage module.

Default ADALNKR

Range Any valid ADALINK load module name

Considerations The default NIM ADALINK is just the ADALNK module taken from the Software AG ADABAS source distribution library and modified to make it reentrant (by following the simple Software AG comments within the module). Users of APAS/INSIGHT should use a reentrant ADALINK module supplied by the APAS INSIGHT distributors.

It is very important that a reentrant ADALNK is used to prevent a new copy being loaded by each NATURAL sub-task.

Example DRIVER TESTD ADALINK=APASLNK

CPUINT – CPU

timer resolution

Purpose Defines the resolution of the CPU timer used in the NATURAL subtask for enforcing NATURAL MT= CPU limits

Default 100 centi-seconds (i.e., 1 second)

Range 10 to 1000 centi-seconds

Considerations Setting this parameter to a low value (say, 10 centi-seconds) slightly increases overheads by increasing the frequency of timer issuing and analysis (and NATURAL does not support a MT= value of less than 1



second).

Setting this parameter to a high value (say, 500 centi-seconds) reduces slightly the timer overhead but also reduces the effectiveness of NIM's priority adjustment system, which reviews a task's dispatching priority at each timer expiry, and reduces the resolution of Natural’s MT= timer.

Remember that Natural’s MT parameter uses units of SECONDS, whereas NIM's CPUINT parameter uses units of 1/100th of a second.

Example DRIVER TESTD CPUINT=200

Sets the CPU timer resolution to 200 centi-seconds (i.e. 2 seconds)

DEFRESP "Require definite VTAM responses from SLU" flag

Purpose Defines whether NIM VTAM-server requires the secondary logical unit (SLU) i.e. the user's terminal, to send a definite response to the VTAM message sent by NIM VTAM-server.

Default Y

Range Y or N

Considerations Requiring the secondary logical unit (SLU) to send a definite response to the NIM VTAM-server output screen slightly increases host CPU and network load. However, it enables the NIM network response time monitor to operate and guarantees to the NATURAL program that an output screen has arrived successfully at the terminal. This last point is probably of dubious benefit, for should a network outage or SLU problem occur then the NATURAL program will be aborted on the next screen read anyway (which normally will immediately follow the screen write).

Setting this parameter to "N" will help relieve congestion in a heavily loaded network. This benefit may be outweighed by the consequent loss of the NIM network response time statistics that can aid in the tracking and location of network problems.

Example DRIVER TESTD DEFRESP=N

DUMP "Disable abend retry and force dumps" flag

Purpose Defines whether NIM establishes an abend recovery and retry environment.

Default N

Range Y or N

Considerations When set to "Y" any abend within a NATURAL program or general subroutine will not be trapped, and an operating system dump will be



produced. The NIM task JCL must have either a //SYSUDUMP or //SYSABEND DD card for the dump to appear.

When set to "N", NIM will establish an abend recovery environment, and attempt to return control to a retry routine (usually defined by NATURAL). The NATURAL "DUMP" program can then be used to help diagnose the error.

In cases where the NATURAL "DUMP" program cannot diagnose the problem, setting the parameter to "Y" will result in the production of a standard operating system format dump.

Example DRIVER TESTD DUMP=Y

DYNP or DYNPARM

Specify NATURAL dynamic parameter

Purpose Defines the NATURAL dynamic parameter string

Default None. N–o dynamic parameter will be passed to NATURAL

Range Up to 256 alphanumeric characters.

NOTE: the DYNPARM parameter can be continued across multiple parameter file records (see below).

Considerations The DYNPARM parameter is very commonly used to define NATURAL execution parameters to implement the logical driver environment.

Typically used dynamic parameters are:

PARM SYS STACK %SIZE

To specify a NATURAL parameter "environment". To specify a set of NATURAL parameters. To specify a startup sequence of NATURAL programs and data where % is replaced with E, F, D etc., to specify the sizes of NATURAL data areas for the session.

Refer to the NATURAL Operations Manual for details on the many parameters available.

NIM will perform parameter substitution into the DYNPARM field from FLEXPARM values, facilitating the construction of dynamic parameter values based on the user's VTAM logon string.

More than 1 DYNPARM (or DYNP) specification can appear for a logical driver. The DYNPARM values for all records for a logical driver are simply concatenated.



Example 1 DRIVER TESTD DYNP=PARM=NATE2,SYS=PROD, DRIVER TESTD DYNP=ESIZE=120,STACK=(LOGON SYS DRIVER TESTD DYNP=DBA;MENU),SM=OFF

NATURAL will be invoked with the following dynamic parameter string:

PARM=NATE2,SYS=PROD,ESIZE=120, STACK=(LOGON SYSDBA;MENU),SM=OFF

Example 2 DRIVER TESTD DYNP=STACK=(LOGON &U;&P),ESIZE=&E DRIVER TESTD FLEXP=U=SYSTEM,P=STARTUP,E=30

Here, the values &U, &P and &E will be substituted with values optionally supplied by the user in their logon string. If not supplied, these values will default to SYSTEM, STARTUP and 30 respectively.

E.g., if the user logged on with the string:

LOGON NIM, TESTD,U=FRED

then NATURAL will be invoked with the following dynamic parameter string:

STACK=(LOGON FRED;STARTUP),ESIZE=30

If the user logged on with the string:

LOGON NIM,TESTD,E=44,P=MENU

then NATURAL will be invoked with the following dynamic parameter string:

STACK=(LOGON SYSTEM;MENU),ESIZE=44

Refer to the section “NIM Asynchronous Session Parameters” on page 28 for full details of FLEXPARMS.

DYNP Additional options for use with NIM’s ATP Server

Example DYNP=,SENDER=<dest>, identifies the destination of Natural generated messages. <dest>=CONSOLE, messages are directed to the console. <dest>=DUMMY, messages are suppressed.

DYNP=,OUTDEST=dest, identifies the destination of Natural generated error messages <dest>=CONSOLE, messages are directed to the console. <dest>=DUMMY, messages are suppressed. DYNP=,STACK=(LOGON libname,pgmname), optional, identifies the application and program to execute at start of ATP session.



ENDMSG Display time of NIM's final session summary screen

Purpose Defines the period that the NIM VTAM-server session summary screen is displayed, or whether this screen is to be suppressed.

Default 3000 centi-seconds (i.e., 30 seconds)

Range 0 - 12000 centi-seconds (i.e., 0 to 120 seconds)

Considerations When set to 0, the final session summary screen is suppressed.

Otherwise, this parameter determines the time (in centi-seconds) that the screen will be displayed before the terminal is released from the NIM VTAM-server application.

The user can cause the immediate release of the terminal by pressing ENTER whilst the final screen is being displayed.

For details on the contents of the summary screen, refer to the section "The NIM VTAM-server Session Summary Screen" on page 10.

Example DRIVER TESTD ENDMSG=1000

The session summary screen will be displayed for 1000 centi-seconds (10 seconds).

EPMNAME Name of the Physical Driver Entry Point Table

Purpose Defines the name of the module that contains the entry points of all the modules that are required to provide NATURAL and NIM services for this Logical Driver.

Default None. This parameter must be specified for each set of Logical Driver definitions.

Range See ‘considerations’ below.

Considerations This module is the very close companion to the NIM driver program (the "physical driver") and MUST match the Version/Release. This module contains the entry points of all the modules that are required to provide NATURAL and NIM services.

The module name is normally of the form NIMvrEPT – where vr is equivalent to the Version and Release level of Natural to which this logical driver applies.

For example: A logical driver required to support NATURAL 3.1.6 would specify EPTNAME=NIM31EPT

FLEXP or FLEXPARM

Specify NATURAL dynamic parameter substitution strings



Purpose Defines the parameters and default values to be substituted into the NATURAL dynamic parameter string.

Default None. N–o FLEXPARM substitution will be performed.

Range Up to 70 alphanumeric characters.

Considerations The FLEXPARM parameter is used to enable controlled customization of the NATURAL dynamic parameter string. Often, logon requests are generated by logon menus or multiple VTAM application monitors. In such cases, the "front-end" software can usually build a logon string to be passed to the target application, typically providing data such as User-id and password so that the user is not required to type these details in to every application. This concept is often extended to pass more information, such as a target application and even data.

The FLEXPARM parameter enables data passed from such a front-end to be easily incorporated into the NATURAL dynamic parameters.

Refer to the section “NIM’s FLEXPARM Facilities”.

Example Refer to the DYNPARM parameter description.

FREEBIND "free VTAM BIND and logon string" flag

Purpose Defines whether NIM VTAM-server frees the VTAM BIND and VTAM logon string areas before invoking NATURAL.

Default Y.

Range Y or N.

Considerations When set to "N", the data areas containing the VTAM BIND and logon message will be retained for the term of the NATURAL session.

When set to "Y", NIM VTAM-server will free these areas just before passing control to the NATURAL nucleus (but after invoking any NATURAL subtask startup user exit (user exit UEX1).

Retaining these areas means that a user written assembler program could be called from NATURAL to retrieve the VTAM BIND or logon string data. These areas combined occupy 384 bytes of above- the-line storage.

Example DRIVER TESTD FREEBIND=Y

HIGHPRTY Maximum relative dispatching priority

Purpose Defines the maximum dispatching priority (relative to the NIM address space control program's dispatching priority) of NATURAL subtasks running under the logical driver.



Default 2

Range 0 to 255

Considerations The value of this parameter sets a limit on how high the operating system dispatching priority for NATURAL subtask running under the logical driver can be when compared to the maximum dispatching priority of the NIM address space control program.

Lower numbers indicate higher absolute dispatching priorities.

A value of 0 means that the subtask competes for the CPU equally with the main NIM control program task, and is not recommended.

This parameter should be used with the LOWPRTY parameter to define a range of dispatching priorities in which the subtask will operate.

NIM will reduce the dispatching priority of a subtask when a CPU monitoring interval expires (see the CPUINT parameter) and the subtask has not issued any conversational I/Os (i.e., the subtask is classified as "CPU bound").

The dispatching priority will continue to be reduced by one priority unit at a time for each additional CPUINT interval over which no conversational I/Os were issued. When the dispatching priority has been reduced to the LOWPRTY setting, it will not be reduced any further.

The issuing of a conversational I/O restores the subtask priority to it's HIGHPRTY setting.

Example DRIVER PROD HIGHPRTY=2 DRIVER PROD LOWPRTY=5 DRIVER PROD CPUINT=1 DRIVER TEST HIGHPRTY=4 DRIVER TEST LOWPRTY=8 DRIVER TEST CPUINT=1 DRIVER DEV HIGHPRTY=5 DRIVER DEV LOWPRTY=12 DRIVER DEV CPUINT=1

If the above definitions were in force in a single NIM address space, then PROD users would normally compete more effectively for the CPU than TEST users, who in turn would compete more effectively than DEV users.

However, PROD users who used more than 2 seconds CPU without performing any screen I/O would have their relative dispatching priority reduced to the same level as non-CPU intensive TEST users. If the PROD user continued to use CPU and not perform screen I/Os, their dispatching priority would drop once more, to settle at a level just below that of top priority TEST users, and at the same level as DEV users.



CPUMAX "Logical driver CPU control parameter"

Purpose Defines the amount of CPU NIM will allow a task before it is determined that the task is a runaway task.

Default 6000

Range 100 - 10000 centi-seconds

Considerations

When set this value will enforce a strict CPU limit on tasks running in the NIM address space.

The amount of CPU allowed to be consumed between screen I/Os. This is a very fine measurement of CPU usage. It will prevent user sub-tasks from running away… It is complimentary to the Natural MT parameter, but provides much more control. If this time is exceeded by an application, NIM will interrupt the user session and return a NAT953 error message.

Example DRIVER TESTD CPUMAX=3000

LOWPRTY Minimum relative dispatching priority

Purpose Defines the minimum dispatching priority (relative to the NIM address space control program's dispatching priority) of NATURAL subtasks running under the logical driver.

Default 2

Range 0 to 255

Considerations

The value of this parameter sets a limit on how low the operating system dispatching priority for NATURAL subtask running under the logical driver can be when compared to the maximum dispatching priority of the NIM address space control program.

Lower numbers indicate higher absolute dispatching priorities.

Refer to the HIGHPRTY parameter for a discussion on the use of this parameter.

MTRACE "Trace NATURAL GETMAINs and FREEMAINs" flag

Purpose Defines whether NIM reports to the console and log all of Natural’s memory getmain and freemain requests

Default N

Range Y or N

Considerations When set to "Y", NIM will report all NATURAL memory GETMAINs (NIM message 242) and memory FREEMAINs (NIM message 243) to



the console and log.

This flag should only be set to "Y" when investigating the pattern and size of NATURAL memory use. The GETMAIN/ FREEMAIN ID field indicates the type of memory being handled, and is documented in the NATURAL DSECT "CMIOCB".

Example DRIVER TESTD MTRACE=Y

NATNUC NATURAL nucleus name

Purpose Defines the NATURAL nucleus to be invoked by the NATURAL subtask.

Default None. Must always be supplied

Range Load module name.

Considerations The recommended approach of configuring NATURAL is discussed in the sections "Configuring the Natural Environment" on page 86 and "Supporting the Basic NATURAL Environment* on page 48 and in the NATURAL 2 Operations Manual.

In summary, there are significant advantages in the following approach:

• Link an environment independent NATURAL nucleus into ELPA (or LPA);

• Link one or more parameter and environment dependent modules into LPA;

• Invoke the environment independent NATURAL nucleus with a PARM= dynamic parameter, referring to the parameter and environment dependent modules.

In this scenario, the logical driver NATNUC parameter defines the name of the environment independent NATURAL nucleus.

However, another approach is possible, but are not recommended as it reduces flexibility and shared usage of the NATURAL nucleus:

• Link the environment independent and dependent modules together. The name of this module is then provided to the NATNUC parameter

Example DRIVER TESTD NATNUC=NAT22LPA

NONACT Non-activity interval before time-out

Purpose Defines the length of time since the last inbound message received from a terminal after which the session will be terminated with a timeout



Default 1800 seconds (30 minutes)

Range 60 - 99999 seconds

Considerations The NIM address space control program checks for non-activity time-outs every minute, on the minute. Hence, depending on the exact time of last receive request, the user may obtain a grace period of up to 59 seconds.

Example DRIVER TESTD NONACT=1200

Specifies a non-activity interval of 1200 seconds (20 minutes)

NONACTW Non-activity interval before time-out warning

Purpose Defines the length of time since the last inbound message received from a terminal after which a warning beep will be sent to the terminal, warning of an impending time-out

Default 1740 seconds (29 minutes)

Range 60 - 99999 seconds

Considerations The NIM address space control program checks for non-activity time-outs every minute, on the minute. Hence, all warnings will be sent just after "on the minute". Because time-outs and warnings are checked together, and only at 60 second intervals, the NONACTW parameter should be at least 60 seconds less than the NONACT parameter

Example DRIVER TESTD NONACTW=1140

Specifies a non-activity interval of 1200 seconds (20 minutes), and send a warning after 19 minutes of inactivity.

PDRIVER Physical Driver Module Name

Purpose Defines the load module to be attached by the NIM address space control program when initiating a new user session.

Default None. This parameter must be specified.

Range See ‘considerations’ below.

Considerations This module is the NIM driver program (the "physical driver") for the NATURAL nucleus that enables all the services that NATURAL requires as well as coordinating the NIM-NATURAL interface.

The module name is normally of the form NIMvrNAT – where vr is equivalent to the Version and Release level of Natural to which this logical driver applies.

For example: A logical driver required to support NATURAL 2.2.8 would



specify PDRIVER=NIM22NAT

Example DRIVER TESTD PDRIVER=NIM23NAT

PRINTPF PF key name to activate optional screen dump

Purpose Defines the default PF key to enable users to dump a VTAM screen to printer.

Default NONE

Range NONE, CLEAR, PF1, PF2,..,PF24, PA1, PA2, PA3

Considerations This option should not be used unless ALL terminals and applications can have a common spare key. It can be set individually by the NATSET utility in a user session.

Screen dumping will only operate on terminals where a default printer-id has been defined (by the NATSET function or a user exit). The default SYSOUT class may also need changing (by zap to NIMTPINI or by NATSET utility).

Typically, the 3270 print key will be used - so this NIM option need not be specified.

Example DRIVER TESTD PRINTPF=PA2

SERVER Specify NIM server type for use with this logical driver.

Purpose Optional, identifies logical driver for use by ATP sessions.

Default None.

Range Either not specified or ATP.

Considerations Used to defining logical driver for use with ATP server sessions.

Example DRIVER ATPTESTD SERVER=ATP

UEX <x> Specify NATURAL subtask related user exit.

Purpose Defines the name of a user written exits to be called from a user exit processing point in the NIM NATURAL subtask driver program.

Default None. If not supplied, no user exit processing will be performed

Range In the above specification should be a number in the range 1 to 8. The user exit load module must be a valid load module name, performing the required processing and adhering to the user exit interface.

Considerations Refer to the section "NIM User Exits" on page 39 for details on the use of the driver UEX parameter.



Example DRIVER UEX1=RACFEXIT DRIVER UEX7=ABEXIT

Defines 2 user exits: UEX1 (Session start exit) is RACFEXIT; UEX7 (abend recovery exit) is ABEXIT.

USERDATA User data

Purpose Defines user data that may be accessed by user written exits and subroutines.

Default None (field is 8 binary zeros)

Range 8 bytes

Considerations This field can be accessed by user written exits or subroutines in the NIM logical driver DSECT "LPMAP", field "LDUDATA".

User programs can make any use of this field to store logical driver related data, an address of an additional data area, etc.

Example DRIVER TESTD PDRIVER=NIM23NAT

UMAX or USERMAX

Specify logical driver user max

Purpose Defines a logical driver limit on the number of concurrent users. When a user attempts to log on to a logical driver and the number of users on the driver is already at the usermax, NIM will attempt to transfer the logon request to another address space.

Default 999

Range 0 to 1000. If set to 0, NIM will always attempt to transfer users to another address space.

Considerations The GLOBAL usermax is checked before logical driver usermax limits. Hence, a user may be transferred even if the logical driver usermax has not yet been reached. The GLOBAL usermax is a way of limiting the total number of subtasks in the NIM address space, and a coarse regulator of virtual memory usage per address space (the REGION= and MEMTEST H/L parameters provide more accurate control).

The logical driver usermax check is made only after the address space usermax check has succeeded. The purpose of the logical driver user max is to limit a certain category of users concurrently logged on to a particular address space.



A special use of the logical driver usermax parameter is to set the value to 0, and to set a logical driver XFER application. The effect of this combination is to pass all logon requests for a certain logical driver to a specific address space.

Example DRIVER TEST USERMAX=0 DRIVER TEST XFER=NIMTEST

Specifies that any logon attempts to this address space using logical driver "TEST" are to be automatically transferred to another address space running the NIM VTAM-server application "NIMTEST".

VTAMBUFF Size of NIM VTAM-server's VTAM I/O buffer

Purpose Specifies the size of the NIM VTAM-server VTAM I/O buffer

Default 4096 bytes

Range 1000 - 9999 bytes

Considerations This buffer is used by NATURAL to construct its outbound screen, and to receive data from the terminal. Whilst 4096 bytes is a generous screen size for 4 color 3270 terminal devices operating in 24 rows by 80 column format. A full color and/or large screen device may be sent longer messages by a NATURAL application producing many colors, windows and having many separate fields on a single screen.

Example DRIVER TESTD VTAMBUFF=6000

VTRACE "trace VTAM activity" flag

Purpose Defines whether NIM VTAM-server traces all VTAM activity for sessions using the logical driver.

Default N

Range Y or N

Considerations When set to "Y", NIM VTAM-server will attempt to trace all VTAM activity on sessions to file //DB2TPTRA DD which must be included in the NIM job JCL.

If used, //DB2TPTRA should be either a dataset initially emptied, and allocated with DISP=MOD or a SYSOUT dataset. The DCB for the dataset should be RECFM= FB,LRECL=120,DSORG=PS.

The trace output can be used by NIM support or Data Communications Staff to diagnose difficult communications problems.

Example DRIVER TESTD VTRACE=Y



XFER Specify logical driver transfer VTAM application name

Purpose Defines the name of the VTAM application to which transfer attempt will be made. When NIM VTAM-server decides that it must transfer a user requesting logon to another address space (due to global or driver usermax, or memory tests). Then it first determines if a transfer application has been associated with the logical driver used by the user (either an explicit logical driver or the default logical driver). If none has been specified at the logical driver level, then the value of the GLOBAL XFER is used.

Default None (the global transfer name will be used)

Range An active NIM VTAM-server application name. The VTAM application name (as specified in the APPL parameter) must be different from the transfer application name (as specified in the XFER parameter).

Considerations The logical driver XFER application name can be used to cause users to be transferred to an address space dependent on which logical driver they attempted to log on with (refer to the discussion of the USERMAX parameter).

Example DRIVER TESTD XFER=NIMPROD2

Default Logical Driver Parameter

Rather than accept the default logical driver parameters described above and constantly override them explicitly in many or all logical drivers, DEFAULT logical driver parameters can be specified in the PARM dataset. For a user specified DEFAULT to take effect, it must be declared before any logical driver parameters for the logical drivers for which it is to replaced the NIM default value. In general, the DEFAULT logical driver records should be defined before any logical drivers are defined.

The syntax of the DEFAULT logical driver parameter is:

DEFAULT <parameter> = <parameter value>

The literal "DEFAULT must begin in column 1. An arbitrary number of blanks may separate the parameter operands.

The rules for specification of the parameter and parameter value are identical for those described in the DRIVER parameter section above.

Example:



DEFAULT PDRIVER=NIM31NAT DEFAULT NATNUC=NAT31LPA DEFAULT ADALNK=APASLNK DEFAULT UEX1=RACFEXIT * DRIVER TEST DYNPARM=PARM=NATPARME,SYS=TEST DRIVER PROD PDRIVER=NIM31NTX DRIVER DEV UEX1= DRIVER DEV MTRACE=Y

In this example, all 3 logical drivers will have NATNUC set to "NAT31LPA" and ADALNK set to "APASLNK". The TEST and PROD drivers will be using "RACFEXIT" as their user exit 1, but DEV won't have any user exit 1. Both TEST and DEV will use "NIM31NAT" for the value of the PDRIVER parameter, but the PROD driver will use "NIM31NTX" for this parameter.

File Parameters

File parameter records are used to define file names and their associated dataset names for file resources to be controlled by NIM. Normally, only NATURAL-VSAM users will specify file parameters, and even for NATURAL-VSAM users, their use is an optional alternative to including the //file DSN=dsn JCL cards directly in the NIM job JCL.

However, by defining the NATURAL-VSAM files in the NIM parameter cards rather than directly in the JCL, additional flexibility of operation is achieved. By using the console or operator interface, files so defined can easily be dynamically allocated or removed from the NIM job, allowing other jobs which may require exclusive access to the datasets to execute, whilst not affecting NIM users who do not require access to these files.

The syntax of the file record is:

FILE <allocation option> <FILE DDname><FILE DSN nam e>

and where the allocation option is either "ALLOC" or "DEFINE".

The literal "FILE" must begin in column 1. An arbitrary number of blanks may separate the parameter operands.

The allocation option "ALLOC" means that the file is to be dynamically allocated at the start of the NIM job, whereas the allocation option "DEFINE" merely defines the file and dataset to the NIM address space control blocks, but does not allocate it.

Example:

FILE ALLOC PRDMAST1 FINANCE.GL.MASTER FILE ALLOC PRDTRN1 FINANCE.GL.TRANS1 FILE ALLOC PRDTRN2 FINANCE.GL.TRANS2 FILE DEFINE COSTCODE FINANCE.GL.COSTCODE



NIM Asynchronous Session Parameters

Session parameters are used to define additional parameters for the management of ATP sessions. The parameter is defined in the following format:

SESSION <SESSNAME> <PARM> <=><VALUE>

The PARM has the following values:

DRIVER <drivername> SERVER=ATP, defines this session with logical drivername to be an ATP session.

DYNP Optional, dynamic Natural pseudo-logon parameters

USERID Userid for security logon. Optional pseudo logon parameter.

PASSWORD Password for Userid. Optional pseudo-logon parameter.

Examples:

SESSION ASYNGEN DRIVER ATPS0001 SESSION ASYNGEN DYNP=<dynamic Natural parameters> SESSION ASYNGEN USERID=<userid> SESSION ASYNGEN PASSWORD=<password>

Using NIM’s FLEXPARM Facility

The flexparm facility is a mechanism to allow a user to choose the values in their NATURAL dynamic parameters at logon time. Flexparms allow the NATURAL administrator to make certain of the dynamic parameters into variables which are resolved at logon time by user overrides or by defaults set up in the logical driver definition.

For example, the NATURAL dynamic parameters may be defined as follows:

"DRIVER xxxxxxxx DYNPARM=DBID=&D".

This sets up a base NATURAL dynamic parameter string of "DBID=&D", where "&D" is a flexparm variable name. "&D" cannot be presented to NATURAL as it stands because it is illegal syntax, so it has to be replaced.

If the administrator had also defined another logical driver parameter:



"DRIVER xxxxxxxx FLEXPARM=D=1"

then a default of 1 is provided for &D. All FLEXPARMs must have a default. If a user logged on in the normal way, (e.g. "LOGON NIM xxxxxxxx") the NATURAL dynamic parameter string used would be "DBID=1".

To continue this example, if a user logged on as "LOGON NIM xxxxxxxx,D=99" then they would override the flexparm variable so that the effective NATURAL dynamic parameter string would be "DBID=99" for this user.

Multiple flexparm variables can be provided but they cannot be nested. The DYNPARM and FLEXPARM logical driver parameter records are processed in a similar way by NIM - multiple records can be concatenated. Internally each is a 256-byte string. At logon time, a 3 way "merge and substitution" process takes place using 3 256 byte strings: the user logon string, the base dynamic parameter string and the flexparm string for the logical driver involved.

At some sites, FLEXPARMs have been used so that logons from a session handling product (NETMASTER) which authenticates users, could be generated with 2 FLEXPARMs representing a Userid and password which could be passed as data to a NATURAL program stacked using the STACK dynamic parameter.

NIM User Exits

In NIM user exits are divided into three separate types, they are:

� Address space control program exits;

� Server Exits

� Natural Driver Exits.

Both types are described in detail in the following sections.

Address Space Control Program Exits

These exits all have an alphabetic suffix in their name and are loaded once by the control program at the time of reading the parameters. They can use the words GBLUWRD1/2/3/4 in the GLOBMAP area for their own purpose.

UEXA Start of job user exit

Called by the main control program after initialization, but before opening VTAM or the log.

R11 = address of GLOBMAP (31 bit) R13 = standard save area (31 bit) R14 = return address (31 bit) R15 = entrypoint address (31bit)



called by BALR in AMODE 31, must return in AMODE 31.

On return, R15 is not examined.

UEXB End of job user exit

called by the main control program after cleanup, when VTAM and the log are closed.

R11 = address of GLOBMAP (31 bit) R13 = standard save area (31 bit) R14 = return address (31 bit) R15 = entrypoint address (31 bit)



UEXC Task startup exit

called by the main control program when a NATURAL terminal session task is about to be attached (just after message 011).

R08 = address of LDMAP (31 bit) R09 = address of TERMMAP (31 bit) R10 = address of TASKMAP (31 bit) R11 = address of GLOBMAP (31 bit) R13 = standard save area (31 bit) R14 = return address (31 bit) R15 = entrypoint address (31 bit)



UEXD Task end exit

called by the main control program when a NATURAL terminal session task is about to be detached (just before message 011).

R10 = address of TASKMAP (31 bit) R11 = address of GLOBMAP (31 bit) R13 = standard save area (31 bit) R14 = return address (31 bit) R15 = entrypoint address (31 bit)



UEXE Logging exit



called by the main control program after a log record has been set up. If the exit has been defined, it will be called even if standard logging has been turned off. The user exit will see 4 types of log record:

0 = open log (one call only) 1 = end of NAT session 2 = close log (one call only) 3 = snapshot record.

R01 = address of parameter list (1st parameter is the log record image as described in appendix C) R11 = address of GLOBMAP (31 bit) R13 = standard save area (31 bit) R14 = return address (31 bit) R15 = entrypoint address (31 bit)



UEXF One minute time interval exit

called by the main control program in its main wait loop after doing all required work (just before re-issuing a WAIT).

R11 = address of GLOBMAP (31 bit) R13 = standard save area (31 bit) R14 = return address (31 bit) R15 = entrypoint address (31 bit)


On return, R15 is not examined

Server Exits


UEXG Logon data conversion user exit

called by the main control program before examining and parsing the logon data (i.e. before deciding on which logical driver is to be used) - can change the data pointed to by TRM@LMSG field in TERMMAP DSECT.

R09 = address of TERMMAP (31 bit) R11 = address of GLOBMAP (31 bit)



R13 = standard save area (31 bit) R14 = return address (31 bit) R15 = entrypoint address (31 bit)



NATURAL Subtask Exits

These exits all have a numeric suffix in their name and are loaded once by the driver program at the time of initializing the NATURAL session. Each logical driver can define a different set of these user exits if needed. The areas LDUDATA and LDUSERW1 in LDMAP can be used by these exits, and also areas TRMUSR1/2/3/4 in TERMMAP. Reentrant coding techniques MUST be used.

UEX1 Session start security exit

called by the NATURAL driver just before calling NATURAL, after setting up the IOCB control block and before the terminal bind and logon data is freed.

R07 = address of N$MFB (NATIOMAP) (31 bit) R08 = address of LDMAP (31 bit) R09 = address of TERMMAP (31 bit) R11 = address of GLOBMAP (31 bit) R13 = standard save area (31 bit)| R14 = return address (31 bit) R15 = entrypoint address (31 bit)


On return, R15 is examined. If nonzero the session will abort.

UEX2 Session end exit

called by the NATURAL driver just after NATURAL returns.

R02, R03 = NATURAL's backend exit module (or garbage) R06 = NATURAL's return code R07 = address of N$MFB (NATIOMAP) (31 bit) R08 = address of LDMAP (31 bit) R09 = address of TERMMAP (31 bit) R11 = address of GLOBMAP (31 bit) R13 = standard save area (31 bit) R14 = return address (31 bit)



R15 = entrypoint address (31 bit)



UEX3 VTAM send exit

called by the NATURAL driver just before sending a screen

R01 = standard parameter list (31 bit) parm1 = send buffer (may be modified) parm2 = send buffer length word (may be modified) parm3 = send type word (0=conversational, 1= not) parm4 = 8 character terminal id

R07 = address of N$MFB (NATIOMAP) (31 bit) R08 = address of LDMAP (31 bit) R09 = address of TERMMAP (31 bit) R11 = address of GLOBMAP (31 bit) R12 = address of BB area (31 bit) R13 = standard save area (31 bit) R14 = return address (31 bit) R15 = entrypoint address (31 bit)



UEX4 VTAM receive exit

called by the NATURAL driver just before after receiving a screen from VTAM but before passing it to NATURAL

R01 = standard parameter list (31 bit) parm1 = receive buffer (may be modified) parm2 = receive buffer length word (may be modified) parm3 = 8 character terminal id

R07 = address of N$MFB (NATIOMAP) (31 bit) R08 = address of LDMAP (31 bit) R09 = address of TERMMAP (31 bit) R11 = address of GLOBMAP (31 bit) R12 = address of BB area (31 bit) R13 = standard save area (31 bit) R14 = return address (31 bit) R15 = entrypoint address (31 bit)





UEX5 Not used with NATURAL 2.3/3.1

UEX6 DB2 dynamic plan switch (security exit)

called by the NATURAL DB2SERV "front end" before opening a new DB2 application plan (DB2SERV called from user NAT program).

R01 = standard parameter list (31 bit) parm1 = DB2 subsystem id (user parm) parm2 = DB2 plan (user parm) parm3 = DB2 return code (user parm) parm4 = DB2 subsystem as used by this NIM job parm5 = NATURAL user's library parm6 = NATURAL user's program parm7 = NATURAL CMUSERID parm8 = terminal name

R07 = address of N$MFB (NATIOMAP) (31 bit) R09 = address of TERMMAP (31 bit) R11 = address of GLOBMAP (31 bit) R12 = address of BB area (31 bit) R13 = standard save area (31 bit) R14 = return address (31 bit) R15 = entrypoint address (31 bit)


On return, R15 is examined - if zero, the plan switch will happen but if R15 is non-zero the plan switch won't happen (the R15 value will be propagated to NATURAL).

UEX7 ESTAE user exit

called by the NATURAL driver ESTAE exit after an abend other than normal task detaching. Care must be used as this runs under a special MVS ESTAE environment, under which certain SVC calls are not advisable.

R06 = SDWA address from MVS R07 = address of N$MFB (NATIOMAP) (31 bit) R08 = address of LDMAP (31 bit) R09 = address of TERMMAP (31 bit) R11 = address of GLOBMAP (31 bit) R12 = address of BB area (31 bit) R13 = standard save area (31 bit) R14 = return address (31 bit)



R15 = entrypoint address (31 bit)


On return, R15 is examined. If non-zero the task will continue the abend process with no retry and no console message. If zero the default NIM ESTAE processing will continue.

NIM User Subtask

Attached by the main control program at start of job, after opening log and becoming ready to accept logons.

R01 = address of GLOBMAP (31 bit) R13 = standard save area (24 bit) R14 = return address (24 bit)

This subtask must periodically wait on ECB GBLUECB in GLOBMAP. When posted it must clean up promptly and post ECB GBLUECB1 in GLOBMAP and then wait indefinitely on a dummy ECB (the main task will detach it).

Modifying NIM Operational Defaults

To modify NIM operational defaults requires the modification and recompile of the NIM table of Contents. NIM has a macro, which is compiled to the Table of Contents module NIMTOC. The TOC is then read by NIM at startup to provide the standard NIM system default definitions. This allows the setting of site standard values for such things as the default SYSOUT class for online print files, the format of the response code fields for various utilities, default NIM system values (eg MEMTSTLO). For further information look at the N##TOC member in the general install JCL dataset.



Configuration

Configuring the NIM-Natural-Adabas-DB2 Interface

The heart of NATURAL contains no environment dependent code, so it needs environment dependent services from a "driver" in order to be able to write to terminals, obtain memory, and perform database calls.

Each instance of NATURAL (one instance per user) is controlled by parameters from 4 sources:

1. A NATURAL parameter module built by the DBA using the NTPARM macro;

2. Optional modules linked in with the parameter module;

3. Dynamic parameters supplied at the startup call for the user logon which supplement the parameter module;

4. An IO control block (IOCB) initialized by the "driver". This IOCB tells NATURAL what services are available from the supporting environment.

In the NIM environment, most of NATURAL's parameters are supplied directly, in the normal way. The IOCB parameters are mainly set up transparently by NIM. Certain NIM logical driver parameters will also relate to NATURAL parameters (see the sections "NIM Parameters" on page 11 and "Configuring the Natural Environment" on page 86).

In a TP monitor environment, such as NIM, the TP monitor provides an interface between NATURAL and the operating system. NIM is responsible for accepting LOGONs from terminals desiring a NATURAL session, then preparing appropriate parameters for NATURAL before transferring control to a NATURAL load module. Each terminal session goes its own way - the user interacting with NATURAL and NIM in the background providing services when NATURAL calls for them, and cleaning up when the session finishes.

The terminal user may provide some logon data at logon time - this is used to select a package of parameters that we call a "logical driver". Included in the logical driver package are details such as the name of a NIM driver module, the name of an ADABAS link module, and a set of NATURAL dynamic parameters.

Chapter

4



NATURAL's dynamic parameters are an important control because they can nominate the NATURAL parameter module to be used as base parameters for the session; in addition, they can selectively override the base parameters. NIM recognizes the essential nature of the dynamic parameters by allowing the dynamic parameters to include special text variables that may be allowed to default or which may be filled in according to extra fields in the terminal logon string.

Configuring NIM consists firstly of configuring NATURAL by assembling the parameter module, then linking it and other nucleus components together, then setting up 1 or more "logical driver" parameter definitions. For the ADABAS call interface, a reentrant ADALINK will have to be made available. For the DB2 call interface, we recommend that you re-link some DB2 service modules with a NIM "front end" which allows us to check on correct subsystem ids and monitor DB2 resource usage.

ADABAS Linkage – ADALNK Specification

For NATURAL to call ADABAS in a NIM environment, the only thing you have to do is to specify a standard ADABAS reentrant ADALNK module to NIM.

ADABAS calls are made by NIM on behalf of NATURAL. NATURAL passes a standard ADABAS parameter list (up to 6 buffers) to the TP monitor, with the ADABAS DBID specified in the 1st parameter (the CB). NIM then calls the standard ADABAS module to make the calls.

Because NIM multi-tasks its users, each ADABAS call must be made reentrantly. SAG have written their ADALNK module so that, as delivered, it is not reentrant. However, provision has been made for reentrancy by applying a standard zap, or by re-assembling after changing one line of code (at label NONRENT, as defined in the ADALNK source).

It is mandatory that this simple change be made before using ADALNK in a NIM environment. Having made the change, the only other thing to do is define the ADALNK module name to NIM using the "DRIVER xxxxxxxx ADALNK=yyyyyyyy" parameter (see the section NIM Parameters on page 11). Normally all NIM logical drivers would use the same ADALNK module, so it would be sensible to define it as "DEFAULT ADALNK=yyyyyyy" so that it need not be made explicit in DRIVER definitions.

When NIM calls the reentrant ADALNK defined to it, it generates a unique 8 byte ADABAS Userid for each user session. This user id is of the form 'DB2TP' followed by a 4 byte STCK based binary number. The user id is held in a UB block which is passed by NIM to ADALNK in a special "reentrant work area" pointed to by a 7th parameter required by the reentrant ADALNK. (NIM copies the NATURAL parameter list to a special 7 word parameter list to provide the 7th parameter.) If your installation needs to modify the ADABAS Userid, it could do it in NIM user exit 1 via the TRM@UB address contained in the TERMMAP DSECT (see source library). The TRM@UB address points to an area mapped by the UB DSECT (provided by SAG), containing the user id at UBUID.

SAG provides 2 user exits to ADALNK, namely user exits A and B. We recommend that these not be used, as they significantly add to the ADABAS call path length. However, these exits can be useful - they are documented in the ADALNK source, as well as in other SAG documents. For NIM purposes, it is important that these user exits be coded reentrantly.



Supporting the Basic NATURAL Environment

Using a Common NATURAL Nucleus

The NATURAL nucleus components should be linked together to form a common nucleus which can be shared by BATCH and NIM. Normally this nucleus module should be placed in the extended link pack area so that it will in fact be shared. Doing so will reduce system use of real memory and will cause the NATURAL nucleus to be write protected (a protection against accidental corruption).

When the NUCLEUS has been linked, the name of the nucleus module should be specified in the NIM logical driver parameter "NATNUC=" so that NIM will be able to dynamically load it.

The link of the nucleus modules is documented in the NATURAL operations manual and in JCL in the NATURAL installation tape. The INCLUDE modules will normally be NATSTUB, NATURAL, NATCONFG, NATTEXT, NATTXT2, NATPM, NATINPL, NATEDIT, NAT3270, NAT3279, NATTTY, NATBTCH. The entry point should be CMSTUB. The module name can be an arbitrary choice. The NATPARM module should be linked with this nucleus to act as a bootstrap for NATURAL initialization.

The result of the link as specified above will be a module with the attributes RENT, REUS, RMODE ANY, AMODE 31. It will be environmentally independent and will be eligible for the ELPA.

Using NATURAL Dynamic Parameters

NATURAL dynamic parameters must be defined for each NIM "logical driver" parameter package. The parameters are defined, typically, as follows:

"DRIVER xxxxxxxx DYNPARM=PARM=yyyyyyyy, SYS=zzzzzzz ,..."

In the above example, the dynamic parameter starts off with "PARM=xxxxxxxx" - this is mandatory where an independent nucleus is in use, and should be the first dynamic parameter (see the section "Using the NATURAL “PARM=” Parameter" on page 49 for more details). The "SYS=zzzzzzzz" dynamic parameter is optional but highly recommended, as it enables the DBA to predefine a small package of parameters (typically ESIZE, FSIZE, system file numbers etc) as a "profile" in a concise way. Other dynamic parameters can follow the PARM and SYS parameters, but with wisely chosen profile definitions there should normally be no need for any others.

The dynamic parameters from NIM can extend to 256 bytes (using 2 or more DYNPARM logical driver parameter records) if needed.

A NIM "logical driver" is a way of tailoring a set of NATURAL startup parameters for a whole CLASS of users who logon specifying a "logical driver" name denoting that parameter set. A further refinement can be provided in a NIM environment (if needed) by our "flexparm" system (see the section “Using NIM’s Flexparm Facility” on page 38) which enables each individual user to specify certain dynamic parameters at logon time. This is accomplished by defining a DYNPARM with a special ampersand variable - for example, "SYS=&S". Then if a user logs on with (say) "LOGON NIM DRIVER1,S=NAT001", and if DRIVER1 was the logical driver containing the dynparm with "SYS=&S", it will be expanded to "SYS=NAT001".



Using the NATURAL “PARM=” Parameter

When a common independent NATURAL nucleus is used, the NATURAL parameter module, and other environmentally dependent modules such as print and work file support and sort routines must be separately linked together and made available to NATURAL at run time.

The mechanism by which this module is made available to NATURAL is by the "PARM=" dynamic parameter discussed in the above section. When a NATURAL session is started up, the NATURAL nucleus first reads the dynamic parameters, then calls a NIM service module to dynamically load the "alternative parameter module" named in the "PARM=" parameter. NATURAL is able to find the print, work, and sort file routines from address constants set up by the linkage editor.

Typically, the link edit of the "alternate parameter module" would include your NATPARM module (as assembled using the NTPRM, NTSYS macros etc) as well as NATWKFO, NATSRINC, NATSRMOV, NATSRDUM. The module resulting from this link edit should have the attributes RENT, REUS and (for XA type systems) RMODE ANY, AMODE 31. The name can be chosen arbitrarily and should be specified in the "DYNPARM PARM=" logical driver parameter.

NATURAL Buffer Pools

As of NATURAL 2.2, the buffer pool mechanism is fully integrated into NATURAL and no NIM configuration is needed to accommodate the buffer pool (local or global).

If a Global buffer pool is used (NATURAL parms ADASVC and BPID set up), you should ensure that you start the buffer pool before starting NIM. MVS XA (and similar) should use a buffer pool located above the 16MB line by specifying XA in the NATGBPM startup parameters.

Note: The local buffer pool parameters BPSIZE and BPTEXT are only allowed to be specified statically in the NATPARM module (not dynamically). This is because the local buffer pool is shareable among many users in an address space and it would cause chaos if each user were able to redefine the existing buffer pool at logon time through dynamic parameters.

Supporting NATURAL Add-ons

This covers NATURAL add-ons include DB2, VSAM, SUPERNATURAL, TRS, etc. from Software AG plus certain 3rd party products.

Mostly these can be installed without worrying about the presence of NIM, by following the release documentation for the add-on product. For example, DB2 is quite a major addition, yet it can be set up without having to do anything special for NIM, however we now provide special support for DB2 (security and resource accounting) in order to enhance it. NATURAL VSAM is a similar case where we provide special support (dynamic file allocation an special operator commands) in order to enhance that environment too.



A "generic" add-on product requires no extra support from NIM. Most of the functionality of such products is built into NATURAL programs, which of course are not a problem. Quite frequently, the functionality is dependent also on some assembler routines which are recommended to be linked in with NATURAL (some CSTATIC, some not) or which are to be available to be loaded.

When linking in new modules, remember that we recommend you configure NATURAL in two parts:

1. an independent nucleus which is reentrant, RMODE ANY (if XA) and shareable;

And

2. an environment dependent part consisting of the NATURAL parameter module and associated modules which is reentrant, RMODE (ANY) and AMODE (31) (if XA).

The new routines should be linked in to the appropriate part. Any non-reentrant add-on routines can not be linked in but must be put in the steplib for dynamic loading.

NATURAL DB2 Support

Additional DB2 support from NIM is available in the form of a global parameter (SSID), a special user exit (UEX6) and 2 "front ends" to be linked with NATURAL DB2 components.

The parameter SSID is the DB2 subsystem id which is to be serviced by this NIM address space. It is a DB2 limitation that any address space can only be associated with at most 1 subsystem id.

The two NIM front ends are DB2SERV and NAT2REQI in the NIM load library. They REPLACE CSECTS of the same name in DB2 modules NAT2DB2E (the NATURAL DB2 interface) and DB2NUCF (the DB2 CAF interface). The real DB2SERV and NAT2REQI are linked in with entry points NAT2REQI changed to REALREQI, ACM2REQI changed to REALREQI and REALREQA in NATDB2E, and entry point DB2SERV changed to REALSERV in DB2NUCF. The above replacing and changing is all done using the link editor, using JCL along the lines of source member $ALDB2.

User exit 6 can be used, if needed, to act as a security exit validating dynamic plan switches.

With NIM and NATURAL DB2, the CAF (call attach facility) must be used - this is ideally suited to a multi-tasking DB2 environment.

NATURAL VSAM Support

There is no special NIM installation requirements, but features have been added to make life easier - files can be dynamically allocated at startup time according to parameters or can be freed or allocated by operator command. An operator command is also available to determine which terminals are currently using a nominated VSAM file. These features are useful when other systems must also use some of the VSAM files used by NATURAL.

See the section "File Parameters" on page 37 for definitions of the FILE DEFINE and FILE ALLOC parameters. See the section "File Related Commands" on page 65 for description of the ALLOC and DEALLOC operator commands and the section "File Status Commands" on page 69 for a description of the STATUS,FILE operator command, also see the SZERO global parameter.



Other Products

Treat other products according to their documentation and taking into account the observations in the introduction to the section "Supporting NATURAL Add-ons" on page 49.

Whenever a new product is installed with NATURAL, it is a good idea to examine the various NIMBLE utility displays (see the section "NIM On-line Services" on page 73), especially the ones concerned with memory and module usage, to see what effect use of the product has. It is also a good idea to conduct tests on concurrent use by 2 or more NATURAL users and to conduct load tests.

Online Print and Work Files

NATURAL has always been able to send output to printers and to read and write to work files in batch mode. With NIM, these same features are available in on-line mode.

In a multi-user environment it is not possible to use the "hard coded" printers and work files defined as CMPRTnn and CMWKFnn DD names in the job JCL, because this would make it hard for each user to use different work files and have different (personalized) printer definitions. NIM solves the problem by providing subroutines that can be called to dynamically allocate or free printer or work files and associate them with a NATURAL report number or work file number.

The CMPRTnn and CMWKFnn DD statements were required for Natural up to version 2.2.*. From 2.3 onwards with NIM 4.2.1 these definitions must be removed. If left in the NIM job they can mask errors with Online print/work files. If a call to allocate an online print file fails and the error is not detected a subsequent write to that print file will have the output go to the equivalent CMPRT xx definition and not to the dynamic print file as intended. When the CMPRTnn definitions are removed a write to an un-opened print file will produce a natural error 1520 which is easily identified and fixed.

The PRINTER=n and WORK=n NATURAL statements should be set to the maximum concurrent number of print/work files in use by any program. The value of n here should be no more than 10. Note that n bears no relation at all to the total number of open print/work files in a NIM job, nor to the total number of print files that can be written to by a single user. For example, even if PRINT=1 were to be specified to NATURAL, 100 users could each write to 20 different print files each - they would simply have to call the NIM dynamic allocate before writing each print file, and the NIM dynamic free after completing each print. NIM supports the full range of print/work file numbers 1 through 31

NIM V4.30 introduces consolidated Print/Work file management with the NIMDRPWM utility. This utility will replace the current four Print/Work file utilities (NIMTPALP, NIMTPALW, NIMTPFRP, NIMTPFRW for print file allocation, work file allocation, print file deallocation (free), work file deallocation (free) respectively which have been re-written to call NIMDRPWM internally.

Allocating Online Print Files This following example code fragments demonstrate:

(1) CALL 'NIMDRPWM' #ecode #f #dest #class #copies #for ms



where: #ecode entry code (A4 format) = ‘APRT’ #f file number (B1 format) #dest destination name (A8 format) = 'LASER7' #class SYSOUT class (A1 format) = 'Z' #copies Number of copies (B1 format) = 1 #forms forms code (A8 format) optional = 'PREPRINT9'

(2) Initiate a processing loop containing WRITE(1) or DISPLAY(1);

(3) After the processing is finished, CALL 'NIMDRPWM' #ecode #f

Where: #ecode entry code (A4 format) = ‘FPRT’ #f file number (B1 format)

Steps (1), (2), (3) could be in the same NATURAL program if desired, as long as step (1) is done before the dataset is opened and step (3) is done after it is closed. Note that the NATURAL statement CLOSE PRINT 1 will ensure that the file is closed. Alternatively, the 3 steps can be done in separate programs.

See the sections "Dynamic Print File Allocation Using " and "Dynamic Work File Allocation Using " below for more details.

Allocating Data Sets Online Suppose a user wishes to write to a workfile named 'ABC.WORK.DATA'. This would be a way to do it:

(1) CALL 'NIMDRPWM' #ecode #f #dsn #dd

where #f=1 (b1 format), #dsn= 'ABC.WORK.DATA' (a52 format), #dd is blank (a8 format).

(2) initiate a processing loop containing WRITE WORK FILE 1

(2) after the processing is finished, CALL 'NIMDRPWM' #ecode #f, where #f=1 (b1 format).

Steps (1), (2), (3) could be in the same NATURAL program if desired, as long as step (1) is done before the dataset is opened and step (3) is done after it is closed. Note that the NATURAL statement CLOSE WORK 1 will ensure that the file is closed. Alternatively, the 3 steps can be done in separate programs.

Dynamic Print File Allocation Using NIMDRPWM

NIMDRPWM is called to allocate a Print File from NATURAL with 5 parameters:

Parameter 1 the entry code ‘APRT’ in A4 format;



Parameter 2 the report number in B1 format, which may take a value in the range 1 through 10;

Parameter 3 the destination in A8 format, which must be a valid printer name which could appear in the DEST= parameter of a JCL DD statement;

Parameter 4 the sysout class in A1 format, which must be a appropriate value which would appear in a CLASS= parameter of a JCL DD statement;

Parameter 5 the number of report copies to be printed in B1 format which represents an appropriate value which could appear in a CLASS= parameter of a JCL DD statement.

Parameter 6 the FORMS code in an alpha 8 format, this would represent the parameter FORMS= in an equivalent JCL DD statement..

A successful call [to NIMDRWPM] will result in the file being dynamically allocated using the operating system SVC 99. It will not be opened. It will remain allocated until NIMDRPWM is called to free the file or the user session ends.

The NATURAL function RET('NIMDRPWM') should be zero if successful. Otherwise it will be the system SVC99 error code and a message will also appear on the NIM job log.

Dynamic Work File Allocation Using NIMDRPWM

NIMDRPWM is called to allocate a Work File from NATURAL with 4 parameters:

Parameter 1 the entry code ‘AWRK’ in A4 format;

Parameter 2 the work file number in B1 format, which may take a value in the range 1 through 31;

Parameter 3 the data set name in A52 format, which must be a valid dataset name in the first 44 bytes with optionally a member name in the last 8 bytes;

Parameter 4 an area where the DD name may be returned in an A8 format.

A successful call will result in the file being dynamically allocated using the operating system SVC 99. It will not be opened. It will remain allocated until NIMDRPWM is called to free the file or the user session ends. The DDname will be returned in the 3rd parameter, although this will usually not be of interest.


Dynamic Print/Work Free Using NIMDRPWM

NIMDRPWM is called to free a Print/Work file from NATURAL with 2 parameters:

Parameter 1 the entry code ‘FPRT’ (to free a Print File) or ‘FWRK’ (to free a Work File) in A4 format;

Parameter 2 the work file number in B1 format, which may take a value in the range 1 through 10 and must have been specified in a previous allocation call.



A successful call will result in the file being dynamically freed (after closing if necessary) using the operating system SVC 99.


3GL and Assembler Subroutine Support

This section details the requirements when calling subroutines directly from Natural using the "CALL" statement. There are a number of considerations when writing non-Natural routines, which are called from Natural under NIM, particularly if the languages used are COBOL II or PL/I.

Calling Subroutines

Calling a subroutine in a NIM environment is simple - just follow directions in the NATURAL reference manual (CALL statement) and ensure that the subroutine load module is either in the STEPLIB DD in the NIM job JCL or resides in a system linklist library.

Note that most computing chores can be handled by NATURAL. Only infrequently will there be a need to call external non-NATURAL subroutines, maybe for historical reasons or because of difficulty of converting a 3GL to NATURAL.

The TP Monitor is required to load, call and delete subroutines. In a multi-user environment it is necessary to be aware of subroutine characteristics, which may be "anti-social". Subroutine performance can be affected by the NIM parameter "PRELOAD" (see the section "NIM Parameters" on page 11) and by the NATURAL parameters "CSTATIC", "RCA", "CDYNAM" and "DELETE" (see the NATURAL operations manual).

A subroutine which, after linking, has the RMODE ANY and RENT attributes, which is relatively small (say <5K), which does not perform IO and which is written in assembler will never be a problem. If it is frequently called, it should be considered for inclusion as NIM PRELOAD or NATURAL CSTATIC or RCA should be used to reduce the number of program loads. If all subroutines are in this "nice" category, then the NATURAL parameter DELETE=OFF could be specified in order to keep active modules in storage. The NIM NATURAL utility suite can be used to check on loaded modules if necessary (see the section NIM'S NATURAL BASED COMPONENTS & TOOLS on page 73).

Beware of seemingly "nice" subroutines which, although small in themselves, dynamically acquire large amounts of memory for work areas (especially if this memory is below the 16MB line). It is the DBA’s responsibility to ensure that all 3GL subroutines behave correctly – in particular they must not allocate memory in SUBPOOL zero particularly below the line. An informal standard for 3GL subroutines called in NIM is that below the line memory is allocated in SUBPOOL 24, above the line memory in SUBPOOL 31.

The NIM NATURAL utility suite can be used to watch the effect on memory use as a NATURAL program calling a suspect subroutine is executed on another terminal (see the section NIM'S NATURAL BASED COMPONENTS & TOOLS on page 73). A poorly written assembler subroutine can fail to free memory - this will wastefully remain in the NIM address space until NIM automatically releases it at the end of the terminal user's session. Note that if the SZERO=Y NIM GLOBAL parameter is in use (not normally the case), then unfreed memory can remain even after the end of the terminal user's session.



Subroutine Parameter Lists and AMODE

NATURAL generates a standard assembler parameter list and also a special parameter descriptor list. If a subroutine has the AMODE 24 attribute, then it will not be able to address parameters which are built above the 16MB line by NATURAL. NIM solves this problem by detecting the AMODE 24 and then copying the parameters below the 16MB line before transferring control to the subroutine and finally copying them back after the subroutine finishes.

This process is based on NATURAL's parameter descriptor list and is normally transparent. Under some circumstances there may be problems if a called subroutine "assumes" something about the existence of "de facto" parameters which are related to the proper parameters by an offset - this is bad programming practice and the subroutine should be rewritten to make all parameters explicit and to remove dependencies on NATURAL's internal layout.

Subroutines Which Load Below 16MB

Subroutines, which do not have RMODE ANY, should not be linked with the NATURAL nucleus in an MVS XA type environment because this would force the RMODE of the resultant module to become 24, even though NATURAL itself had RMODE ANY.

It is preferable for a large load module such as NATURAL to have RMODE ANY so it can be loaded above the line and so it is eligible for placement in the system extended link pack area (ELPA). Virtual memory below 16MB is more precious than memory above 16MB because there is less of it, therefore you should try to ensure that large subroutines can run with RMODE ANY.

Most assembler programs that do not perform IO can be easily converted to RMODE ANY.

Non-Reentrant Subroutines

Subroutines which are non-reentrant must NEVER be linked with the NATURAL (i.e. never specified in the CSTATIC list). It is perfectly alright for non-reentrant modules to be dynamically loaded, but be aware that no sharing can be done - each terminal user needs a private copy and this may be wasteful. It is pointless and wasteful to PRELOAD a non reentrant subroutine.

A reentrant module is one which can be concurrently executed by multiple users without any "time window" where shared resources can be corrupted. Normally a reentrant module will not write to its own code area (although this is actually permissible if some form of queuing or locking is in use) - a module in the link pack area or in an authorized library should never write to its own code area, it should be STRICTLY reentrant.

Compilers using the appropriate RENT option will always generate strictly reentrant code modules. However, assembler programs are written by human beings and can be marked reentrant although they are not. Even the RENT checking option in the assembler will not ensure that the code is in fact reentrant. Therefore, use caution when using assembler subroutines.



Subroutines Imported from Other Environments

Subroutines developed to run called from NATURAL but in another environment will need to be examined for environmental dependencies before using them in a NIM environment. Subroutines designed to work in batch will work under NIM, subroutines designed to run under TSO will usually work, subroutines designed to run under CICS will usually not work because of the non-standard CICS register conventions and prolog and epilog code (subroutines designed to run as CSTATIC under CICS can often work under NIM, because such subroutines are called by NATURAL, rather than the CICS driver, and so use standard entry conventions - under NIM they can be called as CSTATIC or dynamically if needed).

Conversely, subroutines written to be called under a NIM environment will work fine in a TSO or batch environment. The only exceptions are the NIM specific utilities distributed as part of the official NIM system - these reference NIM internal structures.

Subroutines Which Call ADABAS

It is probably a good idea to call ADABAS exclusively from NATURAL directly. A subroutine, which calls ADABAS, would normally be linked with ADAUSER - this has 2 side effects:

(1) many modules are loaded (ADARUN, ADALNK, ADAIOR etc)

and

(2) the ADABAS calls are seen by ADABAS as being unrelated to the calls made in the parent NATURAL session (i.e. they generate a separate UQE, and ETs or BTs issued in the parent session have no effect on any updates issued by the subroutine).

If it is unavoidable to call ADABAS from a subroutine, you should consider linking your subroutine with the NIM replacement for ADAUSER - NIMADA. NIMADA will ensure that in a NIM environment the ADABAS call is made using the same NIM mechanism as is used by the parent NATURAL session.

Note that the subroutine making direct calls must ensure that the correct DBID is placed in the ADABAS CB. You can also use such subroutines in a batch environment too, as NIMADA will dynamically load ADARUN etc. if it detects that a NIM environment is not present. To ensure that the same ADABAS session is used as the parent NATURAL in batch, the DBA could make the "reusable ADARUN" available to the batch job - this is the module ADARUNR which must be renamed ADARUN (see ADABAS documentation). When running under NIM, you do NOT need ADARUN cards, because the call is made by the TP monitor using the reentrant ADALNK, not ADARUN.

If possible, avoid doing ADABAS IO from subroutine.

Subroutines Written in the PL1 Language

Please see the comments in the NATURAL reference manual (CALL statement), plus the PL1 manuals (Assembler calling PL1). Keep PL1 subroutines simple and monitor the performance of new PL1 subroutines. Avoid using timer, sub task and abend recovery PL1 services if possible.

Subroutines Written in the COBOL 2 Language

COBOL 2, like PL1, sets up its own environment when called. Unless everything is correctly set up as outlined below, very large overheads can be involved.



The "COB pack" should be built by your system programmer so as to exclude modules with RMODE 24 - by default; COBOL 2 includes these modules even though it is a silly default. If your installation has many COBOL 2 applications, the COB pack should be in the system ELPA. The COB pack comprises IGZCPCO and IGZCPAC, which should both be RMODE ANY after the COB pack, has been rebuilt correctly. The rebuild procedure is detailed in "VS COBOL 2 Installation and Customization" from IBM.

COBOL module IGZCTCO should be re-linked into the NIM steplib with attribute changed to NORENT. This module is the thread control module, and the purpose of relinking a special version for NIM NATURAL callers is to ensure that each user has a private thread control module so as not to clash with other users. This re-linking procedure is mandatory for NIM if COBOL 2 subroutines are used. If the COBOL 2 libraries are included in the steplib concatenation, obviously they should be behind the library containing the re-linked IGZCTCO, so that the re-linked version will be used instead of the standard version.

All COBOL 2 subroutines should be compiled with the RENT, RES options. This has the side effect that code and data can be above the 16MB line. If you link the COBOL with something else, make sure that this link does not force the result to lose the reentrancy or RMODE attributes which the COBOL had before the link.

Keep your COBOL subroutines reasonably simple and always use the GOBACK statement in preference to the STOP RUN to terminate the subroutine. Working storage values do not need to be explicitly initialized by the subroutine because a reusable run time environment is NOT being used. (See IBM documentation of IGZERRE if you want a reusable run time environment!).

The COBOL 2 modules IGZCPCO, IGZCPAC, IGZEPSU, IGZEINI, IGZEPCL should be preloaded to the NIM session (see the section "NIM Parameters", PRELOAD on page 16). If the above modules are not preloaded, the COBOL subroutines will take longer to execute because of the multiple loads which have to be done at the start of most calls to set up the COBOL 2 environment.

Subroutines Which Access NIM Control Blocks

NIM internal control blocks can be referenced via a register interface (for dynamically loaded subroutines) or by the TCB first save area (for other subroutines). In particular, R9 addresses TERMMAP. A TERMMAP pointer is also contained at 8 bytes negative offset from NATURAL's IOCB. This how the NIMBLE functions are done. We recommend that you DO NOT try to access or modify NIM control blocks - they are subject to change without notice. Accessing NIM internals makes a subroutine non portable and may compromise system integrity.

Special Considerations for FUJITSU Operating Systems

3GL FUJITSU compilers generate reentrant code using PSECTs. A PSECT is a loadable module containing initialized data. Under NATURAL, each call is done by a BALR to a loaded module - a BALR (unlike a LINK) does not generate a new PSECT for each call. This means that a NATURAL program which makes several calls to the one subroutine will be using modified working storage at each successive call - the PSECT (and hence working storage) will only be refreshed when the NATURAL nucleus re-loads the module (i.e. at the start of any NATURAL program using that subroutine).



This can be an advantage or a nuisance - if it is a nuisance, then the problem can be avoided by having the 3GL subroutine explicitly refresh its working storage where needed at the start of its execution.

Batch Job Submission

Batch job submission is handled under NIM exactly as documented in the NATURAL utilities manual. There are no NIM parameters that affect job submission.

If your site is using RACF, and is not using NIM user exit 1, the jobs will be submitted with the RACF profile of the NIM job, therefore it is important to set the profile appropriately. If user exit 1 is in use, then you have the option of setting RACF profiles on a user basis, for more control over job submission - this is done in the exit by issuing a RACINIT macro and retaining the ACEE in a special task related subpool (see the section "Server Exits


UEXG Logon data conversion user exit

called by the main control program before examining and parsing the logon data (i.e. before deciding on which logical driver is to be used) - can change the data pointed to by TRM@LMSG field in TERMMAP DSECT.

R09 = address of TERMMAP (31 bit) R11 = address of GLOBMAP (31 bit) R13 = standard save area (31 bit) R14 = return address (31 bit) R15 = entrypoint address (31 bit)



NATURAL Subtask Exits" on page 41).

Job submission under NIM was formally done by calling a special subroutine. Job submission has now been integrated into the NATURAL system and is done by calling a "pseudo subroutine", NATRJE. The calls to this "pseudo" subroutine are diverted by NATURAL to a special service routine in NIM.



Although existing job submission subroutine(s) will still work, we recommend changing to the standard NATURAL method. However, if you had a special job submission routine that happened to be called NATRJE, you should be aware that it would never be called by NATURAL 2.3. If it happens that the parameters accepted by your NATRJE are the same as the new integrated RJE, then all will be well, unless your NATRJE does (say) extra checking on the JCL, e.g. for security reasons.


Console Operator Interface

The NIM console operator interface allows the console operator or an automated operations package to monitor and control basic NIM operations. The operator interface cannot provide all of the sophisticated monitoring and control facilities of the full screen NIMBLE interface. It is intended to provide the basic facilities required for address space control, such as stopping, quiescing, status summary, message sending, user cancellation and file control.

Operator Commands

Operator commands are entered using the standard MVS operator MODIFY and POST commands, using the name of the NIM job or started task as the first operand and the command body as the second operand. The examples below assume that the NIM job or started task has a job name of "NIMPROD".

The NIM address space accepts one operator command at a time. Processing of the previous command must be completed before a further command can be entered. Readiness to accept another command is signaled by the message:

NIMPROD 100I Waiting for command

The NIM operator commands are classified into the following groups:

termination commands immediate termination, setting and unsetting of the quiesce state;

user cancellation commands cancel a specific user based on terminal id or UserID, or all users of a specific file;

message related commands send a message to a specific user or all users send a broadcast or logon message, list or cancel the current logon message;

file related commands allocate or de-allocate all defined operating system files, or those with a specific filename prefix;

status display commands display system status summary, all users with a specific terminal id or UserID prefix or just specific users, in summary and detail, display file status for all files or files with a specific filename prefix;

miscellaneous commands load and unload modules, set the usermax, set the global transfer VTAM application.

Chapter

5


References in the following command descriptions to "terminal ID" refer to a VTAM secondary LU name in session with the NIM VTAM application. The terminal ID will typically represent a physical device, connected via a communications network to the host mainframe. However, when multiple VTAM session manager software is being used, the "terminal ID" is actually just a secondary LU defined and supported by a VTAM application. Further, when LAN gateways and 3270 emulators are used to connect users to mainframe sessions, the "terminal ID" field often starts to have little physical meaning, and becomes a poor identifier of a session.

The "UserID" field referred to in the following command descriptions can also be slightly difficult to interpret, as is possible for a single session to be associated with two userids:

a logon UserID, probably verified against an external security package such as RACF or ACF2, and retained in a NIM control block;

a NATURAL security UserID, probably initially set from the above "external" UserID, but possible changed since.

By appropriate use of the NIM NATURAL subtask user exit 1 and the NATURAL parameter "AUTO=ON", the NATURAL UserID can be forced to remain the same as the external UserID. Additionally, if the NATURAL UserID is changed, the NIM external UserID can be kept in synchronization by the NATSET utility (refer to the "NIM utility programs" chapter). Commands that specify UserID matching will always check both of the above fields, and match on either.

All lower case alphabetic characters in the operating system command string are converted into upper case by the NIM operator interface before the command is interpreted.

Termination Commands

The NIM address space can be stopped in at least 4 ways:

operating system cancellation:

CANCEL NIMPROD

Canceling the NIM address space will probably result in some NIM log data from completed sessions being lost, as the data in the NIM log dataset QSAM buffer will not be flushed, and sessions in progress will not be logged.

immediately with an operating system POST command:

P NIMPROD

Sessions in progress will be cancelled, all log data will be written.

immediately with a MODIFY command:

F NIMPROD,STOP

C O N S O L E O P E R A T O R I N T E R F A C E


The F ...,STOP command is treated internally by NIM as being identical with the P ... command - sessions in progress will be cancelled, all log data will be written.

when all users have logged off (i.e., set a quiesce mode):

F NIMPROD,QUIESCE

New logon attempts are rejected, and when all current users have completed their sessions (either logging off normally of their own accord or being cancelled or timed out), the NIM address space shuts down.

If the QUIESCE state is to be revoked (i.e., logons are to be accepted and NIM is not to shut down when all users have logged off), the UNQUIESCE command can be entered:

F NIMPROD,UNQUIESCE

To force the NIM to shutdown immediately whilst it is in the QUIESCE state, issue the STOP command:

F NIMPROD,STOP

User Cancellation Commands

Specific users can be cancelled if either their terminal id or UserID is known.

To cancel users based on their terminal ID, use the command syntax:

F <jobname>,CANCEL,TID=<terminal id>

E.g.:

F NIMPROD,CANCEL,TID=P2FLVY7V

To cancel users based on their user id, use the command syntax:

F <jobname>,CANCEL,UID=<user id>

E.g.:

F NIMPROD,CANCEL,UID=DBAINST


Operations staff in a NATURAL-VSAM environment may need to de-allocate NATURAL-VSAM files from the NIM address space, so that another address space may have exclusive update access to those files. The DEALLOC command (discussed below) can only succeed in de-allocating the required file(s) if the file(s) are not open (i.e., "in use") by any users. The NIMBLE interface allows for the identification of all users of a file and the sending of messages, and optional cancellation. The operator interface allows the operator to find out how many users of the file and to cancel all users of the file.

To cancel users of a specific file, use the command syntax:

F <jobname>,CANCEL,FILE=<file name>

F NIMPROD,CANCEL,FILE=GLMAST

The DEALLOC command can then be used to dynamically de-allocate the file from the NIM address space.

Message Related Commands

The operator interface allows the sending of single line messages (up to 80 characters) to a single user or all users and allows the listing, deleting and set up of the logon message. The NIMBLE full screen NATURAL interface supports a flexible and interactive full function message control system.

To send a message to a single user based on their terminal ID, the command syntax is:

F <jobname>,MSG,TID=<terminal id>,<message>

E.g.:

F NIMPROD,MSG,TID=P2FLVY7V,Please ring ext 253 now.

To send a message to a single user based on their UserID, use the command syntax:

F <jobname>,MSG,UID=<userid>,<message>

E.g.:

F NIMPROD,MSG,UID=DBAINST, We can't find your tape

To send a broadcast message to all users currently logged on, use the command syntax:

F <jobname>,MSG,NOW,<message>

E.g.:



F NIMPROD,MSG,NOW, Please evacuate the building now .

To send a broadcast message to all users currently logged on, and retain the message so that new users will get the message when they logon, use the command syntax:

F <jobname>,MSG,SAVE,<message>

E.g.:

F NIMPROD,MSG,SAVE, Do not forget Friday is a holid ay!

To send a broadcast message to all users currently logged on, and retain the message so that new users will get the message when they logon, use the command syntax:

F <jobname>,MSG,SAVE,<message>

E.g.:

F NIMPROD,MSG,SAVE, Do not forget Friday is a holid ay!

To list the current logon ("Greeting") message, use the command syntax:

F <jobname>,MSG,LIST

E.g.:

F NIMPROD,MSG,LIST

To delete the current logon ("Greeting") message, use the command syntax:

F <jobname>,MSG,DELETE

E.g.:

F NIMPROD,MSG,DELETE

File Related Commands

The operator interface allows operating system files defined to the NIM address space (using the NIM PARMS "FILE" parameter and the NIMBLE interface) to be dynamically allocated and de-allocated from the NIM address space. Either all files, a single file, or files with a specific filename prefix can be allocated or de-allocated. This function would normally only be used at sites using NATURAL-VSAM.


To allocate all files, use the command syntax:

F <jobname>,ALLOC

E.g.:

F<N> NIMPROD,ALLOC

This command will report to the console and log on files that are already allocated, files that have been allocated by this command, and files that could not be allocated with the dynamic allocation error code.

To allocate just a specific file, or all files with a common filename prefix, use the command syntax:

F <jobname>,ALLOC,FILE=<filename prefix>

E.g.:

F NIMPROD,ALLOC,FILE=GLMAST

As with the simple ALLOC command, actions resulting from this command are reported to the console and log.

To de-allocate all files, use the command syntax:

F <jobname>,DEALLOC

E.g.:

F NIMPROD,DEALLOC

This command will report to the console and log on files that are already de-allocated, files that have been de-allocated by this command, and files that could not be de-allocated with the dynamic deallocation error code.

Files currently in use by one or more users cannot be de-allocated. First, they must be closed, by either the user exiting the part of their application system that uses the file, logging off or being cancelled. The NIMBLE interface contains facilities to identify and send messages to and/or cancel users using an operating system file. The operator interface "CANCEL,FILE=" command described above allows the console operator to cancel all users of a file, and hence make it eligible for deallocation.

To de-allocate just a specific file, or all files with a common filename prefix, use the command syntax:



F <jobname>,DEALLOC,FILE=<filename prefix>

E.g.:

F NIMPROD,DEALLOC,FILE=GLMAST

As with the simple DELLOC command, actions resulting from this command are reported to the console and log.

Status Display Commands

The operator interface supports summary displays of NIM address space, user and file status. As the amount of potential information to be display on each entity is very large, and the number of entities (especially users) is potentially very large, only a small amount of vital information can be displayed in the limited operator interface context. Complete display facilities are provided by the NIMBLE interactive full screen interface.

The Status Display commands are classified into the following subgroups:

address space status;

user status;

file status.

Address Space Status Commands

To display address space summary information, use the command syntax:

F <jobname>,STATUS

E.g.:

F NIMPROD,STATUS

This command will report to the console and log the current address space status, showing:

- number of current users - global usermax> - current status - VTAM application name - default driver - number of completed sessions - accumulated session statistics: - CPU seconds - VTAM writes - ADABAS calls - DB2 calls


Refer to the descriptions for NIM messages 164, 165, 166 and 167 for details of the address space summary report.

An alternative form of the address space status command displays some address space control flags and addresses in a hexadecimal format, and is only used by NIM support staff during problem investigation:

F <jobname>,STATUS,DUMP

User Status Commands

The NIM user status commands allow summary data to be displayed for a single user, a group of users with a common terminal ID or UserID prefix, or all users.

To display user data for a single UserID, use the command syntax:

F <jobname>,STATUS,UID=<userid>

E.g.:

F NIMPROD,STATUS,UID=DBAINST

To display user data for a group of users with a common UserID prefix use the following command syntax:

F <jobname>,STATUS,UID=<userid prefix>

E.g.:

F NIMPROD,STATUS,UID=DBA

To display user data for a single terminal Id, use the command syntax:

F <jobname>,STATUS,TID=<terminal ID>

E.g.:

F NIMPROD,STATUS,TID=P2FLV7V

To display user data for a group of users with a common terminal ID prefix use the following command syntax:

F <jobname>,STATUS,TID=<terminal ID prefix>

E.g.:



F NIMPROD,STATUS,TID=P2FL

To display all users, enter either of the STATUS,UID or STATUS,TID commands, omitting the UserID or terminal ID:

F NIMPROD,STATUS,TID=

or

F NIMPROD,STATUS,TID=

Both UserID and terminal ID driven displays produce a report to the console and log showing, for each user:

- terminal ID - UserID - current status - database calls - VTAM writes - CPU time - non activity time

Refer to the description for NIM message 175 for details of the user status report.

An alternative form of the user status command displays some additional user data, including flags and addresses in a hexadecimal format, and is only used by NIM support staff during problem investigation:

F <jobname>,STATUS,DUMPU=<userid>

F <jobname>,STATUS,DUMPT=<terminal ID>

File Status Commands

The NIM file status command displays the count of NATURAL sessions using a specific operating system file defined to NIM by using the NIM PARM "FILE" record or the NIMBLE interface. To display the number of users with a specific file open, use the command syntax:

F <jobname>,STATUS,FILE=<filename>

E.g.:

F NIMPROD,STATUS,FILE=GLMAST1

Refer to the description for NIM message 181 for details of the file status report.


Miscellaneous Commands

Setting the Global Usermax

The global usermax parameter determines the total number of concurrent users that may be logged on to the NIM address space. To set the usermax, use the command syntax :

F <jobname>,USERMAX=<usermax>

E.g.:

F NIMPROD,USERMAX=10

The usermax must be in the range 0 to 1000 inclusive. Refer to the "NIM Parameters" Chapter for details on the use of the global usermax parameter.

Setting the NIM VTAM-server Global Transfer VTAM Application

The NIM VTAM-server global transfer VTAM application name specifies the VTAM application to which intending users will be transferred if for some reason they cannot be accommodated in the current NIM VTAM-server address space, and transfer VTAM applications have not been specified at the logical driver level. To set the transfer VTAM application use the command syntax :

F <jobname>,XFER=<transfer VTAM application name>

E.g.:

F NIMPROD,XFER=NIMPROD2

Refer to the "NIM Parameters" Chapter for details on the use of the NIM VTAM-server global VTAM transfer parameter.

Loading and Unloading Operating System Load Modules

Load modules invoked by NIM as user exits or from NATURAL as subroutines can be preloaded and unloaded from the NIM address space by operator commands. Only reentrant load modules should be preloaded.

To load a module into memory, use the command syntax:

F <jobname>,LOAD=<load module name>

E.g.:

F NIMPROD,LOAD=DATECNV1



If the load module is already in memory, its usage count (maintained by operating system) the will be increased by one.

To delete a load module from memory, use the command syntax:

F <jobname>,UNLOAD=<load module name>

E.g.:

F NIMPROD,UNLOAD=DATECNV1

If the load module has been loaded by a NATURAL subtask, its usage count will be reduced by one, but the module will not be immediately deleted (the NIMBLE Job Pack Queue display can be used to determine the usage count for any load module).

Refer to the NIM Parameters Chapter for details on the use of the PRELOAD parameter


NIM'S NATURAL BASED COMPONENTS & TOOLS

NIM is distributed with a NATURAL INPL format sequential dataset containing 2 NATURAL application sub-systems:

"NIMBLE", a monitoring and control suite, typically used by DBA, systems and operations staff to monitor the address space and users and dynamically change operating parameters, cancel users, send messages, etc

"NIMOS", a suite of programs providing many of the functions typically used by programmers to interact with the operating system. Facilities available include allocating, deleting, editing, browsing, copying and printing of normal operating system sequential and partitioned datasets, listing the system catalog, job submission, printing NATURAL objects, etc

The installation of either or both of these suites is entirely optional. However, the monitoring and control facilities of NIMBLE and the access to common OS functions provided by NIMOS greatly enhance the ease of use and flexibility of the NIM-NATURAL environment. The installation of NIMBLE and NIMOS is described in the section "Installing the NIM Natural Objects" on page 97, and their use is described in sections "NIM On-line Services" on page 73 and "NIM On-line Services/NIMOS" on page 75.

Additionally, NIM is distributed with 2 assembler routines that may be called from NATURAL to set and return various NIM and NATURAL control information (NATSET and NATGET). The facilities offered by these routines are described in the section "NIM ON-line Services/Utility Programs" on page 77.

As distributed, both NIMBLE and NIMOS will operate completely correctly only in the NIM environment. To verify installation of NIMBLE, logon to NIM VTAM application, and then execute the NATURAL logon to the NATUAL application library containing the NIMBLE suite (by default, NIMV4) and execute the startup program, "MENU". The startup program for the NIMOS function is "OSMENU". The NIMBLE and NIMOS main menus contain options that transfer control between the two suites.

NIM On-line Services/NIMBLE

All objects in the NIM On-line Services/NIMBLE suite start with the prefix "NIM" with the exception of the startup program named "MENU" and the error transaction program named "ERROR-TA".

Chapter

6

N I M L U 6 . 2 S E R V I C E S


The MENU program simply sets ZD=OFF and fetches the NIMBLE main menu program, NIM0. Sub-functions are implemented by programs named "NIM" suffixed by the NIM0 menu command code - e.g., the "Users" function is implemented by program "NIMU" and its subprograms, maps, and help routines, all of which start with "NIMU".

Security Issues

Access to the NIMBLE suite would normally be restricted to DBA, systems, communications and operator users. End users and application programmers would normally not be allowed full access to NIMBLE, as the intentional or accidental misuse of some NIMBLE functions could inconvenience users or compromise security or site standards (by, for example, defining a logical driver with site non-standard dynamic parameters).

Users (Option ‘U’ in Menu)

The user display screen gives a summary display of all users currently in the same address space as the NIMBLE user. The display is scrollable both vertically and horizontally. If needed, a set of mask values can be entered on the bottom line of the screen in order to limit the display to user entries of particular interest (e.g. terminal id containing 'L01', user id containing 'DBA', response time greater than 5 etc).

A user entry can be picked for cancellation or as a target for a message or for an expanded display or to add to a selection list. (the selection list will be remembered across screens and can be used later in the message sending screen to send a message to all selected users).

Logical Drivers (Option ‘L’ in Menu)

The driver display screen gives a summary display of all logical drivers defined in the same address space as the NIMBLE user. The display is scrollable vertically only.

A driver entry can be picked for cancellation or for expanded display or for modification. A modified logical driver will take effect immediately but will only be effective until the NIM job is stopped. When the job is restarted you should modify the job parameter file to make a lasting change.

The expanded details displayed for a driver reflect nearly all the possible parameters which can be set in the PARM DD.

A new logical driver can be created using PF2. The parameter settings will be initialized to be the same as the driver entry most recently examined, and can be adjusted as needed.

Files (Option ‘F’ in Menu)

The file display screen gives a summary display of all files defined in the same address space as the NIMBLE user. The display is scrollable vertically only. Note that it does not included allocated print and work files but only those files defined by startup parameter or operator action (typically VSAM files).

A file entry can be picked for display of users currently holding that file or it can be freed (if no users on it), or allocated. A freed file can be cancelled (i.e. removed from the definition list) or a new file can be defined.

Address Space Summary (Option ‘S’ in Menu)

This screen gives a summary of setting applicable to the job as a whole, plus the user count and the memory in use.



PF2 will access a menu enabling some of the settings to be changed on the fly. PF9 will show a pop up display of accumulated resource usage totals for completed NATURAL sessions.

Messages (Option ‘M’ in Menu)

This option brings up a sub menu with options to modify or remove the logon greeting message or to compose and send a message to either all users or a set of users.

Messages are 5 lines long at most. The greeting message is entirely distinct from any message sent to logged on users.

The criteria for defining a set of users to receive a message are quite flexible - from a list, from a previous selection done in the user display, for users with a particular user id or on a particular logical driver or NATURAL library or terminal.

Utilities (Option ‘T’ in Menu)

The utilities option brings up a sub menu for functions which display data relating to the operating system which is either an important NIM resource or useful to the DBA.

Loaded modules for the job can be displayed, enabling the DBA to check on usage and attributes of NATURAL components and subroutines.

Memory usage can be displayed, categorized as below or above the line, with indication of the available memory and limits applying to the job. This is followed by a scrollable display of memory used by task (terminal).

Particular memory areas can be located, searched and displayed in dump format with a zap option. Comprehensive help is available for this function. Note that each display screen comprises 256 bytes which must all be addressable.

All jobs in the machine can be displayed, giving various total and sampled resource consumption figures for each job. The display can be reduced by specifying a job mask or job categories (TSO, ordinary job, started task, initiator). It can be a useful tool to follow the progress of important batch jobs or see which job is hogging the CPU etc. Active jobs are displayed intensified.

A console display is available in certain environments.

A switch to OSMENU (see below) is available from this menu.

NIM On-line Services/NIMOS

All objects in the NIM On-line Services/NIMOS suite start with the prefix "OS". The startup program is "OSMENU".

Sub functions are implemented by programs named "OS" suffixed by the OSMENU menu command code - e.g., the "Dataset Manipulation" function is implemented by program "OSD" and its subprograms, maps, and help routines, all of which start with "OSD".

Security Issues

The NIMOS programs allow users to define, access, update, delete and copy operating system sequential and partitioned datasets.



Most sites will want to carefully restrict operations on general datasets by all users. Tools such as RACF and ACF2 are commonly used to define and enforce access rules. By defining the appropriate logon procedures, sites can ensure that user's RACF (or ACF2) security profiles are in effect when they access datasets using the NIMOS facilities, and hence that access is in accordance with site standards. The same logon procedures will ensure that general on-line access to datasets through NATURAL work files also complies with site standards.

Refer to the section "Security Considerations" on page 7 for full details.

Use of the NATURAL System (FUSER) File

Each user of the OS functionality suite needs a permanent profile (similar to TSO/ISPF) to provide user-friendly defaults. Each user also needs a semi-permanent work area in which to hold a copy of the OS member or dataset currently being viewed or modified. The FUSER system file is used for these purposes.

User profiles are stored as "programs" with program name taken from *init-user and library name = **NIMPRO.

Work areas are created when needed as "programs" with program name taken from *init-id and library name = current library name. Only one of these work areas will exist for a given terminal at one time - old work areas will be re-used. The work area is necessary because the NATURAL editor is used to edit OS datasets and members.

The NIM modules use 'SAGDA-SYSTEM' as the DDM - modified to have DBID=0,FNR=255 which specifies the FUSER system file, regardless of its actual number (see the section "INPL Dataset Details" on page 98 for more detail on this).

User Profiles (Option ‘P’ in OSmenu)

The profile represents defaults and will be stored as specified for the next time the user logs on. The default options may change during the course of a session, but these changes will not be remembered past the session end unless this option is again chosen.

The defaults cover dataset naming and printer selection (DEST and SYSOUT CLASS) plus an "empty line insertion character". The latter is a character that acts as a place for lines intended to be blank in the OS dataset - it is needed because the NATURAL editor suppresses blank lines.

Editing and Browsing Datasets (Option ‘E’ in OSmenu)

On selecting this menu, you are presented with screens looking and acting very much like ISPF 1 or 2 screens. Members can be selected from these screens or datasets can be selected.

Upon selection, the OS data is read (using NIM work file subroutines) and copied into the work area in the FUSER file, and the user is thrown into a NATURAL editor session against this "pseudo program" object.

After editing and/or browsing the data, the user quits the edit session and is picked up by another NIM stacked program which allows the user to save the data back onto MVS, replacing the existing data, or alternatively to do submit the data as a batch job or to simply exit without save/submit.



Listing the Catalog (Option ‘L’ in OSmenu)

This selection activates a pop up window that asks for a catalog prefix (e.g. the project and group part of a filename, omitting the type). This causes a scrollable display to appear containing all files with this prefix. The user can select one and be thrown into an edit/browse selection screen.

Data Manipulation (Option ‘D’ in OSmenu)

This option has a submenu with options to allocate a new dataset, delete an old one, copy datasets (or members), and perform library manipulation.

The new allocation screen acts a little like ISPF 3.2 option, allowing the user to fill in RECFM, SPACE and other allocation details.

The copy screen acts very much like ISPF 3.3 option.

The library screen acts very much like ISPF 3.1 option. It allows the user to delete rename or print members or to submit them as batch JCL.

NATURAL Print/Work File Allocation (Option ‘N’ in OSmenu)

This options allows you to allocate a printer or work file associate it with a NATURAL printer number or work file number. It also allows you to free such printers/files.

This can be useful if you have user written programs which use printers and work files but do not allocate them (e.g. a typical batch type program) - by "bracketing" the execution of such a program with appropriate allocate and free functions from this menu, the user program can be made to operate on a chosen printer or work file.

Utilities (Option ‘U’ in OSmenu)

This option allows you to print a NATURAL program or range of programs on an OS printer.

NIM ON-line Services/Utility Programs

NATGET and NATSET Subroutines

These subroutines are callable from NATURAL and allow various NATURAL and NIM control fields to be inspected (NATGET) or modified (NATSET). This facility should be used with caution.

NATGET is called as follows from NATURAL:

CALL 'NATGET' 'xxxxxxxx' #DATA-AREA

where 'xxxxxxxx' is a function code (it can be a variable rather than a literal if desired) and #DATA-AREA is a field large enough to hold the data returned with NATGET. A 3rd parameter, a 1 byte response code, can be provided (for backward compatibility only) but should not normally be used, as the RET('NATGET') NATURAL function will suffice.

The binary return code word from the RET function will have the hex value of X'000000F0' if the function worked and data has been returned.



The allowable function codes and the corresponding data returned are listed below:

Code Corresponding data returned

SYSDFNR 5 system file numbers in use (system, user, predict, security, spool), each 2 bytes binary.

DBID 1 byte ADABAS DBID of system file (BCMFNR).

NIMAPPL 8 byte NIM VTAM name (i.e. the LOGON application id).

GETAPPL as above.

NIMVER 8 byte alphanumeric string representing the version of NIM under which the call is made.

NIMUDATA 16 byte user exit area contents (TERMUSR1)

NIMTERM 8 byte VTAM terminal name used by caller.

GETTERM as above.

NIMPRT 8 byte VTAM printer name which will be used as default in this user session (TERMPRT).

GETPRT as above

GETPRINT as above

ABEND 8 byte abend code last trapped (TPABCDE).

SYSOUT 1 byte SYSOUT class for screen print (TSYSOUT).

PRINTPF 5 byte PF key name for screen print (NONE,CLEAR, PF1-PF24, PA1-3).

PRTPF as above

NATSET Operations

NATSET is called as follows from NATURAL:

CALL 'NATSET' 'xxxxxxxx' #DATA-AREA

where 'xxxxxxxx' is a function code (it can be a variable rather than a literal if desired) and #DATA-AREA is a field large enough to hold the data provided for NATSET. A 3rd parameter, a 1 byte response code, can be provided (for backward compatibility only) but should not normally be used, as the RET('NATSET') NATURAL function will suffice.

The binary return code word from the RET function will have the hex value of X'000000F0' if the function worked and data has been returned.



The allowable function codes and the corresponding data provided are listed below:

Code Corresponding data provided by caller

NIMUID 8 byte UserID to be set up in NATURAL's CMUSERID area (*init-user) and NIM's TERMUID area.

INITUSER as above.

SYSPSWD 8 byte NATURAL system password to go into NATURAL's BCMPSW area.

SYSCIPH 8 byte NATURAL system cipher code to go into NATURAL's BCMCIP area.

NIMPRT 8 byte VTAM printer name which will be used as default in this user session (TERMPRT).

SETPRT as above.

SETPRINT as above.

DIVERT 1 byte binary main printer number (BCMPRT).

COPYUSER dummy data only, USRID field in BB is copied to *init-user (CMUSERID) and NIM user id (TERMUID).

STARTPNO dummy data only, start rerouting terminal data to printer (no page throws included).

STARTP dummy data only, start rerouting terminal data to printer (page throws included).

STOPP dummy data only, stop rerouting terminal data to printer.

SYSDFNR 10 byte string containing 5 system file numbers (dbid+fnr) in the same format as returned by NASTGET 'SYSDFNR' for replacement in BCMFNR (and UFNR1), BCMFNRU, FNRDICT, FNRSEC, FNRSPL.

AUTOPRT dummy data, set x'80' bit on in TERMUSR1 (obsolete).

NAUTOPRT dummy data, set x'80' bit off in TERMUSR1 (obsolete).

TIMEOUT 2 byte binary data representing a number of minutes which will be allowed to elapse before a user is timed out if 'enter' is not pressed in the interval.

NIMUDATA 16 bytes of data (for user exits) which is placed at location TERMUSR1.

PASS 144 bytes of formatted data which is used to set up an automatic logon to another VTAM application when the current NATURAL session ends. The 1st 8 bytes are the VTAM application name, the 2nd 8 bytes are the



Code Corresponding data provided by caller

terminal LOGMODE to use (blank for default), and the last 128 bytes are logon data padded with blanks. A recursive logon is not allowed. A blank VTAM application will cancel any existing PASS specification.

SYSOUT 1 byte SYSOUT class for screen print (TSYSOUT). PRINTPF -5 byte PF key name for screen print (NONE,CLEAR, PF1-PF24, PA1-3).

PRTPF as above.

NIMTPHCP Subroutine

This subroutine is callable from NATURAL and defines the destination of any printed output produced by the NATURAL %H command (hardcopy). NIMTPHCP must be called before using %H (to allocate the hardcopy environment) and after completing all %H operations (to de-allocate the hardcopy environment).

NIMTPHCP is called as follows from NATURAL:

CALL 'NIMTPHCP' #TYPE #DEST #UCS #FCB #WRITER

where #TYPE is mandatory and if 'A' for allocate or 'D' for the de-allocate function. If #TYPE is 'D', no more parameters are needed, however, if #TYPE is 'A' then #DEST is a mandatory parameter and #UCS, #FCB and #WRITER are optional.

#DEST is the destination, i.e. printer name (JCL: DEST=).

#UCS, #FCB, #WRITER correspond to JCL UCS, FCB and WRITER parameters respectively - most times these will be omitted.

The return code word from the RET function will have the hex value of X'00000000' if the function worked.

81

INSTALLATION

This chapter contains the information required to perform a basic installation of NIM. Depending on site requirements, the result of this process may well be all the work needed to define and run NIM in a production environment. However, for sites requiring advanced facilities and customization, the basic installation will serve to define fundamental operating principles and form the basis for further configuration. The topics to be covered in this chapter is:

the contents of this release;

Uploading the release datasets;

defining a test NIM VTAM application;

configuring the NATURAL environment, including options for the establishment of a NATURAL nucleus and parameter module;

assembling and linking modules, such as the NIM driver and user exits;

providing the ADABAS call interface (the reentrant ADALNKR);

setting up the NIM logical driver environments;

setting up NIM parameters;

creating and running JCL to execute NIM;

verifying the accuracy of the installation.

Despite this long list of topics, the installation of NIM is quite simple. An experienced DBA can usually complete a trial installation in just a few hours. No IPL is required, and no NIM components need to reside in an authorized library. However, assistance from Systems or Communications staff is usually required to define and activate a test VTAM application name.

Chapter

8

I N S T A L L A T I O N


Release Contents

NIM is now distributed ONLY in an electronic format. It consists of a single compressed [zipped] File. NIM System code is now distributed in Load Module format - only. The actual contents will vary between the MVS & the MSP releases. The release when unzipped will contain the following components. Readme.txt An ASCII text file detailing last minute information of

value to the installer about this release; NM440Release_Notes The Release Notes in Word or PDF format. NM440_Manual The User Manual in Word or PDF format. NM440_Upload_Images Examples of various mainframe components after upload

and before / after decompression. In Word format. NM440N NIM Online Services formerly the Nimble application in

ASCII / SYSTRANS format. MVS only NM440L The NIM system Load modules.

The format is EBCDIC compressed. NM440G A general file containing source, JCL, Macros and user exit

examples. The format is EBCDIC compressed.

MSP only NM440LF The NIM system load modules.

The format is EBCDIC compressed.

NM440GF A general file containing source, JCL, Macros and user exit examples. The format is EBCDIC compressed.

NM440DEC Sample Job to Allocate datasets, transfer the binary modules

and decompress the datasets on the mainframe.



Uploading the Release Datasets

Using Winzip (or equivalent software) extract all members of the distribution to an empty folder.

MVS & MSP installations.

NM440N – NIM Online Services [the Nimble application].

Pre-allocate a mainframe target dataset e.g. HLQ.NIM440.NIMBLE with attributes

DSORG=PS, RECFM=VB, LRECL=4624,BLKSIZE=4628.

Space required is approx 1 megabyte.

Upload to the mainframe as file type ASCII.

The file that has been uploaded to the mainframe should then be loaded into Natural using a job based on the supplied $SYSTRNL member in the “G” or “GF” dataset.

MVS Installations Only

NM440G – The General Dataset.

Pre-allocate a mainframe target dataset e.g. HLQ.NIM440.CNTL.CMPRESD with attributes :

RECFM=FB, LRECL=80, BLKSIZE=3120. Space required is 300 Kilobytes.

Upload this file as type BINARY.

Logon to TSO and go to Native mode…..[usually option 6]

Type the command “RECEIVE INDSN(‘use the dataset name from the previous step’) when prompted press ENTER. When prompted the following additional parameters may be supplied to name and position the decompressed dataset

DATASET(‘HLQ.NIM440.CNTL’) NEW VOL(xxxxxx)

This will extract approx 30 members into a standard partition data set.

NM440L – The NIM System Module load library.

Pre-allocate a mainframe target dataset like HLQ.NIM440.LOAD.CMPRESD with attributes :

RECFM=FB, LRECL=80, BLKSIZE=3120. Space required is 400 Kilobytes.

Upload this file as type BINARY.



Logon to TSO and go to Native mode…..[usually option 6]

Type the command “RECEIVE INDSN(‘use the dataset name from the previous step’) when prompted press ENTER

.or supply extra parameters like :

DATASET(‘HLQ.NIM440.LOAD’) NEW VOL (xxxxxx)

This will extract approx 175 load modules .

MSP Installations Only

General Note

A sample job { NM440DEC } has been supplied as part of this release. The job will delete/re-allocate datasets ; perform batch FTP file transfers from the pc to the Host and finally decompress the 2 uploaded files. It is not import whether the delete step and file transfer steps are followed however it is CRITICAL that the allocate step is followed exactly to ensure successful creation of datasets which will decompress correctly. If the datasets are allocated manually although all steps may show return code = 00 the process will not complete correctly. This process is required for the load library and the sample jcl and macro files which are supplied in a compressed format..

NM440GF – The source/jcl library.

This component must be uploaded as binary and decompressed with sample job NM440DEC

NM440LF – The NIM system code load modules.

This component must be uploaded as binary and decompressed with sample job NM440DEC



Defining a NIM VTAM-server Application

NIM VTAM-server operates as a VTAM application, to accept logon requests from terminals, to establish sessions and at the end of the session, to relinquish control of the terminal. Optionally, NIM VTAM-server may pass a logon request from one NIM VTAM-server application to another (refer to XFER and USERMAX parameters, in the section "NIM Parameters" on page 11), or, to pass a terminal onto another VTAM application automatically at the end of the session (refer to the "PASS" function of the NATSET program, section "NATGET and NATSET Subroutines" on page 77).

Before NIM VTAM-server can operate as a VTAM application, it must be defined to VTAM. The definition process is very simple, and involves specifying a VTAM application name and any special functions that the application should be able to perform. The specification is typically made in a member of the VTAMLST dataset (often named SYS1.VTAMLST), that must be activated before being usable.

The easiest method of testing NIM VTAM-server is to create a new member of the VTAMLST dataset, containing merely the definition of the test NIM VTAM-server application, saving the member and then issuing a VTAM operator command to activate the application ("V NET,ACT,ID=" command).

It is not necessary to IPL the computer, or stop and start VTAM to define and activate the NIM application.

The installation systems or communications programmer should always be asked to perform the definition and activation process, and to advise on how the NIM VTAM-server application definition can be incorporated into the installation's standard application nodeset, which is automatically activated when VTAM starts.

A typical VTAM application definition for NIM is:

NIMTEST APPL AUTH=PASS,ACBNAME=NIMTEST

This specification will define a VTAM application known as "NIMTEST". The actual name of the VTAM application is not significant, except that:

the name chosen must also be used in the NIM GLOBAL APPL parameter, (refer to the section "NIM Parameters" on page 11), which defines to NIM what NIM VTAM-server application name it should use;

the name chosen must also be used in the VTAM logon string used to request connection of a terminal to NIM, e.g.:

LOGON NIMTEST



In summary, to define a NIM VTAM-server application name, work with your systems or communications programmer to:

1. Create the application definition in the VTAMLST dataset;

2. Activate the new application definition with the "V NET,ACT,ID=..." operator command.

Configuring the Natural Environment

NIM's function is to provide "teleprocessing" ("TP") support for NATURAL. NIM prepares an execution environment for NATURAL before invoking the NATURAL nucleus, and then provides support services to NATURAL, such as terminal I/O and operating system interactions (obtaining and releasing virtual memory, recovering from errors, monitoring CPU time, submitting batch jobs, etc).

The relationship between NIM and NATURAL is necessarily very close - both components must be able to invoke routines in the other.

This section assumes that NATURAL 2.2 or higher has been installed, and that a NATURAL 2.2+ environment independent nucleus has been linked, and that a NATURAL parameter module suitable for TP mode execution (such as would be used under TSO) has been assembled.

The environment independent nucleus should normally be placed in the extended link pack area (ELPA), but this is not a requirement. If the environment independent nucleus is not in the ELPA or LPA, NIM must be able to load it at run time from the NIM job STEPLIB. The name of the environment independent nucleus is defined to NIM with the logical driver "NATNUC=" parameter.

Note that this NUCLEUS should have a default NATPARM module included for "boot" purposes - it will normally only be needed to process the dynamic parameters which tell NATURAL where the "real" NATPARM is (see below) and does not need any special settings - it is essentially a "dummy". This dummy NATPARM can be set to the ‘real’ production NATPARM for convenience.

In the NIM environment, the environment dependent module should consist of the NATURAL parameter modules (created by assembling and linking the site's NATURAL parameters), the NATURAL work file module and the NATURAL internal sort modules.

A special version of the NATURAL work file module used to be required to be zapped before it would work correctly under NIM – this is NO longer the case. There is no zap for print & work file support required by NIM 440 from Natural 2.3 onwards.

The name of the NATURAL environment dependent module is defined to the NATURAL nucleus by the NATURAL "PARM=" parameter, which is supplied to NATURAL as part of the NIM logical driver "DYNPARM=" parameter.



As an example, assume that the name of the environment independent NATURAL nucleus is "NAT31LPA" and that the name of the environment dependent module containing the linkage of the NATURAL parameters, zapped work file and sort support modules is "NATPARME". To invoke NAT31LPA with the NATPARME module, the dynamic parameter string would include the specification:

PARM = NATPARME

Assume that a NIM logical driver named NATTEST is being constructed to invoke this environment. Included in the logical driver definitions would be:

DRIVER NATTEST PDRIVER=NIM31NAT DRIVER NATTEST EPTNAME=NIM31EPT DRIVER NATTEST NATNUC=NAT31LPA DRIVER NATTEST DYNPARM=PARM=NATPARME, DRIVER NATTEST DYNPARM=<other dynamic parms >

In the above example, the NIM NATURAL environment is split into 3 separate modules:

the NATURAL environment independent component (here named "NAT31LPA");

the NATURAL environment dependent component (here named "NATPARME");

the NIM-NATURAL interface (the physical driver, distributed as the module "NIM31NAT").

The “EPTNAME“ parameter specifies the NIM NATURAL entry point table name associated with the specified “physical driver”.

Other configuration possibilities exist, but are not recommended.

Link all NATURAL components together - in the above example, this would involve linking together NAT31LPA and NATPARME into a module with an arbitrary name, say "BIGNAT", with an entry point of CMSTUB. The NIM logical driver parameters to invoke this environment would still specify a "NATNUC=" parameter, but the "PARM=" value would not appear in the NATURAL dynamic parameter:

DRIVER NATTEST PDRIVER=NIM31NAT DRIVER NATTEST NATNUC=BIGNAT DRIVER NATTEST DYNPARM=<other dynamic parameters>

This approach is recommended because:

the creation of separate NATURAL environment dependent and independent modules is advocated in the NATURAL installation notes;

the environment independent nucleus can be shared by all NATURAL using address spaces (TSO, batch, NIM, ...);



any of the 3 components can be replaced independently of the others (e.g., CSTATIC modules could be added to the NATURAL environment dependent component without requiring changes to the NIM NATURAL interface or the environment independent component).

Creating the NIM Natural Environment

To create the NATURAL environment for NIM execution, follow these steps: Create the NATURAL environment independent nucleus.

Follow the steps outlined in the NATURAL installation notes.

This step has probably already been completed as part of NATURAL 2installation. The nucleus may or may not be added to the LPA or ELPA (adding it to the ELPA is strongly recommended, as it provides protection against corruption and allows this relatively large module to be shared by many address spaces, promoting efficient use of real storage).

1. Create the NATURAL environment dependent module. This step involves the following sub-steps:

a) Define, assemble and link NATURAL parameters for on-line use

A NATPARM module may have already been constructed for TSO, which will be quite suitable for NIM use;

Refer to the NATURAL Operations Manual for details on the process of defining, assembling and linking a NATPARM module.

b) Link together the environment dependent components:

the NATURAL parameter ("NATPARM") module created in step 3.1;

the zapped NATURAL work and print file support module created in step 2 (NATWKFO);

the internal NATURAL sort modules (NATSRINC, NATSRMOV, NATSRDUM);

any CSTATIC modules defined in the NATPARM module;

The sample job in member $LNKNAT2 from the NIM distribution SOURCE dataset provides an example of this substep.



This module may or may not be added to the LPA/ELPA in an IBM OS390 or z/OS environment it may have RMODE(ANY) but in an MSP/EX environment it will have a residency mode of 24 (RMODE=24), and so must not be added to the ELPA. Adding to the LPA/ELPA has the advantage of protection against corruption, and being able to be shared by multiple address spaces. However, the disadvantage is that an IPL is required to replaced the module in LPA/ELPA. Additionally, the advantages of sharing across address spaces are not that great, as it will only usually be sharable by 1 or 2 NIM address spaces, and the module is not very large anyway unless many large CSTATIC modules have been included.

Providing the ADABAS Interface

NIM invokes an external module to issue ADABAS calls. The name of this module must be defined at the logical driver level with the "ADALNK=" parameter. The ADALNK module should be reentrant so that a single copy can be shared between all users. The standard ADALNK module currently distributed by Software AG (member ADALNK in the ADABAS distribution source library) is not reentrant, but is easily made reentrant by following the very simple procedure described in the ADALNK routine for making it reentrant (FIND the string "NONRENT" and follow the instructions).

If the ADALNK user exit B and/or user exit A facilities of ADALNK are being used (e.g., by the APAS/INSIGHT performance monitor), then the reentrant version of ADALNK should be linked with the user exit(s) and placed into a library included in the NIM job STEPLIB. Be sure to follow the instructions of the monitor supplier for this procedure, such as the setting of the LNUINFO field within the ADALNK module. The name of this module must be defined to NIM with the logical driver "ADALNK=" parameter.

As an alternative to reassembling the ADALNK module to make it reentrant, copy the current non-reentrant ADALNK load module (using the linkage editor is safest) and zap the copied module with the "reentrant making" zap, as described in the ADALNK source. If this is done, make sure that the module has the RENT, REUSE attributes so that the loader will "know" that it is reentrant and will only allow one copy to be loaded into memory. One way to change the attributes of a load module is to use the PDS or PDSMAN third party utility.

It is preferable that the reentrant ADALNK module be linked with RMODE=ANY, however you should check that your ADALNK exits A and B (if used) function properly. The ADABAS SVC should have been configured properly to be able to handle buffers above the 16MB line - this will usually be the case.

Introduction to Logical Drivers

One of more Logical Drivers must be defined in each NIM address space. A logical driver is a collection of parameters and names of load modules that defines an execution environment for a class of service.

By default, up to 40 logical drivers can be defined in a single NIM address space. However, typically only a small number of logical drivers would be defined (say, less than 5). At least one logical driver must always be defined.



The purpose of logical drivers is to provide different execution environments for different types of users, or to meet different execution requirements for various application environments. They allow the DBA to easily optimize performance and resource usage and meet varying levels of service delivery requirements.

The DBA must define the logical drivers required to meet site performance and service objectives. The user selects a logical driver when logging on to NIM, by specifying the logical driver name as part of the logon string, e.g.:

LOGON NIMTEST,DEV

The above logon string requests a logon to VTAM application NIMTEST with

logon data of "DEV". The NIM logon data can contain a logical driver name

and "FLEXPARMs" (refer to the section "NIM Asynchronous Session

Parameters

Session parameters are used to define additional parameters for the management of ATP sessions. The parameter is defined in the following format:

SESSION <SESSNAME> <PARM> <=><VALUE>

The PARM has the following values:

DRIVER <drivername> SERVER=ATP, defines this session with logical drivername to be an ATP session.

DYNP Optional, dynamic Natural pseudo-logon parameters

USERID Userid for security logon. Optional pseudo logon parameter.

PASSWORD Password for Userid. Optional pseudo-logon parameter.

Examples:

SESSION ASYNGEN DRIVER ATPS0001 SESSION ASYNGEN DYNP=<dynamic Natural parameters> SESSION ASYNGEN USERID=<userid> SESSION ASYNGEN PASSWORD=<password>

Using NIM’s FLEXPARM Facility" on page 38). The above string contains just a logical driver name: "DEV". If no logical driver name is specified, or the logical driver name has not been defined to NIM, then the default logical driver (also defined by the DBA) is used.



Many sites customize the logon screen received by users, often providing a menu, in which a simple selection generates a logon string not seen by the user. Such systems are easily used to generate logon strings to NIM VTAM-server applications, including the logical driver and other parameters (the "FLEXPARMs"), giving the site the ability to automate the logon and session initialization.

The name of the logical driver in use by a NATURAL session is made available to NATURAL programs by the *INIT-PROGRAM system variable. The address space control program user exit C and the task startup user exit 1 can enforce site specified access to logical drivers before the NATURAL session is initiated (refer to the section "NIM User Exits" on page 39).

The types of settings that are defined at the logical driver level include:

relative execution priorities;

a logical driver can be defined to receive execution priority above or below other logical drivers. The frequency of priority review and the reduction of priority for "CPU intensive" users can also be defined at the logical driver level, allowing the DBA complete flexibility to set execution priorities to meet site standards and ensure that higher priority applications can meet service objectives defined by the site;

NATURAL environment;

the names of the NATURAL environment independent and dependent modules can be specified at the logical driver level, as are dynamic parameters passed to NATURAL at NATURAL session initialization. The dynamic parameters can be further tailored with information passed through the VTAM logon string by the use of the NIM "flexparm" facility;

timeout interval;

the amount of non-activity time before the session is cancelled;

diagnostic and trace information;

ADABAS linkage module;

various flags and limits.

Setting up NIM Parameters

During initialization, the NIM address space control program reads a dataset describing the operating parameters to be used. The parameters describe "global" attributes of the address space (such as the NIM VTAM-server application name to be used), logical driver definitions and file definitions for datasets to be controlled by NIM (usually only applicable to NATURAL-VSAM users).



Most of the global and all of the file and logical driver parameters can be modified by authorized users of the NIMBLE NATURAL application. Changes made via NIMBLE will remain for the life of the NIM address space, or until changed again using NIMBLE (i.e., changes made using NIMBLE will not effect subsequent executions of NIM, as such changes do not update the dataset containing NIM parameters read during initialization).

The NIM parameters are described in details in the section "NIM Parameters" on page 11. This section describes the parameters in general terms, sufficient to modify the sample parameters distributed in member $PARMS of the SOURCE dataset to meet site requirements.

The NIM parameters are read by NIM from the //PARM DD file. All 80 columns of each record are parsed. Any record beginning with an asterisk ("*") in column 1 is treated as a comment, and ignored.



Changing the Sample Test Parameters

Edit the $PARMS member of the distribution SOURCE dataset, and follow these steps:

Step 1: Review the value of the GLOBAL APPL= parameter.

This parameter must be set to the name of the NIM VTAM-server application defined to VTAM as described in the section "Defining a NIM VTAM-server Application" on page 85.

Step 2: Review the value of the MESSAGE1, MESSAGE2, MESSAGE5 parameters.

As distributed, these parameter settings will cause a logon message of 2 lines (MESSAGE1 and MESSAGE2), 2 blank lines (MESSAGE3 and MESSAGE4 have been omitted) and another message line (MESSAGE5) to be sent to the terminal after session establishment but before the first screen sent from NATURAL. To remove any logon message, delete these parameters. Alternatively, change the message, or add MESSAGE3 and MESSAGE4 parameters.

Step 3: Review the value of the logical driver PDRIVER= and EPTNAME parameters.

If the NATURAL environment is established as suggested in the section, "Configuring the Natural Environment" on page 86, the value of the PDRIVER parameter will be the distributed NIM NATURAL driver module, NIM22NAT and the EPTNAME parameter will be NIM22EPT. However, if the NIM and NATURAL components have been linked together, then this parameter must be set to the name of the resulting load module (and the NATNUC parameter must be removed and the PARM= setting of the DYNPARM parameter must be removed).

Step 4: Review the value of the logical driver NATNUC= parameter.

If the NATURAL environment is established as suggested above, the value of this parameter will be the name of the NATURAL environment independent nucleus, which may or may not reside in the ELPA.

Step 5: Review the value of the logical driver DYNPARM= parameter.

If the NATURAL environment is established as suggested above, the value of this parameter will include the PARM= specification which will identify the name of the NATURAL environment dependent parameter module. This specification may be suffixed by an arbitrary NATURAL dynamic parameter string, e.g.:

",ESIZE=32", "STACK=HELLO, MT=3,MADIO=5000",... etc

Step 6: Review the value of the logical driver ADALNK= parameter.

The value of this parameter must identify a reentrant ADALNK module, as



discussed in the section "Providing the ADABAS Interface" on page 89.

Step 7: Save the edited member.

Creating JCL to Execute NIM

The NIM address space can be run as either a started task or as a batch job. This section describes the JCL statements making up a typical NIM address space in the context of a batch job. However, translation to a started task procedure is simple.

JCL Component – the EXEC card

The basic EXEC card to run NIM is very simple:

// EXEC PGM=NIMTPCP

To this basic EXEC card can be added:

a jobstep name, e.g. //NIM EXEC PGM=NIMTPCP.

The jobstep name is ignored by NIM.

Site related accounting information such as REGION and TIME, e.g.:

//NIM EXEC PGM=NIMTPCP,REGION=64M,TIME=1439

NIM Version 4 does not accept any parameters from the EXEC PARM= construct.

JCL Components – the STEPLIB

The STEPLIB will usually point to one or more PDS's containing:

mandatory

the distribution NIM library, from which are loaded the components of the NIM software Note that with the exception of the NIMADA module, all NIM components are candidates for the ELPA or LPA. If they are placed in the ELPA or the LPA then the STEPLIB must not contain these modules, as the STEPLIB is searched before the link pack areas.

optional, but likely

a load library containing one or more components of NATURAL software. Unless both the environment independent and dependent components of the NATURAL environment have been placed in the ELPA and LPA, these modules must be available to be loaded from the STEPLIB.

If one of both of these modules has been placed in ELPA/LPA, then ensure that they DON’T appear in any STEPLIB datasets.



optional, but likely a load library containing the reentrant ADALNK module. Unless this module has been placed in the ELPA or LPA, it must be available to be loaded from the STEPLIB.

optional, but likely a load library containing local 3GL and assembler routines called from NATURAL but not included in CSTATIC, or in ELPA/LPA.

NIM does not require any STEPLIB at all - it will be quite happy to "find" all required modules in the link pack areas. Similarly, it is completely oblivious to the division of modules amongst the STEPLIB datasets - e.g., all modules could be in just one PDS.

The following general observations about concatenating STEPLIBs and the use of STEPLIBs in long running jobs should be understood:

when concatenating libraries of different blocksize, put the library with the largest blocksize first, or use the DCB=BLOCKSIZE override on the first dataset in the STEPLIB list to specify a blocksize at least equal to the largest blocksize of any concatenated library.

inclusion of many libraries in the STEPLIB can reduce performance, especially when many modules are loaded from libraries well down the concatenation. Consider consolidating libraries, removing unnecessary libraries and pre-loading commonly used modules (refer to the GLOBAL PRELOAD= parameter on page 16).

ensure that the number of disk extents occupied by libraries does not increase whilst the NIM job is running. The operating system builds a map of the extents occupied by datasets when the dataset is allocated and opened. If a STEPLIB dataset gains a new extent whilst the NIM job is running, attempts to load a module from the new extent will fail with a system abend code S106.

JCL Components – the DD Definitions

The DD statements appearing in the NIM JCL are:

PARM contains the NIM parameters read at initialization time.

DCB=(RECFM=F or FB,LRECL=80,DSORG=PS)

NIMTPLOG can be defined as SYSIN defines the sequential dataset to which NIM log records are written.

DCB=(RECFM=F or FB ,LRECL=160,DSORG=PS)

DB2TPTRA can be defined as SYSOUT defines the sequential dataset to which NIM VTAM trace data is written:



DCB=(RECFM=F or FB,LRECL=120,DSORG=PS)<R> OR can be defined as SYSOUT

CMPRTxx defines the dummy file "place markers" which force NATURAL to recognize the availability of print file support. set xx to 01 through 10, depending on the number of on-line print files required. each file defined slightly increases the below-the-line memory requirements of each user NATURAL sub-task, so only define place markers for files that will be used. Should normally be defined as //CMPRT01 DD DUMMY

CMWKFxx defines the dummy file "place markers" which forces NATURAL to recognize the availability of work file support set xx to 01 through 10, depending on the number of on-line work files required. each file defined slightly increases the below-the-line memory requirements of each user NATURAL sub-task, so only define place markers for files that will be used. Should normally be defined as //CMWKF01 DD DUMMY

SYSABEND the space allocation should be minimal defines a sequential dataset to receive abend dumps produced during NIM operation generally defined as a SYSOUT file

Running the Job

Complete the job card with job card parameters meeting site standards, and submit the job.

If the VTAM application has been correctly defined and activated, the NIM address space control program should write the following messages to the console and job log:

422I NIMTPAUT: NIM Subspace Creation in progress +NIM 001I Initialization in progress, Ver:V5.0 .0 Zaplev:000a +NIMCCA1 438I GblSubsp is at 0A900000 +NIMCCA1 400I Initializing Server : VTAM-Server +NIMCCA1 100I Waiting for command +NIMCCA1 003I Accepting logons with VTAM applname NIMTEST +NIMCCA1 401I Initialization complete: VTAM-server +NIMCCA1 400I Initializing Server : ATP-Server +NIMCCA1 401I Initialization complete: ATP-server



The "NIMTEST" literal will be changed to the VTAM application name being used to run NIM. The version ("Ver") and zap level ("Zaplev") fields will display the current version and zap levels of the software. The new message 422I indicates NIM is creating the internal sub-spaces required for it to protects its own internal control blocks.

The NIM job may be stopped by canceling the job, from the NIMBLE online monitor or by an operator command. To stop the job by operator command, ask the console operator to enter the operator command:

P <NIM job name>

e.g.. P DBANIMT

In response to this command, the following messages should be written to the console and job log:

NIMTEST 103I STOP COMMAND RECEIVED NIMTEST 005I Termination in progress NIMTEST 006I Termination complete - NORMAL END

Installing the NIM Natural Objects

NIM is distributed with a NATURAL INPL format sequential dataset containing two NATURAL application sub-systems:

NIM On-line Services/NIMBLE - a monitoring and control suite, typically used by DBA, systems and operations staff to monitor the address space and users and dynamically change operating parameters, cancel users, send messages, etc

NIMUTILS – online examples and interface subprograms. This library when loaded into a separate library from the NIMBLE application will provide many example test programs for both the DBA and programmers.

NIM On-line Services/NIMOS - a suite of programs providing many of the functions typically used by programmers to interact with the operating system. Facilities available include allocating, deleting, editing, browsing, copying and printing of normal operating system sequential and partitioned datasets, listing the system catalog, job submission, printing NATURAL objects, etc.

The installation of either or both of these suites is entirely optional. However, the monitoring and control facilities of NIMBLE and the access to common OS functions provided by NIMOS greatly enhance the ease of use and flexibility of the NIM-NATURAL environment.



INPL Dataset Details

The NIM NATURAL INPL datasets contains source and object for the NIMBLE and NIMUTILS application suites.

Both NIMBLE and NIMUTILS applications will, by default, be loaded into two separate NATURAL libraries named "NIMBLE" and “NIMUTILS”. Site security and operation procedures will dictate what types of users have access to which functions. Typically, access to full NIMBLE functions would be heavily restricted, as many functions could disable the entire NIM address space if misused. However, some NIMBLE functions (such as message sending) may be incorporated into application systems for use by end-users. Access to the NIMUTILS suite will similarly be determined by site standards as it contains both example programs, interface programs (API) to lower level NIM routines and test programs for the DBA to prove the NIM installation.. This issue is discussed later.

All programs except one are written in NATURAL 3.1 structured mode. The exception is the program "MENU", which uses the reporting mode SET GLOBALS statement to set the ZD parameter to "OFF" (this is required, as some NIMBLE programs can perform a "divide by zero" and a result of zero is required).

Using “NATLOAD” to load the INPL Dataset

The standard NATURAL 3 NATLOAD program should be used to copy the INPL dataset objects into the database FUSER file, and the DDM into the database FDIC file.

Follow these steps:

a) If NATURAL SECURITY is used at your site, define the application "NIMV4" to NATURAL SECURITY with a startup program name "MENU". Protect the application to allow access according to site requirements. For convenience, it may be useful to have this library initially empty.

b) Run a special NIM job which has a //CMWKF01 DD statement in the JCL pointing to the NATUNLD dataset which you copied from the NIM installation files.

c) Ensure that the NATURAL session started in Step b) has suitably large values for MT, MADIO, MAXCL etc. If you are doing the NATLOAD under NIM, make sure that no other users are logged on (unless using the alternative installation method detailed under the heading "alternative method" below).

d) Logon and enter NATLOAD on the command line. Press enter to start the on-line load process. The default is that all source and cataloged objects and views will be loaded. The source and cataloged objects will go to library NIMV4 on the user system file and the view SAGDA-SYSTEM will go to your dictionary system file. Examine the NATLOAD summary screen to see that the objects have been loaded.

e) Logon to NIMBLE and NIMUTILS to double check that the programs are there. Execute the MENU program to start NIMBLE. Do not proceed further into the menus, but logoff immediately and stop the NIM job (if you were using NIM for the NATLOAD). Change the //CMWKF01 DD statement so it does NOT point to the dataset containing the unloaded NATURAL - this will avoid destruction of the dataset which could happen accidentally if a NATURAL program happened to write to work file 1.



f) This step is not required to perform the initial installation, but is necessary before programs in the NIMOS suite can be modified and re-stowed.

Alternative Method:

If you already have a copy of the NIM NATURAL programs working and you want to update these programs to a newer release level, or for some reason you want to reinstall over the top of the installed programs. Then you don't need to specially "boot" from work file 1 in the JCL but you can use the NIM dynamic file allocation facility instead - just pick the 'WA' option under the 'N' option of the OSMENU command to allocate the file, then proceed with the on-line execution of NATLOAD.

Verifying the Installation

To verify that NIM has been correctly installed, follow these steps:

Step 1: Start the NIM job, and observe the normal startup sequence as described in the section "Running the Job" on page 96.

Step 2: Logon to the NIM VTAM-server application, using a VTAM logon string such as:

LOGON NIMTEST

The VTAM application name (NIMTEST) actually used will depend on the VTAM application name defined as discussed in the section "Defining a NIM VTAM-server Application" on page 85.

Step 3: Use the NATURAL LOGON command to logon to the NIM NATURAL library, NIMBLE.

Step 4: If this application has not been defined to NATURAL SECURITY, execute program MENU at the NEXT prompt. You should be presented with the NIM application MAIN MENU.

Step 5: Select option "U" from the main menu. You should be presented with the "USER DISPLAY 1" screen, showing details for only 1 user (i.e., you). Press PF10 and PF11 to scroll this display right and left (observe PF10 and PF11 prompts on the bottom line of the screen).

Step 6: Using another terminal, logon a second time. On the original terminal session, press enter, and 2 sessions should be displayed.

Step 7: On the original terminal session, press PF3 to return to the MAIN MENU, then select the MESSAGES MENU by pressing PF10 or by entering option "M". From the MESSAGES MENU, enter option "B" to display the "send broadcast message" popup window.


P A G E 1 0 0 N I M U S E R S G U I D E

Step 8: Enter a message, and press enter. You should receive the message immediately. Press enter on the second terminal, and the message should be received again.

Step 9: Press enter again on the second terminal to return to the NEXT prompt. Type "FIN" and press enter to terminate the session and receive the NIM session statistics screen. Press enter again to logoff NIM.

Step 10: On the original terminal, press PF9 to display the NIM STATUS SUMMARY SCREEN. Press PF2 to invoke the update functions, and then option "S" to select the "Stop, Quiesce, ..." function. From the "stop functions" pop-up sub-menu, select option "S" to stop the NIM address space immediately. Your session should be immediately terminated, and the NIM address space will terminate a few seconds later.

101

PROBLEM DETERMINATION GUIDE

Problems should be approached on the assumption that the software is generally reliable and that some unusual event is associated with the problem. The event might be problems with VTAM or the operating system, a modification to the NIM or NATURAL configuration, a hardware problem with a terminal controller, a RACF change, or a NATURAL program causing troubles in a development environment.

NIM v5.00 is the first NIM release to protect core NIM/Natural control blocks from accidental user corruption. The use of sub-spaces has allowed NIM to essentially separate out various user work areas (called threads in other environments) from the core NIM control blocks. This means that users cannot update the core NIM control blocks even accidentally, and any attempt to do so will result in an S0C4 exception for that user. This will essentially prevent the rare corruption problems as seen when a rogue program writes to an area of important but not protected NIM storage.

The time of occurrence of a problem should be noted so that the joblog can be examined for any suspicious messages at about that time. The NIMBLE or operator user displays etc can be examined if the system is still useable to see if anything appears different to normal.

If the NIM system appears to be essentially unusable (for example new users cannot logon or many users are "hung") then the sensible thing to do is to stop and restart that job, and then try to find the cause.

If a user has logged on to NIM or is attempting to logon to NIM but has become "stuck", you should try the NIM cancellation of user facility - if this fails, or if NIM user displays do not show the terminal concerned then you should issue a VTAM operator command to VARY the terminal inactive, then active again (using the "force" option if necessary). See the relevant IBM VTAM documentation for a description of the VARY command.

General user task abends affect only the abending user and are accompanied by a joblog message, which details the NATURAL program which seems to be involved (among other things). A commonly mentioned NATURAL program should be checked out, maybe in consultation with the terminal user.

If there are many NIM messages relating to user abends with system 0C4 and 0C1 errors, then be suspicious of NATURAL programs calling subroutines. On rare occasions, a wild subroutine or even (very rarely) a bug in NATURAL can cause general memory corruption.

Appendix

A

P R O B L E M D E T E R M I N A T I O N G U I D E


If code becomes corrupt, the problem will remain until the use count has dropped to zero for the affected module - this may not happen and the NIM job may have to be stopped and restarted to cure the problem. Note that normally, an 0C4 or similar user abend simply causes the termination of one user task with absolutely no effects on other users. Also note that if the NATURAL nucleus is placed in the (extended) link pack area, as we encourage you to do, then it is impossible to corrupt the NATURAL code as the link pack area is in protected read only memory.

For problems which are repeatable by issuing a sequence of commands in a NATURAL session, the VTAM tracing can be turned on at the logical driver level (see VTRACE parameter in the section "Parameters and User Exits" on page 35 ). It is best to arrange a special logical driver for 1 user so that other terminals will not confuse the trace. This tracing should only be done when the terminal is causing VTAM IO errors or perhaps if the screen contents are garbled and the NATURAL program is not at fault (e.g. the screen corruption occurs on only one type of terminal). If you prefer, a normal VTAM buffer trace can be done - your network support personnel will be familiar with this type of trace.

When a task abends, the whole NIM job does not abend, because NIM traps the abend. The PSW, registers, NATURAL program involved, whether an external subroutine was called and other information will appear on the joblog as evidence of the task abend. This may be the only evidence visible to the administrator. The user will receive notification from NATURAL of the abend if it is a 0C1, 0C4 or similar program check, or will notice an abrupt termination of their session if it is a more serious system abend code.

Usually, a user will be able to have several "normal" abends in their session up to a number specified in the NIM logical driver parameter "ABMAX". If needed, the administrator can cause an immediate termination of the session at the first abend of any kind, with a dump produced on SYSUDUMP, by specifying "DUMP=Y" in the logical driver. This should only be done if there is reason to believe that a dump will enable the problem to be solved. If you do need such a dump, we suggest that you create a temporary logical driver w.

103

MESSAGES

Messages produced by NIM components have the following format:

<message-prefix> <message-number><message-type> <m essage-text>

where:

message-prefix is the write-to-operator (WTO) prefix defined by the NIM GLOBAL parameter "WTOHEAD", or if this parameter was omitted, defaults to the VTAM application name of the address space

message-number is a unique 3 digit number, used to reference this appendix

message-type is a 1 character code describing the type of message:

I information message (general interest)

W warning message (something may be wrong, processing usually continues)

E error (something has gone wrong with a particular process. The task in error is terminated. Other NIM processing continues.)

S Severe error (something so drastic has gone wrong that processing cannot continue. NIM issues a message and abends the task in error (which may be the NIM mainline).)

Instead of defining a separate verbosity level (as in previous releases), NIM now uses the message type indicator as a message’s verbosity (or importance) level. Verbosity level decides whether or not the message is displayed on the operator’s console. The type indicators are ranked by importance with I being the least important, W next highest, then E, then S being the most important. The default rules are:

1. All messages are always written to NIM’s JOBLOG;

2. Severe error messages are always written to the operator’s console as well as NIM’s JOBLOG;

Appendix

B

M E S S A G E S


3. I, W and E messages are written to NIM’s JOBLOG but not to the operator’s console.

PARM command GLOBAL CONSMSG= may be used to override the default verbosity level (which is S). See the new parameter CONSMSG in the parameter section of this manual.

M E S S A G E S

N I M U S E R S G U I D E P A G E 1 0 5

Messages

001I Initialization in progress, Ver:VVVVVVVV Zaplev:ZZZZZZZZ

Meaning: The NIM address space is initializing.

VVVVVVVV: NIM version number ZZZZZZZZ: Zap level of the NIM program

The version and zap level of the software are displayed.

Action: None.

002I Initialization complete

Meaning: The initialization of the NIM address space is complete. User logons can proceed.

Action: Rejoice.

003I Accepting logons with VTAM applname AAAAAAAA AAAAAAAA: NIM VTAM application name

Meaning: The NIM VTAM interface has been initialized using the VTAM application name AAAAAAAA.

Action: None.

004I All users logged off, now quiescing

Meaning: NIM had been previously set into "quiesce" mode, and now that no users are logged on, the NIM job is entering its termination phase.

Action: None.

005I Termination in progress

Meaning: The NIM job termination phase has started.

Action: None.

006I Termination complete - NORMAL END

Meaning: The NIM job termination phase is complete - all processing has been completed and the NIM job is about to return control to the operating system address space control programs.

M E S S A G E S


Action: None.

007E Initialization failed: function name

Meaning: NIM failed to complete initialization. The last attempted function is shown as function. The object name associated with the failing function is shown as name. This message will be followed by a User Abend 007 with a dump.

The following shows the possible values for function and name.

Function name GENCB EXLST GENCB ACB GENCB RPL OPEN acbname

Action: For function GENCB, the system dump and job log should be provided to NIM technical support.

For functionOPEN, ensure that the indicated acbname is valid

010I Timed out UID:UUUUUUUU TID:TTTTTTTT UUUUUUUU: UserID TTTTTTTT: Terminal ID

Meaning: The NIM NATURAL session associated with UserID UUUUUUUU and terminal ID TTTTTTTT has been timed out due to the inactivity limit for the session (defined by the logical driver NONACT parameter) being exceeded.

Action: None.

011I Accepted TID:TTTTTTTT Using Driver:DDDDDDDD TTTTTTTT: Terminal ID DDDDDDDD: Logical driver

Meaning: The terminal ID TTTTTTTT has started a session with NIM using logical driver DDDDDDDD.

Action: None.

012I Transferring:TTTTTTTT from:AAAAAAAA to:BBBBBBBBB RRRRRRRR TTTTTTTT: Terminal ID AAAAAAAA: Current VTAM application BBBBBBBB: Target VTAM application RRRRRRRR: Reason for transfer - USERMAX(G) The address space global usermax has

M E S S A G E S


been exceeded - USERMAX(D) The logical driver usermax has been exceeded - MEMTEST(H) The above-the-line (high) memory test failed - MEMTEST(L) The below-the-line (low) memory test failed

Meaning: The terminal ID TTTTTTTT could not be accepted by the current NIM VTAM application (AAAAAAAA) and has been transferred to another VTAM application (BBBBBBBB). The reason that the terminal could not be accepted by this address space is given by RRRRRRRR.

Action: None.

013W Invalid Driver:DDDDDDDD TID:TTTTTTTT Using default:EEEEEEE DDDDDDDD: Logical driver supplied by user in logon string TTTTTTTT: Terminal ID EEEEEEEE: Default logical driver

Meaning: The terminal ID TTTTTTTT could not be accepted by the current NIM VTAM application (AAAAAAAA) and has been transferred to another VTAM application (BBBBBBBB). The reason that the terminal could not be accepted by this address space is given by RRRRRRRR.

Action: The choice of an invalid logical driver is probably due to a spelling mistake on behalf of the user attempting to log on. Ensure that users know the appropriate driver names for the services they require, and that all logical drivers are correctly defined to NIM. Users attempting to log on to a logical driver that is not available will receive a message from NIM during logging on, warning them that they have been assigned to the default driver.

014S CORRUPTION DETECTED IN GLOBAL CONTROL BLOCK:BBBBBBBB BBBBBBBB: Global control block which is corrupt - GLOBMAP Main global control block - TASKMAPSubtask chain control block - LDMAP Logical driver table

Meaning: NIM periodically checks the structure of its main address space level control blocks. If any corruption is detected, this message is produced and the job abended with user abend code 14.

Action: The system dump and job log should be provided to NIM technical support.

020S INITIALIZATION FAILED - RRRRRRRR... RRRRRRRR: The reason that NIM initialization failed

M E S S A G E S


- PARAMETER ERROR an error in the NIM PARM records was detected - ATTACH OPER FAILED the NIM operator communication task could not be attached - ATTACH USERTCB FAILED the user address space subtask could not be attached

Meaning: Initialization of the NIM address space was aborted for the reason indicated. The NIM job will abend with user abend code 14.

Action: PARAMETER ERROR - correct the NIM parameters ATTACH OPER FAILED - contact NIM technical support ATTACH USERTCB FAILED - ensure that the user subtask module is available in the job STEPLIB and that the GLOBAL SUBTASK parameter is correct

021S CPREQST FLAG CORRUPT:FF FF : Corrupt value of the CPREQST flag

Meaning: An internal status flag is corrupt. The job will be abended with user abend code 21.


022S VTAM APPLICATION AAAAAAAA NOT ACTIVE OR NOT DEFINED AAAAAAAA : NIM VTAM application name.

Meaning: The attempt to open the NIM-VTAM interface failed with an error indicating that either the VTAM application was inactive, or was unknown to VTAM.

Action: Ensure that the NIM GLOBAL APPL parameter is correctly defined, and make sure that this application is defined to VTAM and currently active (the nodeset containing the application definition may be inactive). The status of the VTAM application can be determined from the output of the operating system command: D NET,ID=AAAAAAAA

023S TERMMAP MISSING, TASKMAP:MMMMMMMM FLAGS:FFFFFFFF MMMMMMMM : TASKMAP address FFFFFFFF : TASKFLGS value

Meaning: An internal error has occurred in the NIM logging processor. The job will abend with user abend code 23.


M E S S A G E S


025S OPEN ACB FAILED, VTAMID:AAAAAAAA RC:HHHH AAAAAAAA : NIM VTAM application name. HHHH : VTAM ACB Error code.

Meaning: The attempt to open the NIM-VTAM interface failed with an unanticipated error. The job will abend with user abend code 25.

Action: Diagnose the error using the appropriate VTAM programming reference - OPEN ACB return codes. If the problem is not obvious, and VTAM seems to be active and operating normally, describe the error to NIM technical support.

026S SETLOGON START FAILED, VTAMID:AAAAAAAA RC:HHHH AAAAAAAA : NIM VTAM application name. HHHH : VTAM SETLOGON Error code.

Meaning: The attempt to allow sessions to logon to the NIM VTAM application failed. The job will abend with user abend code 26.

Action: Diagnose the error using the appropriate VTAM programming reference - SETLOGON return codes. If the problem is not obvious, and VTAM seems to be active and operating normally, describe the error to NIM technical support.

027S VTAM APPLICATION AAAAAAAA ALREADY ACTIVE AAAAAAAA : NIM VTAM application name.

Meaning: The attempt to open the NIM-VTAM interface failed with an error indicating that this application name was already in use by another address space. The job will abend with user abend code 26.

Action: Ensure that the NIM GLOBAL APPL parameter is correctly defined, and make sure that this application is not in use by another address space. The status of the VTAM application can be determined from the output of the operating system command: D NET,ID=AAAAAAAA

028S CLOSE ACB FAILED, VTAMID:AAAAAAAA RC:HHHH AAAAAAAA : NIM VTAM application name. HHHH : VTAM ACB Error code.

Meaning: The attempt to close the NIM-VTAM interface failed. The job will abend with user abend code 28.

Action: Diagnose the error using the appropriate VTAM programming reference - OPEN ACB return codes. If the problem is not obvious, and VTAM seems to be active and operating normally, describe the error to NIM technical support.

029S TASKTAB TABLE FULL

M E S S A G E S


Meaning: An internal error has occurred in the NIM logon exit. The job will abend with user abend code 29.

Action: Ensure that the global address space usermax does not exceed the size of the NIM TASKTAB (unless your site has zapped the size of TASKTAB in module NIMTPINI, it will have a value of decimal 1020 - the current value for TASKTAB can be most easily obtained from the NIMBLE "Address space status summary and control" option). The system dump and job log should be provided to NIM technical support.

030S OPNDST DIDNT TAKE, VTAMID:VVVVVVVV RC:HHHH VVVVVVVV : SLU name (terminal ID) HHHH : OPNDST Feedback code.

Meaning: The attempt to issue an OPNDST to acquire terminal VVVVVVV in the NIM logon exit failed (i.e., it was not the OPNDST that failed, but the attempt to issue the OPNDST, which was not accepted by VTAM). The terminal will not be acquired by NIM, and may need to be released back to VTAM by a “V NET,INACT,F,ID=VVVVVVVV” system operator command.

Action: Diagnose the error using the appropriate VTAM programming reference - RPL Feedback codes. If the problem is not obvious, and VTAM seems to be active and operating normally, describe the error to NIM technical support.

031S END OF TASK ERROR, TASK:TTTTTTTT OPER:OOOOOOOO TIME:UUUUUU X TTTTTTTT : TCB of task that has ended OOOOOOOO : TCB of the operator task UUUUUUUU : TCB of the user subtask

Meaning: The NIM control program end-of-control-task exit has been unexpectedly entered, with reports that a task we don't recognize (OOOOOOOO) has ended. This is an internal error and the job will now abend with user abend code 31.


032S END OF TASK PPPP, TCB:TTTTTTTT COMPL CODE:CCCCCCCC PPPP: Type of task that has ended - OPER - operator communication subtask - USER - user subtask OOOOOOOO : TCB of the terminating task CCCCCCCC : completion code of the terminating task

Meaning: The NIM control program end-of-control-task exit has been unexpectedly entered, reporting that either the operator communication or user subtask has ended. The job will now abend

M E S S A G E S


with user abend code 32.

Action: If the user task has ended, check the logic and correct. If the operator communication task has ended, then the system dump and job log should be provided to NIM technical support.

033S ATTACH FAILED, TID:VVVVVVVV MODULE:MMMMMMMM VVVVVVVV : VTAM SLU (terminal ID) for whom a subtask was being attached. MMMMMMMM : name of the module being attached as a subtask

Meaning: The NIM control program attempted to attach a new subtask as part of session establishment for terminal VVVVVVVV. However, the attach of module MMMMMMMM failed, and the terminal was released from NIM.

Action: Check that the correct module is being attached, and that the NIM STEPLIB hasn't gone into an additional extent since the NIM job was started. Describe the problem to NIM technical support.

034S END OF USER TASK LOST, TASK:TTTTTTTT TTTTTTTT : TCB of task that has ended

Meaning: The NIM control program end-of-NATURAL-task exit has been unexpectedly entered, with reports that a task we don't recognize (TTTTTTTT) has ended. This is an internal error and the job will now abend with user abend code 34.


035S END OF TASK TCB:TTTTTTTT COMPL CODE:CCCCCCCC TID:VVVVVVVV TTTTTTTT : TCB of the terminating task CCCCCCCC : completion code of the terminating task VVVVVVVV : VTAM SLU (terminal ID) associated with subtask

Meaning: The NIM control program end-of-NATURAL-task exit has been entered, reporting that a NATURAL subtask has abended. NIM normally performs the controlled termination of tasks, whereby this exit is not entered. However, if the subtask control program detected corruption in the subtask's data areas, or if the logical driver was defined with the parameter DUMP=Y, tasks will terminate through this end- of-task exit.

Action: If the task termination is unexpected, the system dump and job log should be provided to NIM technical support.

036S INTERNAL ERROR #1, TASKMAP:TTTTTTTT FLAGS:FFFFFFFF TTTTTTTT : TASKMAP address

M E S S A G E S


FFFFFFFF : TASKFLAGS

Meaning: An internal error has been detected. The job will be abended with user abend code 36.


037S SETLOGON STOP FAILED, VTAMID:AAAAAAAA RC:HHHH AAAAAAAA : NIM VTAM application name. HHHH : VTAM SETLOGON Error code.

Meaning: The attempt to disable session log on to the NIM VTAM application failed. The job will abend with user abend code 37.

Action: Diagnose the error using the appropriate VTAM programming reference - SETLOGON return codes. If the problem is not obvious, and VTAM seems to be active and operating normally, describe the error to NIM technical support.

038E ‘GENCB RPL failed:<module-name> RC:<return-code> R0=<reason-code>

Meaning: NIM failed to generate a basic control block and will report the module name return code and reason code.

Action: Contact NIM technical support with the information reported in this message and any other messages in the NIM joblog and system log.

040W UNUSUAL VTAM STATUS ON CLSDST, TASKMAP:TTTTTTTT FLAGS:FFFFFFFF TID:VVVVVVVV TTTTTTTT : TASKMAP address FFFFFFFF : TASKFLAGS VVVVVVVV : VTAM SLU (terminal ID) associated with TASKMAP

Meaning: An unusual logic condition has been detected, but processing will continue.

Action: Describe the problem to NIM technical support.

041W OPNDST FAILED, TID:VVVVVVVV RTNCD:HHHHHH SENSE:SSSS VVVVVVVV : SLU name (terminal ID) HHHHHH : OPNDST Feedback code SSSS : OPNDST Sense code

Meaning: The OPNDST issued by NIM to acquire terminal VVVVVVV in the NIM logon exit failed with feedback code HHHHHHHH and sense code SSSS. The terminal will not be acquired by NIM.

M E S S A G E S


Action: Diagnose the error using the appropriate VTAM programming reference - RPL Feedback codes. Ensure that the terminal and either the default logmode or any explicitly provided logmode is correctly defined for the characteristics of the terminal. Determine whether any other VTAM applications can be accessed from the terminal. If the problem is not obvious, and VTAM definitions seem appropriate, describe the error to NIM technical support.

042W SEND FAILED, TID:VVVVVVVV RTNCD:HHHHHH SENSE:SSSS VVVVVVVV : SLU name (terminal ID) HHHHHH : SEND Feedback code SSSS : SEND Sense code

Meaning: The SEND issued by NIM immediately after successfully acquiring the terminal (sending the "LOGON IN PROGRESS..." message) has failed with feedback code HHHHHHHH and sense code SSSS. The terminal will be released by NIM.

Action: Diagnose the error using the appropriate VTAM programming reference - RPL Feedback codes. Ensure that the terminal and either the default logmode or any explicitly provided logmode is correctly defined for the characteristics of the terminal. Determine whether any other VTAM applications can be accessed from the terminal. If the problem is not obvious, and VTAM definitions seem appropriate, describe the error to NIM technical support.

043W CLSDST FAILED, TID:VVVVVVVV RTNCD:HHHHHH SENSE:SSSS VVVVVVVV : SLU name (terminal ID) HHHHHH : CLSDST Feedback code SSSS : CLSDST Sense code

Meaning: The CLSDST issued by NIM to release the terminal has failed with feedback code HHHHHHHH and sense code SSSS.

Action: Diagnose the error using the appropriate VTAM programming reference - RPL Feedback codes. A feedback code of "1413" may usually be ignored, as it indicates an attempt by NIM to release a terminal which VTAM has probably already released from session with NIM. Determine the current state of the terminal by issuing the operator command: D NET,ID=VVVVVVVV If the terminal seems to be hung in session with NIM, attempt to release it with the operator command sequence: V NET,INACT,F,ID=VVVVVVVV V NET,ACT,ID=VVVVVVVV

044S SIGNAL DIDNT TAKE, VTAMID:VVVVVVVV RTNCD:HHHH VVVVVVVV : SLU name (terminal ID)

M E S S A G E S


HHHHHH : SEND SIGDATA Feedback code

Meaning: The SEND SIGDATA issued by NIM to prepare for inactivity timeout warning on terminal VVVVVVVV has failed with feedback code HHHH. VTAM refused to accept the SEND SIGNAL command. The terminal will not receive a timeout warning.

Action: Diagnose the error using the appropriate VTAM programming reference - RPL Feedback codes. Non SNA terminals cannot usually process the SIGNAL protocol.

045W SIGNAL FAILED, TID:VVVVVVVV RTNCD:HHHHHH SENSE:SSSS VVVVVVVV : SLU name (terminal ID) HHHHHH : SEND SIGDATA Feedback code SSSS : SEND SIGDATA Sense code

Meaning: The SEND SIGDATA issued by NIM to prepare for inactivity timeout warning on terminal VVVVVVVV has failed with feedback code HHHHHH and sense code SSSS. The terminal will not receive a timeout warning.

Action: Diagnose the error using the appropriate VTAM programming reference - RPL Feedback codes. Non SNA terminals cannot usually process the SIGNAL protocol. If the problem is not obvious, and VTAM definitions seem appropriate, describe the error to NIM technical support.

046W CLSDST PASS FAILED, TID:VVVVVVVV RTNCD:HHHHHH SENSE:SSSS VVVVVVVV : SLU name (terminal ID) HHHHHH : CLSDST Feedback code SSSS : CLSDST Sense code

Meaning: The CLSDST issued by NIM to pass the terminal VVVVVVVV to another VTAM application has failed with feedback code HHHHHHHH and sense code SSSS. The CLSDST PASS command was not accepted by VTAM. A CLSDST RELEASE command will be attempted.

Action: Diagnose the error using the appropriate VTAM programming reference - RPL Feedback codes. If the problem is not obvious describe the error to NIM technical support.

047W CLSDST PASS FAILED, TID:VVVVVVVV RTNCD:HHHHHH SENSE:SSSS VVVVVVVV : SLU name (terminal ID) HHHHHH : CLSDST Feedback code SSSS : CLSDST Sense code

Meaning: The CLSDST issued by NIM to pass the terminal VVVVVVVV to another VTAM application has failed with feedback code

M E S S A G E S


HHHHHHHH and sense code SSSS. The CLSDST PASS command was accepted by VTAM, but did not complete normally. A CLSDST RELEASE command will be attempted.

Action: Diagnose the error using the appropriate VTAM programming reference - RPL Feedback codes. Perhaps the application being transferred to is not active, or not accepting logon requests. If the problem is not obvious describe the error to NIM technical support.

050I Ended, UID:UUUUUUUU TID:VVVVVVVV Cpu:CCC Screens:WWWWW UUUUUUUU : UserID VVVVVVVV : SLU name (terminal ID) CCC : CPU seconds consumed by the session WWWWW : VTAM screen writes sent during the session

Meaning: The session with UserID UUUUUUUU at terminal ID VVVVVVVV has been completed. During the session, CCC CPU seconds were consumed by the NIM-NATURAL driver and WWWWW VTAM screen writes were sent to the terminal.

Action: None.

051I CLSDST ERROR, TID:VVVVVVVV TASKMAP:TTTTTTTT FLAGS:FFFFFFFF RC:HHHHHHHH VVVVVVVV : SLU name (terminal ID) HHHHHH : CLSDST Feedback code SSSS : CLSDST Sense code

Meaning: The CLSDST issued by NIM to release the terminal VVVVVVVV back to VTAM application has failed with feedback code HHHHHHHH and sense code SSSS. The CLSDST RELEASE command was not accepted by VTAM.

Action: Diagnose the error using the appropriate VTAM programming reference - RPL Feedback codes. The terminal has not been released from session with NIM. Determine the current state of the terminal by issuing the operator command: D NET,ID=VVVVVVVV If the terminal seems to be hung in session with NIM, attempt to release it with the operator command sequence: V NET,INACT,F,ID=VVVVVVVV V NET,ACT,ID=VVVVVVVV

070I Dynalloc failed, DD:FFFFFFFF Err:HHHHHHHH DSN:LLLLLLLLLLLL FFFFFFFF : File name (DD Name) HHHHHHHH : Dynamic allocation return code LLLLLL.. : Data set name

Meaning: File FFFFFFFF, dataset LLLLLLL... defined to NIM with the FILE PARM record could not be dynamically allocated. The dynamic

M E S S A G E S


allocation error was HHHHHHHH.

Action: Diagnose the error using the appropriate systems programming reference - dynamic allocation return codes. The most likely errors are: 17080000 - dataset not cataloged 02100000 - dataset in use

080I VTAM TERMINATION IN PROGRESS, REASON:HHHH HHHH : VTAM Termination reason

Meaning: VTAM has informed NIM that it is about to terminate. NIM will immediately start termination processing.

Action: None.

081I VTAM LOSTERM FOR TID:VVVVVVVV REASON:HH FLAGS:FFFFFFFF VVVVVVVV : SLU name (terminal ID) HH : LOSTTERM reason code FFFFFFFF : NIM TASKFLAGS

Meaning: VTAM has informed NIM of a communications outage with terminal VVVVVVVV. The type of problem is classified by the reason code HH. The current status of the task and terminal session according to NIM is FFFFFFFF. NIM will now initiate session cleanup processing.

Action: Diagnose the error using the appropriate VTAM programming reference - LOSTTERM reason codes. The terminal may have been turned off, become disconnected, or the session may have been aborted by the user with the SYSREQ key.

082E VTAM LOSTERM INVALID USERFLD, REASON:HH USERFLD:RRRRRRRR HH : LOSTTERM reason code RRRRRRRR : VTAM LOSTTERM RPL USERFLD

Meaning: VTAM has informed NIM of a communications outage. NIM tries to match the USERFLD provided by VTAM with the list of USERFLDs currently in session, but can’t find a match. The LOSTERM alert is ignored.


083I NSEXIT, TYPE:HHHHHH CID:CCCCCCCC USERFLD:RRRRRRRR HHHHHH : NSEXIT call type CCCCCCCC : VTAM communications ID of the session RRRRRRRR : VTAM USERFLD associated with the session

Meaning: VTAM has invoked the NIM network services exit. The type of network services event is classified by the call type HHHHH. The

M E S S A G E S


communications ID of the session involved is CCCCCCCC and the USERFLD associated with the session is RRRRRRRR. NIM will now initiate session cleanup processing.

Action: Diagnose the error using the appropriate VTAM programming reference - network service call types. VTAM normally invokes the network services error to inform the application program of a fatal error on a communications session.

084E UNRECOGNIZED NSEXIT REQUEST UNIT, TYPE:HHHHHH HHHHHH : NSEXIT call type

Meaning: VTAM has invoked the NIM network services exit. The type of network services event (HHHHHH) is not recognized by the NIM exit logic. NIM ignores the network services call.


085E NSPE REASON:HH SENSE:SSSSSS HHHHHH : NSPE reason code SSSSSS : NSPE sense information

Meaning: VTAM has invoked the NIM network services exit with a call type of NSPE, reason code HHHHHH, sense SSSSSS.

Action: Diagnose the error using the appropriate VTAM programming reference - network service NSPE reason codes.

086I VTAM EEEEEEEE FOR TID:VVVVVVVV FLAGS:FFFFFFFF EEEEEEEE : VTAM Network services call type - CLEANUP - NOTIFY VVVVVVVV : SLU name (terminal ID) FFFFFFFF : NIM TASKFLAGS

Meaning: VTAM has invoked the NIM network services exit with a call type of wither CLEANUP or NOTIFY, referencing the NIM session with terminal VVVVVVVV. The current status of the session is recorded in NIM as FFFFFFFF. NIM will initiate session termination processing.

Action: None.

087E VTAM NSEXIT INVALID USERFLD:RRRRRRRR RRRRRRRR : VTAM LOSTTERM RPL USERFLD

Meaning: VTAM has invoked NIM's network services exit. NIM tries to match the USERFLD provided by VTAM with the list of USERFLDs currently in session, but cant find a match. The network services alert

M E S S A G E S


is ignored.


090S INVALID LOG TYPE:LL LL : Invalid log type

Meaning: An internal logging error has occurred. The NIM address space will be abended with user abend code 90.


091E DEFAULT LOGGING TURNED OFF - DB2TPLOG COULD NOT BE OPENED

Meaning: The NIM log file (//DB2TPLOG DD ...) could not be opened. Logging to this file has been disabled.

Action: Add the //DB2TPLOG DD file to NIM JCL.

092S PARM FILE COULD NOT BE OPENED

Meaning: The NIM parm file (//PARM DD ...) could not be opened. The NIM address space will be abended with user abend code 92.

Action: The //PARM DD file containing the NIM parameters must be added to the NIM JCL.

093S DEFAULT DRIVER DDDDDDDD HAS NOT BEEN DEFINED

Meaning: The default logical driver has been defined as DDDDDDDD. However, no logical driver with that name has been defined. The NIM address space will be abended with user abend code 93.

Action: Ensure that the GLOBAL DRIVER parameter value is the name of a valid logical driver.

094S TABLE OVERFLOW, TTTTTTTTTTTTTTTTTTTT TTTTTTTTTTTTTTTTTT: table that overflowed - LOGICAL DRIVERS - FILE ENTRIES

Meaning: An internal table has overflowed whilst processing the PARM file records. The NIM address space will be abended with user abend code 90.

Action: Either reduce the number of entries of the type reported, or apply a zap to increase the relevant table size (refer to section 3.6).

M E S S A G E S


095S PARAMETER ERROR: PPPPPPPPPPPPPPPPPPPPPPP PPPPPPPPPPPPPPPPPP: parameter error message

Meaning: A parameter error has been detected whilst processing the PARM file records. The NIM address space initialization will be aborted. The message will be followed by message number 097S, which shows the parameter record in error. Types of errors: Invalid Type Invalid Parameter Parameter Value Missing Required Name Missing Parameter Missing Value must be Y or N Invalid Option File ALLOC Option Missing File DDname Missing Duplicate File DDname USERMAX Value Too High PRINTPF must be valid PF Key

Action: Correct the parameter error.

096S PARAMETER WARNING: PPPPPPPPPPPPPPPPPPPPP PPPPPPPPPPPPPPPPPP: parameter warning message

Meaning: A parameter warning has been generated whilst processing the PARM file records. The NIM address space initialization will be continue. The message will be followed by message number 097S, which shows the parameter record causing the warning. Types of warnings: Module Could not be loaded The load module specified in a GLOBAL PRELOAD or UEXn parameter record could not be loaded into memory

Action: Correct the parameter record.

097S PARM CARD:CCCCCCCCCCCCCCCCCCCCCC.. CCCCCCCCCCCCCCCC..: parameter record generating the error or warning

Meaning: Refer to message 095S or 096S.

Action: Correct the parameter record.

098S DB2 CONNECT TO SSID:DDDD FAILED RET=HHHHHHHH REAS=SSSSSSSS DDDD : DB2 subsystem ID HHHHHHHH : return code from DB2 CONNECT SSSSSSSS : reason code from DB2 CONNECT

M E S S A G E S


Meaning: The attempt of NIM to CONNECT to the DB2 subsystem specified by the NIM GLOBAL SUBSYS parameter (DDDD) has failed with return code HHHHHHHH, reason code SSSSSSSS. The NIM address space initialization will be aborted.

Action: Ensure that the DB2 subsystem id has been correctly specified.

100I Waiting for command

Meaning: The NIM operator communications task is waiting for an operator command.

Action: None.

101E UNRECOGNIZED QEDIT COMMAND CODE:QQ QQ : Unrecognized QEDIT command code

Meaning: A logic error has occurred within the NIM operator interface. An unrecognized command class has been received. Operator commands may now be disabled.

Action: This is an internal error. Describe the problem to NIM technical support.

102S QEDIT RELEASE ERROR:HHHHHHHH HHHHHHHH : QEDIT release return code

Meaning: A logic error has occurred within the NIM operator interface. The most recent command cannot be released. Operator commands may now be disabled.

Action: This is an internal error. Describe the problem to NIM technical support.

103I STOP COMMAND RECEIVED

Meaning: Either the P <NIM address space name> or F <NIM address space name>,

STOP command has been received. Address space termination processing will now be initiated.

Action None

104I Received command:LLLLLLLLLLLLLLLLLLLLLLL...... LLLLLLLLLLLLLL.. : echo of the operator command received

Meaning: An operator command has been received. The first 50 characters of the command are echoed.

M E S S A G E S


Action: The operator command will now be processed. Another command cannot be entered until message 100I is reissued.

105I Available Operator commands are:

Meaning: An invalid operator command has been received. A list of valid command syntax will now be written to the system console and job log (messages 106 through 132)

Action: Correct the command.

The text of the operator syntax help messages follows:

106I STOP - stop immediately 107I QUIESCE - inhibit logons, stop when idle 108I UNQUIESCE - cancel previous quiesce state 109I USERMAX=NNN - set address space user max 110I XFER=AAAAAAAA - set VTAM transfer applname 111I CANCEL,UID=UUU.. - cancel specific user 112I CANCEL,TID=TTT.. - cancel specific terminal 113I CANCEL,FILE=FFF.. - cancel all users with spec ific file 114I MSG,NOW,MMM.. - send message now, dont save 115I MSG,SAVE,MMM.. - send message now and save for logon 116I MSG,DELETE - delete logon message 117I MSG,UID=UUU..,MM. - send message to specific u ser 118I MSG,TID=TTT..,MM.. - send message to specific terminal 119I MSG,LIST - list current logon message 120I LOAD=MMMMMMMM - load module into memory 121I UNLOAD=MMMMMMMM - unload module from memory 122I ALLOC - allocate all files defined in parms 123I ALLOC,FILE=FFFF.. - allocate specific files wi th prefix 124I DEALLOC - de-allocate all files defined in par ms 125I DEALLOC,FILE=FFFF.. - de-allocate specific fil es with prefix 126I STATUS - summary status display 127I STATUS,UID=UUU.. - show status of a specific u ser 128I STATUS,TID=TTT.. - show status of a specific t erminal 129I STATUS,FILE=FFFF.. - Show status of a specific file 130I STATUS,DUMP - dump control information 131I STATUS,DUMPU=UUU - dump details of a specific user 132I STATUS,DUMPT=TTT - dump details of a specific terminal

140I Loaded module:MMMMMMMM MMMMMMMM: name of module

Meaning: In response to the LOAD command, module MMMMMMMM has been loaded into the address space.

Action: None.

141E Load failed for module:MMMMMMMM MMMMMMMM: name of module

M E S S A G E S


Meaning: In response to the LOAD command, the load of module MMMMMMMM has failed.

Action: Correct the load module name on the LOAD= command.

142I Unloaded module:MMMMMMMM MMMMMMMM: name of module

Meaning: In response to the UNLOAD command, module MMMMMMMM has been unloaded (its usage count has been reduced by 1, and if it fell to zero, the module will have been deleted from the address space).

Action: None.

143E Unload (DELETE) failed for module:%A8 MMMMMMMM: name of module

Meaning: In response to the UNLOAD command, the deletion of module MMMMMMMM has failed.

Action: Correct the load module name on the UNLOAD= command.

144I Quiesce mode now set

Meaning: In response to the QUIESCE command, NIM has entered into the quiesce state. No new logon requests will be accepted and when all sessions have been completed the address space will terminate.

Action: None.

145I Quiesce mode now cancelled

Meaning: In response to the UNQUIESCE command, the quiesce state has been cancelled. Logon requests will be accepted.

Action: None.

146I VTAM transfer application now set to:AAAAAAAA AAAAAAAA: global transfer VTAM application name

Meaning: In response to the XFER command, the global VTAM transfer application name has been set to AAAAAAAA.

Action: None.

147I Current logon ("greeting") message:

148I LLLLLLLLLLLLLLLLLL.... LLLLLL..: lines 1 to 5 of the current logon message

Meaning: In response to the MSG,LIST command, message 147I and then 5 occurrences of message 148I will be output displaying the 5 lines of the current logon

M E S S A G E S


message.

Action: None.

149I Message sent to NNNN users NNNN : number of users sent the message

Meaning: In response to the MSG,NOW or MSG,SAVE command, the number of users sent the message is displayed.

Action: None.

150I New logon ("greeting") message recorded

Meaning: In response to the MSG,SAVE command, the confirmation that a new logon message has been recorded.

Action: None.

151I Logon ("greeting") message deleted

Meaning: In response to the MSG,DELETE command, the confirmation that the logon message has been deleted.

Action: None.

152I Operator canceling TID:VVVVVVVV UID:UUUUUUUU VVVVVVVV : SLU name (terminal ID) UUUUUUUU : UserID

Meaning: In response to the CANCEL set of commands, each session being cancelled is reported.

Action: None.

153W No users found matching selection criteria to CANCEL

Meaning: In response to the CANCEL set of commands, no sessions have been cancelled, as no sessions satisfied the criteria for cancellation.

Action: None.

154W File not found in TIOT:FFFFFFFF (file is not allocated) FFFFFFFF : filename

Meaning: In response to the CANCEL,FILE= or the STATUS,FILE= command, the specified file is not allocated to the NIM address space.

Action: None.

155I File already allocated:FFFFFFFF FFFFFFFF : filename

M E S S A G E S


Meaning: In response to the ALLOC or ALLOC,FILE= command, the specified file is already allocated to the NIM address space.

Action: None.

156I File now allocated :FFFFFFFF FFFFFFFF : filename

Meaning: In response to the ALLOC or ALLOC,FILE= command, the specified file has been successfully allocated to the NIM address space.

Action: None.

157E File allocation error :FFFFFFFF Dynalloc RC:RRRRRRRR FFFFFFFF : filename RRRRRRRR : dynamic allocation return code

Meaning: In response to the ALLOC or ALLOC,FILE= command, the specified file has not been allocated. The dynamic allocation return code was RRRRRRRR.

Action: Diagnose the error using the appropriate systems programming reference - dynamic allocation return codes. The most likely errors are: 17080000 - dataset not cataloged 02100000 - dataset in use

158I Count of files successfully allocated:NNNN NNNN : number of files successfully allocated

Meaning: In response to the ALLOC or ALLOC,FILE= command, the number of files actually allocated is displayed.

Action: None.

159I File already deallocated:FFFFFFFF FFFFFFFF : filename

Meaning: In response to the DEALLOC or DEALLOC,FILE= command, the specified file is not currently allocated by the NIM address space.

Action: None.

160I File now deallocated :FFFFFFFF FFFFFFFF : filename

Meaning: In response to the FRALLOC or DEALLOC,FILE= command, the specified file has been successfully deallocated from the NIM address space.

Action: None.

161E File deallocation error :FFFFFFFF Dynalloc RC:RRRRRRRR FFFFFFFF : filename

M E S S A G E S


RRRRRRRR : dynamic deallocation return code

Meaning: In response to the DEALLOC or DEALLOC,FILE= command, the specified file has not been deallocated. The dynamic deallocation return code was RRRRRRRR.

Action: Diagnose the error using the appropriate systems programming reference - dynamic allocation return codes. The most likely error is: 04400000 - dataset is in use

162I Count of files successfully deallocated:NNNN NNNN : number of files successfully deallocated

Meaning: In response to the DEALLOC or DEALLOC,FILE= command, the number of files actually deallocated is displayed.

Action: None.

163S UNEXPECTED ABEND IN DB2TPOPR

Meaning: The abend recovery environment of the operator communications task was unexpectedly entered (i.e., no retry routine was registered). This is an internal error. The operator communications task will abend, which will cause the NIM address space to abend.


164I DB2TP Summary --- Users:AAAAAAAA Usermax :BBBBBBB

165I Status:CCCCCCCC Vtam appl:DDDDDDDD Def Driv :EEEEEEE

166I Cpusec:FFFFFFFF Vtam wrts:GGGGGGGG Sessions :HHHHHHH

167I Database calls Adabas:IIIIIIII DB2 :JJJJJJJ

M E S S A G E S


AAAAAAAA : Current user count BBBBBBBB : Global usermax CCCCCCCC : Current address space status NORMAL - QUIESCE - in quiesce state - REQ TERM - immediate termination requested - TERMIN#1 - termination phase 1 - TERMIN#2 - termination phase 2 - TERMIN#3 - termination phase 3 DDDDDDDD : NIM VTAM application name EEEEEEEE : Default logical driver FFFFFFFF : Total CPU seconds consumed by NATURAL se ssions GGGGGGGG : Total VTAM writes generated by NATURAL s essions HHHHHHHH : Total number of completed NATURAL sessio ns IIIIIIII : Total ADABAS call generated by NATURAL s essions JJJJJJJJ : Total DB2 calls generated by NATURAL ses sions

Meaning: In response to the STATUS command, the address space status summary is displayed.

Action: None.

168I U DUMP1: TID:AAAAAAAA ATTN:BB ST:CC VST:DD NST:EE

169I U DUMP2: TCB:FFFFFFFF TASKMAP:GGGGGGGG TERMMAP:HHHHHH

170I U DUMP3: UID:IIIIIIII TASKMAP:JJJJJJJJ ST1:KK ST2:LL

171I U DUMP4: ST3:MM TFLG:NN COMM:OO CPFL:PPPPPPPPQQQQ

172I U DUMP5: LASTACT:RRRRRRRR TRM:SSSSSS REAS:TTTTTTTT UU

M E S S A G E S


AAAAAAAA : VTAM SLU (Terminal ID) BB : TASKMAP ATTN flag CC : TASKMAP ST flag DD : TASKMAP VST flag EE : TASKMAP NST flag FFFFFFFF : task TCB address GGGGGGGG : TASKMAP address HHHHHHHH : TERMMAP address IIIIIIII : TERMMAP UserID JJJJJJJJ : TERMMAP TASKMAP pointer KK : TERMMAP ST1 flag LL : TERMMAP ST2 flag MM : TERMMAP ST3 flag NN : TERMMAP TERMFLAG flag OO : TERMMAP COMMFLAG communication capabilit y flag PPPPPPPP : TERMMAP COMMFLAG communication parameter s flag and write erase character, default rc QQQQ : TERMMAP alternate rows, cols RRRRRRRR : TERMMAP Last activity time SSSSSS : TERMMAP TERMBY termination by code TTTTTTTTT: TERMMAP TERMREAS termination reason code UUUU : TERMMAP TERMSENS termination sense code

Meaning: In response to the STATUS,DUMPU or STATUS,DUMPT command, internal fields and flags are displayed for a session, for diagnostic purposes.

Action: None.

173W No users matching selection criteria to display

Meaning: In response to the STATUS,UID or STATUS,TID or STATUS,DUMPU or STATUS,DUMPT command, no sessions were found matching the selection criteria.

Action: None.

174W --TID--- --UID--- -Status- DBcalls Writes CPU Nonact

175W AAAAAAAA BBBBBBBB CCCCCCCC DDDDDDD EEEEE FFF GGGGGGG

M E S S A G E S


AAAAAAAA : VTAM SLU (terminal ID) BBBBBBBB : UserID CCCCCCCC : Current session status - ATTACH - attach requested - DETACH - detach requested - CLSDST - VTAM session release in progress - CLSDSTOK - VTAM session release done OK - CLSDSTNZ - VTAM session release failed - SESSLOST - VTAM session reported as lost - NAT TERM - NATURAL session has completed - NATURAL - NATURAL has been invoked - NAT-ESTA - in session ESTATE exit - NAT-LOOP - in CPU loop cleanup pending - NAT-SUBR - in 3GL/ASM subroutine - NAT-ADA - in ADABAS call - NAT-VTAM - waiting for VTAM I/O - NAT-PROC - executing NATURAL (CPU) - WAIT DET - waiting to be detached - TROUBLE - subtask in trouble - SETUP OK - subtask attached OK - TASKINIT - subtask is being initialized - IN SETUP - session is being setup - OPNDST E - in OPNDST END exit - LOGON EX - in LOGON exit - CLAIMED - TASKMAP entry has been claimed DDDDDDDD : Total database calls generated by the se ssion EEEEE : Total VTAM writes generated by the sessi ons FFF : Total CPU seconds consumed by the sessio ns GGGGGGG : Seconds since last VTAM input was receiv ed

Meaning: In response to the STATUS,UID= or STATUS,TID= command, a session summary is display for each selected session.

Action: None.

176I ST DUMP1: CPST:AA CPREQST:BB CPTIME:CC CPFLAG1:DD

177I ST DUMP2: SNAPMIN:EEEE INT:FFFF WAITSTCK:GGGGGGGG CPECB:HHHHHHHH

AA : GLOBMAP CPST Flag BB : GLOBMAP CPREQST Flag CC : GLOBMAP CPTIME Flag DD : GLOBMAP CPFLAG1 Flag EEEE : GLOBMAP SNAPMIN field FFFF : GLOBMAP SNAPINT field GGGGGGGG : GLOBMAP WAITSTCK field HHHHHHHH : GLOBMAP CPECB field

M E S S A G E S


Meaning: In response to the STATUS,DUMP command, internal fields and flags are displayed from the address space GLOBMAP control block for diagnostic purposes.

Action: None.

178I Usermax now set to:NNNNN NNNNN : usermax

Meaning: In response to the USERMAX= command, the global usermax has been set to NNNNN.

Action: None.

179E Usermax invalid - enter number from 0 to 1000

Meaning: In response to the USERMAX= command, an invalid new value for the global usermax was specified.

Action: Correct the usermax parameter.

180I Nimble UID:UUUUUUUU TID:VVVVVVVV Cancelling TID:CCCCCCCC UUUUUUUU : Nimble UserID performing the cancel VVVVVVVV : Nimble terminal id performing the cancel CCCCCCCC : Terminal id being cancelled.

Meaning: The user UUUUUUUU on terminal VVVVVVVV has used the Nimble user cancellation facility to cancel the session on terminal CCCCCCCC.

Action: None.

181I File:FFFFFFFF is in use by:NNNN users FFFFFFFF : filename NNNN : number of users having the file open

Meaning: In response to the SHOW,FILE= command, the number of users currently using file FFFFFFFF is reported.

Action: None.

190S Initial QEDIT Failed

Meaning: The NIM Operator Task was unable to establish console communication. This message will be followed by a User Abend 190.


200E VTAM error, TID:VVVVVVVV Rtncd:HHHHHH Sense:SSSS Cmd:CC VVVVVVVV : SLU name (terminal ID) HHHHHH : VTAM RPL Feedback code SSSS : VTAM RPL Sense code

M E S S A G E S


CC : VTAM command

Meaning: The VTAM command, type CC issued to LU VVVVVVVV received return code HHHHHH and sense code SSSS. NIM will terminate the session.

Action: Diagnose the error using the appropriate VTAM programming reference - RPL Feedback codes. Verify that the communications network and the terminal equipment are functioning normally. Ensure that the terminal and either the default logmode or any explicitly provided logmode is correctly defined for the characteristics of the terminal. Determine whether any other VTAM applications can be accessed from the terminal. If the problem is not obvious, and VTAM definitions seem appropriate, describe the error to NIM technical support.

201E LOAD ERROR, TID:VVVVVVVV MODULE TYPE:MMMMMMMM NAME:NNNNNNN VVVVVVVV : SLU name (terminal ID) MMMMMMMM : Type of the module being loaded - ADALNK - ADABAS linkage module - NATNUC - NATURAL nucleus - LDUSEREX - a logical driver user exit - NATEND - program specified by NATURAL to be executed at session termination NNNNNNNN : Name of the module being loaded

Meaning: A load module of type MMMMMMMM and name NNNNNNNN could not be loaded. NIM will terminate the session.

Action: For modules of type ADALNK, NATNUC and LDUSEREX, correct the logical driver parameters which contain the names of these modules. For modules of type NATEND, correct the NATURAL programs which set the post-session processing program.

Check that the NIM job STEPLIB libraries have not gone to additional extents since the NIM job was started.

Check that sufficient virtual memory exists to load the module into memory.

202E Nat Sess Err, TID:VVVVVVVV RC:HHHHHHHH - LLLLLLLLLLLLL.. VVVVVVVV : SLU name (terminal ID) HHHHHHHH : Return code from the NATURAL nucleus LLLLLL.. : Return message set by the NATURAL nucleus

Meaning: The NATURAL session completed abnormally.

Action: The message set by NATURAL (LLLLLL....) will normally contain a NATURAL message number and text describing the error. Refer to the NATURAL error message manual to diagnose the problem.

203E GETMAIN FAILED, TID:VVVVVVVV TYPE:IIIIIIII SIZE:SSSSSSSS VVVVVVVV : SLU name (terminal ID) IIIIIIII : NATURAL memory type

M E S S A G E S


SSSSSSSS : Size of memory requested

Meaning: A request to acquire (GETMAIN) some virtual memory on NATURAL's behalf failed. NATURAL will be informed of this condition, and will normally terminate the session. The type of memory requested (IIIIIIII) is documented in the NATURAL CMIOCB DSECT (distribution library source member).

Action: Review the size of NATURAL memory parameters (ESIZE, FSIZE, SORTSIZ, DSIZE, etc, especially those required by NATURAL subsystems).

Monitor the impact of large 3GL/assembler modules (particularly those that are not reentrant) using the NIMBLE Module and Memory utilities.

Review the virtual region allocated to the NIM job, and the NIM parameter settings for USERMAX, MEMTESTH and MEMTESTL.

Consider using the MTRACE=Y logical parameter to trace the memory type and size requested by NATURAL

If help is required, contact NIM technical support.

204E FREEMAIN FAILED, TID:VVVVVVVV ADDR:AAAAAAAA SIZE:SSSSSSSS VVVVVVVV : SLU name (terminal ID) AAAAAAAA : Address of memory to be freed SSSSSSSS : Size of memory to be freed

Meaning: A request to release (FREEMAIN) some virtual memory on NATURAL's behalf failed. This condition usually indicates that some NATURAL control blocks have been corrupted.

Action: Ensure that 3GL and assembler subroutines are not causing memory corruption, and that NATURAL is at the latest ZAP levels.


205E DELETE FAILED, TID:VVVVVVVV MODULE:NNNNNNNN VVVVVVVV : SLU name (terminal ID) NNNNNNNN : Name of module to be deleted

Meaning: A request to delete a load module on NATURAL's behalf failed. This condition usually indicates that some NATURAL control blocks have been corrupted.

Action: Ensure that 3GL and assembler subroutines are not causing memory corruption, and that NATURAL is at the latest ZAP levels. If help is required, contact NIM technical support.

206E PROGRAM CHECK, TID:VVVVVVVV TYPE:TTTT PSW:PPPPPPPP

207E TID:VVVVVVVV NATLIB/PROG:LLLLLLLL/NNNNNNN IN SUBRTN:S

M E S S A G E S


208E TID:VVVVVVVV R0-3:RRRRRRRR RRRRRRRR RRRRRRRR RRRRRRRR


208E TID:VVVVVVVV R8-B:RRRRRRRR RRRRRRRR RRRRRRRR RRRRRRRR

208E TID:VVVVVVVV RC-F:RRRRRRRR RRRRRRRR RRRRRRRR RRRRRRRR VVVVVVVV : SLU name (terminal ID) TTTT : Abend code PPPPPPPP : Program status word (PSW) at time of abend LLLLLLLL : Active NATURAL library NNNNNNNN : Active NATURAL program S : "In 3GL/assembler external subroutine" flag - Y yes - executing in a program called via CMOCAL - N no - executing in NATURAL, in a CSTATIC program, or in the NIM Driver, user exit or ADALNK RRRRRRRR : General register at time of abend

Meaning: A program check (or abend) has occurred in the NIM NATURAL subtask. The type of abend (TTTT) is prefixed by an "S" for system abend or "U" for user abend. The PSW, current NATURAL library and program and registers at time of abend are displayed.

Action: If the abend has occurred in a 3GL or assembler subroutine then correct the subroutine. Beware of subroutines that require 24 bit parameters and assume offsets past specified parameters (refer to the section "3GL and Assembler Subroutine Support" on page 54).

Ensure that NIM and NATURAL are at their latest ZAP levels. The NATURAL "DUMP" program can be used by experienced assembler programmer to diagnose many problems. However, if a complete operating system sump is required, reproduce the error whilst logged on to a logical driver with the logical driver DUMP=Y parameter specified, and include a //SYSUDUMP DD or //SYSABEND DD JCL statement in the NIM JCL.


209E Natural not prepared for Program Check, TID:VVVVVVVV VVVVVVVV : SLU name (terminal ID)

Meaning: A program check has been trapped by the NIM abend recovery environment for the session at terminal VVVVVVV. However, the NATURAL retry routine is not able to attempt a recovery, possibly because the NATURAL environment has not been completely initialized. The session will be terminated.

Action: Ensure that 3GL and assembler subroutines are not causing memory corruption, and that NATURAL is correctly configured, that the NATURAL DUMP=NO parameter has been specified and that NIM and NATURAL are at their latest

M E S S A G E S


zap levels. If help is required, contact NIM technical support.

210E Program Check recovery limit exceeded, TID:VVVVVVVV VVVVVVVV : SLU name (terminal ID)

Meaning: A program check has been trapped by the NIM abend recovery environment for the session at terminal VVVVVVV. However, the logical driver determined recovery retry count (as specified by the ABMAX parameter) has been exceeded. The session will be terminated.

Action: Determine the causes of the repeated abends that are occurring. If these abends are "normal" (e.g., caused by repeatedly attempting to browse unallocated storage when using the NATURAL "DUMP" or NIM "NATLOOK" program), then consider increasing the value of the ABMAX parameter in the environments in which these utilities are used. If help is required, contact NIM technical support.

212E Fatal Cpu loop, TID:VVVVVVVV Nat Lib/Prog:LLLLLLLL/NNNNNNN VVVVVVVV : SLU name (terminal ID) LLLLLLLL : Active NATURAL library NNNNNNNN : Active NATURAL program

Meaning: The NIM CPU timing exit has been reentered after informing NATURAL that a CPU loop condition exists, without NATURAL resetting the CPU loop condition by issuing a screen I/O. The session will be terminated. This problem may be caused by "excessive" CPU usage in an external 3GL or assembler subroutine.

Action: If a large amount of CPU time is being consumed in assembler subroutines, review the NATURAL MT parameter value. This problem may also be caused by recursion in NATURAL error transactions, so check ON ERROR clauses and the *ERROR-TA program in the application. Ensure that NATURAL is at the latest ZAP levels. If help is required, contact NIM technical support.

213E NO SDWA IN ESTAE EXIT, TID:VVVVVVVV VVVVVVVV : SLU name (terminal ID)

Meaning: A program check (or abend) has occurred in the NIM NATURAL subtask, but the operating system could not acquire the abend recovery work area (SDWA), which usually indicates a chronic virtual memory shortage.

Action: Increase the virtual region allocated to the NIM address space or reduce the number of concurrent users per address space. Describe the problem to NIM technical support.

214E Abend, TID:VVVVVVVV Type:TTTTAAAA SYS PSW:PPPPPPPP

215E TID:VVVVVVVV EPName:EEEEEEEE Addr:YYYYYYYY

M E S S A G E S


USERPSW:UUUUUUUU

216E TID:VVVVVVVV Natlib/Prog:LLLLLLLL/NNNNNNN In Subrtn:S



217E TID:VVVVVVVV R8-B:RRRRRRRR RRRRRRRR RRRRRRRR RRRRRRRR

217E TID:VVVVVVVV RC-F:RRRRRRRR RRRRRRRR RRRRRRRR RRRRRRRR VVVVVVVV : SLU name (terminal ID) TTTT : Abend code type - SYS - USER AAAA : Abend code type PPPPPPPP : System program status word at time of abend EEEEEEEE : Active entry point program name YYYYYYYY : Active entry point program address UUUUUUUU : User program status word at time of abend LLLLLLLL : Active NATURAL library NNNNNNNN : Active NATURAL program S : "In 3GL/assembler external subroutine" flag - Y yes - executing in a program called via CMOCAL - N no - executing in NATURAL, in a CSTATIC program, or in the NIM Driver, user exit or ADALNK RRRRRRRR : General register at time of abend

Meaning: A program check (or abend) has occurred in the NIM NATURAL subtask. The type of abend (TTTT), the abend code, the system and user PSW's, current NATURAL library and program and registers at time of abend are displayed.

Action: If the abend has occurred in a 3GL or assembler subroutine then correct the subroutine. Beware of subroutines that require 24 bit parameters and assume offsets past specified parameters (refer to section 4.6). Ensure that NIM and NATURAL are at their latest ZAP levels. The NATURAL "DUMP" program can be used by experienced assembler programmer to diagnose many problems. However, if a complete operating system sump is required, reproduce the error whilst logged on to a logical driver with the logical driver DUMP=Y parameter specified, and include a //SYSUDUMP DD or //SYSABEND DD JCL statement in the NIM JCL. If help is required, contact NIM technical support.

218S TID:VVVVVVVV TERMMAP CORRUPTION FOUND BY MMMMMMMM VVVVVVVV : SLU name (terminal ID) MMMMMMMM : NIM driver routine discovering the corruption

M E S S A G E S


Meaning: The NIM driver checks the structure of its main subtask control block (TERMMAP). If any corruption is detected, this message is produced and the subtask is abended with user abend code 218.

Action: Ensure that NIM and NATURAL are at their latest ZAP levels. The system dump and job log should be provided to NIM technical support.

219W TID:VVVVVVVV Unknown Service Code: HHHHHHHH VVVVVVVV : SLU name (terminal ID) HHHHHHHH: Invalid service code

Meaning: The NIM driver service process has been called with an unknown service code.

Action: Report the error to NIM technical support.

240E TID:VVVVVVVV Dynalloc of INTRDR failed, Err:HHHHHHHH VVVVVVVV : SLU name (terminal ID) HHHHHHHH : Dynamic allocation return code

Meaning: The NIM-NATURAL job submission interface ("NATRJE" support program) attempted to dynamically allocate an internal reader (required for job submission). The dynamic allocation error was HHHHHHHH.

Action: Diagnose the error using the appropriate systems programming reference - dynamic allocation return codes. If help is required, contact NIM technical support.

241E TID:VVVVVVVV Open of INTRDR file:FFFFFFFF Err:HHHHHHHH VVVVVVVV : SLU name (terminal ID) FFFFFFFF : Filename of dynamically allocated internal rdr HHHHHHHH : OPEN SVC return code

Meaning: The NIM-NATURAL job submission interface ("NATRJE" support program) attempted to open the file just allocated to the internal reader, but the OPEN failed.

Action: Describe the error to NIM technical support.

242I TID:VVVVVVVV Getmain id:III A:AAAAAAAA L:LLLLLLLL VVVVVVVV : SLU name (terminal ID) III : NATURAL memory type AAAAAAAA : Address of memory required LLLLLLLL : Size of memory requested

Meaning: NATURAL has instructed the NIM driver to acquire (GETMAIN) some memory on its behalf. The logical driver parameter MTRACE has been set to "Y", causing all memory operations to be logged to the system console and job log. The NATURAL memory type (III) is documented in the NATURAL CMIOCB DSECT (distribution library source member).

Action: Used for diagnostic purposes.

M E S S A G E S


243I TID:VVVVVVVV Freemain A:AAAAAAAA L:LLLLLLLL VVVVVVVV : SLU name (terminal ID) AAAAAAAA : Address of memory required LLLLLLLL : Size of memory requested

Meaning: NATURAL has instructed the NIM driver to release (FREEMAIN) some memory on its behalf. The logical driver parameter MTRACE has been set to "Y", causing all memory operations to be logged to the system console and job log.

Action: Used for diagnostic purposes.

260E TID:VVVVVVVV Invalid DB2 SSID specified:UUUU, overridden with:SSSS

261E TID:VVVVVVVV Natlib/Prog:LLLLLLLL/NNNNNNNN Plan:PPPPPPPP VVVVVVVV : SLU name (terminal ID) UUUU : Requested DB2 subsystem id SSSS : NIM GLOBAL SSID parameter DB2 subsystem id LLLLLLLL : Active NATURAL library NNNNNNNN : Active NATURAL program PPPPPPPP : Plan being selected.

Meaning: A NATURAL program (NNNNNNNN in library LLLLLLLL) has requested connection to the DB2 subsystem UUUU using plan PPPPPPPP. However, when NIM was started, the GLOBAL SSID parameter caused the main NIM address space task to establish a connection with DB2 subsystem SSSS. As DB2 will allow only 1 subsystem to be used from an address space, the request is overridden.

Action: Check programs using the NATURAL DB2 dynamic plan selection facility for incorrect sub system specification.

262E TID:VVVVVVVV Editor - Logical File Error: hhhh VVVVVVVV : SLU name (terminal ID) hhhh : RPL Error Code.

Meaning: The NIM Driver Editor Work File Manager received a Logical File error code whilst attempting to Get or Put a record.

Action: Ensure that the Editor File definitions are correct. If so, report the error to NIM technical support.

263E TID:VVVVVVVV Editor - Physical File Error: hhhh VVVVVVVV : SLU name (terminal ID) hhhh : RPL Error Code.

Meaning: The NIM Driver Editor Work File Manager received a Physical File error code whilst attempting to Get or Put a record.

M E S S A G E S



264E TID:VVVVVVVV Editor - Bad Lrecl - RPL:rrrrrrrr PRM:pppppppp VVVVVVVV : SLU name (terminal ID) rrrrrrrr : RPL Record Length pppppppp : Passed Record Length

Meaning: The NIM Driver Editor Work File Manager read a record which has a record length different to that requested.


265E TID:VVVVVVVV Editor - I/O Error in:rrrrrrrr RC:hhhhhhhh VVVVVVVV : SLU name (terminal ID) rrrrrrrr : Request type hhhhhhhh : Return Code

Meaning: The NIM Driver Editor Work File Manager received an error whilst processing the indicated request.

Action: Report the error to NIM technical support.

266E Invalid DS: dsname1 DS: dsname2 dsname1 : dsname from JFCB dsname2 : dsname provided

Meaning: The NIM Driver Editor Work File Manager detected an inconsistency with the dataset name originally opened and the dsname provided.


280E Resource release Dynfree failed, DD:FFFFFFFF Err:RRRRRRRR FFFFFFFF : filename RRRRRRRR : dynamic deallocation return code

Meaning: After subtask termination, the NIM address space control program attempts to dynamically free any files left allocated by the subtask. An attempt to free file FFFFFFFF has failed, with deallocation return code RRRRRRRR.

Action: Diagnose the error using the appropriate systems programming reference - dynamic allocation return codes. If help is required, contact NIM technical support.

281E Missing message skeleton:NNNN NNNN : message number without a skeleton

Meaning: The NIM message production subroutine has been passed a message number for which no entry in the NIM message skeleton list (NIMTPWTL) exists.

M E S S A G E S


Action: Ensure that during message customization, skeletons were not deleted (refer to the section "Error! Reference source not found." on page Error! Bookmark not defined.). If help is required, contact NIM technical support.

290I In cleanup, TID:VVVVVVVV Flags:FFFFFFFF VVVVVVVV : SLU name (terminal ID) FFFFFFFF : TASKMAP flags

Meaning: A NATURAL subtask is being cleaned up (detached and VTAM session released) for terminal VVVVVVVV. The current status of the session if recorded by the flag settings FFFFFFFF. This message is only output when the debug mode has been selected.

Action: None.

291I LLLLLLLLLLLLLLLLLLLL HEX:HHHHHHHH LLLLLL.. : arbitrary debug text FFFFFFFF : arbitrary debug hexadecimal value

Meaning: A message has been output for diagnostic purposes (the debug mode has been selected).

Action: None.

292W TID:VVVVVVVV LLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLL VVVVVVVV : SLU name (terminal ID) LLLLLL.. : arbitrary debug text

Meaning: A message has been output for diagnostic purposes (the debug mode has been selected).

Action: None

420I 'Subspace service is not available on this operating system'

421I ' Continuing without subspace protection'

Meaning: The operating system under which you are running NIM does not support Subspaces. NIM will continue, but you will not have the benefits of Subspace storage protection.

These two messages 420 & 421 are always output together.

Action: Either continue with this situation or change to an operating system that supports Subspaces.

422I '<module-name>: NIM Subspace Creation in progress'

Meaning: This is an informative message to let you know that NIM is about to acquire its working memory (which is called Subspace Storage). This memory is required

M E S S A G E S


even if Subspace services are not available or not in use. If Subspace services are available and in use, NIM will also create its major working subspace called the Global Subspace.

Action: None.

423I '<module-name>: Subspace protection disabled at user request'

424W ' Unpredictable results and storage corruption may result'

425I ' Subspaces are available. You are strongly advised to use them'

Meaning: This is a set of messages to let you know that you have requested NIM to not use Subspace storage protection even though the operating system supports that service. IE. PARM=NOSS has been specified on the JCL EXEC statement for NIM.

Action: As the message says, you are strongly advised to remove the PARM=NOSS from the EXEC statement and use the storage protection afforded by this release of NIM. The authors and distributors of NIM cannot be responsible for inter-task storage corruption if you use PARM=NOSS.

426S '<module-name>: Failed to obtain <type> storage,'

Meaning: There is a storage shortage above the 16Mb line. NIM was unsuccessful in obtaining the type of storage mentioned.

If <type> has the value ‘subspace’ then, during initialisation, NIM was unable to obtain enough storage for all possible user sessions. NIM cannot continue and terminates with user abend 426.

If <type> has the value ‘PC1 work’ then, NIM was unable to obtain working storage to initialise the session for a user who was attempting to log in. The login attempt is terminated with abend 426.

If <type> has the value ‘PC2 work’ then, NIM was unable to obtain working storage when processing the NONSWAP=Y parameter. NIM cannot continue and terminates with user abend 426.

This message is accompanied by messages 427I which details how many bytes of storage were wanted and how many were available

Action: Rerun NIM with a larger address space. (It is recommended to run NIM with the JCL EXEC statement specification of REGION=0M so that NIM can use as much virtual memory as it needs.) If the problem persists contact your NIM supplier for support.

427I ' Bytes wanted in R3, bytes obtained in R2'

Meaning: This message accompanies several other NIM messages. It specifies that in the register summary in the NIM joblog or abend dump, the number of bytes of storage that NIM requested is in register 3 and the number of bytes the system

M E S S A G E S


could supply is in register 2.

Action: As for the accompanying message.

427S 'NIMTPAUT: Could not make eligible subspace storage,'

Meaning: NIM was unsuccessful in its attempt to reserve above the 16Mb line storage to be used for subspaces. This message is accompanied by message 429I. NIM could not continue.

Action: Contact your NIM supplier for support. Have the values of register 2 (the return code) and register 3 (the reason code) available.

429I ' RC in R2, Reason in R3'

Meaning: This message accompanies several other NIM messages. It specifies that in the register summary in the NIM joblog or abend dump, the return code from the function that failed is in register 2 and the reason code that qualifies the return code is in register 3.


430S 'NIMTPAUT: Could not create subspace,'

Meaning: If this message is issued during NIM initialization, NIM was unsuccessful in its attempt to create the Global Subspace. NIM cannot continue.

� If this message is issued during a session logon attempt, NIM was unsuccessful in its attempt to create that session’s subspace. The session cannot continue.

� This message is accompanied by message 431I.

Action: Contact your NIM supplier for support. Have the dump and NIM joblog available.

431I ' RC in R2, Reason in R3, @ in R7'

Meaning: This message accompanies message 430S. It specifies that in the register summary in the NIM joblog or abend dump, the return code from the subspace create is in register 2, the reason code that qualifies the return code is in register 3 and the address of the storage that was to have been used for the subspace is in register 7.


432S 'NIMTPAUT: Could not assign subspace storage,'

Meaning: If this message is issued during NIM initialisation, NIM was unsuccessful in its attempt to associate a block of memory with the Global Subspace. NIM cannot continue.

M E S S A G E S


If this message is issued during a session logon attempt, NIM was unsuccessful in its attempt to associate a block of memory with that session’s subspace. The session cannot continue.

This message is accompanied by message 429I.


433S 'NIMTPAUT: Could not add subspace to DU-AL,'

Meaning: If this message is issued during NIM initialisation, NIM was unsuccessful in its attempt to register the Global Subspace with the operating system. NIM cannot continue.

If this message is issued during a session logon attempt, NIM was unsuccessful in its attempt to register that session’s subspace with the operating system. The session cannot continue.

This message is accompanied by message 434I.


434I ' RC in R2'

Meaning: This message accompanies several other NIM messages. It specifies that in the register summary in the NIM joblog or abend dump, the return code from the function that failed is in register 2.


435S 'NIMTPAUT: NIMTPCP terminated with unrecoverable error'

Meaning: The NIM mainline task has abended. Messages explaining the abend will have been produced and (possibly) a dump taken

Action: Take the action specified for the mainline task abend and accompanying messages.

436S 'NIMTPWTO fatal error: can't find NIMTPCP's RSA'

Meaning: This is an internal NIM error.


437S 'NIMTPAUT: Could not attach NIMTPCP'

Meaning: NIM was unsuccessful in its attempt to start the NIM mainline task. This message is accompanied by message 434I. NIM cannot continue.

M E S S A G E S


Action: Check that the load module ‘NIMTPCP’ is in the //PROGLIB DD concatenation and not in the STEPLIB. Check that NIMTPCP is linked as not APF authorised.

438I <ctl-area-name> is/are at <address>'

Meaning: This is an informative message, issued during NIM startup, that displays the memory address of one or more of NIM’s major control blocks and/or storage areas.

During NIM initialization, the address of the Global Subspace storage area is always displayed. If you contact your NIM supplier for assistance, you may be asked to run NIM with parameter GLOBAL SHOWGADR=Y so that NIM displays the addresses of all its major areas.

Action: None, unless instructed otherwise by your NIM supplier.

439I 'Session <luname> < ctl-block-name > is at <address>'

Meaning: This is an informative message issued during session logon. It displays the memory address of the control blocks for the new session. By default, this message is not issued. If you contact your NIM supplier for assistance, you may be asked to run NIM with parameter GLOBAL SHOWSADR=Y so that NIM displays the addresses of a session’s major areas.

Action: None, unless instructed otherwise by your NIM supplier.

M E S S A G E S


Return codes from the dynamic print & work file

routines.

NIMALLS will return the condition code set by NIMDRNSP. NIMDRNSP will return the condition code set by NIMDRPWM. NIMDRPWM will return the condition code set by NIMTPDAS/NIMTPDAD or sets one of the following condition codes: 1 Invalid print/work file number 2 Unable to find a valid Print/Work file table entry in Natural's Print/Work table 5 Unable to locate NATAM01 (Natural's Print/Work File Manager) 8 Invalid function code

NIMTPDAS will return the DYNALLOC error code or set one of the following condition codes: 4 Missing DDNAME address or missing SYSOUT Class address or blank or invalid SYSOUT Class NIMTPDAD will return the DYNALLOC error code or set one of the following condition codes: 4 Missing DDNAME address or missing DSNAME address or blank or invalid DSNAME 12 Invalid value for SPACE type ie. Not Blocks, Cylinders not Tracks.

145

LOG RECORD LAYOUT

General Description

The logging record is an image of data which may be written to a dataset with REFM=FB and LRECL=160 if logging is enabled. Each record contains a header part, which includes a log record type (halfword) which has values 0,1,2,3 for open, NAT user session end, close, snapshot respectively. Type 2 has a session data part following the header, and type 4 has a snapshot data part following the header. Types 0 and 3 have no defined data following the header.

In the following layouts, all numeric information is in binary format unless otherwise indicated.

Header Layout

Offset Length Content

0 4 System date (YYYDD, packed decimal.

4 4 system time (centi-seconds after midnight)

8 4 Unused

12 8 VTAM application id of this NIM job

20 2 Record type: 0 Header 1 User session end layout 2 Snapshot layout 3 Trailer

22 2 Unused

Appendix

C


Session End Layout

Offset Length Content

24 8 VTAM terminal name

32 8 NIM user id (if set by user exit 1)

40 8 Logical driver name

48 1 Flag indicating NIM Component causing termination

‘D’ DRIVER

49 1 Termination error type flag

‘N’ Natural initialization error

‘I’ Timeout

‘U’ Unknown

‘1’ Aborted by User exit 1

‘V’ VTAM error

‘A’ Normal end

‘L’ Record load error

‘M’ Memory error

‘E’ Program check exceeded

‘S’ ESTAE abend

‘T’ Program timer loop

‘O’ User cancelled

50 1 Termination error subtype flag VTAM Command in error. (i.e.) 22 for Send, 23 for Receive.

L O G R E C O R D L A Y O U T


51 4 Termination reason code

Error Flag Value

Reason Code Sense Code

‘N’ Natural return code

‘V’ VTAM return code

VTAM sense code

‘L’ First 4 bytes of load module

Second 4 bytes of load module

‘M’ First 4 bytes of memory type

Second 4 bytes of memory type

‘1’ Filled by user exit

Filled by user exit

‘S’ USER/SYS

55 4 Termination sense code. See above table for values.

59 4 STCK time at logon

63 4 STCK time at logoff (Note: this time has been removed in NIM 3.08)

67 4 Worst host response time (STCK “seconds”)

71 4 STCK time at worst host response

75 8 NAT library at worst host response

83 8 NAT program at worst host response

91 4 Total host response time (STCK “seconds”)

95 4 Worst network response time (STCK “seconds”)

99 4 STCK time at worst network response

103 4 Total network response time (STCK “seconds”)

107 4 VTAM send count


111 4 VTAM receive count

115 4 VTAM bytes output

119 4 VTAM bytes input

123 4 NAT CPU time (centi-seconds)

127 4 Elapsed time in ADABAS calls (STCK “seconds”)

131 4 Elapsed time in DB2 calls (STCK “seconds”)

135 4 Count of ADABAS calls

139 4 Count of DB2 calls

143 4 Count trapped program checks

147 8 Last DB2 plan name used

Snapshot Area Layout

Offset Length Contents

24 4 Nr. Of complete NAT sessions so far

28 4 Total amount of NAT CPU used so far

32 4 Total Nr. ADABAS calls issued so far

36 4 Total time in ADABAS calls so far (STCK “seconds”)

40 4 Total DB2 calls issued so far

44 4 Total time in DB2 calls so far (STCK “seconds”)

48 4 Total VTAM sends so far

L O G R E C O R D L A Y O U T


Trailer Layout

Offset Length Contents

0 4 System date (YYYDD, packed decimal.

4 4 System time (centi-seconds after midnight)

8 8 VTAM application id of this NIM job

16 2 Record type

0 Header

1 User session end layout

2 Snapshot layout

3 Trailer

18 2

ZAPPING OPERATIONAL DEFAULTS

NIM is distributed with default settings likely to be applicable at most sites. Most of these defaults can be changed at run time by the specification of an NIM parameters. However, some settings can only be changed by zapping load module NIMTPINI.

Before zapping NIMTPINI we suggest that a backup copy of the module is made to expedite recovery in the case of an error.

The purpose, defaults and valid values for all zappable parameters is described in the section "Modifying NIM Operational Defaults" on page 45. The following table shows the settings that may be zapped, their format and offset within the NIMTPINI module.

Parameter Offset Default Value

Sample Zap

TASKMAP table entries

+0064 1020 VER 0064 000003FC REP 0064 000001F4

(set 500)

LOGICAL DRIVER table entries

+0068 40 VER 0068 00000028 REP 0068 00000032

(set 50)

Resource table size

+006C 32K VER 006C 00008000 REP 006C 00010000

(set 64K)

FILEMAP table entries

+0070 60 VER 0070 0000003C REP 0070 000000F0

(set 240)

VERBOSE-NESS level

+0074 3 VER 0074 03 REP 0074 02

(set 2)

ROUTECODE default

+0075 0 VER 0075 00 REP 0075 0B

(set 11)

NIM LOGGING

+0076 Y VER 0076 E8 REP 0076 D5

(set N)

NATURAL TPSYS type

+0077 TSO VER 0077 08 REP 0077 40

(set HOMEGROWN)

DEBUG +0078 NNNN VER 0078 D5D5D5D5 (set

Appendix

D

Z A P P I N G O P E R A T I O N A L D E F A U L T S


FLAGS type REP 0078 E8D5D5D5 YNNN)

SYSOUT CLASS default for screen dump

+007C A VER 007C C1 REP 007C C2

(set B)

NIM VERSION 4 RELEASE NOTES

NIM Version 4 is a major release of the NIM system. All functions have been redesigned and rewritten to achieve major functionality and reliability gains over the previous release (NIM V4.1.1). The results of user comments and suggestions and operational experiences over the past 8 years in a variety of high volume environments have formed the basis for this release. The major features of NIM V4.3 and important areas of difference with NIM V4.11 follow.

ADABAS and NATURAL

NIM V4.3.0 supports:

NATURAL V2.28, V2.3.x, V3.1.3 and higher;

ADABAS V5.2, V6.1, V6.2, V7.1 and higher.

Users will be able to provide support for ADABAS V4 themselves by providing their own ADALNK module. However, XA/ESA users will need to ensure that ADABAS parameter areas are copied down to below the 16MB line before the call and copied back above the line after the call, as ADABAS V4 does not support above the line parameter areas.

NATURAL V1.1 and V2.1 are not be supported at all by NIM V4.4.0.

Appendix

E

N I M V E R S I O N 4 R E L E A S E N O T E S


Above the Line Addressing

NIM V4 is written as a full 31-bit application. Where possible, all programs are RMODE ANY (i.e., can be loaded above the 16MB line) and all data areas are acquired above the line. Exceptions are the few programs which perform I/O and invoke some operating system services which require 24 bit addressing mode.

The main advantages of extended addressing capabilities are:

the number of concurrent users per NIM address space has increased, from 20 - 80 (with NIM 3.2.6 and NATURAL 2.1) to 500 - 1000 (with NIM 4 and NATURAL 2.3). The actual number of users accommodated depends on:

- below the line region size (approx. 3K below the line is required by the operating system and 4K by NIM/NATURAL for each additional user);

- above the line region size (some sites may enforce an arbitrary limit on the maximum above the line region size, reducing it from the theoretical 2GB maximum).

a large NATURAL global buffer pool can be placed above the line in extended CSA (ECSA) and utilized by all NATURAL using address spaces (NIM's, TSO and batch);

nearly all NIM and NATURAL modules can be placed above the line in the extended link pack area (ELPA), which improves efficiency (as the modules can be utilized by all NATURAL using address spaces) and improves reliability (as the LPA is protected from user mode memory corruption);

Users of 24 bit addressing mode operating systems can successfully use NIM V4 and NATURAL V2.3, but no advantages of extended addressing can be taken.

Link Pack Eligibility

The NIM V4. NATURAL driver could be configured to reside in the link pack area (LPA), hence providing for paging efficiency (many address spaces could share the one copy) and reliability (the LPA is protected against user memory overwrites).

All components of NIM V4 are reentrant, and most programs are RMODE ANY. Hence, NIM V4 can be optionally added to the LPA and ELPA. Additionally, the NATURAL driver can be added to the ELPA and the NATURAL environment-dependent module can be added to the LPA.

Due to the efficiency and reliability improvements achievable by adding these modules to LPA/ELPA, it is strongly recommended that sites with significant production NATURAL usage do so. It is particularly beneficial to add the NATUAL nucleus to the ELPA, as it is a large module required by all NATURAL using address spaces.



Physical Driver Splitting

In NIM V3.2.6, the NIM-NATURAL driver (NIMDR2) was linked with the NATURAL nucleus and additional components to form a single, monolithic and NIM dependent "physical driver".

With NATURAL 2.3 & 3.1 and NIM V4, a different approach is strongly encouraged whereby the "physical driver" is merely the NIM-NATURAL driver (NIM23NAT) which "loads" 2 further modules to implement an execution environment equivalent to the old monolithic physical driver.

The 2 further modules are:

the NATURAL environment DEPENDENT module, which consists of:

- the NATURAL parameter module

- the NATURAL print and work file support module (NATWKFO) which needs to be zapped to support 31 bit addressing (this zap is currently supplied with NIM V4);

- the NATURAL internal sort module, implementing the NATURAL "SORT" statement (the NATURAL external sort interface which calls the operating system sort cannot be used in 31 bit addressing mode due to a bug which corrupts the sort parameter list).

the NATURAL environment INDEPENDENT module, which consists the NATURAL nucleus, text modules, terminal support, etc.

NATURAL 2.3 & 3.1 allows for the flexible dissection of its functions between the environment dependent and independent modules (refer to the NATURAL 2.3, 3.1 Operations Manual for details). Some sites may build the environment dependent nucleus with more features (e.g., CON-NECT, TRS). The RMODE constraints have been removed in NIM V4 which means the environment dependent module can now be linked into the ELPA. This can give the advantage of an additional half megabyte below the line storage for user work areas (so called thread size).

Both the NIM physical driver and the NATURAL environment independent module can (and normally should) be linked into the ELPA.

NATURAL DB2 Support

Although NIM V3.2.6 was capable of running NATURAL DB2, NIM V4 adds several facilities to assist NATURAL DB2 users:

accounting - DB2 calls and elapsed time are accumulated for each user session;

dynamic plan switching is fully supported;

the DB2 "CONNECT" is made at the NIM address space level to the designated DB2 subsystem, eliminating the overhead of individual user DB2 "OPEN"'s.



DB2 users running under NIM can access all DB2 functions and facilities as NIM uses the Call Attach Facility ("CAF") interface. Restrictions and loss of functionality that occur when running NATURAL DB2 under CICS (such as loss of cursor on a screen I/O) do not apply under NIM. The performance problems of NATURAL CICS thread locking and queuing for CICS DB2 attachments are eliminated by NIM's true multi tasking design and use of the DB2 CAF interface.

Parameter Changes

NIM V5 introduces a variety of new parameters:

New GLOBAL parameters:

CONMSG – sets the message verbosity level. See messages section for more details;

NONSWAP=[Y/N], Y sets the NIM address space as non-swappable, the default is N. This parameter only applies if NIM is running in sub-space protection mode.

SHOWGADR=[Y/N], Y turns on the display of the addresses of NIM’s major areas and control blocks during NIM initialisation. The default is N with the exception of the Global Subspace storage area whose address is always displayed. This display is useful when debugging. It is normally turned off but NIM support may ask you to turn it on to assist with problem resolution.

SHOWGADR=[Y/N], Y turns on the display of the addresses of every session’s major areas and control blocks during session initialisation. The default is N.This display is useful when debugging. It is normally turned off but NIM support may ask you to turn it on to assist with problem resolution.

New LOGICAL DRIVER parameters:

NATNUC, name of the environment independent NATURAL driver to be loaded (or located in ELPA/LPA);

NONACTW, non activity interval after which a warning "BEEP" is sent to the terminal (previously hardcoded at 60 seconds before non activity interval expired);

VTAMBUFF, Size of the VTAM I/O buffer used for the session (previously hardcoded at 4000 bytes);

DEFRESP, Yes/No flag to indicate whether VTAM definite responses are required from the terminal after each screen transmission (previously hardcoded to "Yes");

DUMP, Yes/No flag to indicate whether a dump should be produced and the session terminated following any program exception or abend (this function was previously dependent on the name of the logical driver);



MTRACE, Yes/No flag to indicate whether a trace of all memory get and frees should be produced.

VTRACE, Yes/No flag to indicate whether a trace of all VTAM activity should be produced.

FREEBIND, Yes/No flag to indicate whether the VTAM BIND and LOGON MESSAGE areas should be freed by the driver before invoking NATURAL;

ACCPTMSG, Yes/No flag to indicate whether the logon ("greeting") message or broadcast messages should be sent to the terminal (the main use of this flag would be to prevent unsolicited messages from interfering with file transfers or "canned" dialogs).

Default logical driver parameters can now be established in the NIM parameter deck, avoiding the need to duplicate parameters common to all or most logical drivers.

Configurable Messages

The Write-to-operator (WTO) messages generated by NIM V4 are now configurable. By editing and reassembling a WTO text module, sites can change, selectively suppress or re-route any console message.

All messages are classified as either informational (I), warning (W), Error (E) or Very Serious (S). A simple zap can be applied to one module to allow automatic suppression of all I, or all I and W messages. A simple zap can also be used to change the default message route code.

Configurable Tables Sizes

Table sizes in earlier versions of NIM were hard coded and required extensive re-assembly to change. With NIM V4, all table sizes can be varied with simple changes to the NIMTOC, but in most cases this is not necessary:.

The default table sizes are:

user table - 1000 entries;

logical driver table - 40 entries;

file table (used for VSAM or other NIM controlled files) - 64.

NIMBLE Enhanced

The NIMBLE monitoring and control interface has been completely written as a standard NATURAL 3.1 structured mode application. Functionality has been greatly increased to facilitate the effective monitoring and control of hundreds of concurrent users.



“TSOPAK” Renamed “OS Functionality” and Greatly

Enhanced

Users under NIM are now able to reliably perform many of the functions for which access to TSO/ISPF or TSS/PFD was previously required, without leaving their NATURAL environment. Sequential and partitioned datasets can be browsed, edited, allocated and deleted. PDS members can also be renamed, deleted and printed. JCL can be submitted from sequential or partitioned datasets. Members and whole datasets can be copied. Users of the NIMSPOOL product can display, delete and copy job output, and print it on local or remote printers.

When NIM users have been identified to RACF (or ACF2), their RACF (ACF2) profile will be automatically used by the operating system when access to files using the NIM OS functionality (or any NIM-NATURAL work file support) is attempted. Security violations abends are trapped by NIM and reported to the user without the session being abnormally terminated.

Standard Batch Job Submission Support

NATURAL 2.2 and above defines an "official" standard for batch job submission from within a NATURAL session ("NATRJE"). NIM V4 fully supports this standard.

Online Print and Work File Support

NIM V5.00 continues full support for on-line NATURAL print and work files. Although new and improved call interfaces have been provided to these facilities with NIM V4.40, the old style interface (NIMALLP/W, NIMFREEP/W) will continue to be supported as well as the NIM V4 interfaces (NIMTPALP/W, NIMTPFRP/W). The new Print/Work file support interface (including NIMSPOOL) is called NIMDRPWM.

From Natural 2.3 onwards , there is no longer any need to apply a zap to enable Online Print & Work files.

NIM keeps track of all files dynamically allocated by an on-line user, and will automatically free any files not explicitly de-allocated when the user's session ends.

Support for 24-Bit Addressing Mode External Subroutines

NIM V5.00 does NOT support any Natural call to any 24-bit module. If such modules are called from within a Natural program the results will be unpredictable including various abends within the user sub-task.

Where an external subroutine uses parameter values not explicitly passed to it (e.g., by relying on a fixed offset from an explicit parameter), such processing will fail, as NIM cannot know what assumptions the external subroutine is making about the explicit parameter list.



User Exits Reorganized

NIM V4 user exits are organized into 3 sets:

Users exits invoked from the NIM Control Program:

UEXA Address-space initialization

UEXB Address-space termination

UEXC Prior to sub-task attach

UEXD Prior to sub-task detach

UEXE Logging

UEXF Upon expiration of main timer interval

Users exits invoked from the NIM VTAM-server:

UEXG Prior to parsing LOGON data

User exits invoked from NIM session driver modules:

UEX1 Prior to NATURAL invocation

UEX2 After NATURAL termination

UEX3 Prior to NATURAL output eg. VTAM screen write

UEX4 After input received for NATURAL eg. VTAM screen read

UEX5 Prior to NATURAL buffer pool call

UEX6 Prior toDB2 dynamic plan switch

UEX7 During Recovery/Termination (ESTAE) processing

The following areas are reserved for user exit or user program use:

4 full words in the address space global data area

4 full words in each user subtask primary data area

1 full word and 1 8 byte field in each logical driver entry

With NIM V4, an ECB is provided which the address space control program posts immediately prior to job termination.

NATGET/ NATSET Enhanced

The NATGET utility has been enhanced to additionally return:



the current NIM VTAM Application ID;

the current NIM Version number;

the current NIM Zap level;

the last program exception or abend code received by the user task (e.g. S0C4, S913, U199);

4 full words of user task data set by NATSET, user exits, etc - the current sysout class (for screen printing option).

The NATSET utility has been enhanced additionally to set:

the non activity timeout period for the user task;

4 full words of user task data;

VTAM application name to transfer to at end of NAT session;

broadcast message suppression flag on and off;

the current sysout class for (screen printing option).

Operator Interface

The Operator interface has been reorganized to reflect the internal changes to NIM V4 and the large number of users per address space. The emphasis has been shifted from long displays of all users to short specific displays of users and summaries.

Logging

The Logging record layout has been completely redesigned. As before, NIM V4 produces 4 types of log record:

address space start;

user task termination;

interval snapshot (address space summary) - address space termination.

The user task termination record includes more information on session termination (such as abend code, or VTAM FDBK and SENSE information), and separate fields for DB2 usage data. Network response time data is only included if the logical driver DEFRESP parameter is set to "Y".



The interval snapshot records are now produced at a user-specifiable interval which defaults to 15 minutes. Where possible, the production of this record type is synchronized with the hour, making reconciliation of NIM statistics with data from other sources easier. (E.g., if an interval of 20 minutes is specified, the interval snapshot records will be produced on the hour, and at 20 and 40 minutes past the hour. If an interval of say, 35 minutes were specified, then synchronization is not attempted.).

Incompatibilities with NIM V5.00 and V4.40

Data Structures

NIM V5.00 data structures are different from those of NIM V4.40 and V4.30. Thus, all NIM user exits and Assembler subroutines called from NATURAL that read or manipulate NIM or NATURAL control blocks must be reviewed modified and MUST be recompiled.

Because each user session runs in its own subspace it cannot even read the information in the major NIM control blocks. NIM routines that are called from Natural switch to full address space addressability when it is necessary to access NIM’s major control blocks. Similar to object oriented programming, a set of routines is provided to allow proper updating of these control blocks (see NIMSET and NIMGET). User code should NEVER, under any circumstances, be written to alter these areas directly.

CCA Software is available to provide assistance in this area or can be hired by sites needing to convert user exits and local NIM or NATURAL subroutines.

Log Records

The NIM logging data structure is also different, and existing user routines that manipulate NIM log data either directly or from SMF will need minor changes, mostly to their mapping of the log records.

WTO Messages

Many messages have been added in the 400 series. Existing AOF/AOM or other console message package or WTO exits that deal with NIM messages will need to be reviewed. In many cases, message suppression will be more efficiently performed by changing the NIM parameters rather than message filtering in WTO exits.

Miscellaneous Service Routines

The NIM V3 on-line print and work file routines (NIMALLP, NIMALLW, NIMFREEP, NIMFREEW, NIMALLS, NIMFREES) as well as the V4 routines (NIMTPALP, NIMTPALW, NIMTPFRP, NIMTPFRW) have been superseded, but are still compatibility supported for upwards compatibility. New users and applications should use the NIM V4.40 Print/Work file Management routine NIMDRPWM. A sub-program providing a generic API interface is available in the NIMUTILS library. This should be used in all new applications and should be progressively implemented in existing applications.

NIMSORT (aka AGSORT and SORT1D) work as before. AGSORT will attempt to acquire above the line memory in 31 bit addressing mode environments.

The NIMBLE program interface has been modified. Any sites requiring access to NIMBLE functions from their own programs should study the NATURAL source implementing the NIMBLE functions distributed with NIM..



The only job submission interface supported is the "NATRJE" interface.

User Exits

Existing user exits will not function with NIM V5. The new user exit structure should be studied with the new increased functionality in NATURAL 3 and NATURAL 4.1 in particular. RACF UserID authorization subroutines should consider generating the RACF ACEE in a task related, write protected subpool. This will support the maintenance of separate RACF profiles for each NIM user (1 user per subtask), which in turn will mean that the user will have dataset access consistent with their RACF profile whilst running under NIM. In addition, the RACF UserID propagation facility will result in any jobs being submitted by the user from NIM inheriting the user's RACF profile.

INDEX

A ADABAS linkage

generated userid, 48 Specification, 48

ADABAS Linkage, 48

B Batch job submission, 60 Batch Job Submission

NATRJE, 61

C Calling 3GLs, 6, 56, 132

accessing NIM control blocks, 59 calling ADABAS, 58 COBOL II, 59 Fujitsu PSECTs, 60 imported subroutines, 58 loaded below the line, 57 non-reentrant subroutines, 57 subroutines, 56

Commands file, 67 loading and unloading modules, 72 sending messages, 66 setting usermax, 72 setting XFER, 72 status, 69 user cancel, 65

Configuration DB2 call interface, 48 dynamic parameters, 47 LOGON, 47 Overview, 47 user exits, 49

Configuring the Natural Environment, 88 creating the NIM Natural environment, 90 dependent module, 88 ELPA, 88 independent nucleus, 88 logical driver, 89 Natparm module, 89

F File Parameters, 37

G Global Parameters, 12

H Hardcopy option

calling DB2TPHCP, 82

I Installation

ADALNK, 91 IPL, 87 logging on, 87 Natural INPL, 99 NIMBLE, 99 NIMOS, 99 overview, 83 SYS1.VTAMLST, 87 verifying the installation, 101 VTAM application, 87

J JCL

DDnames and components, 97 EXEC card, 96 NIM log, 97 parameter dataset, 97 STEPLIB, 96

L Log record

description, 141 header layout, 141 session end layout, 142 snapshot area layout, 144 trailer layout, 145

Logical DRIVER Parameters, 37 Logical Drivers, 92

M Messages

listed messages, 105

N NATGET

subfunctions, 79 NATSET

subfunctions, 80 NATURAL “PARM=” , 49, 50 NATURAL add-ons, 51

other products, 52 NATURAL buffer pool, 51


NATURAL DB2 considerations, 18, 52

NATURAL dynamic parameters, 49 NATURAL nucleus

components, 49 INCLUDE modules, 49 link attributes, 49 linking a common nucleus, 49

NATURAL VSAM, 52 NIM Introduction

products supported, 2 sub-tasking, 1 supported environments, 3 virtual storage management, 1

NIM parameters parm layout, 12

NIM Parameters, 11 file parameters, 37 FLEXPARMS, 39 global parameters, 12 setting up, 94

NIM User Exits user subtask, 46

NIM utility programs NATGET and NATSET Subroutines, 79

NIMBLE overview, 75 security, 76

NIMOS overview, 77 security, 77

O Online Print and Work Files, 53

allocating Print Files, 53 allocating Work Files, 54 freeing with DB2TPFRW, 55 using DB2TPALP, 54

using DB2TPALW, 55 Operational Characteristics

Architecture, 5 automated LOGON, 9 log record overview, 9 LPA/ELPA eligibility, 6 memory management, 6 multiple NIM regions, 6 security, 7

Operational Considerations session summary screen, 10

Operational defaults overview, 147 zap formats, 147 zapping, 147

Operator Interface commands, 63 overview, 63

P Parameters

changing sample, 95 Problem determination

OCx abends, 103 use NIMBLE, 103 VTAM, 103 VTAM trace, 104

R Release notes, 149

U User Exits, 40

address space exits, 40, 42, 60 task level exits, 43

NIM Users Guide - ccasoftware.com

Documents

Transcript of NIM Users Guide - ccasoftware.com