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:
- Analyze the request to determine its type, the keywords specified, and
their values.
- Modify any value specified by the request before the command is executed.
- Set return codes to specify that either:
- CICS® should continue with the (possibly modified) request.
- CICS should bypass the request. (Note that if you set this return code,
you must also set up return codes for the EXEC interface block (EIB), as if
you had processed the request yourself.)
Using XTDEREQC, you can:
- Analyze the request, to determine its type, the keywords specified, and
their values.
- Set return codes for the EIB.
Both exits are passed eight parameters as follows:
- The address of the command-level parameter structure
- The address of a token (UEPTDTOK) used to pass 4 bytes of data from XTDEREQ
to XTDEREQC
- The addresses of copies of four pieces of return code and resource information
from the EIB
- The address of a token (UEPTSTOK) that is valid throughout the life of
a task
- The address of an exit recursion count (UEPRECUR).
- 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:
- EXEC CICS SHUTDOWN
- EXEC CICS XCTL
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.
- 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.
UEP_TD_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 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.
UEP_TD_REMOTE_NAME
If 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.
- 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:
- EXEC CICS SHUTDOWN
- EXEC CICS XCTL
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 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
- TD_FUNCT
- TD_BITS1
- TD_BITS2
- TD_EIDOPT5
- TD_EIDOPT6
- TD_EIDOPT7
- 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:
- A 4-byte address from SET (if the request is READQ and TD_EIDOPT5 indicates that this is SET).
- Data from INTO (if the request is READQ and TD_EIDOPT5 indicates that this is not SET). You
cannot modify this bit in your user exit.
- Data from FROM (if the request is WRITEQ).
- TD_ADDR3
- is the address of one of the following:
- 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.
- 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:
- Modify or set completion and resource information in XTDEREQ and XTDEREQC
- Examine completion and resource information in XTDEREQC.
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.
[[ Contents Previous Page | Next Page Index ]]