In asynchronous processing, the intersystem session is used only to pass an initiation request, together with various items of data, from one system to the other. All other processing is independent of the session that is used to pass the request.
The two application programming interfaces available in CICS® for asynchronous processing are:
For programming information about the CICS START and RETRIEVE "interval control" commands, see the CICS Application Programming Reference manual. The applicable forms of these commands, together with the specific meanings of the command options in a CICS-to-IMS™ intersystem communication environment, are given later in this section.
When CICS is the front-end system, you can use CICS START and RETRIEVE commands to process IMS nonresponse mode and nonconversational transactions, message switches, and the IMS /DIS, /RDIS, and /FOR operator commands.
The general command sequence for your application program is shown in Figure 75.
After transaction TRANA has obtained an input message from the terminal, it issues a START NOCHECK command to initiate the remote IMS transaction. The START command specifies the name of the IMS editor that is to be initiated to process the message and the IMS transaction or logical terminal (LTERM) that is to receive the message. It also specifies the name of the CICS transaction that is to receive the reply and the name of the associated CICS terminal.
The PROTECT option must be specified on the START command to ensure delivery of the message to IMS.
The start request is not shipped until your application program either issues a SYNCPOINT command or terminates. However, the request does not carry the syncpoint-indicator unless PROTECT was specified on the START command.
Although CICS allows an application program to issue multiple START NOCHECK commands without intervening syncpoints (see Deferred sending of START requests with NOCHECK option), this technique is not recommended for CICS-to-IMS communication.
IMS sends the reply by issuing a start request that is handled in the normal way by the CICS mirror transaction. The request specifies the CICS transaction and terminal that you named in the original START command. The transaction that is started (TRANB) can then retrieve the reply by issuing a RETRIEVE command.
In the above example, it has been assumed that there are two separate CICS transactions; one to issue the START command and one to receive the reply and return it to the terminal. These two transactions can be combined, and there are two ways in which this can be done:
In all cases, you should make no assumptions about the timing of the reply or its relationship to a particular previous request. A RETRIEVE command retrieves any outstanding data intended for the same transaction and terminal. The correlation of requests and replies is the responsibility of your application program.
When IMS is the front-end system, the only supported flow is the asynchronous start request. Your application program must use the RETRIEVE command to obtain the request from IMS, followed by a START command to send the reply if one is required.
The general command sequence for your application program is shown in Figure 76.
If a reply to the retrieved data is required, your start command must specify the IMS editor and transaction or LTERM name obtained by the RETRIEVE command.
This section shows the format of the START command that is used to schedule remote IMS transactions. Note that no interval control is possible (although it is not an error to specify INTERVAL(0)) and that the NOCHECK and PROTECT options must be specified.
EXEC CICS START TRANSID(name)
[SYSID(name)]
[FROM(data-area) LENGTH(value)]
[TERMID(name)]
[RTRANSID(name)]
[RTERMID(name)]
NOCHECK
PROTECT
[FMH]
Alternatively, it can name the installed definition of a "remote" transaction. In this case, the SYSID option is not used. The definition of the remote transaction must name the required IMS editor in the RMTNAME option, which can be up to eight characters long.
If this option is omitted, you must specify the transaction code or the LTERM name in the first eight characters of the data named in the FROM option. You must use this method if the name exceeds four characters (the CICS limit for the TERMID option) or if IMS password processing is required.
This section shows the format of the RETRIEVE command that is used to retrieve data sent by IMS.
EXEC CICS RETRIEVE
[{INTO(data-area)|SET(pointer-ref)}
LENGTH(data-area)]
[RTRANSID(data-area)]
[RTERMID(data-area)]
[WAIT]
For a RETRIEVE command with the INTO option, this must be a data area that specifies the maximum length of data that the program is prepared to handle. If the value specified is less than zero, zero is assumed. If the length of the data exceeds the value specified, the data is truncated to that value and the LENGERR condition occurs. On completion of the retrieval operation, the data area is set to the original length of the data.
For a RETRIEVE command with the SET option, this must be a data area. On completion of the retrieval operation, the data area is set to the length of the data.
Your application can use this name in the TRANSID option of a subsequent START command.
Your application can use this name in the TERMID option of the START command used to send the reply.
If WAIT is not specified, the ENDDATA condition is raised if no data is available. If WAIT is specified, the ENDDATA condition is raised only if CICS is shut down before any data becomes available.
The use of the WAIT option is not generally recommended, because it can cause intervening messages (not the expected reply) to be retrieved.
This form of asynchronous processing is, in CICS, a special case of distributed transaction processing. A CICS transaction acquires the use of a session to a remote system, and uses the session for a single transmission (using a SEND command with the LAST option) to initiate a remote transaction and send data to it. The reply from the remote system causes a CICS transaction to be initiated just as if it were a back-end transaction in normal DTP. This transaction, however, can issue only a single RECEIVE command, and must then free the session.
Except for these additional restrictions, you can design your application according to the rules given for distributed transaction processing later in this section.
The general command sequence for asynchronous SEND and RECEIVE application programs is shown in Figure 77.