Testing indicators

When RETCODE shows a normal return code from a GDS command, the CONVDATA area (where applicable) contains information on the indicators received on the conversation. These indicators can be used to find out why the conversation state is what it is.

The structure of the CONVDATA area is shown in Table 1.

Table 1. Structure of the conversation data block
Field name	Length (bytes)	Meaning
CDBCOMPL	1	X'FF' = data complete
CDBSYNC	1	X'FF' = SYNCPOINT required
CDBFREE	1	X'FF' = FREE required
CDBRECV	1	X'FF' = RECEIVE required
CDBSIG	1	X'FF' = SIGNAL received
CDBCONF	1	X'FF' = CONFIRM received
CDBERR	1	X'FF' = ERROR received
CDBERRCD	4	Error code (when CDBERR set)
CDBSYNRB	1	X'FF' = SYNCPOINT ROLLBACK required
CDBRSVD	12	Reserved

These definitions are provided in copybook DFHCDBLK. There is one copybook for C, which defines a typedef for the structure, and another copybook for assembler. To provide the flexibility to enable your application to manage more than one conversation at the same time, the assembler version does not contain a DSECT statement.

The meanings of the CONVDATA fields are as follows:

CDBERR: when set to X'FF' indicates an error has occurred on the conversation. The reason is in CDBERRCD. This could be as a result of a GDS ISSUE ERROR, GDS ISSUE ABEND, or SYNCPOINT ROLLBACK command issued by the partner transaction. CDBERR can be set as a result of any command that can be issued while the conversation is in receive state (state 5), or following any command that causes a transmission to the partner system. It is safest to test CDBERR in conjunction with CDBFREE and CDBSYNRB after every GDS command.
CDBERRCD: contains the reason for CDBERR. If CDBERR is not set, this field is not used.
CDBFREE: when set to X'FF' indicates that the partner transaction had ended the conversation. It should be tested along with CDBERR and CDBSYNC to find out exactly how to end the conversation.
CDBSIG: when set to X'FF' indicates the partner transaction or system has issued and GDS ISSUE SIGNAL command.
CDBSYNRB: when set to X'FF' indicates the partner transaction or system has issued a SYNCPOINT ROLLBACK command. (This is relevant only for conversations at sync level 2.)

Table 2 shows how these CDB fields interact.

Table 2. Interaction between some CDB fields—all DTP commands
CDB- ERR	CDB- FREE	CDB- SYNRB	CDBERRCD	Description
X'FF'	X'00'	X'00'	X'08890000' X'08890001'	The partner transaction has sent GDS ISSUE ERROR
X'FF'	X'00'	X'00'	X'08890100' X'08890101'	The partner system has sent GDS ISSUE ERROR
X'FF'	X'00'	X'00'	X'A0020000'	Error in data received from partner
X'FF'	X'FF'	X'00'	X'08640000'	The partner transaction has sent GDS ISSUE ABEND
X'FF'	X'FF'	X'00'	X'08640001'	The partner system has sent GDS ISSUE ABEND
X'FF'	X'FF'	X'00'	X'08640002'	A partner resource has timed out
X'FF'	X'FF'	X'00'	X'1008600B'	The session has failed due to a protocol error
X'FF'	X'FF'	X'00'	X'A0000100'	A temporary session failure
X'FF'	X'FF'	X'00'	X'A0010100'	RTIMOUT has triggered
X'FF'	X'FF'	X'00'	X'10086032'	The PIP data sent with the GDS CONNECT PROCESS was incorrectly specified
X'FF'	X'FF'	X'00'	X'10086034'	The partner system does not support basic conversations
X'FF'	X'FF'	X'00'	X'080F6051'	The partner transaction failed security check
X'FF'	X'FF'	X'00'	X'10086041'	The partner transaction does not support the sync level requested on the GDS CONNECT PROCESS
X'FF'	X'FF'	X'00'	X'10086021'	The partner transactions name is not recognized by the partner system
X'FF'	X'FF'	X'00'	X'084C0000'	The partner system cannot start partner transaction
X'FF'	X'FF'	X'00'	X'084B6031'	The partner system is temporarily unable to start the partner transaction
X'FF'	X'00'	X'FF'	X'08240000'	The partner transaction or system has issued SYNCPOINT ROLLBACK
X'00'	X'00'	—	—	The command completed successfully

In addition, the following CONVDATA fields are relevant only to GDS RECEIVE commands:

CDBCOMPL: when set to X'FF' indicates that all the data sent at one time has been received. This field is used in conjunction with the GDS RECEIVE LLID command.
CDBCONF: when set to X'FF' indicates that the partner transaction has issued a GDS SEND CONFIRM command and requires a response.
CDBRECV: is only used when CDBERR is not set. When CDRECV is on (X'FF'), another GDS RECEIVE is required.
CDBSYNC: when set to X'FF' indicates that the partner transaction or system has requested a syncpoint. (This is relevant only for conversations at sync level 2.)

Table 3 shows how some of these CDB fields interact for RECEIVE commands.

Table 3. Interaction between some CDB fields—RECEIVE commands only
CDB- ERR	CDB- FREE	CDB- RECV	CDB- SYNC	CDB- CONF	Description
X'00'	X'00'	X'00'	X'00'	X'00'	The partner transaction or system has issued GDS SEND INVITE WAIT. The local program is now in send state.
X'00'	X'00'	X'00'	X'FF'	X'00'	The partner transaction or system has issued GDS SEND INVITE, followed by a SYNCPOINT. The local program is now in syncsend state.
X'00'	X'00'	X'00'	X'00'	X'FF'	The partner transaction or system has issued GDS SEND INVITE CONFIRM. The local program is now in confsend state.
X'00'	X'00'	X'FF'	X'00'	X'00'	The partner transaction or system has issued GDS SEND or GDS SEND WAIT. The local program is in receive state.
X'00'	X'00'	X'FF'	X'FF'	X'00'	The partner transaction or system has issued a SYNCPOINT. The local program is in syncreceive state.
X'00'	X'00'	X'FF'	X'00'	X'FF'	The partner transaction or system has issued a GDS SEND CONFIRM. The local program is in confreceive state.
X'00'	X'FF'	X'00'	X'00'	X'00'	The partner transaction or system has issued a GDS SEND LAST WAIT. The local program is in free state.
X'00'	X'FF'	X'00'	X'FF'	X'00'	The partner transaction or system has issued a GDS SEND LAST followed by a SYNCPOINT. The local program is in syncfree state.
X'00'	X'FF'	X'00'	X'00'	X'FF'	The partner transaction or system has issued a GDS SEND LAST CONFIRM. The local program is in conffree state.

After analyzing the CONVDATA fields, you can test the conversation state to find out which GDS commands you can issue next. See State transitions in APPC basic conversations.