Transient data EXEC interface program exits XTDEREQ and XTDEREQC

The XTDEREQ exit allows you to intercept a transient data request before any action has been taken on it by transient data. The XTDEREQC exit allows you to intercept a transient data request after transient data has completed its processing.

Using XTDEREQ, you can:

Using XTDEREQC, you can:

Both exits are passed eight parameters as follows:

Example program

CICS supplies--as a softcopy listing only (not as a source code file)--an example program, DFH$XTSE, that shows how to modify fields in the command-level parameter structure passed to EXEC interface exits. DFH$XTSE is listed in topic Appendix F. The example program for the XTSEREQ global user exit, DFH$XTSE.

Exit XTDEREQ

When invoked
Before CICS processes a transient data API request.
Exit-specific parameters
UEPCLPS
Address of the command-level parameter structure. See The UEPCLPS exit-specific parameter.
UEPTDTOK
Address of the 4-byte token to be passed to XTDEREQC. This allows you, for example, to pass a work area to exit XTDEREQC.
UEPRCODE
Address of a 6-byte hexadecimal copy of the EIB return code ‘EIBRCODE’. For details of EIB return codes, refer to the CICS Application Programming Reference manual.
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 that is valid throughout the life of a task. See Use of the task token UEPTSTOK.
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
UERCNORM
Continue processing.
UERCBYP
The transient data EXEC interface program should ignore this request.
UERCPURG
Task purged during XPI call.
XPI calls
All can be used.

Although the exit permits the use of XPI GETMAIN and FREEMAIN calls, we recommend that you use the EXEC CICS GETMAIN and FREEMAIN commands instead.

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 transient data request from the XTDEREQ exit. Use of the recursion counter UEPRECUR is recommended.

Exit XTDEREQC

When invoked
After a transient data API request has completed, and before return from the transient data EXEC interface program.
Exit-specific parameters
UEPCLPS
Address of the command-level parameter structure. See The UEPCLPS exit-specific parameter.
UEPTDTOK
Address of the 4 byte token to be passed to XTDEREQC. This allows you, for example, to pass a work area to exit XTDEREQC.
UEPRCODE
Address of a 6-byte hexadecimal copy of the EIB return code ‘EIBRCODE’. For details of EIB return codes, refer to the CICS Application Programming Reference manual.
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 that is valid throughout the life of a task. See Use of the task token UEPTSTOK.
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_TD_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 the REMOTESYSTEM option of the TDQUEUE definition.)

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
Start of changeUEP_TD_REMOTE_NAMEEnd of change
Start of changeIf the request is to be sent to a remote region, is the address of an area containing the 4-character name by which the queue is known in the remote region.End of change
Return codes
UERCNORM
Continue processing.
UERCPURG
Task purged during XPI call.
XPI calls
All can be used.

Although the exit permits the use of XPI GETMAIN and FREEMAIN calls, we recommend that you use the EXEC CICS GETMAIN and FREEMAIN commands instead.

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 transient data request from the XTDEREQC exit. Use of the recursion counter UEPRECUR is recommended.

The command-level parameter structure

Figure 3. The command-level parameter structure for transient data
 The picture shows, using a series of interconnected boxes, the relationships between the fields in the command-level parameter structure. The command-level parameter structure, and the relationships between its fields, are fully described in the text following the picture.

