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.
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 NRAST value specified in the NTIMSPT macro of
the Natural parameter module.
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
SPATID of the NTIMSPE macro
(Natural parameter module),
SPATID of the
NIMPIXT macro,
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 NAT-B.
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 0 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 IMS-B.
It is assumed that IMS-A and IMS-B have 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 a CMSYNIN file. All output
which is normally written to CMPRINT is sent to the IMS TM destination
specified with the Natural profile parameter SENDER. For details, see SENDER Destination below.
If Natural attempts to retrieve input data and no input data has been supplied by the
application through the STACK 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 CMSNFPRT.
Except for checkpoint processing, Natural for Db2 processes transactions 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 within this Natural session are considered to be related, requiring maintenance of database positioning and PCB usage.
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 via 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 segments.
Since Natural cannot read input from CMSYNIN, it is required to use the
Natural stack for input. This is done by using the Natural profile parameter STACK.
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 STACK parameter. Specify
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 is the 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 JCL.
A standard batch Natural is executed in a Batch Message Processing region. In comparison
with the standard batch Natural run, the optional input data set CONTROL may
be used.
The optional BMP CONTROL file contains a maximum
of two input cards.
The first input card contains the following keyword parameters:
| Keyword | Meaning |
|---|---|
ENV-TAB=
|
The name of the environment table to be used. |
TRNCODE= |
The name of the transaction code to be used, see the TRNCODE
parameter description.
|
ENV-TAB=ENVBMP0 TRNCODE=NATIMS
The second input card of the CONTROL file contains dynamic Natural
parameters.
If the CMPRMIN data set is also used to pass dynamic Natural parameters, the
input of CONTROL is appended to the input of CMPRMIN. This means
the parameters specified in CONTROL overwrite the parameters specified in
CMPRMIN.
If the 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).
With the WRITE
(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 DEFINE PRINTER
(n) statement. You have to specify
AM=IMS in the
NTPRINT 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 WRKPCBS keyword subparameter of the
NTIMSPT macro (Natural parameter module).
 |
Warning: Be aware that the first alternate TP-PCB is used by the Natural IMS TM Interface. |
When using the WRITE (n) statement in a
dialog-oriented environment, the following restriction applies:
The generation of a report cannot span one or more screen I/Os. 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 CLOSE PRINTER
(n) statement.
To create reports, the following keyword subparameters of the NTPRINT macro are relevant:
| Keyword Subparameter | Meaning |
|---|---|
AM
|
Must be set to IMS.
|
DEST
|
Specifies the IMS TM destination. |
BLKSIZE
|
Specifies the size of the buffer which is sent to the destination. Report lines are buffered. |
DRIVER
|
Specifies the driver to
be used to create the report. For a list of possible values, see the PRTDRIV keyword subparameter of the
NTIMSPE macro in the Natural parameter module. The driver
determines where you want to have the form feed (at the start of the report, the
end, both the start and the end, or no form feed), where you want to start your
page (on Line 1 or on Line 2 for compatibility with Natural IMS TM Interface
Version 2.2) and where you want to print your
report (SCS or non-SCS printer). In addition, you can specify that you want to use
the JES API.
|
| These parameters are only evaluated if you use the JES API. |
You are strongly recommended that you always use the defaults for the OPEN and
CLOSE subparameters in the
NTPRINT macro or PRINT profile
parameter definition for IMS TM printers (that is, for printers defined with AM=STD). This means either
do not specify any values for OPEN and
CLOSE or use te defaults OPEN=ACC and
CLOSE=CMD.
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
OPEN and CLOSE and if you dynamically
overwrite the access method with AM=IMS. In this case, always specify
AM=IMS,OPEN=ACC,CLOSE=CMD together.
Note:
The NTPRINT options are merged with the dynamically
specified PRINT
options, even though the access method has been overwritten.
Problems which may occur with non-default values:
With OPEN=OBJ you may print to a wrong destination or get a
NAT8211 error if the OUTPUT option has been specified in a
DEFINE PRINTER
statement. With 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
PRINT parameter.
With CLOSE=FIN the printer is not closed at CLOSE PRINTER time but at
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 CLOSE PRINTER statement.
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 CLOSE
PRINTER or DEFINE
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 to a NAT1518 error.
DEFINE PRINTER (1) WRITE (1) 'line 1' INPUT 'Press ENTER' or CALL 'CMGETMSG' (both issue a GU) WRITE (2) 'line 2'
The INPUT/CMGETMSG will
"physically" close the printer and IMS TM will print a report
containing the line 'line 1'.
As the printer is still "logically" open to Natural, the line
'line 2' will not start a new report and error NAT1518
will be caused as the destination is purged by the GU call.
You are therefore strongly recommended to observe the following rule:
|
Warning: A CLOSE PRINTER
statement is required if, after the GU, the report with the same number is
continued. |
Please note that the DEFINE
PRINTER statement does an implicit close in which case the
CLOSE PRINTER statement is obsolete, for example:
| Correct | Correct | Wrong (NAT1518) |
|---|---|---|
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 |
The statement SET CONTROL 'N'
(Terminal Command %N) does not apply under IMS TM. If it is used
under IMS TM, it causes the next logical output screen to be suppressed.
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. With 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:
| Value | Meaning |
|---|---|
*WTO
|
Natural output is sent to the job log using a WTO with routing code 11 (programmer information). |
*MTO
|
Natural output is sent to the IMS TM master console using a
/BROADCAST MASTER command.
|
*PRINTnn
|
Natural output is written to Natural printer
nn, that is the output is written
using an internal WRITE(nn).
The print file is closed after each output line and the carriage control character of each output line is the blank. |
Notes:
/BROADCAST MASTER command 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
SENDER destination is internally set to *WTO.
*PRINT nn, you are strongly
recommended to use only printers defined with AM=STD.
SENDER destination
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
NAT3048 or NAT3148).
SENDER destination
dynamically, you must enclose the reserved values in single quotes (for example,
SENDER='*WTO').
The Natural profile parameter PROGRAM is supported in the dialog-oriented
environments and in the BMP environment.
In the BMP environment, the parameter PROGRAM behaves in the same
way as in a standard z/OS batch environment. An example with name 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 PROGRAM or the Natural
subprogram CMPGMSET is the name of an IMS TM transaction code.
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.