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