Temporary storage EXEC interface program exits XTSEREQ and XTSEREQC

The XTSEREQ exit allows you to intercept temporary storage API requests before any action has been taken on the request. The XTSEREQC exit allows you to intercept the response after a temporary storage API request has completed.

The API requests affected are:

Using XTSEREQ, you can:

Using XTSEREQC, you can:

You can also:

It is possible that programs invoked from the exits in the temporary storage domain (XTSQRIN, XTSQROUT, XTSPTIN, and XTSPTOUT) could modify situations set up by XTSEREQ; therefore you must consider the order in which the exits are invoked.

If all the temporary storage exits are enabled, the order of invocation is as follows:

  1. XTSEREQ
  2. XTSQRIN
  3. XTSQROUT
  4. XTSEREQC

Exit XTSEREQ

When invoked
Before CICS® processes a temporary storage API request.
Exit-specific parameters
UEPCLPS
Address of a copy of the command parameter list. See The command-level parameter structure.
UEPTQTOK
Address of a 4-byte area which can be used to pass information between XTSEREQ and XTSEREQC for a single temporary storage request.
UEPRCODE
Address of a 6-byte hexadecimal copy of the EIB return code EIBRCODE. For details of EIB return codes, see the CICS Application Programming Reference.
UEPRESP
Address of a 4-byte binary copy of the EIB response code EIBRESP.
UEPRESP2
Address of a 4-byte binary copy of the EIB response code EIBRESP2.
UEPTSTOK
Address of a 4-byte token which can be used to pass information between successive temporary storage requests within the same task (for example, between successive invocations of the XTSEREQ exit).
UEPRECUR
Address of a halfword recursion counter. The counter is set to 0 when the exit is first invoked, and is incremented for each recursive call.
UEPRSRCE
Address of an 8-character copy of the EIB resource value, EIBRSRCE.
Return codes
UERCBYP
Bypass this request.
UERCNORM
Continue processing.
UERCPURG
Task purged during XPI call.
XPI calls
All can be used.
API and SPI commands
All can be used, except for:
Note:
Take care when issuing recursive commands. For example, you must avoid entering a loop when issuing a temporary storage request from the XTSEREQ exit. Use of the recursion counter UEPRECUR is recommended.

Exit XTSEREQC

When invoked
After a temporary storage API request has completed, before return from the temporary storage EXEC interface program.
Exit-specific parameters
UEPCLPS
Address of a copy of the command parameter list. See The command-level parameter structure.
UEPTQTOK
Address of a 4-byte area which can be used to pass information between XTSEREQ and XTSEREQC for a single temporary storage request.
UEPRCODE
Address of a 6-byte hexadecimal copy of the EIB return code EIBRCODE. For details of EIB return codes, see the CICS Application Programming Reference.
UEPRESP
Address of a 4-byte binary copy of the EIB response code EIBRESP.
UEPRESP2
Address of a 4-byte binary copy of the EIB response code EIBRESP2.
UEPTSTOK
Address of a 4-byte token which can be used to pass information between successive temporary storage requests within the same task (for example, between successive invocations of the XTSEREQC exit).
UEPRECUR
Address of a halfword recursion counter. The counter is set to 0 when the exit is first invoked, and is incremented for each recursive call.
UEPRSRCE
Address of an 8-character copy of the EIB resource value, EIBRSRCE.
Start of changeUEP_TS_REMOTE_SYSTEMEnd of change
Start of changeIf the request is to be sent to a remote region, is the address of an area containing the 4-byte name of the remote region. (The remote region may have been specified by, for example, the SYSID option of the command, function shipping, or work-load management.)

If the request is to be executed on the local region, this parameter is the address of a 4-byte area containing blanks.

End of change
Return codes
UERCNORM
Continue processing.
UERCPURG
Task purged during XPI call.
XPI calls
All can be used.
API and SPI commands
All can be used, except for:

You can update the copies of EIBRSRCE, EIBRCODE, EIBRESP, and EIBRESP2 that you are given in the parameter list. If you update the values, temporary storage copies the new values into the application program’s EIB after the completion of XTSEREQC or if you specify a return code of UERCBYP in XTSEREQ.

You must set valid temporary storage responses. You must set all three of EIBRCODE, EIBRESP, and EIBRESP2 to a consistent set of values, such as would be set by temporary storage to describe a valid completion. CICS does not check the consistency of EIBRCODE, EIBRESP, and EIBRESP2. If EIBRCODE is set to a non-zero value and EIBRESP is set to zero, CICS will override EIBRESP with a non-zero value. To help you set values for EIBRCODE, EIBRESP, and EIBRESP2, the values used by temporary storage are specified in DSECT DFHTSUED.

Note:
Take care when issuing recursive commands not to cause a loop. For example, it is your responsibility to avoid entering a loop when issuing a temporary storage request from the XTSEREQC exit. Use of the recursion counter UEPRECUR is recommended.

The command-level parameter structure

The command-level parameter structure consists of a series of addresses. The first address points to the EXEC interface descriptor (EID), which consists of a bit string that describes the type of request and identifies each keyword specified with the request. The remaining addresses point to pieces of data associated with the request.

