This section describes application programming for CICS®-to-IMS™ distributed transaction processing (DTP). For further information about DTP, see the CICS Distributed Transaction Programming Guide.
The commands that can be used to acquire and use CICS-to-IMS sessions are:
Except in the special case of the receiving transaction in SEND and RECEIVE asynchronous processing, the CICS transaction is always the front-end transaction in CICS-to-IMS DTP.
The front-end transaction is responsible for acquiring a session to the remote IMS system and initiating the remote transaction. Thereafter, the two transactions become equals. However, the front-end transaction is usually designed as the client, or driving, transaction.
You acquire an LUTYPE6.1 session to a remote IMS system by means of the ALLOCATE command, which has the following format:
ALLOCATE {SYSID(name)|SESSION(name)}
[PROFILE(name)]
[NOQUEUE]
You can use the SESSION option to request the use of a specific session to the remote IMS system, or you can use the SYSID option to name the remote system and allow CICS to select an available session. The use of the SESSION option is not normally recommended, because it can result in an application program queuing on a specific session when others are available. In most cases, therefore, you will use the SYSID option to name the system with which the session is required.
If CICS cannot find the named system, or no sessions are available, it raises the SYSIDERR condition. If CICS cannot find the named session or the session is out of service, CICS raises the SESSIONERR condition.
The PROFILE option allows you to specify a communication profile for an LUTYPE6.1 session. The profile, which is set up during resource definition, contains a set of terminal control processing options that are to be used for the session.
If you omit the PROFILE option, CICS uses the default profile DFHCICSA. This profile specifies INBFMH(ALL), which means that incoming function management headers are passed to your program and cause the INBFMH condition to be raised.
The NOQUEUE option allows you to specify explicitly that you do not want your request for a session to be queued if a session is not available immediately. A session is "not immediately available" in any of the following situations:
The action taken by CICS if a session is not immediately available depends on whether you specify NOQUEUE and also on whether your application has issued a HANDLE (which is still active) for the SYSBUSY condition. The possible combinations are shown below:
Whether a delay in acquiring a session is acceptable or not is dependent on your application.
Similar considerations apply to an ALLOCATE command that specifies SESSION rather than SYSID. The associated condition is ‘SESSBUSY‘ (EIBRCODE=X'D2').
When a session has been allocated, the name by which it is known is available in the EIBRSRCE field in the EIB. Because EIBRSRCE will probably be overwritten by the next EXEC CICS command, you must acquire the session name immediately. It is the name that you must use in the SESSION parameter of all subsequent commands that relate to this session.
If the front-end transaction is designed to be started by automatic transaction initiation (ATI) in the local system, and is required to hold a conversation with an LUTYPE6.1 session as its principal facility, the session has already been allocated when the transaction starts. You can omit the SESSION parameter from commands that relate to the principal facility. If, however, you want to name the session explicitly in these commands, you should obtain the name from EIBTRMID.
When a session has been acquired, the next step is to cause the remote IMS process to be initiated.
The LUTYPE6.1 architecture defines a special function management header, called an attach header, which carries the name of the remote process (in CICS terms, the transaction) that is to be initiated, and also contains further session-related information.
CICS provides the BUILD ATTACH command to enable a CICS application program to build an attach header to send to IMS, and the EXTRACT ATTACH command to enable information to be obtained from attach headers received from IMS.
Because these commands are available, you do not need to know the detailed format of an LUTYPE6.1 attach header. In most cases, however, you need to know the meaning of the information that it carries.
The format of the BUILD ATTACH command is:
BUILD ATTACH
ATTACHID(name)
[PROCESS(ISCEDT|BASICEDT|name)]
[RESOURCE(name)]
[RPROCESS(name)]
[RRESOURCE(name)]
[QUEUE(name)]
[IUTYPE(0|data-value)]
[DATASTR(0|data-value)]
[RECFM(data-value)]
The parameters of the BUILD ATTACH command have the following meanings:
In CICS-to-IMS communication, the remote process is always an editor. It can be ISCEDT (or its alias), BASICEDT, or an MFS MID name. The process name must not exceed eight characters.
If the PROCESS option is omitted, IMS assumes ISCEDT.
The RESOURCE option specifies the primary resource name (up to eight characters) that is to be assigned to the remote process that is being initiated.
In CICS-to-IMS communication, the primary resource name is either an IMS transaction code or a logical terminal name. You can omit the RESOURCE option if the IMS message destination is specified in the first eight bytes of the message or if the destination is preset by the IMS operator.
If a primary resource name is supplied to IMS, the data stream is not edited for destination and security information. You should therefore omit the RESOURCE option if IMS password processing is required.
The name in the RESOURCE option is ignored during conversational processing, or if the remote process is BASICEDT.
The RPROCESS option specifies a suggested return destination process name. IMS returns this name as a destination process name (ATTDPN) when it sends a reply to CICS, although the name may be overridden by MFS.
CICS uses the returned destination process name to determine the transaction that is to be attached after a session restart. At any other time, it is ignored. The RPROCESS option should therefore name a transaction that will handle any queued messages when it is attached by CICS at session restart following a session failure.
The RRESOURCE option specifies a suggested primary resource name that is to be assigned to the return process. IMS returns this name as the resource name (ATTPRN) when it sends a reply to CICS.
Although CICS normally ignores this field, one use for it in ISC is to specify a CICS terminal to which output messages occurring after session restart should be sent.
The QUEUE option specifies a queue that can be associated with the remote process. In CICS-to-IMS communication, it is used only to send a paging request to IMS during demand paging. The name used must be the one obtained by a previous EXTRACT ATTACH QNAME command. The name must not exceed eight characters.
The IUTYPE option specifies SNA chaining information for the message. The value is halfword binary. The bits in the binary value are used as follows:
0-7 | X'00' - must be set to zero |
8-15 | X'00' - multiple RU chains |
X'01' - single RU chains. |
The DATASTR option is used to select an IMS component. The value is halfword binary. The bits in the binary value are used as follows:
0-7 | X'00' - must be set to zero |
8-11 | 0000 - (user-defined data stream) |
12-15 | 0000 - IMS Component 1 |
0001 - IMS Component 2 | |
0010 - IMS Component 3 | |
0011 - IMS Component 4. |
If the DATASTR option is omitted, IMS Component 1 is assumed.
The RECFM option specifies the format of the user data that is sent to the remote process. The name must represent a halfword binary value. The bits in the binary value are used as follows:
0-7 | X'00' - reserved - must be set to zero |
8-15 | X'01' - variable-length variable-blocked (VLVB) format |
X'04' - chain of RUs. |
If VLVB is specified, your application program must add a two-byte binary length field in front of each record. If chain of RUs is specified, you can send your data in the usual way; no length fields are required.
A record is interpreted by IMS as either a segment of a message (without MFS) or an MFS record (with MFS).
The RECFM option indicates only the type of the message format. Multiple records can be sent by one SEND command. In this case, it is the responsibility of your application program to perform the blocking.
Having built the attach header, you must ensure that it is transmitted with the first data sent to the remote system by naming it in the ATTACHID option of the SEND or CONVERSE command.
CICS allows you to build an attach header, or any function management header, as part of your output data. You can therefore initiate the remote transaction by including an LUTYPE6.1 attach header in the output area referenced by the first SEND or CONVERSE command. You must specify the FMH option on the command to tell CICS that the data contains an FMH.
A CICS transaction can be the back-end transaction in CICS-to-IMS communication only in the special case of SEND and RECEIVE asynchronous processing.
The transaction is initiated by an LUTYPE6.1 attach FMH received from the remote IMS system, and is allowed to issue only a single RECEIVE command, possibly followed by an EXTRACT ATTACH command.
You can use the EXTRACT ATTACH command to recover session-related information from the attach FMH if required, but the use of this command is not mandatory.
The presence of an attach header is indicated by EIBATT, which is set after the first RECEIVE command has been issued.
The format of the EXTRACT ATTACH command is:
EXTRACT ATTACH
[SESSION(data-area)]
[PROCESS(data-area)]
[RESOURCE(data-area)]
[RPROCESS(data-area)]
[RRESOURCE(data-area)]
[QUEUE(data-area)]
[IUTYPE(data-area)]
[DATASTR(data-area)]
[RECFM(data-area)]
The parameters of the EXTRACT ATTACH command have the following meanings:
The data area must be a halfword binary field. The values set by IMS are as follows:
0-7 | X'00'- (zero) |
8-11 | 0000 - (user-defined data stream) |
12-15 | 0000 - IMS Component 1 |
0001 - IMS Component 2 | |
0010 - IMS Component 3 | |
0011 - IMS Component 4. |
The data area must be a halfword binary field. The values set by IMS are as follows:
0-7 | X'00' - (zero) |
8-15 | X'00' - multiple RU chains, MFS autopaged output |
X'01' - single RU chains, MFS nonpaged output | |
X'05' - single RU chains, MFS demand-paged output. |
The data area must be a halfword binary field. The values set by IMS are as follows:
0-7 | X'00' - (zero) |
8-15 | X'01' - variable-length variable-blocked (VLVB) format |
X'04' - chain of RUs (can also be X'00' or X'05'). |
If VLVB is specified, your application program must deblock the message by using the halfword-binary length field that precedes each record.
The back-end transaction is initiated in receive state, and should issue RECEIVE as its first command or after EXTRACT ATTACH.
The conversation between the front-end and the back-end transactions is held using the usual SEND, RECEIVE, and CONVERSE commands. For programming information about these commands, see the CICS Application Programming Reference manual.
In each of these commands, you must name the session in the SESSION option unless the conversation is with the principal facility.
On ISC sessions, when you issue a SEND command, CICS normally defers sending the data until it becomes clear what your further intentions are. This mechanism enables CICS to avoid unnecessary flows by adding control indicators on the data that is awaiting transmission.
In general, IMS does not accept indicators such as change-direction, syncpoint-request, or end-bracket as stand-alone transmissions on null RUs. You should therefore always allow deferred transmission to operate, and avoid using the WAIT option or the WAIT TERMINAL command to force transmissions to take place.
The LAST option on the SEND command indicates the end of the conversation. No further data flows can occur on the session, and the next action must be to free the session. However, the session can still carry CICS syncpointing flows before it is freed.
A syncpoint on an ISC session is initiated explicitly by a SYNCPOINT command, or implicitly by a RETURN command.
If your conversation has been terminated by a SEND LAST command, without the WAIT option, transmission has been deferred, and the syncpointing activity causes the final transmission to occur with an added syncpoint request. The conversation is thus automatically involved in the syncpoint.
The command used to free the session has the following format:
FREE SESSION(conversation-name)
You must free the session after issuing a SEND LAST command, or when the EIBFREE field has been set.
CICS allows you to issue the FREE command at any time that your transaction is in send state. CICS determines whether the end-bracket indicator has already been transmitted, and transmits it if necessary before freeing the session. If there is also deferred data to transmit, the end-bracket indicator is transmitted with the data. Otherwise, the indicator is transmitted by itself.
Because only some IMS input components accept a stand-alone end-bracket indicator, this use of FREE is not recommended for CICS-to-IMS communication.
For programming information about the EXEC interface block (EIB), see the CICS Application Programming Reference manual. This section highlights the fields that are of particular significance in ISC applications. For further details of how and when these fields should be tested or saved, refer to Command sequences for CICS-to-IMS sessions.
The following EIB fields enable you to obtain the name of the ISC session.
These fields contain information on the state of the session. In most cases, the settings relate to the session named in the last-executed RECEIVE or CONVERSE command, and should be tested, or saved for later testing, after the command has been issued. Further information about the use of these fields is given in Command sequences for CICS-to-IMS sessions.
The following fields contain information about FMHs received from the remote transaction:
If you want to use these facilities, you must ensure that you use communication profiles that specify INBFMH(ALL). The default profile (DFHCICSA) for a session allocated by a CICS front-end transaction has this specification. However, the default principal facility profile (DFHCICST) for a CICS back-end transaction does not. Further information about this subject is given under Defining communication profiles.
The command sequences that you use to communicate between the front-end and the back-end transactions are governed both by the requirements of your application and by a set of high-level protocols designed to ensure that commands are not issued in inappropriate circumstances.
The protocols presented in this section do not cover all possible command sequences. However, by following them, you ensure that each transaction takes account of the requirements of the other. This helps to avoid errors during program development.
The protocols are based on the concept of several separate states. These states apply only to the particular conversation, not to your entire application program. In each state, there is a choice of commands that might most reasonably be issued. After the command has been issued, fields in the EIB can be tested to learn the current requirements of the conversation. The results of these tests, together with the command that has been issued, may cause a transition to another state, when another set of commands becomes appropriate.
The states that are defined for this section are:
Normally, the front-end transaction in a conversation starts in state 1 (session not allocated) and must issue an ALLOCATE command to acquire a session.
An exception to this occurs when the front-end transaction is started by automatic transaction initiation (ATI), in the local system, with an LUTYPE6.1 session as its principal facility. Here, the session is already allocated, and the transaction is in state 2. For transactions of this type, you must immediately obtain the session name from EIBTRMID so that you can name the session explicitly on later commands.
You must always assume that the back-end transaction is initially in state 4 (receive state). Even if it is designed only to send data to the front-end transaction, you must issue a RECEIVE to receive the SEND INVITE issued by the front-end transaction and get into send state.
The following figures help you to construct valid command sequences. Each diagram relates to one particular state, as previously defined, and shows the commands that you might reasonably issue and the tests that you should make after issuing the command. Where more than one test is shown, make them in the order indicated.
The combination of the command issued and a particular positive test result lead to a new, resultant state, shown in the final column.
The tests that are shown in the figures are those that are significant to the state of the conversation. Tests for other conditions that may arise, for example, INVREQ or NOTALLOC, should be made in the normal way.
STATE 1 -- CICS-TO-IMS CONVERSATIONS -- SESSION NOT ALLOCATED | ||
---|---|---|
Commands you can issue | What to test | New state |
ALLOCATE [NOQUEUE] * | SYSIDERR | 1 |
Ditto | SYSBUSY * | 1 |
Ditto | Otherwise (obtain session name from EIBRSRCE) | 2 |
If you want your program to wait until a session is available, omit the NOQUEUE option of the ALLOCATE command and do not code a HANDLE command for the SYSBUSY condition.
If you want control to be returned to your program if a session is not immediately available, either specify NOQUEUE on the ALLOCATE command and test EIBRCODE for SYSBUSY (X'D3'), or code a HANDLE CONDITION SYSBUSY command.
STATE 2 -- CICS-TO-IMS CONVERSATIONS -- SEND STATE | ||
---|---|---|
Commands you can issue * | What to test | New state |
SEND | 2 | |
SEND INVITE | -- | 3 or 4 |
SEND LAST | -- | 6 |
CONVERSE
|
Go to the STATE 4 table and make the tests shown for the RECEIVE command. | -- |
RECEIVE | Go to the STATE 4 table and make the tests shown for the RECEIVE command. | -- |
SYNCPOINT | (Transaction abends if SYNCPOINT fails.) | 2 |
FREE
|
-- | 1 |
For the front-end transaction, the first command used after the session has been allocated must be a SEND command or CONVERSE command that initiates the back-end transaction in one of the ways described under Attaching the remote transaction.
STATE 3 -- CICS-TO-IMS CONVERSATIONS -- RECEIVE PENDING after SEND INVITE | ||
---|---|---|
Commands you can issue | What to test | New state |
SYNCPOINT | (Transaction abends if SYNCPOINT fails.) | 4 |
STATE 4 -- CICS-TO-IMS CONVERSATIONS -- RECEIVE STATE | ||
---|---|---|
Commands you can issue | What to test | New state |
RECEIVE [NOTRUNCATE] * | EIBCOMPL * | -- |
Ditto | EIBSYNC | 5 |
Ditto | EIBFREE | 7 |
Ditto | EIBRECV | 4 |
Ditto | Otherwise | 2 |
If NOTRUNCATE is specified, a zero value in EIBCOMPL indicates that the data passed to the application by CICS is incomplete (because, for example, the data area specified in the RECEIVE command is too small). CICS saves the remaining data for retrieval by later RECEIVE NOTRUNCATE commands. EIBCOMPL is set when the last part of the data is passed back. If the NOTRUNCATE option is not specified, over-length data is indicated by the LENGERR condition, and the remaining data is discarded by CICS.
STATE 5 -- CICS-TO-IMS CONVERSATIONS -- RECEIVER TAKE SYNCPOINT | ||
---|---|---|
Commands you can issue | What to test | New state |
SYNCPOINT | EIBFREE (saved value) | 7 |
Ditto | EIBRECV (saved value) | 4 |
Ditto | Otherwise | 2 |
STATE 6 -- CICS-TO-IMS CONVERSATIONS -- FREE PENDING AFTER SEND LAST | ||
---|---|---|
Commands you can issue | What to test | New state |
SYNCPOINT | -- | 7 |
FREE | -- | 1 |
STATE 7 -- CICS-TO-IMS CONVERSATIONS -- FREE SESSION | ||
---|---|---|
Commands you can issue | What to test | New state |
FREE | -- | 1 |