Identify holder of a resource (ENQHOLD)

Use the ENQHOLD SYSEVENT to identify a holder of a resource causing contention. SRM may boost the service to the resource holder to help resolve the contention more quickly. A holder can be either an address space or an enclave. You must specify the address space or enclave in the parameter list pointed to by register 1. Use the IRAEVPL mapping macro described in z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/. Specify either the ASID or STOKEN value for the address space or the enclave token for the enclave. The enclave token must have been obtained from the IWMECREA macro or IWMESQRY macro.

Specify parameter TYPE=3 for SYSEVENT ENQHOLD and ENQRLSE to pass the following data to SRM:

Subsystem information

Specify subsystem information that will be kept by SRM for RAS purposes and is formatted in IPCS.

Enqueue promotion function request

Choose either the standard enqueue management promotion, or the short time/high frequency enqueue promotion:

Standard enqueue promotion:
Use the SYSEVENT ENQHOLD to signal a resource contention to SRM and use the SYSEVENT ENQRLSE when the resource contention ends. This function causes SRM to boost the service to the resource holder for the number of service units defined by the ERV parameter in the IEAOPTXX member.
Short time/high frequency enqueue promotion:
Use the SYSEVENT ENQHOLD to signal a short time resource contention to SRM. This function causes SRM to boost the service to the holder of the resource for a small number of service units and after that, terminates this enqueue promotion process. For this reason, no SYSEVENT ENQRLSE is required nor should one be issued. No enqueue hold token is provided by SRM for this function in the parameter list.
Note: The number of service units used by SRM to boost the resource holder for a short time/high frequency enqueue promotion is a fixed value and cannot be modified. It has no relation to the ERV parameter in the IEAOPTxx member.

You can select the enqueue promotion functions with the FUNCTION parameter in the parameter list pointed to by register 1.

Enqueue hold token

Receive an output token from the ENQHOLD request and use the same token on the matching ENQRLSE request. The enqueue hold token is only valid for the standard enqueue management promotion.

When using enclaves for tasks that serialize on resources using the ENQ macro or the latch manager callable services, note that a task cannot change its transaction status. That is, it cannot join or leave an enclave, while holding a resource using ENQ or the latch manager. Otherwise, enqueue promotion processing might not work properly. The recommended sequence is:

Join an enclave (through IWMEJOIN, IWMSTBGN, or SYSEVENT ENCASSOC).
Obtain resource with ENQ or latch manager.
Process using serialized resource.
Release resource.
Leave an enclave (through IWMELEAV, IWMSTEND, or SYSEVENT ENCASSOC).

In addition, to ensure correct enqueue promotion processing, a task executing in an enclave should not make the following types of ENQ requests:

Directed enqueues, that is, issuing the ENQ macro with the TCB= parameter
Matching task enqueues, that is, issuing the ENQ macro with the MTCB or MASID parameter.

Return and reason codes

When processing is complete for the ENQHOLD SYSEVENT, the last byte of register 15 contains one of the following hexadecimal return codes:

Table 1. Return Codes for ENQHOLD
Return Code (Decimal)	Meaning
00	Successful completion.
08	Invalid enclave token specified.
10	The ASID specified did not map to a valid, active address space. This may occur because the address space it represents is no longer active or was never active. Note: Only valid if parameter IraEnqHR_FLAGS_RhTerm=1 was specified in the parameter list.
12	The STOKEN specified did not map to a valid, active address space. This may occur because the address space it represents is no longer active or was never active. Note: Only valid if parameter IraEnqHR_FLAGS_RhTerm=1 was specified in the parameter list.
14	The TCB address specified did not map to a valid, active TCB. This may occur because the TCB address is no longer active or was never active.
16	Invalid combination of ASID, STOKEN, or enclave token was specified in the parameter list. Specify either ASID, or STOKEN, or enclave token.

Input register information

Return and reason codes