The command-level parameter structure consists of a series of addresses. The first address points to the EXEC interface descriptor (EID), which consists of an 8-byte area 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. (For example, the second address points to the queue name.)

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. (For example, you could change the sysid specified in 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.

For example, if the parameter list specifies only the first two addresses (TD_ADDR0, the address of the EID, and TD_ADDR1, the address of the name of the queue named in a DELETEQ request), the high-order bit is set on in TD_ADDR1. If you extend the parameter list by setting the address of a SYSID in TD_ADDR7, you must reset the high-order bit in TD_ADDR1 and set it on in TD_ADDR7 instead.

The maximum size of parameter list is supplied to the exit, thus allowing your exit program to add any parameters not already specified without needing to first obtain more storage.

The original parameter list, as it was before XTDEREQ was invoked, is restored after the completion of XTDEREQC. It follows that the execution diagnostic facility (EDF) displays the original command before and after execution. EDF does not display any changes made by the exit.

The UEPCLPS exit-specific parameter

The UEPCLPS exit-specific parameter is included in both exit XTDEREQ and exit XTDEREQC. It is the address of the command-level parameter structure. The command-level parameter structure contains 8 addresses, TD_ADDR0 through TD_ADDR7. It is defined in the DSECT TD_ADDR_LIST, which you should copy into your exit program by including the statement COPY DFHTDUED.

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

TD_ADDR0
is the address of an 8-byte area called the EID, which is made up as follows:
TD_GROUP
Always X'08', indicating that this is a transient data request.
TD_FUNCT
One byte that defines the type of request:
X'02'
WRITEQ
X'04'
READQ
X'06'
DELETEQ.
TD_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 keyword. If set, TD_ADDR1 is meaningful.
X'40'
Set if the request contains an argument for any of the INTO, SET, or FROM keywords. If set, TD_ADDR2 is meaningful.
X'20'
Set if the request contains an argument for the LENGTH keyword. If set, TD_ADDR3 is meaningful.
X'02'
Set if the request contains an argument for the SYSID keyword. If set, TD_ADDR7 is meaningful.
TD_BITS2
Two bytes not used by transient data.
TD_EIDOPT5
Indicates whether certain keywords were specified on the request.
X'01'
SET (and not INTO) was specified.
TD_EIDOPT6
One byte not used by transient data.
TD_EIDOPT7
Indicates whether certain functions and/or keywords were specified on the request:
X'40'
WRITEQ specified
X'80'
READQ specified
X'C0'
READQ(nosuspend) specified
X'04'
DELETEQ specified.
TD_ADDR1
is the address of a 4-byte area containing the name from QUEUE.
TD_ADDR2
is the address of one of the following:
TD_ADDR3
is the address of one of the following:
TD_ADDR4
is the address of a value intended for CICS internal use only. It must not be used.
TD_ADDR5
is the address of a value intended for CICS internal use only. It must not be used.
TD_ADDR6
is the address of a value intended for CICS internal use only. It must not be used.
TD_ADDR7
is the address of an area containing the value of SYSID.
TD_ADDR8
is the address of a value intended for CICS internal use only. It must not be used.

Modifying fields in the command-level parameter structure

Some fields that are passed to transient data 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.

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.

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, such as changing a READQ request to a WRITEQ request.

However, you can make minor changes to requests, such as turning 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.

TD_BITS1
X'20'
The existence bit for LENGTH.
X'02'
The existence bit for SYSID.
TD_EIDOPT5
X'01'
Existence bit for SET keyword. You cannot modify this bit from your user exit.
TD_EIDOPT7

Changes to TD_EIDOPT7 are limited to READQ requests. X'80'-READQ is interchangeable with X'C0'-READQ(nosuspend). No other changes may be made to this byte.

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 transient data 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 transient data requests in the same task. (By contrast, UEPTDTOK is usable only for the duration of a single transient data 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 XTDEREQ exit, UEPTSTOK provides a means of doing this.

The EIB

Copies of EIBRSRCE, EIBRCODE, EIBRESP, and EIBRESP2 are passed to the exit, so that you can:

You can update the copies of EIBRSRCE, EIBRCODE, EIBRESP, and EIBRESP2 that you are given in the parameter list. Transient data copies your values into the real EIB after the completion of XTDEREQC; or if you specify a return code of ‘ bypass’ in XTDEREQ.

You must set valid transient data responses. You must set all three of EIBRCODE, EIBRESP, and EIBRESP2 to a consistent set of values, such as would be set by CICS transient data to describe a valid completion. CICS does not police the consistency of EIBRCODE, EIBRESP, and EIBRESP2. However, if EIBRCODE is set to a non-zero value and EIBRESP is set to zero then CICS will override EIBRESP with a non-zero value. To aid you in setting the values of EIBRCODE, EIBRESP, and EIBRESP2, the values used by transient data are specified in DFHTDUED.

Related concepts
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 ]]