The external CICS® interface provides two forms of programming interface: the EXCI CALL interface and the EXEC CICS interface.
The EXCI CALL interface: This interface consists of six commands that allow you to:
The six EXCI commands are:
The EXEC CICS interface: The external CICS interface provides a single, composite command--EXEC CICS LINK PROGRAM--that performs all six commands of the EXCI CALL interface in one invocation.
This command is similar but not identical to the distributed program link command of the CICS command-level application programming interface.
A CICS server program invoked by an external CICS interface request is restricted to the DPL subset of the CICS application programming interface. This subset (the DPL subset) of the API commands is the same as for a CICS-to-CICS server program.
See the CICS Application Programming Guide for details of the DPL subset for server programs.
As illustrated in the various language versions of the CICS-supplied sample client program (see Using EXCI sample application programs for details), you can use both the CALL interface (all six commands) and the EXEC CICS LINK command in the same program, to perform separate requests. As a general rule, it is unlikely that you would want to do this in a production program.
Each form of the external CICS interface has its particular benefits.
It is easier to code, and therefore less prone to programming errors.
Note that each invocation of an EXEC CICS LINK command causes the external CICS interface to perform all the functions of the CALL interface, which results in unnecessary overhead.
Note also that this overhead is greatly increased if you use the EXEC CICS LINK command to communicate with a CICS server region in a different LPAR. In
this case each invocation of the EXEC CICS LINK command generates a great
deal of XCF activity because of the IRP logon, connect, disconnect and logoff
which is required. You might find that you experience severe degradation of
elapsed time between EXEC CICS LINK commands issued to a CICS server region
in a separate LPAR, compared to the elapsed time of the same commands issued
to a CICS server region in the same LPAR.
This is more efficient, because you need only perform the Initialize_User and Allocate_Pipe commands once, at or near the beginning of your program, and the Deallocate_Pipe once on completion of all DPL activity. In between these functions, you can open and close the pipe as necessary, and while the pipe is opened, you can issue as many DPL calls as you want.
The diagrams in Figure 15 through Figure 18 illustrate the external CICS interface using the EXCI CALL interface.
Closing pipes: When the client application program closes a pipe, it remains allocated ready for use by the same user, and the status is as shown in Figure 16. At this stage, the MRO session is available for use by another open pipe request, from the same or from a different client application program (provided the connection is generic).
Deallocating pipes: When the client application program deallocates a pipe, it logs off from MRO and frees all the storage associated with the session. This leaves the status as shown in Figure 15.
Figure 19 illustrates the EXEC CICS interface, and how it resolves to the six EXCI CALLs.