The XNQEREQ exit allows you to intercept enqueue API requests before any
action has been taken on the request. The XNQEREQC exit allows you to intercept
the response after an enqueue API request has completed.
The API requests affected are:
- EXEC CICS ENQ
- EXEC CICS DEQ.
Using XNQEREQ, 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. This enables you to replace the CICS® function with
your own processing.
Using XNQEREQC, you can analyze the API parameter
list.
You can also:
- Pass data between your XNQEREQ and XNQEREQC exit programs when they are
invoked for the same request
- Pass data between your enqueue exit programs when they are invoked within
the same task.
- When invoked
- Before CICS processes an EXEC CICS ENQ or DEQ request, or attempts to match
it to an installed ENQMODEL resource definition.
- Exit-specific parameters
-
- UEPCLPS
- Address of a copy of the command parameter list. See The command-level parameter structure.
- UEPNQTOK
- Address of a 4-byte area which can be used to pass information between
XNQEREQ and XNQEREQC for a single enqueue 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 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 which can be used to pass information between
successive enqueue requests within the same task (for example, between successive
invocations of the XNQEREQ 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.
- UEPSCOPE
- Address of the 4-byte ENQSCOPE name to be used.
- Return codes
-
- UERCBYP
- Bypass this request.
- UERCNORM
- Continue processing.
- UERCPURG
- Task purged during XPI call.
UERCSCPE
An ENQSCOPE name has been supplied.
- 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 an enqueue request from the XNQEREQ
exit. Use of the recursion counter UEPRECUR is recommended.
- When invoked
- After an enqueue API request has completed, before return from the enqueue
EXEC interface program.
- Exit-specific parameters
-
- UEPCLPS
- Address of a copy of the command parameter list. See The command-level parameter structure.
- UEPNQTOK
- Address of a 4-byte area which can be used to pass information between
XNQEREQ and XNQEREQC for a single enqueue 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 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 which can be used to pass information between
successive enqueue requests within the same task (for example, between successive
invocations of the XNQEREQC 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.
- UEPSCOPE
- Address of the 4-byte ENQSCOPE name used.
- 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 EIBRCODE, EIBRESP, and EIBRESP2 that you are
given in the parameter list. If you update the values, CICS copies the
new values into the application program’s EIB after the completion of
XNQEREQC or if you specify a return code of UERCBYP in XNQEREQ.
You must set valid enqueue responses. You must set all three of EIBRCODE,
EIBRESP, and EIBRESP2 to a consistent set of values, such as would be set
by the enqueue domain 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 the enqueue domain are specified in DSECT DFHNQUED.
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
an enqueue request from the XNQEREQC 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 XNQEREQ and
exit XNQEREQC. It is the address of the command-level parameter structure.
The command-level parameter structure contains four addresses, NQ_ADDR0 through
NQ_ADDR3. It is defined in the DSECT NQ_ADDR_LIST, which you should copy into
your exit program by including the statement COPY DFHNQUED.
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 enqueue commands in
Table 3.
- NQ_ADDR0
- is the address of a 9-byte area called the EID, which is made up as
follows:
- NQ_GROUP
- NQ_FUNCT
- NQ_BITS1
- NQ_BITS2
- NQ_EIDOPT5
- NQ_EIDOPT6
- NQ_EIDOPT7
- NQ_EIDOPT8
- NQ_GROUP
- Always X'12', indicating that this is a task control request.
- NQ_FUNCT
- One byte that defines the type of request:
- X'04'
- ENQ
- X'06'
- DEQ
- NQ_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 RESOURCE keyword. If
set, NQ_ADDR1 is meaningful.
- X'40'
- Set if the request contains an argument for the LENGTH keyword. If set, NQ_ADDR2 is meaningful.
- X'20'
- Set if the request contains an argument for the MAXLIFETIME keyword.
If set, NQ_ADDR3 is meaningful.
- NQ_BITS2
- Two bytes not used by the enqueue domain.
- NQ_EIDOPT5
- One byte not used by the enqueue domain.
- NQ_EIDOPT6
- One byte not used by the enqueue domain.
- NQ_EIDOPT7
- One byte not used by the enqueue domain.
- NQ_EIDOPT8
- Indicates whether certain keywords were specified on the request.
- X'04'
- NOSUSPEND was specified.
- X'02'
- DEQ was specified.
- X'01'
- ENQ was specified.
- NQ_ADDR1
- is the address of an area containing the value from RESOURCE.
- NQ_ADDR2
- is the address of the halfword value of LENGTH.
- NQ_ADDR3
- is the address of the fullword value of MAXLIFETIME.
Modifying fields in the command-level parameter structure
The fields that are passed to the enqueue domain are used as input to the
request. 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.
Notes:
- 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.
- There are no output fields on EXEC CICS ENQ and DEQ requests.
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 an ENQ request to a DEQ request.
However, you can make minor changes to requests, such as to turn on the existence
bit for LENGTH. 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.
- NQ_BITS1
-
- X'40'
- The existence bit for LENGTH
- X'20'
- The existence bit for MAXLIFETIME.
- NQ_EIDOPT7
- A user exit program at XNQEREQ can set the following on or off for ENQ
commands:
- X'04'
- The existence bit for NOSUSPEND.
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 enqueue 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 enqueue requests in the same task. (By contrast,
UEPNQTOK is usable only for the duration of a single enqueue 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 XNQEREQ
exit, UEPTSTOK provides a means of doing this.
Notes:
- The lifetime of the area pointed to by UEPTSTOK is the lifetime of the
task.
- The value of UEPTSTOK is shared by all the exits to which it is passed
during the lifetime of the task.
Modifying user arguments
User exit programs can modify user input arguments by:
- Obtaining sufficient storage to hold the modified argument
- Setting the storage to the required value
- Setting the associated pointer in the parameter list to the address of
the newly-acquired area.
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 XNQEREQC to modify input arguments.
Adding user arguments
Global user exit programs can add arguments associated with the LENGTH
and MAXLIFETIME keywords. You must ensure that the arguments you specify or
modify in your exit programs are valid. The valid values for MAXLIFETIME are
DFHVALUE(TASK) and DFHVALUE(UOW), which are 233 and 246 respectively.
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 LENGTH and MAXLIFETIME keywords:
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.
CICS supplies a sample exit program, DFH$XNQE, for the XNQEREQ
exit.
The program gives examples of:
- Coding Exec Interface Global User Exits
- Issuing a mixture of XPI and EXEC CICS API calls within Global User Exits
- Three methods of adding a SCOPE value to exec ENQ and DEQ requests, so
that they apply to multiple regions within the Sysplex. Methods A and B force
a match to an installed ENQMODEL resource definition. Method C bypasses the
use of ENQMODEL resource definitions even if there would have been a match.
The methods are:
- Method A
- Prefix the Resource name with a 1- to 255-character value (this sample
uses a 4-character value) for the ENQNAME on the ENQMODEL resource definition
to which you wish to force a match. The exit terminates and processing continues
as though the chosen ENQMODEL had been matched normally. The scope is then
supplied by the matched ENQMODEL definition.
This method applies only to
resource names shorter than 255-n (where n is the length of you chosen prefix).
- Method B
- Similar to method A, but you replace the first 1- to 8-characters of
the resource name with your chosen string instead of prefixing it. This method:
- applies only to resource names of length equal to or greater than that
of your replacement string.
- is an alternative to method A when a resource name too long to allow the
use of that method.
- Method C
- Place a 4-character Scope value in UEPSCOPE, and return UERCSCPE in
R15. This will bypass any installed ENQMODEL resource definition, forcing
a Sysplex Scope ENQ/DEQ request.
This method is not recommended if you
have an ENQMODEL table, because the latter is designed to preserve data integrity by preventing
the possibility of a region scope enqueue and a sysplex scope enqueue (or
two sysplex scope enqueues with different scopes) existing for the same resource.
(Because sysplex and region scope enqueues use separate namespaces, a region
scope enqueue will never wait on a sysplex enqueue, nor will a sysplex scope
enqueue wait on a region enqueue.)
Notes about the use of XNQEREQ to alter ENQ or DEQ scope.
- XNQEREQ enables you to allow existing applications to be converted to
use sysplex enqueues without changing the application.
Note:
Use
of either the ENQMODEL resource definition or the user exit allows this in
most cases, but those applications where the resource name is determined dynamically
and not known in advance can only be so converted by use of this exit.
- Sysplex and region scope enqueues use separate namespaces. A region scope
enqueue will never wait on a sysplex enqueue, nor will a sysplex scope enqueue
wait on a region enqueue.
Note:
This situation can only arise when
you use the exit. Use of the ENQMODEL resource definitions as your only method
of defining the SCOPE of an ENQ or DEQ avoids this potential risk.
- Both region and sysplex scope are supported for string ENQs, but sysplex
scope is not supported for address ENQs.
[[ Contents Previous Page | Next Page Index ]]