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.

Using the XPI directory functions, you can:
- Establish a session with an LDAP server. See The BIND_LDAP call.
- Terminate a session with an LDAP server. See The UNBIND_LDAP call.
- Remove the contents of all cached search responses for the specified LDAP connection. See The FLUSH_LDAP_CACHE call.
- Send a search request to a specified LDAP server. See The SEARCH_LDAP call.
- Browse the results (attributes or entries) returned by the SEARCH_LDAP call. See The START_BROWSE_RESULTS call.
- Get the next attribute in a series, from an entry returned by the SEARCH_LDAP call. See The GET_NEXT_ATTRIBUTE call.
- Get the next entry, from a series of entries returned by the SEARCH_LDAP call. See The GET_NEXT_ENTRY call.
- Retrieve the value associated with an attribute returned by the SEARCH_LDAP call. See The GET_ATTRIBUTE_VALUE call.
- End the browse session that was started by the START_BROWSE_RESULTS call. See The END_BROWSE_RESULTS call.
- Release all storage held by the SEARCH_LDAP function. See The FREE_SEARCH_RESULTS call.
Using the XPI dispatcher functions, you can:
- Obtain a suspend token for a task. See The ADD_SUSPEND call.
- Suspend execution of the issuing task. See The SUSPEND call.
- Resume execution of a suspended task. See The RESUME call.
- Release a suspend token associated with a task. See The DELETE_SUSPEND call.
- Request a wait on one or more MVS™ event control blocks (ECBs). See The WAIT_MVS call.
- Change the priority of the issuing task. See The CHANGE_PRIORITY call.
Using the XPI dump control functions, you can:
- Request a system dump. See The SYSTEM_DUMP call.
- Request a transaction dump. See The TRANSACTION_DUMP call.
Using the XPI enqueue domain functions, you can:
- Enqueue on a named resource. See The ENQUEUE function.
- Release a resource previously enqueued by an ENQUEUE function call. See The DEQUEUE function.
Using the XPI kernel domain functions, you can:
- Inhibit purge for the current task. See The START_PURGE_PROTECTION function.
- Re-enable purge for the current task. See The STOP_PURGE_PROTECTION function.
Using the XPI loader functions, you can:
- Define a new program to the loader domain. See The DEFINE_PROGRAM call.
- Load a program or, if it is already loaded, obtain its load and entry-point addresses. See The ACQUIRE_PROGRAM call.
- Locate a program and obtain information about it. See The IDENTIFY_PROGRAM call.
- Release the storage occupied by a program, or decrement its use count by one. See The RELEASE_PROGRAM call.
- Delete a program definition from the list of current programs. See The DELETE_PROGRAM call.
Using the XPI log manager functions, you can:
- Retrieve information about the activity keypoint frequency of the system. See The INQUIRE_PARAMETERS call.
- Set the activity keypoint frequency of the system. See The SET_PARAMETERS call.
Using the XPI monitoring functions, you can:
- Process a user event-monitoring point. See The MONITOR call.
- Retrieve the application context data for the issuing task. See The INQUIRE_APP_CONTEXT call.
- Retrieve the current monitoring data for the issuing task. See The INQUIRE_MONITORING_DATA call.
Using the XPI object transaction domain functions, you can:
- Link the current unit of work of a task to an external transaction - see The IMPORT_TRAN call.
- Perform a sync point on the unit of work of the current task, without referencing an external coordinator - see The COMMIT_ONE_PHASE call.
- Perform the first phase of the sync point on the CICS unit of work on behalf of an OTS transaction - see The PREPARE call.
- Perform the second phase of the sync point of an OTS transaction, ensuring that the transaction is committed - see The COMMIT call
- Roll back an OTS transaction - see The ROLLBACK call.
- Mark the CICS unit of work so that the global transaction is rolled back at the next sync point - see The SET_ROLLBACK_ONLY call.
- Associate a link with the current task's unit of work to represent a remote coordinator - see The SET_COORDINATOR call.
Using the XPI program management functions, you can:
- Inquire about the attributes of a specified program. See The INQUIRE_PROGRAM call.
- Inquire about the attributes of the program that is currently running. See The INQUIRE_CURRENT_PROGRAM call.
- Set selected attributes in the definition of a specified program. See The SET_PROGRAM call.
- Browse through program definitions, optionally starting at the definition of a specified program. See The START_BROWSE_PROGRAM call, The GET_NEXT_PROGRAM call, and The END_BROWSE_PROGRAM call.
- Inquire about the settings of the autoinstall function for programs, mapsets, and partitionsets. See The INQUIRE_AUTOINSTALL call.
- Change the settings of the autoinstall function for programs, mapsets, and partitionsets. See The SET_AUTOINSTALL call.
Using the XPI state data access functions, you can:
- Inquire on application system data in the AP domain. See The INQ_APPLICATION_DATA call.
- Inquire on CICS system data in the AP domain. See The INQUIRE_SYSTEM call.
- Set CICS system data values in the AP domain. See The SET_SYSTEM call.
Using the XPI storage control functions, you can:
- Obtain and initialize storage. See The GETMAIN call.
- Release storage. See The FREEMAIN call.
- Inquire about the access-key of an element of storage. See The INQUIRE_ACCESS call.
- Obtain the start address and length of an element of task-lifetime storage. See The INQUIRE_ELEMENT_LENGTH call.
- Discover whether CICS is short on storage. See The INQUIRE_SHORT_ON_STORAGE call.
- Inquire about a tasks task-lifetime storage. See The INQUIRE_TASK_STORAGE call.
- Cause CICS to switch from a subspace to base space. See The SWITCH_SUBSPACE call.
Using the XPI trace control function, you can:
- Write a trace entry to the active trace destinations. See The TRACE_PUT call.
Using the XPI transaction management functions, you can:
- Inquire about the environment in which a transaction is running. See The INQUIRE_CONTEXT call.
- Discover the name of the dynamic transaction routing transaction definition. See The INQUIRE_DTRTRAN call.
- Discover the current value of the MXT system initialization parameter. See The INQUIRE_MXT call.
- Inquire about a specified transaction class. See The INQUIRE_TCLASS call.
- Inquire about a specified transaction definition. See The INQUIRE_TRANDEF call.
- Inquire about an attached transaction. See The INQUIRE_TRANSACTION call.
- Change the task priority and transaction class of the current task. See The SET_TRANSACTION call.
Using the XPI user journaling function, you can:
- Write a record to a CICS journal. See The WRITE_JOURNAL_DATA call.

Important

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.
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, refer to Writing initialization and shutdown programs.
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.
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.