Filter
Top Products
The XPI copy books
There is a copy book for each XPI function, to provide 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 copy book name is
the same as the macro name, except that the final letter “X” becomes a letter “Y”.
For example, to include the copy book for the XPI function DFHSMMCX, you must
include the statement:
COPY DFHSMMCY
Trace entries for your XPI calls show these parameter lists if you have tracing on
for the function you are using.
Reentrancy considerations resulting from XPI calls
During an XPI call, CICS may give control to another task while processing the XPI
call. This second task could also cause the same exit program to be invoked and
the same XPI call to be made, but perhaps this time with different parameter
values. It is your responsibility to ensure that lockout situations do not occur.
While processing an XPI call, CICS may encounter another user exit point that uses
the same user exit program. Therefore the XPI parameter lists must be built in
storage associated with a single invocation of the exit program.
If your exit program is a global user exit, CICS provides it with 320 bytes of LIFO
storage, which is exclusive to a single invocation of your exit program. Your exit
program can access this storage using parameter UEPXSTOR of the DFHUEPAR
parameter list. Use this storage to base the DSECT provided by the DFHxxyyY
copy book when building the XPI parameter list. In this way, the parameters are not
corrupted if the exit program is reentered.
Parameter lists for the XPI services provided here do not exceed 256 bytes. The
remaining 64 bytes of the UEPXSTOR storage can be used by your exit program
for its own purpose. It is expected that the 64 bytes of spare storage will, in most
cases, avoid the need for your exit programs to obtain more storage. If you do need
to obtain more than the extra 64 bytes provided, obtain it by either a DFHSMMCX
FUNCTION (GETMAIN) macro, or an MVS GETMAIN request.
Information to be kept across invocations of an exit program can be stored in the
global work area that you can define for an exit program (or group of exit
programs). The 320 bytes of LIFO storage cannot be used for this purpose because
it is dynamic.
Global user exit XPI examples, showing the use of storage
The example in Figure 12 on page 315 illustrates the use of the XPI and storage in
a global user exit program. It is not a complete program, but merely an example of
entry and exit code for any global user exit program, and the use of the XPI
function.
The options of the DFHSMMCX macro used in the example are described in
“Storage control XPI functions” on page 392.
The example uses the technique of obtaining some storage for this invocation of the
program using the XPI GETMAIN call, and then saving the address of this storage
Chapter 3. The user exit programming interface (XPI) 313