The format of the 5-word return area for the EXCI CALL interface is as follows:
CICS provides four language-specific copybooks that map the storage areas for the return_area and dpl_retarea parameters of the EXCI CALL commands. The copybooks also provide EQUATE statements for each type of EXCI CALL.
These copybooks, and the libraries they are supplied in for the supported languages, are shown in Table 18.
Copybook name | Language | Library |
---|---|---|
DFHXCPLD | Assembler | CICSTS31.CICS.SDFHMAC |
DFHXCPLH | C | CICSTS31.CICS.SDFHC370 |
DFHXCPLO | COBOL | CICSTS31.CICS.SDFHCOB |
DFHXCPLL | PL/I | CICSTS31.CICS.SDFHPL1 |
All the possible return codes are contained in a CICS-supplied copybook, which you must include in the program source of your external, non-CICS program. The names of the copybooks for the supported languages, and the libraries they are supplied in, are shown in Table 19.
Copybook name | Language | Library |
---|---|---|
DFHXCRCD | Assembler | CICSTS31.CICS.SDFHMAC |
DFHXCRCH | C | CICSTS31.CICS.SDFHC370 |
DFHXCRCO | COBOL | CICSTS31.CICS.SDFHCOB |
DFHXCRCL | PL/I | CICSTS31.CICS.SDFHPL1 |
OS/390® provides copybooks for use with the interfaces described on Taking a syncpoint in the client program. These are described in OS/390 MVS Programming: Resource Recovery and OS/390 MVS Programming: Callable Services for HLL.
These are the same as for CICS-to-CICS EXEC CICS DPL commands but with the following additions for the EXCI call interface:
Condition | RESP2 | Meaning |
---|---|---|
LENGERR | 22 | COMMAREA_LEN_TOO_BIG |
LENGERR | 23 | COMMAREA_BUT_NO_COMMAREA_LEN |
SYSIDERR also can be returned on an EXCI DPL_Request, if the DPL_Request specifies a program defined in the CICS server region as a remote program, and the link between the server and the remote CICS region is not open. In this situation, SYSIDERR is returned in the first word of the DPL_Retarea (code 53). The reason code qualifying SYSIDERR is placed in the second word of this area (the equivalent of a RESP2 value).For SYSIDERR, the information stored in this field is derived from bytes 1 and 2 of the CICS EIBRCODE field. For example, if a remote link is not available, the EIBRCODE value stored in bytes 2 and 3 of the DPL_Retarea RESP2 field is X'0800'. For a list of the SYSIDERR reason codes that can be returned in the RESP2 field, see the SYSIDERR section of the notes on EIBRCODE in the CICS Application Programming Reference manual.
TERMERR also may be returned on an EXCI DPL request if the DPL request was to a program defined as remote, and an unrecoverable error occurs during conversation with the mirror on the remote CICS system. For example, suppose client program BATCH1 issues an EXCI DPL request to CICSA for program PROG1, which is defined as remote, and the request is function-shipped to CICSB where the program resides. If the session between CICSA and CICSB fails, or CICSB itself fails whilst executing the program PROG1, then TERMERR is returned to CICSA, and in turn to BATCH1.
No unique EXCI_DPL_RESP2 values are returned for TERMERR, PGMIDERR, NOTAUTH, and ROLLBACK.