Making an XPI call

An XPI call has two sets of parameters: input parameters, including the XPI function call and the parameters passed to the call, and output parameters, by which CICS® can return values to you, including response and reason codes that tell you whether the call was successful.

Before you begin

If you are going to use any of the XPI functions in an exit program, you must include the following macro in your program, before you issue any XPI calls:

DFHUEXIT TYPE=XPIENV

About this task

To use an XPI macro call, you must include a copybook that defines the input and output parameters. The name of the macro is always of the form DFHxxyyX, and the associated copybook 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 copybook is DFHSMMCY.

Example:

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

COPY DFHSMMCY

The general format (omitting the assembler-language continuation character) of all XPI calls is as follows:

        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:

The macro-name must begin before column 16.
The continuation lines must begin in column 16.
There must be no embedded blanks apart from the blank between the macro-name and the first keyword (usually CALL).
Entries on lines other than the final line must end with a comma.
Lines other than the final line must have a continuation character in column 72.
Parentheses around the input and output values are required—and if you use a register reference as an input or output value, it must be enclosed in an inner pair of parentheses, thus: ((R6)).
For details about how to set the values of the XPI options, refer to XPI syntax.

There are three uses of these XPI functions. You can perform the following operations:

Clear the parameter list used by the XPI call.
Set up the input parameters.
Make the call to the CICS function.

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.

CALL

Causes code generation that issues a call to the XPI function. If you specify CALL, IN, FUNCTION, and OUT, then code is generated to perform the whole operation of building the parameter list, invoking the function, and receiving the result. You can omit the CALL, but specify IN to build your parameter list incrementally; later you can use CALL with that list, coding CALL, IN, FUNCTION, OUT, and all required options. You can then represent the values of the preset options by an asterisk (*) to show that the value is already present in the list.

Note: If you build your parameter list incrementally, do not specify CLEAR when you finally issue the call, because the CLEAR option sets the parameter list to zeros, which will cause you to lose the preset values.

CLEAR

Sets the existence bits in the parameter list (both mandatory and optional parameters) to binary zeros. Each macro has a COPY code, which defines the parameter list by a DSECT consisting of a header section, followed by a set of existence bits, and the parameters themselves. For performance reasons, the header section and the existence bits only are cleared. The rest of the parameter list remains unchanged.

Note: 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.

IN

Tells CICS that any parameter following the IN option and preceding the OUT option is an input value. It must be specified when CALL is specified. If you use the function without CALL to build a parameter list, you can specify IN and some parameter values to store values into your list.

FUNCTION

Specifies which function of the macro you require; for instance, GETMAIN or FREEMAIN. It must be specified when CALL is specified, and unlike other options, it must always be explicit—you cannot code “FUNCTION(*)”.

mandin(value)

mandin represents an option that becomes mandatory if CALL is specified. value may be represented by an asterisk (*) to show that a previous use of the macro has already set the value in the parameter list (see CALL). For further details about how to complete value, refer to the specific function calls in XPI syntax.

OUT

tells CICS that any parameter following the OUT option is a receiver field. It must be specified when CALL is specified.

Note: The use of the following output parameters with values other than an asterisk (*) is invalid if CALL is not specified.

mandout(value)

mandout represents an option that becomes mandatory if CALL is specified. The output is placed in the parameter list if an asterisk (*) is coded, or in the location that you have specified in value. RESPONSE is a special case of a mandout option (see RESPONSE). For further details about how to complete “value”, refer to the specific function calls (see XPI syntax).

optin1,2…; optout1,2….

Represent items that are completely optional for all forms of the macro; in particular, they do not have to be specified when CALL is specified.

RESPONSE

is a mandatory data area that you define to receive the response from your XPI call. You can use an asterisk (*) to indicate to CICS that the RESPONSE value is to be placed in the parameter list, or you can specify the name of a field in which you want the RESPONSE value to be placed. You need not code the RESPONSE option if you are using the macro without CALL to build a parameter list.

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 copybook 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:

OK

The XPI request was completed successfully.

EXCEPTION

The function was not completed successfully for a reason which could be expected to happen, and which may be coded for by a program (for example, TRANSACTION_DUMP, EXCEPTION = SUPPRESSED_BY_DUMPTABLE). Any REASON value may provide more information.

DISASTER

The request has failed completely. You cannot recover from this failure within the user exit program. When this failure occurs, CICS takes a system dump, issues an error message, and sets a DISASTER response. On receiving this, your user exit program should exit without attempting any further processing. The REASON value for this response, shown only in the trace, may provide more information. There is no REASON value returned to the calling program.

INVALID

You have omitted a mandatory value, or you have supplied an invalid value for an option. You cannot recover from this failure within the user exit program. When this failure occurs, CICS takes a system dump, issues an error message, and sets an INVALID response. On receiving this response, your user exit program should return to the caller without attempting any further processing. The REASON value for this response, shown only in the trace, may provide more information. This may help you to correct any error in your exit program. There is no REASON value returned to the calling program.

KERNERROR

The kernel has detected an error with the CICS function you are trying to invoke. Either the function you have requested is unavailable or not valid, or there is an error within CICS.

PURGED

The task has been purged, or an interval specified on your XPI call has expired. Examine the REASON code.

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 timeout 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

This is a mandatory data area that you define to receive more information about the RESPONSE value. You can use (*) to indicate to CICS that the REASON value is to be placed in the parameter list. On most XPI calls, standardized reason names (EQU symbols) are provided only for RESPONSE values of EXCEPTION and PURGED. The REASON values that accompany responses vary from one XPI function to another, so details are provided with the descriptions of the XPI calls.

REASON is not applicable where RESPONSE was OK. In these circumstances, you should not test the REASON field.

Note: For examples of how to initialize the parameter list, set up parameters, make the call, and receive output parameters, see Global user exit XPI examples. That section includes both a complete example, and also an example in which each step is executed separately.

XPI register usage considerations for global user exit programs

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 Global user exit sample program DFH$XTSE.