Overview of the XPI

The user exit programming interface (XPI) provides global user exit programs with access to some CICS® services. It consists of a set of macro function calls that you can use in your user exit programs.

The XPI provides opportunities to extend CICS functions beyond the facilities provided in the standard CICS system, but it must be used with care. Any exit programs you write that use this interface must be written by using the following guidance and must be tested carefully to ensure that they cannot cause system errors.

The user exit programs must be in assembler language; the XPI is not provided for other languages. Programs that contain XPI calls must be written to 31-bit standards and must be reentrant.

You must be in primary-space translation mode when you start the XPI. For information about translation modes, see z/Architecture Principles of Operation.

XPI functions are listed and described in detail in XPI functions (by domain).

Important:
  1. You cannot use all of the XPI calls at every global user exit point. An indication of when these calls cannot be used is in the description of each function call, and in the lists of exit points in Global user exit programs.

    XPI calls are used to start CICS services; using them in the wrong exits causes unpredictable errors in your CICS system.

  2. There is a restriction on using the XPI early during initialization. Do not start exit programs that use the XPI functions INQUIRE_MONITOR_DATA, MONITOR, TRANSACTION_DUMP, and WRITE_JOURNAL_DATA until the second phase of the PLTPI. For further information about the PLTPI, see Customizing with initialization and shutdown programs.
  3. These XPI functions are likely to cause the task executing the user exit program to lose control to another task while the XPI function is being run. Therefore the use of XPI functions must be carefully considered, as interrupting the flow of CICS functions might cause problems, such as lockouts, to occur.
  4. A global user exit or task-related user exit might be assembled using CICS libraries from one CICS release and make an XPI call on a system that runs a different CICS release. In this situation, whether or not control is successfully transferred from the exit to the correct CICS module to handle that XPI call depends on the combination of CICS releases, and whether the XPI call is a release-sensitive call. For the user exit to succeed, you must also check other factors, for example whether XPI parameters have changed between releases. For details, see Upgrading.

The XPI copybooks

For each XPI function, a copybook provides the DSECTs associated with that function. These DSECTs allow you to map the parameters and the response and reason codes of an XPI call.

You must include in your exit program a COPY statement for each XPI function that you are going to use. The copybook name is the same as the macro name, except that the final letter X becomes a letter Y.

Trace entries for your XPI calls show these parameter lists if you have tracing on for the function you are using.

Example:
To include the copybook for the XPI function DFHSMMCX, you must include the following statement in your exit program: 
COPY DFHSMMCY