The EXCI programming interfaces

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.

API restrictions for server programs

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.

Choosing between the EXEC CICS and the CALL interface

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.

Illustrations of the external CICS CALL interface

The diagrams in Figure 15 through Figure 18 illustrate the external CICS interface using the EXCI CALL interface.

Figure 15. Stage 1: Status after an INITIALIZE_USER call
 This diagram shows the MVS Client Application with External CICS user environment established, and the CICS Server region with MRO EXCI CONNECTION installed with 3 sessions (PROTOCOL= EXCI) (RECEIVECOUNT=3)

Notes:
  1. In Figure 15, the target CICS region is running with IRC open, and one EXCI connection with three sessions installed, at the time the client application program issues an INITIALIZE_USER call.
  2. The client application program address space is initialized with the EXCI user environment. There is no MRO activity at this stage, and no pipe exists.

Figure 16. Stage 2: Status after the first ALLOCATE_PIPE call
 This diagram shows the MVS Client Application with Pipe allocated and the CICS Server region with an MRO EXCI CONNECTION installed with 3 sessions (PROTOCOL= EXCI) (RECEIVECOUNT=3)
Note:
In Figure 16, the external CICS interface logs on to MRO, identifying the target CICS server region.
Notes:
  1. In Figure 17, the external CICS interface connects to the CICS server region, and the pipe is now available for use.
  2. The remaining two EXCI sessions are free, and can be used by further open pipe requests from the same, or a different, client application program (provided the connection is generic).
Figure 18. Stage 4: Status with one open pipe, processing a DPL call
 This diagram shows that a DPL Request and data flows from the client to the server and Response and data flows back. The  MVS Client Application has a pipe opened and the CICS Server region has an MRO EXCI CONNECTION installed with 3 sessions (PROTOCOL= EXCI) (RECEIVECOUNT=3)
Note:
In Figure 18, the external CICS interface passes the DPL request over the open pipe, with any associated data. The CICS server region returns a response and data over the open pipe.

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.

Illustration of the EXCI EXEC CICS interface

Figure 19 illustrates the EXEC CICS interface, and how it resolves to the six EXCI CALLs.

Figure 19. Illustration of the external CICS interface using the EXEC CICS command
 This diagram shows the MVS Client Application issuing an EXEC CICS LINK command . The EXEC interface stub DFHXCSTB calls the EXCI EXEC interface program which issues the following calls: INITIALIZE_USER, ALLOCATE_PIPE, OPEN_PIPE, DPL, CLOSE_PIPE, DEALLOCATE_PIPE

Related concepts
Introduction to the external CICS interface
Resource recovery
EXCI concepts
Requirements for the external CICS interface
Related tasks
The EXCI CALL interface
The EXCI EXEC CICS interface
[[ Contents Previous Page | Next Page Index ]]