Design overview

This section provides an overview of the design of the external CICS® interface. For more information about the external CICS interface, see the CICS External Interfaces Guide.

The external CICS interface is an application programming interface that enables a non-CICS program (a client program) running in MVS™ to call a program (a server program) running in a CICS Transaction Server for z/OS®, Version 3 Release 1 region and to pass and receive data by means of a communications area. The CICS application program is invoked as if linked-to by another CICS application program.

This programming interface allows a user to allocate and open sessions (or pipes1) to a CICS region, and to pass distributed program link (DPL) requests over them. The multiregion operation (MRO) facility of CICS interregion communication (IRC) facility supports these requests, and each pipe maps onto one MRO session.

Unless the CICS region is running in a sysplex under MVS/ESA 5.1 and therefore able to use cross-system MRO (XCF/MRO), the client program and the CICS server region (the region where the server program runs or is defined) must be in the same MVS image. Although the external CICS interface does not support the cross-memory access method, it can use the XCF access method provided by XCF/MRO in CICS Transaction Server for z/OS, Version 3 Release 1. See the CICS Intercommunication Guide for information about XCF/MRO.

A client program that uses the external CICS interface can operate multiple sessions for different users (either under the same or separate TCBs) all coexisting in the same MVS address space without knowledge of, or interference from, each other.

Where a client program attaches another client program, the attached program runs under its own TCB.

The 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:

  1. Initialize_User
  2. Allocate_Pipe
  3. Open_Pipe
  4. DPL call
  5. Close_Pipe
  6. Deallocate_Pipe

The processing of an EXCI CALL-level command is shown in Figure 47.

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. The processing of an EXEC CICS LINK command is shown in Figure 48.

This command takes the same form as 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.

For details about the DPL subset for server programs, see the CICS Application Programming Guide.

Figure 47. External CICS interface, CALL-level API
 This is a technical drawing showing the processing of an EXCI CALL-level command
Notes:
  1. An EXCI CALL API request is issued, and invokes the DFHXCIS entry point in the EXCI stub, DFHXCSTB.
  2. DFHXCSTB locates DFHXCPRH, and invokes it to process the EXCI request. If DFHXCPRH is not found, DFHXCSTB loads DFHXCPRH before invoking it.
  3. DFHXCPRH sets up the control blocks needed for the EXCI request. For a DPL request, DFHXCPRH invokes DFHIRP to pass control to CICS.
Figure 48. External CICS interface, EXEC-level API
 This is a technical drawing showing the processing of an EXEC CICS LINK command
Notes:
  1. An EXCI EXEC API request is issued, and invokes the DFHXCEI entry point in the EXCI stub, DFHXCSTB.
  2. DFHXCSTB locates DFHXCEIP, and invokes it to process the EXCI request. If DFHXCEIP is not found, DFHXCSTB loads DFHXCEIP before invoking it.
  3. DFHXCEIP converts the EXCI EXEC-level request into a series of EXCI CALL-level requests.
  4. The CALL-level requests result in calls to the EXCI stub, DFHXCSTB (as in Figure 47).

1.
pipe. A one-way communication path between a sending process and a receiving process. In an external CICS interface implementation, each pipe maps onto one MRO session, where the client program represents the sending process and the CICS server region represents the receiving process.

[[ Contents Previous Page | Next Page Index ]]