Return area for the EXCI CALL interface

The format of the 5-word return area for the EXCI CALL interface is as follows:

  1. 1-word response field.
  2. 1-word reason field.
  3. Two 1-word subreason fields--subreason field-1 and subreason field-2.
  4. 1-word CICS® message pointer field. This is zero if there is no message present. If a message is present, this field contains the address of the storage area containing the message, which is formatted as follows:

Return area and function call EQUATE copybooks

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.

Table 18. Supplied copybooks of return areas and equated names
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

Return codes

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.

Table 19. Supplied copybooks of RESPONSE and REASON codes
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.

Dpl_retarea return codes

These are the same as for CICS-to-CICS EXEC CICS DPL commands but with the following additions for the EXCI call interface:

Table 20. Exceptional conditions RESP and RESP2 values returned to dpl_retarea
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.

Related concepts
Introduction to the external CICS interface
The EXCI programming interfaces
Related tasks
The EXCI CALL interface
The EXCI CALL interface commands
EXCI call response code values
Example of EXCI CALLs with null parameters
The EXCI EXEC CICS interface
[[ Contents Previous Page | Next Page Index ]]