This document of the Natural IMS Interface documentation discusses the configuration macros of the Natural IMS Interface.
The following topics are covered:
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 |
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 |
|||
SRVD |
Server environment is generated. | |||
LE370
|
YES |
LE370 specifies whether Natural under
IMS initializes the IBM Language Environment.
In case of 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 Note: |
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:
Note: |
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
Parameter | Possible Values | Description | Default | Comment | |
---|---|---|---|---|---|
ACTACTV
|
YES |
ACTACTV
specifies whether the accounting function is activated.
In case of |
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
|
or |
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. |
Parameter | Possible Values | Description | Default | Comment |
---|---|---|---|---|
BMPABER
|
YES |
In case of |
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
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. |
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 If a Natural session terminates with an error, |
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
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 |
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 |
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 |
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.
|
Parameter | Possible Values | Description | Default | Comment |
---|---|---|---|---|
PRTDRIV
|
See tables of drivers below.
Drivers for
SCS Printers |
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
|
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. |
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: |
|||
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 JESxxxxx OUTPUT OUTDISP=WRITE,DEST=dest, CLASS=A,COPIES=1,FORMS=form,... Note: |
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 |
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 |
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.
|
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 |
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 |
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 |
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 |
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. |
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.
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:
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.
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 If a user-specific input edit routine is to be called, specify the name of the routine. |
NO |
None. |
NO |
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 |
With |
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 |
ENVTNAM
|
Any valid z/OS module name | None |
This parameter is only used by the bootstrap module for the
message-orineted environment ( 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 The transaction code is used to determine the entry in the
transaction code table |
||
DYNPARM
|
Any character string of up to 80 characters. | None |
This parameter is only used by the bootstrap module for the
message-oriented environment ( 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 |