You can examine the EID to determine the type of request and the keywords specified. You can examine the other parameters in the list to determine the values of the keywords. You can also modify values of keywords specified on the request.

End of parameter list indicator

The high-order bit is set on in the last address set in the parameter list to indicate that it is the last one in the list. On return from your user exit program, CICS scans the parameter list for the high-order bit to find the last parameter. Therefore, if you modify the length of the parameter list, you must also reset the high-order bit to indicate which is the new last address.

The UEPCLPS exit-specific parameter

The UEPCLPS exit-specific parameter is included in both exit XTSEREQ and exit XTSEREQC. It is the address of the command-level parameter structure. The command-level parameter structure contains 8 addresses, TS_ADDR0 through TS_ADDR7. It is defined in the DSECT TS_ADDR_LIST, which you should copy into your exit program by including the statement COPY DFHTSUED.

The command-level parameter list is made up as follows.

Note:
The relationship between arguments, keywords, data types, and input/output types is summarized for the temporary storage commands in the following tables:
Table 9. The relationship between arguments, keywords, data types, and input/output types for the temporary storage commands
Command See
WRITEQ TS Table 10
READQ TS Table 11
DELETEQ TS Table 12
TS_ADDR0
is the address of a 9-byte area called the EID, which is made up as follows:
TS_GROUP
Always X'0A', indicating that this is a temporary storage request.
TS_FUNCT
One byte that defines the type of request:
X'02'
WRITEQ
X'04'
READQ
X'06'
DELETEQ
TS_BITS1
Existence bits that define which arguments were specified. To obtain the argument associated with a keyword, you need to use the appropriate address from the command-level parameter structure. Before using this address, you must check the associated existence bit. If the existence bit is set off, the argument was not specified in the request and the address should not be used.
X'80'
Set if the request contains an argument for the QUEUE or QNAME keyword. If set, TS_ADDR1 is meaningful.
X'40'
Set if the request contains an argument for any of the FROM, INTO, or SET keywords. If set, TS_ADDR2 is meaningful.
X'20'
Set if the request contains an argument for the LENGTH keyword. If set, TS_ADDR3 is meaningful.
X'10'
Set if the request contains an argument for the NUMITEMS keyword. If set, TS_ADDR4 is meaningful.
X'08'
Set if the request contains an argument for the NUMITEMS or ITEM keyword. If set, TS_ADDR5 is meaningful.
X'02'
Set if the request contains an argument for the SYSID keyword. If set, TS_ADDR7 is meaningful.
TS_BITS2
Two bytes not used by temporary storage.
TS_EIDOPT5
Indicates whether certain keywords were specified on the request.
X'80'
QNAME was specified (otherwise QUEUE). You can modify this bit in your user exit if you wish.
TS_EIDOPT6
One byte not used by temporary storage.
TS_EIDOPT7
Indicates whether certain functions and/or keywords were specified on the request.
X'10'
WRITEQ NOSUSPEND specified.
X'80'
WRITEQ MAIN or READQ ITEM specified.
X'04'
WRITEQ REWRITE or READQ NUMITEMS specified.
TS_EIDOPT8
Indicates whether certain keywords were specified on the request.
X'80'
ITEM was specified (otherwise NUMITEMS).
TS_ADDR1
is the address of area containing 8-byte name from QUEUE. or 16-byte name from QNAME. To determine which of these is applied, see TS_BITS2.
TS_ADDR2
is the address of one of the following:
TS_ADDR3
is the address of the halfword value of LENGTH (if the request is READQ or WRITEQ).
Warning:
For requests that specify INTO, do not change the value of LENGTH to a value greater than that specified by the application. To do so causes a storage overlay in the application.
TS_ADDR4
is the address of the halfword value of NUMITEMS (if the request is READQ).
TS_ADDR5
is the address of one of the following:
TS_ADDR6
is the address of a value intended for CICS internal use only. It must not be used.
TS_ADDR7
is the address of an area containing the value of SYSID.

Modifying fields in the command-level parameter structure

Some fields that are passed to temporary storage are used as input to the request, some are used as output fields, and some are used for both input and output. The method your user exit program uses to modify a field depends on the usage of the field.

The following are always input fields:

The following are always output fields:

LENGTH is an input field on a WRITEQ request, and an output field on a READQ request that specifies SET. It is both an input and an output field on a READQ request that specifies INTO.

ITEM is an input field on a READQ request, and on a WRITEQ request that specifies REWRITE. It is both an input and an output field on a WRITEQ request that does not specify REWRITE.

Modifying input fields

The correct method of modifying an input field is to create a new copy of it, and to change the address in the command-level parameter list to point to your new data.

Note:
You must never modify an input field by altering the data that is pointed to by the command-level parameter list. To do so would corrupt storage belonging to the application program and would cause a failure when the program attempted to reuse the field.

Modifying output fields

The technique described in Modifying input fields is not suitable for modifying output fields. (The results would be returned to the new area instead of the application’s area, and would be invisible to the application.)

