Checking the outcome of GDS commands

The CICS® exec interface block (EIB) is not affected by EXEC CICS GDS commands, and no CICS conditions can be raised when EXEC CICS GDS commands are executed. Instead, you must provide data areas in your application to receive return codes and session status information.

The data areas required are:

Within the bounds of the programming language you are using, you can give these areas any identifiers you like. They must be named explicitly in most EXEC CICS GDS commands.

Checking the response from a GDS command can be separated into three stages:

  1. Testing for request failure; this involves testing RETCODE.
  2. Testing for indicators received on the conversation. These indicators are found in CONVDATA.
  3. Testing the conversation state.

Testing for request failure

The RETCODE area is used to detect any errors that occur when an EXEC CICS GDS command is executed. These errors correspond to CICS exception conditions, such as NOTALLOC, that can be raised when EXEC CICS commands are executed.

These errors usually reflect failure of the request. Figure 23 shows the possible hexadecimal values for the first three bytes of RETCODE. These values are structured so that the first byte indicates the general error description and subsequent bytes provide the detail.

Figure 23. RETCODE values
00 .. ..   Normal return code
01 .. ..   ALLOCATE failure (applicable only to GDS ALLOCATE)
01 04 ..     SYSBUSY, unknown modename, task cancelled
01 04 04       No bound contention winner available (SYSBUSY)
01 04 08       Modename not known on this system
01 04 0C       Attempt to use reserved modename SNASVCMG, or no COS
               table in VTAM for the modename
01 04 10       Task cancelled during queuing of ALLOCATE
01 04 14       The requested modegroup is closed
01 04 18       The requested modegroup is draining
01 08 ..     SYSID is out of service
01 08 00       Connection out of service or in quiesce state, no usable
               sessions in requested modegroup, or VTAM ACB is closed

01 08 04       Maximum number of queued ALLOCATE requests specified
               on QUEUELIMIT CONNECTION parameter exceeded
01 08 08       ALLOCATE queue purged because MAXQTIME would be exceeded

01 0C ..     SYSID is not known in TCT
01 0C 00       SYSID name is not known
01 0C 04       SYSID name is not that of an APPC connection
01 0C 14       NETNAME specified in PARTNER definition is not known
02 0C 00   PARTNER is not known
03 .. ..   INVREQ error
03 00 ..     Session is either not defined as APPC, in use by
             CPI Communications, or (for EXTRACT PROCESS) not
             the principal facility
03 04 ..     GDS command issued on a conversation that is not basic
03 08 ..     Command issued in wrong state
03 0C ..     Sync level cannot be supported or cannot support the
             command issued
03 10 ..     LL error on a GDS SEND
03 14 ..     SEND CONFIRM or ISSUE CONFIRMATION used at sync level 0
03 24 ..     GDS ISSUE PREPARE used in wrong state
04 .. ..   NOTALLOC error (CONVID specifies an unallocated session)
05 .. ..   LENGERR error (FLENGTH, MAXFLENGTH, PROCLENGTH, PIPLENGTH,
           or MAXPROCLEN error)
06 00 00   PROFILE specified in PARTNER definition is not known

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 31.

Table 31. 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 32 shows how these CDB fields interact.

Table 32. 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 33 shows how some of these CDB fields interact for RECEIVE commands.

Table 33. 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.

Checking CONVDATA fields and the conversation state

Most of the information supplied by the CONVDATA fields can also be obtained from the conversation state. However, although the conversation state is easier to test, you cannot ignore CDBERR (and CDBERRCD).

For example, if after a GDS SEND INVITE WAIT or a GDS RECEIVE command has been issued, the conversation is in receive state (state 5), only CDBERR indicates that the partner transaction has sent a GDS ISSUE ERROR. This is illustrated in Figure 24 and Figure 25.

It should be noted that the state tables provided contain not only conversation states and commands issued, but also relevant CONVDATA field settings. The order in which these fields are shown provides a sensible sequence of checks for an application.

