Enqueue EXEC interface program exits XNQEREQ and XNQEREQC

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:

Using XNQEREQ, you can:

Using XNQEREQC, you can analyze the API parameter list.

You can also:

Exit XNQEREQ

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.
Start of changeUERCSCPEEnd of change
Start of changeAn ENQSCOPE name has been supplied.End of change
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 an enqueue request from the XNQEREQ exit. Use of the recursion counter UEPRECUR is recommended.

Exit XNQEREQC

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:

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

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
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:
  1. 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.
  2. 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:
  1. The lifetime of the area pointed to by UEPTSTOK is the lifetime of the task.
  2. The value of UEPTSTOK is shared by all the exits to which it is passed during the lifetime of the task.
Table 3. User arguments and associated keywords, data types, and input/output types
Argument Keyword Data type Input/output type
Arg1 RESOURCE DATA-AREA input
Arg2 LENGTH BIN(15) input
Arg3 MAXLIFETIME CVDA input

Modifying user arguments

User exit programs can modify user input arguments by:

  1. Obtaining sufficient storage to hold the modified argument
  2. Setting the storage to the required value
  3. Setting the associated pointer in the parameter list to the address of the newly-acquired area.

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 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:

  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 LENGTH and MAXLIFETIME keywords:

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.

Sample exit program, DFH$XNQE

CICS supplies a sample exit program, DFH$XNQE, for the XNQEREQ exit.

The program gives examples of:

Notes about the use of XNQEREQ to alter ENQ or DEQ scope.

  1. 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.
  2. 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.
  3. Both region and sysplex scope are supported for string ENQs, but sysplex scope is not supported for address ENQs.

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