Starting the conversation

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.

Conversation initiation

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.

Allocating a session to the conversation

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.

Note:
If the remote system is using VTAM® persistent session support, you may need to code a timeout value on the GDS ALLOCATE command. See Using VTAM persistent session support.

Using ATI to allocate a session

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.

Figure 14. Starting an APPC basic conversation at sync level 2
*         ...
          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'
*         ...

Connecting the partner transaction

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.

Note:
For clarity, the EXEC CICS GDS ALLOCATE and GDS CONNECT PROCESS commands shown in Figure 14 identify the partner LU and transaction explicitly. To avoid doing this, you could use the PARTNER option of these commands. This specifies a set of definitions that include the names of the partner LU, the communication profile to be used on the session, and the partner transaction. Thus, in Figure 14, the PARTNER option could be used instead of SYSID on the EXEC CICS GDS ALLOCATE command, and instead of PROCNAME and PROCLENGTH on the EXEC CICS GDS CONNECT PROCESS command. The advantage of using PARTNER is that it makes your DTP programs more maintainable: the details of each partner program can be held in a single definition. For details of the PARTNER resource, see the CICS Resource Definition Guide.

Initial data for the back-end transaction

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:

Figure 15. Format of PIP data.

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.

 This figure shows the layout of a PIP record

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.

Back-end transaction initiation

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.

Figure 16. Startup of a back-end transaction
*         ...
          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
*         ...

What happens if the back-end transaction fails to start up

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.

Table 26. Some indications of back-end failure
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 ]]