EXCI programming considerations

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 considerations

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 considerations

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 C, 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.

Setting the return code (R15) at termination

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.

The external CICS interface is not obliged to clear register 15 and does not clear it upon exit to the client program that invokes it. The value in register 15 reflects a return code for the entire application, not just for the external CICS interface. If register 15 is cleared during exit from the external CICS interface, it might suggest that the client application works without any issue and this might lead the client to make incorrect decisions. By not setting register 15 when control returns from the external CICS interface, it is the responsibility of the client program to set it since it is aware of the application’s overall state.

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.