This document describes the various ways of how Natural can be invoked from user programs.
It covers the following topics:
This section covers the following topics
A Natural session can be activated by user front-end programs with one of the following commands:
or the equivalent CICS macro level requests.
When using EXEC CICS XCTL/LINK, the parameters used by
Natural can be passed in a CICS COMMAREA or in the TWA.
Natural determines the location of the startup parameters by inspecting the length of the COMMAREA passed to it during session initialization.
If the length is 22, Natural tries to locate the parameters in the COMMAREA, otherwise it is assumed that they have been passed in the TWA.
To identify a front-end program properly, it is mandatory that the first 4 bytes of the front-end parameter list represent the current transaction ID.
The transaction ID associated with the front-end program must have a TWA size that is equal to or greater than the Natural TWA size; see also ncitransact in Installing Natural CICS Interface on z/OS in the Natural Installation documentation.
When using EXEC CICS RETURN IMMEDIATE, the front-end
parameters used by Natural can be passed in a CICS COMMAREA and the dynamic parameters
used by Natural can be passed with INPUTMSG (...) and
INPUTMSGLEN (...) of the EXEC CICS RETURN IMMEDIATE
command.
When using EXEC CICS START, the front-end and dynamic
parameters used by Natural can be passed with FROM (...) and LENGTH
(...) of the EXEC CICS START command. The parameters
are described on the following page.
When using EXEC CICS LINK with the
SYSID parameter pointing to a remote region, the front-end and
dynamic parameters used by Natural have to be passed in a CICS COMMAREA. In addition
also a TRANSID parameter has to be specified naming the
transaction code of a mirror transaction with a TWA size satisfying Natural's
requirements.
It should be noted that the same restrictions as for asynchronous Natural sessions apply to Natural sessions invoked via DPL, that is, no input is possible (therefor the same dynamic parameter settings are recommended) and the caller just gets control back after Natural session termination.
A series of sample programs for the various programming techniques is supplied in the Natural CICS source library; see also Natural CICS Sample Programs
It is possible to start a Natural session from a Natural program by calling the
external subroutine CMTASK. Refer to the sample Natural program
ASYNCICS in library SYSEXTP.
The following list of parameters must be supplied to invoke Natural from a user front-end program:
| Pos. | Contents |
|---|---|
1 - 4 |
Invoking transaction ID
This value must be equal to the current transaction ID. Via the invoking transaction ID, Natural identifies that it was called by a user front-end program. When being called with |
5 - 8 |
Address/offset of dynamic parameter string
If dynamic parameter overwrites are to be evaluated, this value should be set to the address located 12 bytes before the dynamic parameter assignment string. When being called with |
9 - 10
|
Length of the dynamic parameter string
Zero indicates that no parameters are to be passed. |
11 - 14
|
Natural transaction ID
The value specified is the transaction ID to be used for controlling a
pseudo-conversational Natural session, when being called with
If the Natural transaction ID is not specified, Natural restarts the transaction ID which initiated the current CICS task, and the front-end program regains control after each pseudo-conversational I/O. |
15 - 22
|
Back-end program name
This 8-byte value is the program name to which control is transferred at the
end of the Natural session with a CICS XCTL command, rather than restarting the
calling transaction ID via If this field is numeric in the first byte, Natural simply
For the conventions of calling non-Natural back-end programs, refer to the Natural Operations documentation. |
On return to the front-end, Natural indicates in the TWA if the session has terminated or
not: when the session has terminated, the TWA holds regular back-end information (see
Back-end Program Calling
Conventions in the Operations documentation), else
Natural puts the NEXTTRANSID into the first four bytes of the
TWA.
If Natural is running in pseudo-conversational mode (profile parameter PSEUDO set to
ON) and has been invoked by EXEC CICS LINK (or
the equivalent CICS macro level request), the original invoking transaction is invoked
each time Natural writes to a terminal and waits for input, which means that Natural
issues a "logical"
CICS RETURN TRANSID (..) after having written its restart information into
CICS temporary storage.
The invoking transaction must recognize this situation (for example, by checking whether
a NEXTTRANSID has been sent or by the existence of
NCOMxxxx TS records - where NCOM
is the Natural CICS parameter generation option and
xxxx is the terminal ID -) and pass control back
to Natural.
The advantage of this method is that, during the session, the front-end program can decide to pass control to another application (for example, COBOL) and to resume the Natural session later.
For further details see the PSEUDO parameter description in the
Parameter Reference documentation.
Per design, Natural treats a LINK front-end program as a back-end program at session termination, that is, the Back-End Program Calling Conventions apply.
Make sure that the NCOMxxxx TS records can be
accessed by all participating CICS AORs (for example via appropriate CICS TST
definitions).
Alternatively the LINK front-end program can also pick up the NCI session restart information in CICS temporary storage on task termination and pass it in a CICS COMMAREA by itself; such a COMMAREA has then to be put into CICS temporary storage again prior to invoking Natural for session resume.
This front-end technique only works for Natural terminal sessions. Natural scans for
start-up parameters supplied with the COMMAREA. Note that when using this technique,
potential dynamic parameters cannot be passed chained to the front-end parameters, that
is, the dynamic parameters' address fields must be zero. Instead, potential dynamic
parameters can be passed via terminal input data, which are obtained by Natural by an
EXEC CICS RECEIVE command.
If the Natural session is a started task (that is, invoked by an EXEC CICS
START or EXEC CICS LINK/XCTL command by a
front-end user program which has been STARTed), Natural first
scans for startup parameters supplied with the COMMAREA, then it scans for parameters in
the TWA and finally it tries to obtain the necessary parameters by an EXEC
CICS RETRIEVE command.
If the Natural session is initiated from a front-end program with
XCTL and no return program is specified (that is, neither a
fifth parameter in the session startup parameters nor a PROGRAM
specification in the Natural dynamic parameters or the NTPRM macro), Natural
restarts the user front-end transaction at session termination via
RETURN with TRANSID by internally simulating a
PROGRAM='RET=xxx' specification, with
xxx being the front-end transaction code.
To avoid a loop condition, logic must be included into the user front-end routine to decide whether a new session is to be started or an old session is to be resumed.
If the Natural session is invoked via DPL, Natural first determines if it is directly
invoked in the server region or indirectly via EXEC CICS
LINK/XCTL by a local front-end program. When being invoked directly,
Natural retrieves the start parameters from the CICS COMMAREA. When being invoked
indirectly, Natural scans for startup parameters supplied with the COMMAREA, then it scans
for parameters in the TWA. On return Natural passes regular back-end data in the TWA when
there is a local LINK front-end program available, otherwise it returns the termination
message and potential back-end data in the remote client's COMMAREA.
If the Natural session is initiated from a front-end program and this program is also specified to be the return program, the user front-end should also check for the initiating transaction ID.
In particular this applies if the front-end program is not in pseudo-conversational mode but Natural is in conversational mode.
In this case Natural is invoked again rather than getting terminated, but this time without detecting that it is called by a front-end program, as the first parameter in the startup parameters is the Natural transaction ID.