An output field is modified by altering the data that is pointed to by the command-level parameter list. In the case of an output field, you can modify the application’s data in place, because the application is expecting the field to be modified anyway.

Modifying fields used for both input and output

An example of a field that is used for both input and output is LENGTH on a READQ request that specifies INTO. You can treat such fields in the same way as output fields, and they are considered to be the same.

Modifying the EID

It is not possible to modify the EID to make major changes to requests. It is not possible, for example, to change a READQ request to a WRITEQ request.

However, you can make minor changes to requests, such as to turn on the existence bit for SYSID so that the request can be changed into one that is shipped to a remote system.

The list that follows shows the bits in the EID that can be modified. Any attempt to modify any other part of the EID is ignored.

TS_BITS1
X'02'
The existence bit for SYSID.
TS_EIDOPT7
A user exit program at XTSEREQ can set the following on or off for all WRITEQ TS commands:
X'10'
The existence bit for NOSUSPEND.
X'08'
The existence bit for MAIN.

The EID is reset to its original value before return to the application program. That is, changes made to the EID are retained for the duration of the temporary storage request only.

Note:
Your user exit program is prevented from making major changes to the EID. However, you must take great care when making the minor modifications that are permitted.

Use of the task token UEPTSTOK

UEPTSTOK provides the address of a 4-byte area that you can use to pass information between successive temporary storage requests in the same task. (By contrast, UEPTQTOK is usable only for the duration of a single temporary storage request, because its contents may be destroyed at the end of the request.) For example, if you need to pass information between successive invocations of the XTSEREQ exit, UEPTSTOK provides a means of doing this.

Table 10. WRITEQ TS: User arguments and associated keywords, data types, and input/output types
Argument Keyword Data type Input/output type
Arg1 QUEUE CHAR(8) input
Arg1 QNAME CHAR(16) input
Arg2 FROM DATA-AREA input
Arg3 LENGTH BIN(15) input
Arg4 * * *
Arg5 ITEM BIN(15) input/output
Arg5 NUMITEMS BIN(15) output
Arg6 * * *
Arg7 SYSID CHAR(4) input
Note:
The different uses of Arg5 are shown, because Arg5 is used by the ITEM and NUMITEMS keywords which are alternatives and the argument to the ITEM keyword is an input field when REWRITE is specified.
Table 11. READQ TS: User arguments and associated keywords, data types, and input/output types
Argument Keyword Data type Input/output type
Arg1 QUEUE CHAR(8) input
Arg1 QNAME CHAR(16) input
Arg2 SET DATA-AREA, PTR output
Arg2 INTO DATA-AREA output
Arg3 LENGTH BIN(15) input/output
Arg4 NUMITEMS BIN(15) output
Arg5 ITEM BIN(15) input
Arg6 * *
Arg7 SYSID CHAR(4) input
Table 12. DELETEQ TS: User arguments and associated keywords, data types, and input/output types
Argument Keyword Data type Input/output type
Arg1 QUEUE CHAR(8) input
Arg1 QNAME CHAR(16) input
Arg2 * * *
Arg3 * * *
Arg4 * * *
Arg5 * * *
Arg6 * * *
Arg7 SYSID CHAR(4) input

Modifying user arguments

User exit programs can modify user arguments, as follows:

For input arguments, the user exit program should obtain sufficient storage to hold the modified argument, set up that storage to the required value, and set the associated pointer in the parameter list to the address of the newly acquired area.

For output arguments, and for input/output arguments, the user exit program can update the argument in place, because the area of storage is represented by a variable in the application which is expected to receive a value from CICS.

Notes:
  1. CICS does not check changes to argument values, so any changes must be verified by the user exit program making the changes.
  2. It is not advisable for XTSEREQ to modify output arguments or for XTSEREQC to modify input arguments.

Adding user arguments

Global user exit programs can add arguments associated with the SYSID keyword. You must ensure that the arguments you specify or modify in your exit programs are valid.

Assuming that the argument to be added does not already exist, the user exit program must:

  1. Obtain storage for the argument to be added
  2. Initialize the storage to the required value
  3. Select and set up the appropriate pointer from the parameter list
  4. Select and set up the appropriate argument existence bit in the EID
  5. Modify the parameter list to reflect the new end of list indicator.

Removing user arguments

User exit programs can remove arguments (for which the program is totally responsible) associated with the SYSID keyword:

Assuming that the argument to be removed exists, the user exit program must:

  1. Switch the corresponding argument existence bit to '0'b in the EID
  2. Modify the parameter list to reflect the new end of list indicator.

Example program

CICS supplies--as a softcopy listing only (not as a source code file)--an example program, DFH$XTSE, that shows how temporary storage requests can be modified. See Appendix F. The example program for the XTSEREQ global user exit, DFH$XTSE.

Related concepts
Appendix F. The example program for the XTSEREQ global user exit, DFH$XTSE
Overview -- what is a global user exit?
Overview of the XPI
Global user exit XPI examples, showing the use of storage
Related tasks
Writing global user exit programs
Making an XPI call
Related reference
List of global user exit points
The XPI functions
[[ Contents Previous Page | Next Page Index ]]