Figure 24. Checking the outcome of a GDS RECEIVE command
*         ...
* Check return code from RECEIVE
          NC    WRETC,WRETC
          BNZ   BADRET         Request-related error, analyze
*         ...                  Request successful
          NC    CDBERR,CDBERR
          BNZ   ERROR          Error indicated, analyze
*         ...                  No errors, check state
          CLC   WSTATE,DFHVALUE(SYNCFREE)
          BE    OKSYNFR        Partner issued SYNCPOINT and LAST
          CLC   WSTATE,DFHVALUE(SYNCRECEIVE)
          BE    OKSYNRC        Partner issued SYNCPOINT
          CLC   WSTATE,DFHVALUE(SYNCSEND)
          BE    OKSYNSE        Partner issued SYNCPOINT and INVITE
          CLC   WSTATE,DFHVALUE(CONFFREE)
          BE    OKCONFR        Partner issued CONFIRM and LAST
          CLC   WSTATE,DFHVALUE(CONFRECEIVE)
          BE    OKCONRC        Partner issued CONFIRM
          CLC   WSTATE,DFHVALUE(CONFSEND)
          BE    OKCONSE        Partner issued CONFIRM and INVITE
          CLC   WSTATE,DFHVALUE(FREE)
          BE    OKFREE         Partner issued LAST
          CLC   WSTATE,DFHVALUE(SEND)
          BE    OKSEND         Partner issued INVITE
          CLC   WSTATE,DFHVALUE(RECEIVE)
          BE    OKRECV         Processing for receipt of data
*                              (including CDBCOMPL for incomplete data)

          B     LOGICERR       Logic error, should never happen
*         ...
ERROR     DS    0H
*                              Error indicated
          CLC   WSTATE,DFHVALUE(ROLLBACK)
          BE    ERRRLBK        ROLLBACK received
          CLC   WSTATE,DFHVALUE(FREE)
          BE    ERRFREE        ISSUE ABEND & TERMERR received,
*                              reason in CDBERRCD
          CLC   WSTATE,DFHVALUE(RECEIVE)
          BE    ERRRECV        ISSUE ERROR received, reason in CDBERRCD

          B     LOGICERR       Logic error, should never happen
*         ...
BADRET    DS    0H
*         ...                  Examine RETCODE for source of error
*         ...
WSTATE    DS    F
WRETC     DS    XL6
WCDB      DS    0CL24
          COPY  DFHCDBLK
*         ...
Figure 25. Checking the outcome of a GDS SEND INVITE WAIT command
*         ...
* Check return code from SEND INVITE WAIT
          NC    WRETC,WRETC
          BNZ   BADRET         Request-related error, analyze RETCODE
*         ...                  Request successful
          NC    CDBERR,CDBERR
          BNZ   ERROR          Error indicated, analyze state
*         ...                  No errors, check state
          CLC   WSTATE,DFHVALUE(RECEIVE)
          BE    OKRECV         Processing for receipt of data
*                              (including CDBCOMPL for incomplete data)

          B     LOGICERR       Logic error, should never happen
*         ...
ERROR     DS    0H
*                              Error indicated
          CLC   WSTATE,DFHVALUE(ROLLBACK)
          BE    ERRRLBK        ROLLBACK received
          CLC   WSTATE,DFHVALUE(FREE)
          BE    ERRFREE        ISSUE ABEND & TERMERR received,
*                              reason in CDBERRCD
          CLC   WSTATE,DFHVALUE(RECEIVE)
          BE    ERRRECV        ISSUE ERROR received, reason in CDBERRCD

          B     LOGICERR       Logic error, should never happen
*         ...
BADRET    ...                  Examine RETCODE for source of error
*         ...
*
WSTATE    DS    F
WRETC     DS    XL6
WCDB      DS    0CL24
          COPY  DFHCDBLK
*         ...
[[ Contents Previous Page | Next Page Index ]]