CICS-to-IMS applications--asynchronous processing

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:

  1. The START and RETRIEVE interface
  2. The SEND and RECEIVE interface.

The START and RETRIEVE interface

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.

CICS front end

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.

Note:
When you issue the operator commands mentioned above, unless you send change direction (CD), IMS expects you to request definite response. You must do this by coding the PROTECT option on the START command.

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.

Figure 75. START and RETRIEVE asynchronous processing-CICS front end
 The picture shows a CICS region and an IMS region, joined by an LUTYPE61 link. A transaction, TRANA, obtains some terminal input, then issues an EXEC CICS START NOCHECK PROTECT request to initiate a remote transaction on the IMS region. When TRANA issues a SYNCPOINT or RETURN command, CICS ships the start request to IMS. When the remote IMS transaction has completed its processing, IMS sends the reply to CICS by issuing a START request which specifies TRANB and the terminal named in the first START command. On CICS, TRANB is started. It retrieves the reply by issuing an EXEC CICS RETRIEVE 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.

IMS front end

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.

Figure 76. RETRIEVE and START asynchronous processing - IMS front end
 The picture shows an IMS region and a CICS region, joined by an LUTYPE61 link. IMS is the front-end region. It issues a START request to start transaction TRANA on CICS. On CICS, TRANA issues an EXEC CICS RETRIEVE command to obtain the details of the request from IMS. It does some processing, then sends its reply to IMS by issuing a START request. The reply is sent when TRANA issues a SYNCPOINT command or terminates.

The START 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]
TRANSID(name)
Specifies the name of the IMS editor that is to be initiated to process the message. It must be an alias (not exceeding four characters) of ISCEDT, or an MFS MID name.

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.

SYSID(name)
Specifies the name of the remote IMS system. This is the name that is specified by the system programmer in the CONNECTION option of the DEFINE CONNECTION command that defines the link to the remote system. You need this option only if you are required to name the remote system explicitly.
FROM(data-area)
Specifies the data that is to be sent. The format of the data (VLVB or chain of RUs) must match the format specified in the RECORDFORMAT option of the DEFINE CONNECTION command that defines the remote IMS system (see Defining links to remote systems).
LENGTH(value)
Specifies, as a halfword binary value, the length of the data specified in the FROM option.
TERMID(name)
Specifies the primary resource name that is to be assigned to the remote process. For IMS, it is a transaction code or an LTERM name.

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.

RTRANSID(name)
Specifies the name of the transaction that is to be invoked when IMS returns a reply to CICS. The name must not exceed four characters in length.
RTERMID(name)
Specifies the name of the terminal that is to be attached to the transaction specified in the RTRANSID option when it is invoked. The name must not exceed four characters in length.
NOCHECK
This option is mandatory.
PROTECT
Specifies that the remote IMS transaction must not be scheduled until the local CICS transaction has taken a syncpoint. PROTECT is mandatory.
FMH
Specifies that the user data to be passed to the started task contains function management headers. This option is not normally used.

The RETRIEVE command

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]
INTO(data-area)
Specifies the user data area into which the data retrieved from IMS is to be written.
SET(pointer-ref)
Specifies the pointer reference to be set to the address of the data retrieved from IMS.
LENGTH(data-area)
Specifies the halfword binary length of the retrieved data.

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.

RTRANSID(data-area)
Specifies an area to receive the return destination process name sent by IMS. It is either an MFS MID name chained from an output MOD, or is blank.

Your application can use this name in the TRANSID option of a subsequent START command.

RTERMID(data-area)
Specifies an area to receive the return primary resource name sent by IMS. It is either a transaction name or an LTERM name.

Your application can use this name in the TERMID option of the START command used to send the reply.

WAIT
Specifies that control is not to be returned to your application program until data is sent by IMS.

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.

The asynchronous SEND and RECEIVE interface

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.

Figure 77. SEND and RECEIVE asynchronous processing - CICS front end
 The picture shows a CICS region and an IMS region, joined by an LUTYPE61 link. On CICS, a transaction, TRANA, issues an EXEC CICS ALLOCATE command to acquire a session to IMS. It then issues three commands--BUILD ATTACH, SEND ATTACHID LAST, and FREE. When the reply is received from IMS, another transaction, TRANB, is started on CICS. TRANB issues the commands RECEIVE, EXTRACT ATTACH, and FREE.

Related concepts
CICS-to-IMS applications--DTP
Related tasks
Designing CICS-to-IMS ISC applications
Defining CICS-to-IMS LUTYPE6.1 links
[[ Contents Previous Page | Next Page Index ]]