This section describes how to get a conversation started. The first two subsections explain how the front-end transaction and the back-end transaction initiate the conversation. The third subsection discusses the possibility of conversation initiation failure. This section also contains program fragments illustrating the commands described and the suggested response code checks.
The front-end transaction is responsible for acquiring a session, specifying the conversation characteristics and requesting the startup of the back-end transaction in the partner system.
Initially, there is no conversation, and therefore no conversation state. By issuing an ALLOCATE command, the front-end transaction acquires a session to start a new conversation.
The RESP value returned should be checked to ensure that a session has been allocated. If successfully allocated, DFHRESP(NORMAL), the conversation is in allocated state (state 1) and the session identifier (convid) from EIBRSRCE must be saved immediately.
The convid must be used in subsequent commands for this conversation. Figure 9 shows a program fragment containing an example of the ALLOCATE command. You will notice that the PROFILE option has been omitted from the command.
If the PROFILE option is specified for an MRO link, CICS® ignores it at execution time. So none of the facilities selected through use of a profile (for example, RTIMEOUT and JOURNALING) are available. The front-end transaction has no control over its session processing options when an MRO session is being used.
A back-end transaction with an MRO session as its principal facility will be sent the INBFMH parameter by CICS, regardless of the what the front-end transaction specifies on the PROFILE option of the ALLOCATE command.
Front-end transactions are often initiated from terminals. But it is also possible to use the EXEC CICS START command to initiate a front-end transaction on an MRO session. When the front-end transaction is successfully started in this way, a conversation can continue as if an ALLOCATE command had been issued. The only difference is that an automatically-initiated front-end transaction has the MRO session as its principal facility.
When a session has been acquired, the next step is to cause the partner transaction to be initiated. The state table shows that, in allocated state (state 1), one of the commands available is SEND. Using this command, the back-end transaction’s identifier can be specified in the first four bytes of the data which, when transferred to the partner system, will be used to attach the required back-end transaction. The send buffer containing the transaction identifier together with any other data, will be flushed immediately and the front-end transaction will wait until a response is received from the back end. Figure 9 shows an example in which a transaction identifier is sent.
Alternatively, when a session has been acquired, the front-end transaction can build and send an attach header with the first transmission of data. The attach header can be built using the BUILD ATTACH command.
When using the BUILD ATTACH command, an eight-character name must be given to the built attach header which can then be used in the ATTACHID option of the first SEND (or CONVERSE) command. The back-end transaction identifier should also be specified.
* ...
DATA DIVISION.
WORKING-STORAGE SECTION.
* ...
01 FILLER.
02 WS-CONVID PIC X(4).
02 WS-RESP PIC S9(8) COMP.
02 WS-STATE PIC S9(8) COMP.
02 WS-SYSID PIC X(4) VALUE 'SYSB'.
02 WS-PROC PIC X(4) VALUE 'BBBB'.
02 WS-LEN-PROCN PIC S9(5) COMP VALUE +4.
* ...
PROCEDURE DIVISION.
* ...
EXEC CICS ALLOCATE SYSID(WS-SYSID) RESP(WS-RESP) END-EXEC.
IF WS-RESP = DFHRESP(NORMAL)
THEN MOVE EIBRSRCE TO WS-CONVID
ELSE
* ... No session allocated. Examine EIBRCODE.
END-IF.
* ...
EXEC CICS SEND CONVID(WS-CONV) RESP(WS-RESP) STATE(WS-STATE)
FROM(WS-PROC) LENGTH(WS-LEN-PROCN)
END-EXEC.
IF WS-RESP = DFHRESP(NORMAL)
THEN
* ... No errors, conversation started.
ELSE
* ... Conversation not started. Examine EIBRCODE.
END-IF.
The back-end transaction is initiated either by an attach header received from the partner system or by a transaction identifier included in the incoming data, and is started with the session as its principal facility. Initially, the back-end transaction should determine the convid from EIBTRMID. This is not strictly necessary because the session is the back-end transaction’s principal facility making the CONVID parameter optional for DTP commands on this conversation. However, the convid is very useful for audit trails. Also, if the back-end transaction is involved in more than one conversation, then always specifying the convid will improve program readability and problem determination. Figure 10 shows a back-end transaction that does obtain the convid.
When the back-end transaction receives data, the presence of an attach header is indicated by either EIBATT or RESP(INBFMH). One of these is normally set after the back-end transaction issues its first RECEIVE command. The EXTRACT ATTACH command can be used to access session-related information from the attach header (for example, the back-end transaction identifier) if required, but it is not mandatory.
* ...
DATA DIVISION.
WORKING-STORAGE SECTION.
* ...
01 FILLER.
02 WS-CONVID PIC X(4).
02 WS-STATE PIC S9(7) COMP.
* ...
01 FILLER.
02 WS-RECORD PIC X(100).
02 WS-MAX-LEN PIC S9(5) COMP VALUE +100.
02 WS-RCVD-LEN PIC S9(5) COMP VALUE +0.
* ...
PROCEDURE DIVISION.
* ...
EXEC CICS ASSIGN FACILITY(WS-CONVID) END-EXEC.
* ...
* Receive data from the front-end transaction.
*
EXEC CICS RECEIVE CONVID(WS-CONVID) STATE(WS-STATE)
INTO(WS-RECORD) MAXLENGTH(WS-MAX-LEN)
NOTRUNCATE LENGTH(WS-RCVD-LEN)
END-EXEC.
*
* ... Check outcome of RECEIVE.
* ...
It is possible that the back-end transaction may fail to start up. This will result in the front-end transaction abending. Message DFHIR3783 contains the reason for the error.
[[ Contents Previous Page | Next Page Index ]]