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, and the third subsection considers the possibility of conversation initiation failure. This section also contains program fragments illustrating the commands described below and the suggested response code checking.
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 remote 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 the session is successfully allocated, DFHRESP(NORMAL), the conversation is in allocated state (state 1) and the session identifier (convid) in EIBRSRCE must be saved immediately.
The convid must be used in subsequent commands for this conversation. Figure 3 shows an example of an 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 APPC session. When this is done, and the front-end transaction is successfully started, a conversation can continue as if an ALLOCATE command had been issued. The only difference is that, when ATI is used, the APPC session is the front-end transaction’s principal facility.
* ...
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(4) COMP VALUE +4.
02 WS-SYNC-LVL PIC S9(4) COMP VALUE +2.
* ...
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 RESP code.
END-IF.
* ...
EXEC CICS CONNECT PROCESS CONVID(WS-CONVID)
STATE(WS-STATE) RESP(WS-RESP)
PROCNAME(WS-PROC)
PROCLENGTH(WS-LEN-PROCN)
SYNCLEVEL(WS-SYNC-LVL)
END-EXEC.
IF WS-RESP = DFHRESP(NORMAL)
THEN
* ... No errors. Check EIB flags.
ELSE
* ... Conversation not started. Examine RESP code.
END-IF.
When the front-end transaction has acquired a session, the next step is to initiate the partner transaction. The state tables show that, in the allocated state (state 1), one of the commands available is CONNECT PROCESS. This command is used to attach the required back-end transaction. It should be noted that the results of the CONNECT PROCESS are placed in the send buffer and are not sent immediately to the partner system. Transmission occurs when the send buffer is flushed, either by sending more data than fits in the send buffer or by issuing a WAIT CONVID command.
A successful CONNECT PROCESS causes the conversation to switch to send state (state 2). The program fragment in Figure 3 shows an example of a CONNECT PROCESS command.
While connecting the back-end transaction, the front-end transaction can send initial data to it. This kind of data, called program initialization parameters (PIPs), is placed in specially formatted structures and specified on the CONNECT PROCESS command. The PIPLIST (along with PIPLENGTH) option of the CONNECT PROCESS command is used to send PIPs to the back-end transaction.
To examine any PIPs received, the back-end transaction uses the EXTRACT PROCESS command.
PIP data is used only by the two connected transactions and not by the CICS systems. APPC systems other than CICS may not support PIP, or may support it differently.
The PIP data must be formatted into one or more subfields according to the SNA-architected rules. The content of each subfield is defined by the application developer. You should format PIP data as follows:
PIP data consists of one or more subfields; each subfield contains
The length includes the length field itself and the length of the reserved field; that is, if the PIP field is n bytes long, then the length field contains n + 4.
CICS inserts information into the reserved fields to make the PIP architecturally correct. The PIPLENGTH option must specify the total length of the PIP list and must be between 4 and 32763.
The back-end transaction is initiated as a result of the front end transaction’s CONNECT PROCESS command. Initially, the back-end transaction should determine the convid. 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 useful for audit trails. Also, if the back-end transaction is involved in more than one conversation, always specifying the CONVID option improves program readability and problem determination.
Figure 5 shows a fragment of a back-end transaction that obtains the conversation identifier. The example uses the ASSIGN command for this purpose; another way is to access the information in EIBTRMID.
The back-end transaction can also retrieve its transaction name by issuing the EXTRACT PROCESS command. In the example shown in Figure 5, CICS places the transaction name in WS-PROC and the length of the name in WS-LEN-PROCN. With the EXTRACT PROCESS, the back-end transaction can also retrieve the sync level at which the conversation was started. In the example, CICS places the sync level in WS-SYNC-LVL.
Both the ASSIGN and the EXTRACT PROCESS commands are discussed here only to give you some idea of what you can do in the back-end transaction. They are not essential. The back-end transaction starts in receive state (state 5), and must issue a RECEIVE command. By doing this, the back-end transaction receives whatever data the front-end transaction has sent and allows CICS to raise EIB flags and change the conversation state to reflect any request the front-end transaction has issued.
* ...
DATA DIVISION.
WORKING-STORAGE SECTION.
* ...
01 FILLER.
02 WS-CONVID PIC X(4).
02 WS-STATE PIC S9(7) COMP.
02 WS-SYSID PIC X(4) VALUE 'SYSB'.
02 WS-PROC PIC X(4) VALUE 'BBBB'.
02 WS-LEN-PROCN PIC S9(4) COMP VALUE +4.
02 WS-SYNC-LVL PIC S9(4) COMP VALUE +2.
* ...
01 FILLER.
02 WS-RECORD PIC X(100).
02 WS-MAX-LEN PIC S9(4) COMP VALUE +100.
02 WS-RCVD-LEN PIC S9(4) COMP VALUE +0.
* ...
PROCEDURE DIVISION.
* ...
EXEC CICS ASSIGN FACILITY(WS-CONVID) END-EXEC.
* ...
* Extract the conversation characteristics.
*
EXEC CICS EXTRACT PROCESS PROCNAME(WS-PROC)
PROCLENGTH(WS-LEN-PROCN)
SYNCLEVEL(WS-SYNC-LVL)
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 fails to start. However there is a transmission delay mechanism in APPC, which informs the front-end transaction of this fact when the session has been active long enough for responses from the back-end system to have been received. The front-end transaction is informed of this via a TERMERR condition in response to a DTP command. EIBERR, EIBFREE, and EIBERRCD are set (see Table 9 for the possible values of EIBERRCD).
Before sending data, the front-end transaction should find out whether the back-end transaction has started successfully. One way of doing this is to issue a SEND CONFIRM command directly after the CONNECT PROCESS command. This causes the front-end transaction to suspend until the back-end transaction responds or the failure notification described above is received. SEND CONFIRM is discussed in How to synchronize a conversation using CONFIRM commands.
[[ Contents Previous Page | Next Page Index ]]