If you make an XPI call, it must be in the form described below. It consists of two sets of parameters:
To use an XPI macro call, you must include a copy book that defines the input and output parameters. The name of the macro is always of the form DFHxxyyX, and the associated copy book has the name DFHxxyyY. For example, the GETMAIN call is part of the storage control XPI. The macro you would use is DFHSMMCX and the associated copy book is DFHSMMCY.
The general format (omitting the assembler-language continuation character) of all XPI calls is:
macro-name [CALL],
[CLEAR],
[IN,
FUNCTION(call_name),
mandin1(value),
mandin2(value),
...
[optin1(value),]
[optin2(value),]
...]
[OUT,
mandout1(value),
mandout2(value),
...
[optout1(value),]
[optout2(value),]
...
RESPONSE,
REASON]
XPI calls follow assembler-language coding conventions:
There are three uses of these XPI functions. You can:
You can code all of these individually (see An example showing how to build a parameter list incrementally), or include them in a single statement.
Some options are common to all uses of the XPI. They are included in all of the syntax descriptions, but their explanation is given here. The options are CALL, CLEAR, IN, FUNCTION, OUT, RESPONSE, and REASON.
Failure to clear the parameter list can cause unpredictable results, such as program checks or storage violations. If you are building the parameter list incrementally, specify CLEAR before specifying any parameters. If you are not building the parameter incrementally, specify CLEAR when the CALL is issued.
The response from any XPI call is always one of ‘OK’, ‘EXCEPTION’, ‘DISASTER’, ‘INVALID’, ‘KERNERROR’, and ‘PURGED’. There are standardized names (EQU symbols) for the response code values provided by CICS:
xxyy_OK, xxyy_EXCEPTION, xxyy_DISASTER, xxyy_INVALID,
xxyy_KERNERROR, and xxyy_PURGED,
where "xxyy" is a prefix derived from the four letters of the relevant macro-name following the string ‘DFH’. Thus for DFHSMMCX the prefix is SMMC; for DFHLDLDX the prefix is LDLD. Equate values with these names are generated when you include the copy book DFHxxyyY for the macro DFHxxyyX. You cannot assume that the arithmetic values of corresponding RESPONSE codes are the same for all macro calls. The meanings of the RESPONSE codes are as follows:
Note that if an XPI call other than DFHDSSRX SUSPEND or WAIT_MVS gets this RESPONSE, your exit program should set the return code to ‘UERCPURG’ and return to the caller.
If a DFHDSSRX SUSPEND or WAIT_MVS call specifies an INTERVAL and gets this RESPONSE with a REASON of ‘TIMED_OUT’, it indicates that the INTERVAL you specified has passed. It is up to you to decide what you do next.
If a DFHDSSRX SUSPEND or WAIT_MVS call specifies an INTERVAL and gets this RESPONSE with a REASON of ‘TASK_CANCELLED’, this indicates that the INTERVAL you specified has not passed but that the task has been purged by an operator or an application. In this case, you must set a return code of ‘UERCPURG’ and return.
If a DFHDSSRX SUSPEND or WAIT_MVS call does not specify an INTERVAL, and gets this RESPONSE with a REASON of ‘TASK_CANCELLED’ or ‘TIMED_OUT’, it indicates that the task has been purged by an operator or an application, or by the deadlock time-out facility. In this case, you must set a return code of ‘UERCPURG’ and return.
You must not return the response code ‘UERCPURG’ to CICS for any other reason. If you attempt to do so, your program will have unpredictable results.
REASON is not applicable where RESPONSE was ‘OK’. In these circumstances, you should not test the REASON field.
The exit programming interface (XPI) does not require the usual CICS transaction environment, but you do need to set up a special exit programming environment before you can use any XPI calls. If you are going to use any of the XPI functions in an exit program, you must include in your program, at a point before you issue any XPI calls, the macro:
DFHUEXIT TYPE=XPIENV
The expansion of this macro provides the DSECTs that are used in all XPI calls. It also provides a list of register equates (R0 EQU 0, R1 EQU 1, and so on), that you can use in your exit program. The other fields generated by the macro are used by CICS to perform the XPI call processing. You must not use any of these fields: if you do so, your user exit program will have unpredictable results.
The user exit program should be in 31-bit addressing mode.
Before you can issue an XPI call from a global user exit program, you must move the contents of the parameter UEPSTACK (the kernel stack entry) of DFHUEPAR to the exit program’s register 13.
The XPI function expansion uses registers 0, 1, 14, and 15, so the exit program must save and restore them if necessary around an XPI call.
For an example of how to use EXEC CICS commands and XPI calls in the same exit program, see Appendix F. The example program for the XTSEREQ global user exit, DFH$XTSE.
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.
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 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.