Version 4.2.6
 —  TP Monitor Interfaces  —

Natural under IMS TM - Configuration Macros

This document of the Natural IMS Interface documentation discusses the configuration macros of the Natural IMS Interface.

The following topics are covered:


NIMDRIV Macro Parameters

The macro NIMDRIV generates environment-dependent interfaces (drivers). The parameters which can be specified with the macro NIMDRIV are described below:

TYPE | LE370 | NIINAME | SUBPOOL | TRNCODE | THRELO

Parameter Possible Values Description Default Comment
TYPE CONV TYPE specifies the type of the driver to be generated.

In case of CONV, a dialog-oriented conversational environment is generated.

None None
NONC Dialog-oriented non-conversational environment is generated.
NTRD Message-oriented (not terminal-driven) environment is generated.
BMP Batch-oriented and transaction-oriented BMP environment is generated.

You can also use this interface in the DLIBATCH environment.

SRVD Server environment is generated.
LE370 YES LE370 specifies whether Natural under IMS initializes the IBM Language Environment.

In case of YES, the IBM Language Environment is initialized and remains so until the Natural IMS front-end returns to the IMS program controller.

LE-conforming 3GL programs are called according to the LE calling conventions. While the LE program has control, user written or language-specific condition handlers are honored.

NO None
AMODE24 The IBM Language Environment is initialized as in case of YES. In contrast to YES, the LE run-time options ALL31=(OFF),STACK=(,,BELOW) are set to support AMODE(24) 3GL programs. This option allows you to execute Natural in the IBM Language Environment (for example, because of the use of the REQUEST DOCUMENT statement) even though you are using AMODE(24) 3GL programs and the system defaults of the LE run-time options do not allow the execution of AMODE(24) 3GL programs.
NO The IBM Language Environment is not initialized. An IBM Language Environment is initialized and terminated for each LE program call.
NIINAME xxxxxxxx Specifies the name of the Natural IMS interface module to be used by the current driver. Any valid module name up to 8 characters is possible.. NIIINTFM None
SUBPOOL n

Specifies the z/OS subpool number for the STORAGE OBTAIN requests. Any valid z/OS task-related subpool number for a problem state program (0 – 127) can be used.

Note:
If you operate an earlier version of the Natural IMS TM interface in the same IMS TM dependent region, you should not use the subpool numbers 126 and 127.

125  
TRNCODE YES The optional TRNCODE parameter is honored. This applies to the NO  
NO The TRNCODE parameter is ignored.
THRELO YES Thread relocation is enabled, that is, the Natural thread may be allocated at a different virtual address after a terminal I/O. YES  
NO Thread relocation is disabled and the Natural thread stays at the same virtual address. The size of the Natural thread is determined by the first Natural session that allocates the thread. As consequence:
  • the Natural/IMS THSIZE parameter is ignored by all except for the first Natural session in an MPP,

  • RELO=FORCE is disabled,

  • the storage for the Natural thread remains allocated until the MPP is stopped.

Note:
This parameter should only be used by customers using Con-form.

Top of page

NIMPARM Macro Parameters

The macro NIMPARM generates parameter tables which are contained in the parameter module NIIPARM.

The parameters which can be specified with the NIMPARM macro are described below. The ENTRYNM parameter identifies the current parameter table.

The parameters are listed in alphabetical order below.

ACTACTV   | ACTAHDR   | ACTARID | ACTLOG | BMPABER | BROACTV | CMBSIZE | COLPSCR | ENDMODN | ENTRYNM | ERRLHDR | HCBSIZE | HDENSDU | LINPSCR | MISIZE | MONACTV | MOSIZE | MSACTV | MSCMPTB | MSCRKEY | MSDBD | MSMAX | MSRSKEY | NSBNAME | PRTDRIV | ROLLSRV | ROLLFN | SPASIZE | SPATID | SUPNONC | TERMDB | TERMIPL | THBELOW | THSIZE | USERID

