There are some language requirements that apply to writing an MVS™ client program that uses the external CICS® interface. These affect programs written in PL/I and C. Also, for all languages, consider how you handle return codes before terminating your MVS client program.
PL/I programs written to the external CICS interface must provide their parameters on the CALL to DFHXCIS in the form of an assembler-style parameter list.
The EXCI copybook for PL/I, DFHXCPLL, contains the necessary definition of the DFHXCIS entry point, as follows:
DCL DFHXCIS ENTRY OPTIONS(INTER ASSEMBLER);
The same rule applies for the EXCI LINK command, and in this case the CICS translator ensures that the correct parameter list is built.
For an example of an EXCI client program written in PL/I, see the source of the sample program, DFH$PXCC.
C programs written to the external CICS interface must provide their parameters on the CALL to DFHXCIS in the form of an assembler-style parameter list. You ensure this by declaring the entry point to DFHXCIS with OS LINKAGE.
The EXCI copybook for PL/I, DFHXCPLH, contains the necessary definition of the DFHXCIS entry point, as follows:
#pragma linkage(dfhxcis,OS)
The same rule applies for the EXCI LINK command, and in this case the CICS translator ensures that the correct parameter list is built.
For an example of an EXCI client program written in C, see the source of the sample program, DFH$DXCC.
The external CICS interface does not clear register 15 at termination, regardless of whether your client program executes normally or not. Therefore, even if your MVS client program terminates normally after successfully using the external CICS interface, the job step could end with an undefined return code.
To ensure a meaningful return code is given at termination, set the job step return code before terminating your program. The sample client programs illustrate how you can do this, using the saved response code from last call to the external CICS interface. For example, the COBOL sample DFH0CXCC program moves SAVED-RESPONSE to special register RETURN-CODE before terminating.