Introduction to the external CICS interface

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 region and to pass and receive data by using a communications area.

The CICS application program is started as if linked to by another CICS application program.

You can use the external CICS interface to allocate and open sessions, or pipes (a one-way communication path between a sending process and a receiving process) 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, where the client program represents the sending process and the CICS server region represents the receiving process. There is a default limit of 100 pipes per EXCI address space; the limit can be changed when MVS is IPLed.

This limit prevents EXCI clients monopolizing MRO resources, which could prevent CICS regions from using MRO. The limit is applied in both MRO and cross-system MRO (XCF/MRO) environments. An allocate_pipe request results in an MRO LOGON request being issued and there is a limit on the total number of MRO LOGON requests allowed from all address spaces. This is critical when using XCF/MRO, where the limit on the number of members in an XCF group also limits the total number of MRO LOGONs.

The external CICS interface identifies the CICS region to communicate with by the CICS region APPLID, as defined in the APPLID system initialization parameter. You can specify the APPLID either on an EXCI API call or by using the DFHXCURM user-replaceable program. You can also use DFHXCURM to change the value of XCFGROUP to be used on an allocate_pipe request. For more information about DFHXCURM, see The EXCI user-replaceable module.
Note: Do not confuse the term generic APPLID with generic resource name. Generic resource names apply only to z/OS® Communications Server generic resource groups, which are not supported by EXCI.
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 unless:
  • The CICS region is running in a sysplex that supports cross-system MRO.
  • All DPL requests issued by the client program specify the SYNCONRETURN option.
Alternatively, if there is no local CICS region in the MVS image, you must specify the SVC parameter that the external CICS interface is to use, by coding a CICSSVC parameter in the DFHXCOPT table. Although the external CICS interface does not support the cross-memory access method, it can use the XCF access method provided by the CICS XCF/MRO facility. See Using the EXCI options table, DFHXCOPT 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.