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 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 partner system.
Initially, there is no conversation, and therefore no conversation state. By issuing a GDS ALLOCATE command, the front-end transaction acquires a session to start a new conversation.
RETCODE should be checked to ensure that a session has really been allocated. If successfully allocated (RETCODE = X'00'), the conversation is in allocated state (state 1) and the session identifier (convid) is placed in the data area specified on the CONVID parameter.
The convid must be used in subsequent commands for this conversation. Figure 14 shows an example of a GDS 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 a GDS 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.
* ...
EXEC CICS GDS ALLOCATE SYSID(WSYSID) CONVID(WCONVID) *
STATE(WSTATE) RETCODE(WRETC)
*
* Check outcome of GDS ALLOCATE
*
NC WRETC,WRETC
BNZ ALLOCERR No session allocated, check RETCODE
* ...
EXEC CICS GDS CONNECT PROCESS CONVID(WCONVID) STATE(WSTATE) *
PROCNAME(WPROC) *
PROCLENGTH(WLENPROC) *
SYNCLEVEL(WSYNCLVL) *
CONVDATA(WCDB) RETCODE(WRETC)
NC WRETC,WRETC
BNZ CONNERR Request failed, analyze RETCODE
* ... No errors, conversation started.
NC CDBERR,CDBERR
BNZ SESSERR Session failed, examine RETCODE.
* ... Start sending data.
* ...
WSTATE DS F
WRETC DS XL6
WCDB DS 0CL24
COPY DFHCDBLK
WCONVID DS CL4
WSYSID DC CL4'SYSB'
WPROC DC CL4'BBBB'
WLENPROC DC F'4'
WSYNCLVL DC F'2'
* ...
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 GDS CONNECT PROCESS. This command is used to attach the required back-end transaction. It should be noted that the results of the GDS 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 GDS WAIT command.
A successful GDS CONNECT PROCESS causes the conversation state to switch to send state (state 2). Figure 14 is a program fragment showing an example of a GDS CONNECT PROCESS.
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 GDS CONNECT PROCESS command. The PIPLIST (along with PIPLENGTH) option of the GDS CONNECT PROCESS command is used to send PIPs to the back-end transaction.
To examine any PIPs received, the back-end transaction uses the GDS 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 in the reserved fields so that the PIP is architecturally correct. The PIPLENGTH option must specify the total length of the PIP list and must be between 4 and 32763.
A back-end transaction is initiated as a result of the front end’s GDS CONNECT PROCESS command. Initially the back-end transaction should determine the convid. Figure 16 shows a fragment of a back-end transaction that uses the EXEC CICS GDS ASSIGN command to obtain the convid. The back-end transaction can also obtain the transaction identifier and sync level used to start the conversation. The GDS EXTRACT PROCESS command is used to obtain this information.
The back-end transaction starts in receive state (state 5). So, after obtaining the convid, the back-end transaction can issue a GDS RECEIVE command.
* ...
EXEC CICS GDS ASSIGN PRINCONVID(WCONVID) RETCODE(WRETC)
*
* ...
*
EXEC CICS GDS EXTRACT PROCESS CONVID(WCONVID) *
PROCNAME(WPROC) RETCODE(WRETC) *
PROCLENGTH(WLENPROC) *
SYNCLEVEL(WSYNCLVL)
* ...
* Receive first data from front-end transaction.
* ...
*
WSTATE DS F
WRETC DS XL6
WCDB DS 0CL24
COPY DFHCDBLK
WCONVID DS CL4
WPROC DS CL4
WLENPROC DS F
WSYNCLVL DS F
* ...
It is possible that the back-end transaction fails to start up. However, because of the transmission delay mechanism in APPC, the front-end transaction is not informed of this fact until the conversation has been active long enough for responses from the back-end system to be received. The front-end transaction is informed of this via CDBERR and CDBFREE. In addition, CDBERRCD is set as shown in Table 26.
CDBERRCD value | Reason |
---|---|
10086032 | The PIP data sent with the GDS CONNECT PROCESS was incorrectly specified. |
10086034 | The partner system does not support basic conversations. |
080F6051 | The partner transaction failed security check. |
10086041 | The partner transaction does not support the sync level requested on the GDS CONNECT PROCESS. |
10086021 | The partner system does not recognize the requested transaction identifier. |
084C0000 | The partner system cannot start the partner transaction. |
084B6031 | The partner system is temporarily unable to start the partner transaction. |
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 GDS SEND CONFIRM command directly after the GDS CONNECT PROCESS. This causes the front-end transaction to be suspended until the back end transaction has responded or the back-end system has sent the failure notification described above.
[[ Contents Previous Page | Next Page Index ]]