This document describes how Natural runs under various IMS TM environments.
The following topics are covered:
IMS TM provides three different types of environments:
To be able to use Natural in each of these environments, different environment-specific interfaces are provided for the Natural IMS TM Interface. The task of such an interface is to receive input (usually a terminal input message) from the environment, to pass the input to Natural for processing and to direct the resulting output back to the correct destination (usually a terminal output message). This way, it is possible to use the functionality of Natural in all available IMS TM environments.
In addition to different available environments, within each environment, there are different ways of operating.
In a message processing region, Natural online transactions can be one of the following:
A dialog-oriented Natural session establishes an ongoing interaction with an IMS TM screen. Input and output messages to and from Natural are logically related and, across dialog steps, Natural saves information so as to be able to correctly process the next input message. In a dialog-oriented way, Natural can be run as either a conversational or a non-conversational transaction.
In a dialog-oriented environment, Natural can be executed in multiple-message processing regions, as Wait-for-Input (WFI) transaction and with the parallel-scheduling option.
To run Natural in dialog-oriented environments, you either have to use the roll server or roll files (see The Roll File and Roll Server).
If the Natural IMS TM Interface detects an error situation, a record containing information about this error situation is written to the IMS TM log file (see Recovery Handling). Thus, all terminals on which Natural is to be executed and all Natural transaction codes have to be authorized to issue the /LOG command using the Automated Operator Interface (AOI).
A message-oriented Natural session processes non-3270-formatted messages from the IMS TM message queue. The input messages are considered to be unrelated to each other and are not part of a dialog. In a message-oriented way, Natural must be run as a non-conversational transaction.
In a batch message processing region, Natural can have access to the IMS TM message queue by using an input transaction code. With batch-oriented BMP regions, Natural supports symbolic checkpoint and extended restart. The input messages are non-3270-formatted messages.
The BMP Natural can also be executed as an off-line DL/I batch job.
For diagnostic purposes, the following feature is available: If Natural
has been started with profile parameter
an informal WTO message is issued, indicating the above fact.
This section discusses special points valid for the dialog-oriented conversational environment only.
The dialog-oriented conversational environment is implemented by the Conversational MPP Interface which is linked with the Natural parameter module to the Conversational MPP Front-End. This front-end is the IMS TM application program and is scheduled by IMS TM if an input message for the assigned transaction code is available in the IMS TM message queue.
The dialog-oriented conversational environment requires a scratch pad
area (SPA) of at least 157 bytes plus the
value specified in the
NTIMSPT macro of the Natural parameter
The dialog-oriented non-conversational environment is implemented by the Non-Conversational MPP Interface which is linked with the Natural parameter module to the Non-Conversational MPP Front-End. This front-end is the IMS TM application program and is scheduled by IMS TM if an input message for the assigned transaction code is available in the IMS TM message queue.
When a dialog-oriented non-conversational environment is used, the Natural Authorized Services Manager with its SIP function enabled and the Physical Input Edit Routine are prerequisites.
The Natural Authorized Services Manager is used to simulate the IMS TM SPA.
The Physical Input Edit Routine is used to insert the transaction code in front of the input message.
You must specify the same Natural subsystem ID in the
NTIMSPE macro (Natural parameter module),
SPATID of the
startup parameters of the Authorized Services Manager.
Assuming the following environment, the Natural IMS TM Interface prepares the message X'000500006D' for NAT-B, which means that the terminal user has pressed CLEAR.
IMS-A IMS-B ----- ----- MPP-A1 MPP-A2 MPP-A3 MPP-B1 MPP-B2 MPP-B3 ------ ------ ------ ------ ------ ------ DIRECT SWITCH NAT-A -----------------------------> NAT-B
Two entries must be created in the transaction code table: the first
entry is for
NAT-A, the second for
These two entries must specify different offsets for the Natural Reserved Area (NRA) and must ensure that these areas do not overlap.
NAT-B detects that a Natural session is to be started in
IMS-B in the usual way and therefore gives control to its
session-start exit routine. The session-start exit routine checks the input
message for the string
X'000500006D' and sets to
the length of the input message as seen by Natural.
If no additional logic is provided in either the exit
NIIXSTAR or the exit
NIIXSSTA, Natural starts a new
user session in
It is assumed that
different dedicated roll files allocated for Natural.
Both (or more) Natural sessions can communicate with each other by transferring data in the SPA when performing direct program-to-program switching.
For the time being, when two or more Natural sessions exist in such an environment, only the "active" session is terminated correctly.
This section describes the message-oriented interface for use with Natural for IMS TM.
This interface is designed to process nett-data input messages, which means that the messages do not represent a 3270 data stream. The message-oriented interface is driven by a user-written Natural program which instructs the interface to access the IMS TM message queue for the purpose of retrieving input messages.
The message-oriented interface has been created to support non-conversational, non-terminal driven transactions which must be executed as non-conversational MPP transactions.
The message-oriented interface incorporates functions from both the MPP and the BMP interfaces. The BMP interface is used as a basis, since much of the processing required emulates BMP-type transactions.
Since the message-oriented interface is not terminal-oriented, no
messages or screen images are automatically generated to be sent to a terminal.
The Natural nucleus is informed that it is running in a batch environment;
therefore output is interpreted to be printer output and input is expected from
CMSYNIN file. All output which is normally written to
CMPRINT is sent to the IMS TM destination specified with the
Natural profile parameter
details, see SENDER
If Natural attempts to retrieve input data and no input data has been
supplied by the application through the
command, EOF indicates that no input exists and Natural is terminated.
You can set
SENDER to a new value at runtime by
using the service module
Except for checkpoint processing, Natural for DL/I and Natural for DB2 process as if they were in BMP mode. This is necessary, since one physical scheduling can (and usually will) process several unrelated input messages. Under the conversational MPP interface, all transactions processed during one Natural session and all DL/I requests within this Natural session are considered to be related, requiring maintenance of database positioning and PCB usage. With the non-conversational interface, this Natural for DL/I logic is not applicable.
Since transactions which are processed during one scheduling (and one
Natural session) are not related to each other, the retention of Natural
session information in the roll file is not required. Thus, no roll data set
needs to be allocated for this interface. A roll slot area is still allocated
GETMAIN and used to store all Natural control
blocks and work areas.
Since processing is performed on a message-by-message basis, there is no need for any relocation logic.
With the message-oriented interface, retrieval of all messages from the message queue is initiated by a front-end Natural program. This program must be user-written to meet your specific processing needs. However, it requires a specific structure, as shown in the following:
PROGRAM INITIALIZATION REPEAT CALL 'CMGETMSG' MESSAGE-AREA MESSAGE-LENGTH IF MSG-LL = 0 /* QC on GU to message queue TERMINATE FETCH RETURN PGMA MESSAGE-AREA REPEAT CALL 'CMGETSEG' MESSAGE-AREA MESSAGE-LENGTH IF MSG-LL = 0 /* QD on GN to message queue ESCAPE FETCH RETURN PGMB MESSAGE-AREA END-REPEAT END-REPEAT END
The service module
CMGETMSG reads the first message
segment. The service module
CMGETSEG reads all further message
Since Natural cannot read input from
CMSYNIN, it is
required to use the Natural stack for input. This is done by using the Natural
It is your responsibility to ensure that the IMS TM message queue is accessed by your application prior to the termination of Natural. If not, the Natural transaction abnormally ends with IMS TM abend code 462, indicating that a GU to the message queue has not been performed.
To obtain these Natural messages even in the case of an abnormal termination, you are recommended to define the first alternate PCB as an EXPRESS PCB.
The message-oriented environment is implemented by the NTRD Interface which is linked with the Natural parameter module to the NTRD Front-End. This front-end can either be called directly by IMS TM or via a bootstrap module that has been generated with the NIMBOOT macro.
If it is called directly by IMS TM, this front-end is the IMS TM
application program which is scheduled by IMS TM if an input message for the
assigned transaction code is available in the IMS TM message queue. You are
recommended to use a Natural profile which contains the required
PROFILE=PROGRAM in your Natural parameter
module and create a profile with a name equal to the transaction code with
which the interface is invoked. This way, you have the flexibility to use a
different profile with a different
STACK for each
transaction code used.
If it is called via a bootstrap module, this bootstrap module is the
IMS TM application program which is scheduled by IMS TM if an input message for
the assigned transaction code is available in the IMS TM message queue. This
bootstrap module provides a string of dynamic profile parameters, one of which
STACK profile parameter, and calls the NTRD
front-end whose name is specified during the generation of the bootstrap
module. If you want to call Natural with varying dynamic profile parameter
settings, you must generate various bootstrap modules, each using its own
string of dynamic profile parameters. Each of these bootstrap modules must be
linked under a unique name. Also a unique IMS TM transaction code has to be
assigned to each of the resultant load modules.
The Batch Message Processing (BMP) environment is implemented by the BMP
Interface which is linked with the Natural parameter module and the work
file/print file access routine
NATWKFO to the BMP Front-End. This
front-end is the IMS TM application program which is specified in the BMP
A standard batch Natural is executed in a Batch Message Processing
region. In comparison with the standard batch Natural run, the optional input
CONTROL may be used.
The first input card contains the following keyword parameters:
||The name of the environment table to be used.|
||The name of the transaction code to be used, see the
The second input card of the
CONTROL file contains
dynamic Natural parameters.
CMPRMIN data set is also used to pass dynamic
Natural parameters, the input of
CONTROL is appended to the input
CMPRMIN. This means the parameters specified in
CONTROL overwrite the parameters specified in
CONTROL file is not used, the name of the
environment table is determined by the entry in the transaction code table
which corresponds to the transaction code used (transaction-oriented BMP) or to
the PSB name used (batch-oriented BMP).
(n) statement, up to 31 different
reports on different printers can be produced within the same Natural program.
The reports are sent to the IMS TM terminals specified either in the Natural
parameter module or by using the Natural
(n) statement. You have to specify
macro which controls the report.
To be able to use this statement, define as many additional alternate
TP-PCBs in your PSB as the number of parallel reports you want to create within
the same Natural program, and specify the number of additional alternate
TP-PCBs in your transaction code table by using the
keyword subparameter of the
NTIMSPT macro (Natural parameter
Be aware that the first alternate TP-PCB is used by the Natural IMS TM Interface.
When using the
statement in a dialog-oriented environment, the following restriction
The generation of a report cannot span one or more screen I/O operations. If you
want to use the same printer after a screen I/O, you have to close it
explicitly before the screen I/O using the
To create reports, the following keyword subparameters of the
macro are relevant:
||Must be set to
||Specifies the IMS TM destination.|
||Specifies the size of the buffer which is sent to the destination. Report lines are buffered.|
the driver to be used to create the report. For a list of possible values, see
|These parameters are only evaluated if you use the JES API.|
You are strongly recommended that you always use the defaults for the
subparameters in the
NTPRINT macro or
AM=STD). This means
either do not specify any values for
CLOSE or use te defaults
This is especially important if you have statically defined a printer
in the Natural parameter
module for a different access method with other options for
CLOSE and if you
dynamically overwrite the access method with
AM=IMS. In this case,
NTPRINT options are merged with the
Problems which may occur with non-default values:
OPEN=OBJ you may print to a wrong destination or
NAT8211 error if the
option has been specified in a
DEFINE PRINTER statement.
OPEN=OBJ the printer is opened before the
OUTPUT overwrite has been evaluated and the printer
destination used is not the one which is specified in the
OUTPUT option but the one specified with the
CLOSE=FIN the printer is not closed at
CLOSE PRINTER time
FIN time. This
means that the
CLOSE may come after a GU has been issued
to the message queue and the destination has been reset in the TP PCB. This
will lead to NII error
NII3641 for IMS TM status code
QF (MPP) or
A3 (BMP and OBMP/NTRD). With
CLOSE=CMD, the printer is really closed with the
A report written to an IMS TM printer is implicitely closed by IMS TM
with the next GU call (that is, either at terminal I/O or through
CMGETMSG). This means, IMS TM will print the report
regardless of a
PRINTER statement in the program.
For Natural, the printer is still open, and the next
WRITE statement with
the same report number will continue the already printed report which will lead
DEFINE PRINTER (1) WRITE (1) 'line 1' INPUT 'Press ENTER' or CALL 'CMGETMSG' (both issue a GU) WRITE (2) 'line 2'
"physically" close the printer and IMS TM will print a report
containing the line
As the printer is still "logically" open to Natural, the
'line 2' will not start a new report and error
NAT1518 will be caused as the destination is purged by the GU
You are therefore strongly recommended to observe the following rule:
Please note that the
PRINTER statement does an implicit close in which case the
CLOSE PRINTER statement is obsolete, for example:
REPEAT DEFINE PRINTER (1) WRITE (1) INPUT LOOP
DEFINE PRINTER (1) REPEAT WRITE(1) CLOSE PRINTER (1) INPUT LOOP
DEFINE PRINTER (1) REPEAT WRITE(1) INPUT LOOP
All Natural under IMS TM messages are translated into upper case if
TS=ON is specified in
the Natural session.
In the message-oriented (NTRD) and in the server (SRVD) environment, all
output that is normally written to
CMPRINT is sent to the
destination specified with the Natural profile parameter
SENDER you either specify a valid IMS TM
destination (usually an
LTERM) to which the output is sent via the
IMS TM message queue or you specify one of the following reserved values:
||Natural output is sent to the job log using a WTO with routing code 11 (programmer information).|
||Natural output is sent to the IMS TM master console using a
||Natural output is written to Natural printer
The print file is closed after each output line and the carriage control character of each output line is the blank.
/BROADCAST MASTERcommand fails (for example, due to authorization problems), an error message is issued using a WTO and all Natural messages, including the current message, are sent to the job log. That is, the
SENDERdestination is internally set to
*PRINT nn, you are strongly recommended to use only printers defined with
SENDERdestination in the Natural profile paramater module. This will ensure that the destination is found even if the Natural initialization fails (e.g due to an Adabas error
SENDERdestination dynamically, you must enclose the reserved values in single quotes (for example,
The Natural profile parameter
supported in the dialog-oriented environments and in the BMP environment.
In the BMP environment, the parameter
behaves in the same way as in a standard z/OS batch environment. An example
XNIIBACK is delivered in the
NIIvrs.SRCE data set. It is expected
that the invoked back-end program returns to the Natural IMS TM Interface.
In a dialog-oriented environment, the Natural profile parameter
PROGRAM behaves slightly different as compared to other
Natural environments, including the BMP environment.
The name specified with the profile parameter
the Natural subprogram
CMPGMSET is the name of an IMS TM
The specified transaction code is only invoked if the Natural session terminates without an error.
The data supplied with the
TERMINATE statement is passed
as input message to the invoked IMS TM transaction.
This environment enables you to execute a Natural Development Server (NDV) or Natural Web I/O Interface (NWO) Server session under the control of IMS TM, and to have access to IMS TM ressources such as IMS TM DB or DB2 databases from within such a session. The server transaction is a non-conversational transaction.
For further information, see:
Introducing the Natural Web I/O Interface Server IMS Adapter , Installing the Natural Web I/O Interface Server IMS Adapter under z/OS and Configuring the Natural Web I/O Interface Server IMS Adapter in the Natural Web I/O Interface documentation.
Access to the IMS TM ressources is done using the user ID
EZAIMSLN. This means no impersonation is used.