Top of page

A

Parameter Possible Values Description Default Comment
ACTACTV YES ACTACTV specifies whether the accounting function is activated.

In case of YES, an accounting record is written with each terminal I/O.

NO Used in dialog-oriented environments only.
NO No accounting record is written.
ACTAHDR xxxxxxxx Defines the header of the accounting records if written to the IMS log file. Any string up to 8 bytes is possible. SAG$$$$$ The parameter is only evaluated when the ACTLOG parameter is set to CMD. It is used for the accounting function only.
ACTARID

log code

or

SMF record type

Specifies the accounting record ID if the accounting record is written using the LOG or SMF settings of the ACTLOG parameter.

None Used for the accounting function only.
Log code
(A0 - FF
When the ACTLOG parameter (see below) is set to LOG.
SMF record type
(128 - 255)
When the ACTLOG parameter is set to SMF.
ACTLOG CMD ACTLOG specifies how accounting records are written. In case of CMD, accounting records are written to the IMS log file using the CMD call. CMD Used for the accounting function only.
LOG Accounting records are written to the IMS log file using the LOG call.
SMF Accounting records are written to SMF using the Authorized Services Manager.

Top of page

B - C

Parameter Possible Values Description Default Comment
BMPABER YES

BMPABER specifies how a BMP run should be terminated if either a Natural runtime error or a Natural IMS interface non-recoverable error occurs.

In case of YES, the BMP run is abended with user Abend Code U3521.

NO None.
NO The BMP run is terminated normally with the Natural termination error as the condition code. If the BMP run is terminated with a non-recoverable Natural IMS error, condition code 1024 is set.
BROACTV YES Specifies whether the broadcasting function is available or not. NO Used in dialog-oriented environments only.
NO
CMBSIZE xxxxx Specifies the size of the command buffer in bytes. Any numeric value up to 16 MB is possible. 1024

The command buffer is used by the service APIs NIICMD and NIIGCMD, the service module CMCMMND and the Accounting function.

The size of the command buffer must accommodate the maximum length of the IMS commands to be processed and the maximum length of the accounting record including the user extension.

COLPSCR xx Specifies the number of columns per screen. Any valid screen width (numeric) is possible. 80 None.

Top of page

E - H

Parameter Possible Values Description Default Comment
ENDMODN xxxxxxxx Specifies the MOD name for formatting the screen which appears after a Natural session is terminated successfully. Any valid MOD name up to 8 characters is possible. DFSMO2

Enables Natural to be included in a customer-specific menu.

The value of the ENDMODN parameter can be overridden by the service API NIIEMOD and the service module CMEMOD.

If a Natural session terminates with an error, DFSMO2 is always used to issue the appropriate Natural error message.

ENTRYNM xxxxxxxx Identifies the current parameter table. Any string up to 8 characters is possible. ENV00000 None.
ERRLHDR xxxxxxxx Specifies the header of the IMS log records which are written when errors occur in the Natural IMS interface. Any string up to 8 characters is possible. NIIERR$$

If you do not wish a message to be written to the IMS log in the case of a non-recoverable Natural IMS error, set the ERRLHDR parameter explicitely to null, that is, specify ERRLHDR=,.

For further information, see Recovery Handling.

HCBSIZE xxxxx Speicifies the size in bytes of the hardcopy print buffer. Any numeric value up to 16 MB possible. 1024 Records which are sent to a printer destination using the Natural hardcopy function are buffered.
HDENSDU YES Specifies whether a snap dump provoked by a Natural IMS error should be written as a high-density dump to a 3800 printing subsystem or not. NO None.
NO

Top of page

L - N

Parameter Possible Values Description Default Comment
LINPSCR xx Defines the number of lines per screen. Any valid screen size (numeric) is possible. 24 None.
MISIZE xxxxx The size in bytes of the buffer which is to contain the input message. Any numeric value up to 16 MB is possible. 4096 This area must be as large as the largest input message to be received from IMS TM.
MONACTV YES MONACTV specifies whether the monitoring function is activated.

In case of YES, the session status is written to the SIP server at each terminal I/O.

NO Used in dialog-oriented environments only.
NO No session status is maintained.
MOSIZE xxxxx The size in bytes of the buffer which is to contain the output message. Any numeric value up to 16 MB is possible. 4096 This area must be as large as the largest output message to be sent to IMS TM.
MSACTV YES Specifies whether the multi-session function is available or not. NO Used in dialog-oriented environments only.
NO
MSCMPTB YES Specifies whether sessions are switched in a mode compatible with Natural IMS Interface Version 2.2/Natural under IMS TM Advanced Interface Version 2.2 or not. NO Used for the multi-session function only.
NO
MSCRKEY NONE Specifies with which PF keys a new session can be started. NONE Used for the multi-session function only.

If MSCMPTB=YES, MSCRKEY must be set to NONE.

PF1 - PF24
MSDBD DBD-name Specifies the name of the multi-session database. Any valid DBD name is possible. None Used for the multi-session function only.
MSMAX 2 - 9 Specifies the highest possible number of parallel Natural sessions per terminal. 9 Used for the multi-session function only.
MSRSKEY NONE Specifies the PF key with which an old session can be restarted. NONE Used for the multi-session function only. MSRSKEY must be set to NONE, if MSCMPTB=YES.
PF1 - PF24
NSBNAME PSBNAME Set the NSB name to the PSB name used by IMS TM. PSBNAME Used by the Natural for DL/I interface.
NIITRTAB Set the NSB name to the PSB name that is assigned in the transaction code table NIITRTAB to the transaction code in use.

Top of page

P

Parameter Possible Values Description Default Comment
PRTDRIV See tables of drivers below.

Drivers for SCS Printers
Drivers for Non-SCS Printers
Drivers for JES API

Specifies the print driver to be used for reports which are directly written to an IMS TM printer. SCS_S2 For further information, see Support of the Natural WRITE(n) Statement

Drivers for SCS Printers

Driver Purpose
SCS_B1 Form feed at start and end of report, starts page on line 1.
SCS_B2 Form feed at start and end of report, starts page on line 2.
SCS_E1 Form feed at end of report, starts page on line 1.
SCS_E2 Form feed at end of report, starts page on line 2.
SCS_N1 No form feed at start or end of report, starts page on line 1.
SCS_N2 No form feed at start or end of report, starts page on line 2.
SCS_S1 Form feed at start report, starts page on line 1.
SCS_S2 Form feed at start of report, starts page on line 2.

Drivers for Non-SCS Printers

Driver Purpose
NSCS_B1 Form feed at start and end of report, starts page on line 1.
NSCS_B2 Form feed at start and end of report, starts page on line 2.
NSCS_E1 Form feed at end of report, starts page on line 1.
NSCS_E2 Form feed at end of report, starts page on line 2.
NSCS_N1 No form feed at start or end of report, starts page on line 1.
NSCS_N2 No form feed at start or end of report, starts page on line 2.
NSCS_S1 Form feed at start report, starts page on line 1.
NSCS_S2 Form feed at start of report, starts page on line 2.

Drivers for JES API

Driver Purpose
JES In this case, the following dataset processing options for JES are taken from the corresponding NTPRINT macro parameters or DEFINE PRINTER statement options:
JES NTPRINT DEFINE PRINTER
CLASS CLASS CLASS
COPIES COPIES COPIES
DEST DEST OUTPUT
FORMS FORMS FORMS
NAME NAME NAME
OUTDISP DISP DISP
PRTY PRTY PRTY

The generated JES API parameter string is:

IAFP=A0M,PRTO=..OUTDI(disp),DES(dest),
CLA(class,COP(copies),
FORMS(forms),NAME(name),
PRTY(prty)

Note:
Unspecified NTPRINT/DEFINE PRINTER parameters/options are ignored.

JES xxxxx In this case, the dataset processing options for JES are taken from the OUTPUT JCL statement with the name JESxxxxx.

The generated JES API parameter string is:

IAFP=A0M,OUTN=JESxxxxx

The OUTPUT JCL statement may look like:

JESxxxxx OUTPUT OUTDISP=WRITE,DEST=dest,
CLASS=A,COPIES=1,FORMS=form,...

Note:
If the OUTPUT JCL statement is missing in the job stream, an error is reported.

Top of page

R - S

Parameter Possible Values Description Default Comment
ROLLSRV YES ROLLSRV specifies the medium for saving a Natural thread between terminal output and input. If ROLLSRV=YES, the Natural roll server is used. YES

Used in dialog-oriented environments only.

See also Roll File and Roll Server in Natural under IMS TM - Components.

NO Roll files are used, see ROLLFN below.
ROLLFN 1 - 5 Specifies the number of roll files to be used, if ROLLSRV=NO. 1 Used in dialog-oriented environments only.
SPASIZE xxxxx Specifies the size in bytes of the buffer which is to contain the scratch-pad area.

Any numeric value up to 16 MB is possible.

1024 In a non-conversational environment, this is also the size of the simulated SPA which is written to the SIP server.
SPATID xxxx Specifies the Natural subsystem ID for the Authorized Services Manager which is used to save the SPA for a non-conversational driver. Any string up to 4 characters is possible.   This value must be the same for all parameter tables and must be the same as the value specified for SPATID in the NIMPIXT macro.
SUPNONC YES Specifies whether switching from a terminal-oriented non-conversational environment to a conversational environment is possible. NO Used in the dialog-oriented conversational environment only.
NO

Top of page

T - U

Parameter Possible Values Description Default Comment
TERMDB YES Specifies whether the Natural session has to be terminated if one of the DL/I databases specified in the PSB is not available. NO

Used in dialog-oriented environments only.

If you set TERMDB to NO and one of the databases is not available when it is accessed, the Natural transaction code is suspended by IMS TM.

NO
TERMIPL YES Specifies whether a Natural session is terminated with an error message when an IPL has taken place between the current transaction step and the start of the session. NO Used in dialog-oriented environments only.
NO
THBELOW YES Specifies where the Natural thread is allocated. In case of YES, the Natural thread is allocated below the 16 MB line. YES For batch message processing, the thread is always allocated below the 16 MB line.
NO The Natural thread is allocated above the 16 MB line.
THSIZE   Specifies the size of the Natural thread. Any numeric value in multiples of eight greater than or equal to 100000 is possible. 300000 This is the area which contains all user session related Natural buffers.
USERID YES Specifies how the value of the system variable *INIT-USER is determined. In case of YES, the Natural user ID specified in *INIT-USER is either taken from the security access control block if a security package is active or from the USER parameter of the job card. NO Used by the BMP driver only.
NO The Natural user ID specified in *INIT-USER is taken from the job name.

Top of page

NIMTRNTG Macro Parameters

The macro NIMTRNTG generates an entry in the transaction code table NIITRTAB containing the specified transaction code with related parameters. For each Natural transaction code an entry has to be included in the transaction code table. For further information on NIITRTAB, see Transaction Code Table NIITRTAB.

The parameters which can be specified with the macro NIMTRNTG are  listed in alphabetical order below:

ALTPCB | HCPCB | MSGPCB | MSPCB | NIIPENT | NRASTART | PSBNAME | TRANCODE | TYPE | WRKPCBS

Parameter Possible Values Description Default Comment
ALTPCB 1 - 255 ALTPCB specifies which alternate TP PCB is used for the service modules CMQUEUE, CMQUEUEX, NIIDQUMS and NIIDPURG. 1 The number of the alternate TP PCB specified with the NIMTRNTG macro can be overwritten by the service modules.
HCPCB SYSPCB HCPCB specifies which PCB is used for the hardcopy function.

In case of SYSPCB, the first alternative TP PCB is used.

SYSPCB None.
WRKPCB One of the additional alternative TP PCBs is used. This enables you to use an express TP PCB for the hardcopy function.
MSGPCB SYSPCB MSGPCB specifies which PCB is used when printing error messages and standard output in the non-terminal-oriented environment and for the server driver.

In case of SYSPCB, the first alternative TP PCB is used.

SYSPCB Relevant for non-terminal-oriented environments and the server driver only.
OWNPCB The second alternative TP PCB is reserved and used. This enables you to use an express TP PCB for sending messages.
MSPCB NO MSPCB specifies the number of the multi-session database PCB.

If NO is specified, the multi-session feature is not used.

NO Relevant for the multi-session feature only.
1 - 255 The PCB of the multi-session database.
NIIPENT xxxxxxxx Specifies the name of the Natural IMS parameter table to be used for this entry in the transaction code table. Any non-blank character string up to 8 characters is possible. ENV00000 None.
NRASTART offset value Defines the offset of the Natural Reserved Area (NRA) within the scratch-pad area. Any numeric value greater than 14 is possible. 16 The current length of the NRA is 157 bytes. The length of the NRA may change from version to version of the Natural IMS interface.

If you want to save your own information in the SPA in order to pass it to a non-Natural transaction, it is recommended that you save your data in front of the NRA in order to be version compatible.

PSBNAME PSB-name Specifies the PSB name corresponding to the current transaction code. Any valid PSB name is possible. None Used to identify the entry in the transaction code table for non-message-driven batch message processing and for the batch processing environment.
TRANCODE transaction-code-name Specifies the identifier of each entry within the transaction code table. Any valid transaction code name is possible. None Has no effect in both the non-message-driven BMP and the batch processing environment.
TYPE CONV TYPE specifies the type of the Natural transaction code. In case of CONV, the transaction code is for a conversational Natural session. CONV None.
NONC The transaction code is for a non-conversational Natural session.
WRKPCBS 0 WRKPCBS specifies the number of alternative TP PCBs available for printing additional to the first TP PCB and, if appropriate, to the MSGPCB.

In case of 0, no IMS printer is available.

0 See examples below.
1 - 32 The number of alternate TP PCBs used for printing additional to the first TP PCB and, if appropriate, to the MSGPCB.

Examples

Example 1:

You specified the following:

MSGPCB=SYSPCB
WRKPCBS=2

The PSB must contain 3 alternate TP PCBs.

Example 2:

You specified the following:

MSGPCB=OWNPCB
WRKPCBS=2

The PSB must contain 4 alternate TP PCBs. The second alternate TP PCB is reserved for the error messages and standard output of the non-terminal-oriented environment.

Top of page

NIMLPCB Macro Parameters

The macro NIMLPCB can optionally follow a NIMTRNTG entry in the transaction code table.

The parameters which can be specified with the macro NIMLPCB are listed in alphabetical order below:

NAME | NUM

Parameter Possible Values Description Default Comment
NAME xxxxxxxx Specifies the logical name of the PCB. Any non-blank string up to 8 characters is possible. None None.
NUM PCB-positional-number Specifies the positional number of the PCB in the PSB. Any integer is possible. None If NUM is not specified, the positional number of the NIMLPCB macro is used.

Top of page

NIMMSGT Macro Parameters

The macro NIMMSGT generates each entry in the message text module NIIMSGT which is part of the Natural IMS interface module. Each generated entry provides a message text for each possible Natural IMS error number.

The NIMMSGT macro is specified in one of the following two ways:

  Nerror-number [*] NIMMSGT  message-text

In this case, Natural under IMS TM will display the message text as defined. The message text may be up to 72 characters long.

  Xerror-number [*] NIMMSGT message-text

In this case, Natural under IMS will append an error-specific reason code to the current message text. The message text may be up to 64 characters long.

If the error number is followed by an asterisk (*), a snap dump will be generated when an error occurs. You may adapt the message text to your own requirements. You may also add or delete the DUMP option of a specific error number. You must not modify the error number and the characters N or R that precede the error number.

Top of page

NIMPIXT Macro Parameters

The NIMPIXT macro generates the Physical Input Edit Routine.

The parameters which can be specified with the macro NIMPIXT are listed in alphabetical order below:

PIXTE | SIPSE | SPATID | WTO | USER

Parameter Possible Value Description Default Comment
PIXTE 1 - 999 Specifies the start value for error numbers if errors are detected by the physical input edit routine. 400 This value is added to the return code set by the physical input edit routine. The result is the IMS TM error message number in the user message table DFSCMTU0.
SIPSE 1 - 999 Specifies the start value for error numbers if errors are detected by the Authorized Services Manager. 500 This value is added to the return code set by the Authorized Services Manager. The result is the IMS TM error message number in the user message table DFSCMTU0.
SPATID xxxx Specifies the Natural subsystem ID for the Authorized Services Manager which is used to save the SPA for the non-conversational driver. Any string up to 4 characters is possible. None The value of this parameter must be the same as the value specified for the SPATID parameter in the NIMPARM macro.
WTO YES Specifies whether a WTO message is issued if the Authorized Services Manager fails. NO None.
NO
USER xxxxxxxx

Specifies whether a user-specific physical input edit routine is to be called if the NIMPIXT macro does not find the SPA.

If a user-specific input edit routine is to be called, specify the name of the routine.

NO None.
NO

Top of page

NIMBOOT Macro Parameters

The macro NIMBOOT generates the bootstrap module used by the message-oriented environment or the server call interface used by the server environment.

NIMBOOT includes the following parameters:

TYPE | DRIVERN | ENVTNAM | TRNCODE | DYNPARM | SERVERN

Parameter Possible Values Default Comment
TYPE SERVER Empty

TYPE specifies the type of the interface module to be generated.

With TYPE=SERVER, the server call interface NIIBOOTS is generated.

Empty If nothing is specified, the bootstrap module used by the message-oriented environment is generated.
DRIVERN Any valid z/OS module name None

This parameter specifies the name of the front-end module.

If TYPE=SERVER is specified, the front-end module must have been generated for the server environment (NIMDRIV parameter TYPE=SRVD). If no TYPE is specified the front-end module must have been generated for the message-oriented environemt (NIMDRIV parameter TYPE=NTRD).

ENVTNAM Any valid z/OS module name None

This parameter is only used by the bootstrap module for the message-orineted environment (TYPE is empty).

This parameter specifies the name of the environment table. This parameter is optional. If it is not specified, the environment table is determined by the entry in the transaction code table which corresponds to the transaction code used.

TRNCODE    

This parameter is only used by the bootstrap module for the message-orineted environment (TYPE is empty).

This parameter specifies the name of the transaction code which is internally used by the Natural IMS interface. This parameter is optional and is only honored if TRNCODE=YES is coded in the NIMDRIV macro. If it is not specified or if TRNCODE=YES is not specified in the NIMDRIV macro, the transaction code returned by the IMS TM INQY call is used.

The transaction code is used to determine the entry in the transaction code table NIITRTAB.

DYNPARM Any character string of up to 80 characters. None

This parameter is only used by the bootstrap module for the message-oriented environment (TYPE is empty).

This parameter is used to define a valid string of up to 80 characters of Natural dynamic parameters.

SERVERN Any valid z/OS module name NIIBOOTS This parameter is only used by the server call interface (TYPE=SERVER).

This parameter specifies the name of the server environment. It is only relevant if you want to use several Natural servers in the same region. In this case, you must generate multiple server call interfaces and specify a unique name with SERVERN for each each of them. See Special Functions, Server Environment.

Top of page