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:
- EXEC CICS WRITEQ TS
- EXEC CICS READQ TS
- EXEC CICS DELETEQ TS.
Using XTSEREQ, you can:
- Analyze the API parameter list (function, keywords, argument values, and
responses)
- Modify any input parameter value prior to execution of a request
- Prevent execution of a request.
Using XTSEREQC, you can:
- Analyze the API parameter list
- Modify any output parameter value after request completion.
You can also:
- Pass data between your XTSEREQ and XTSEREQC exit programs when they are
invoked for the same request
- Pass data between your temporary storage exit programs when they are invoked
within the same task.
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:
- XTSEREQ
- XTSQRIN
- XTSQROUT
- XTSEREQC
- 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:
- EXEC CICS SHUTDOWN
- EXEC CICS XCTL
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.
- 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.
UEP_TS_REMOTE_SYSTEM
If 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.
- 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:
- EXEC CICS SHUTDOWN
- EXEC CICS XCTL
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 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:
- TS_ADDR0
- is the address of a 9-byte area called the EID, which is made up as
follows:
- TS_GROUP
- TS_FUNCT
- TS_BITS1
- TS_BITS2
- TS_EIDOPT5
- TS_EIDOPT6
- TS_EIDOPT7
- TS_EIDOPT8
- 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:
- A 4-byte address from SET (if the request is READQ and TS_EIDOPT5 indicates that this is SET).
- Data from INTO (if the request is READQ and TS_EIDOPT5 indicates that this is not SET).
- Data from FROM (if the request is WRITEQ).
- 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:
- The halfword value of NUMITEMS (if the request is WRITEQ)
- The halfword value of ITEM (if the request is READQ or WRITEQ).
- 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. |
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:
- CICS does not check changes to argument values, so any changes must be
verified by the user exit program making the changes.
- 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:
- Obtain storage for the argument to be added
- Initialize the storage to the required value
- Select and set up the appropriate pointer from the parameter list
- Select and set up the appropriate argument existence bit in the EID
- 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:
- Switch the corresponding argument existence bit to '0'b in the EID
- Modify the parameter list to reflect the new end of list indicator.
[[ Contents Previous Page | Next Page Index ]]