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.