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 the z/OS Internet library. 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.
- Standard enqueue promotion:
- 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.
- 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).
- 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.
Input register information
If this SYSEVENT is invoked with the TYPE=3 keyword, then register 1 must point to a parameter list. The parameter list must be non-pageable and addressable via the caller's primary address space. To map the parameter list, use the IRAEVPL mapping macro described in z/OS MVS Data Areas in the z/OS Internet library.
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:
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. |