ISGLPR64 — Purge a requestor from a latch set in 64-bit mode

Description

Call the 64-bit Latch_Purge service to purge all granted and pending requests for a particular requestor within a specific 64-bit latch set. Recovery routines should call 64-bit Latch_Purge when one or more errors prevent requestors from releasing latches. The following callable services are related to the 64-bit Latch_Purge:
ISGLCR64
Creates a 64-bit latch set that an application can use to serialize resources.
ISGLOB64
Requests exclusive or shared control of a 64-bit latch.
ISGLRE64
Releases control of an owned 64-bit latch or a pending request to obtain a 64-bit latch.

In the following description of 64-bit Latch_Purge, equate symbols defined in the ISGLMASM macro are followed by their numeric equivalents; you may specify either when coding calls to 64-bit Latch_Purge.

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization: Supervisor state or PSW allowing key 0-7
Dispatchable unit mode: Task or SRB
Cross memory mode: Any PASN, any HASN, any SASN
AMODE: 64-bit
ASC mode: Primary
Interrupt status: Enabled for I/O and external interrupts
Locks: No locks held
Control parameters: Control parameters must be accessible from the primary address space.

Programming requirements

Before you use the 64-bit Latch_Purge service, you need to include the ISGLMASM macro to obtain assembler declaration statements for Latch_Purge. ISGLMASM provides the following equate symbols for use when calling Latch_Purge: 
*
*   Latch Purge Return Codes
*
ISGLPRG_SUCCESS               EQU   0
ISGLPRG_DAMAGE_DETECTED       EQU   4
*

Restrictions

  1. The caller of 64-bit Latch_Purge must have a PSW key that allows access to the latch set storage.
  2. You must call the 64-bit Latch_Purge from the same primary address space from which the 64-bit Latch_Create service was called.

Input register information

Before calling the 64-bit Latch_Purge service, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
Register
Contents
13
Address of a standard 144-byte save area located in the primary address space

Output register information

When control returns to the caller, the GPRs contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14-15
Used as work registers by the system
When control returns to the caller, the ARs contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14-15
Used as work registers by the system

Performance implications

None.

Syntax

Write the CALL as shown on the syntax diagram. You must code all parameters on the CALL statement in the order shown.

Assign values to the following parameters:
  • latch_set_token
  • requestor_ID
The 64-bit Latch_Purge returns a value in the return_code parameter.
Syntax Description

CALL ISGLPR64

 
,(latch_set_token
,requestor_ID
,return_code)
 

Parameters

All input to callable services is in the form of RX-type addresses.

The parameters are explained as follows:

latch_set_token
Specifies an 8-byte area that contains the latch_set_token previously returned by the Latch_Create service. The latch set token identifies the latch set from which latch requests are to be purged.
,requestor_ID
Specifies an 8-byte area that contains the requestor_ID originally specified on one or more previous calls to the Latch_Obtain service. The Latch_Purge service is to release all Latch_Obtain requests that specify this requestor_ID.
,return_code
A fullword integer that contains the return code from the Latch_Purge service.

ABEND codes

The caller might encounter abend code X'9C6' for certain errors. See z/OS MVS System Codes for explanations and responses.

Return codes

When the 64-bit Latch_Purge service returns control to your program, return_code contains a hexadecimal return code. The following table identifies return codes in hexadecimal and decimal (in parentheses), the equate symbol associated with each return code, the meaning of each return code, and a recommended action:

Table 1. ISGLPRG Return Codes
Return code and Equate Symbol Meaning and Action

00
(0)
ISGLPRG_SUCCESS

 Meaning: The Latch_Purge service completed successfully.

Action: None.

04
(4)
ISGLPRG_DAMAGE_DETECTED

 Meaning: Program error. While purging all requests for a particular requestor from a latch set, the latch manager found incorrect data in one or more latches. The latch manager tries to purge the latches that contain incorrect data, but the damage might prevent the latch manager from purging those latches. The latch manager purges the remaining latches (those with correct data) for the specified requestor.

Action: Take a dump and check for a storage overlay. If your application can continue without the resources serialized by the damaged latches, no action is required.

Example

See LATCHX64 - How to call AMODE 64 latch services for an example of how to call 64-bit Latch_Purge in assembler language.