ISGLPBA — Purge a group of requestors from a group of latch sets

Description

Call the Latch_Purge_by_Address_Space service to purge all granted and pending requests for a group of requestors for a group of latch sets in the same address space. To effectively use this service, your latch_set_names and your requestor_IDs should be defined such that they have a common portion and a unique portion. Groups of latch sets can then be formed by masking off the unique portion of the latch_set_name, and groups of latch requests in a latch set can then be formed by masking off the unique portion of the requestor_ID. Masking off the unique portion of the requestor_ID allows a single purge request to handle multiple latch sets and multiple requests in a latch set. Recovery routines should call Latch_Purge_by_Address_Space when one or more errors prevent requestors from releasing latches.

The following callable services are related to Latch_Purge_by_Address_Space:

ISGLCRT: Creates a latch set that an application can use to serialize resources.
ISGLOBT: Requests exclusive or shared control of a latch.
ISGLREL: Releases control of an owned latch or a pending request to obtain a latch.
ISGLPRG: Purges all granted and pending requests for a particular requestor within a specific latch set.

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

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Supervisor state or PKM allowing key 0-7
Dispatchable unit mode:	Task or SRB
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	31-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 Latch_Purge_by_Address_Space service, you need to include the ISGLMASM macro to obtain assembler declaration statements for Latch_Purge_by_Address_Space. ISGLMASM provides the following equate symbols for use when calling Latch_Purge_by_Address_Space

  *
  *   Latch Purge by Address Space Return Codes
  *
  ISGLPRG_SUCCESS               EQU   0
  ISGLPRG_DAMAGE_DETECTED       EQU   4
  ISGLPRG_INCORRECT_MASK        EQU   C
  *

Restrictions

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

Input register information

Before calling the Latch_Purge_by_Address_Space service, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:

Register: Contents
13: Address of a standard 72-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
requestor_ID_mask
latch_set_name
latch_set_name_mask

Latch_Purge_by_Address_Space returns a value in the return_code parameter.

Syntax	Description
CALL ISGLPBA	,(latch_set_token ,requestor_ID ,requestor_ID_mask ,latch_set_name ,latch_set_name_mask ,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 or a value of zero. If the value is not zero, the latch_set_token identifies the latch set from which latch requests are to be purged. If the latch_set_token is set to zero, a group of latch sets, determined by the latch_set_name and latch_set_name_mask, will have their latch requests purged.
,requestor_id: Specifies an 8-byte area that contains a portion of the requestor_ID originally specified on one or more previous calls to the Latch_Obtain service. This operand will be compared to the result of logically ANDing each requestor_ID in the latch set with the requestor_ID_mask. Make sure that any corresponding bits that are zero in the requestor_ID_mask are also zero in this field, otherwise no ID matches will occur. Each requestor_ID that has a name match will have its Latch_Obtain requests released.
,requestor_id_mask: Specifies an 8-byte area that contains the requestor_ID_mask that will be logically ANDed to each requestor_ID in the latch set and then compared to the requestor_ID operand. Each requestor_ID that has a name match will have its Latch_Obtain requests released.
,latch_set_name: Specifies a 48-byte area that contains the portion of the latch_set_name that will be compared to the result of logically ANDing the latch_set_name_mask with each latch set name in the primary address space. Make sure that any corresponding bits that are zero in the latch_set_name_mask are also zero in this field, otherwise no name matches will occur. Each latch set that has a name match will have its Latch_Obtain requests released. If the latch_set_token operand is non-zero this operand is ignored.
,latch_set_name_mask: Specifies a 48-byte area that contains the mask that will be logically ANDed to each of the latch set names in the primary address apace and then compared to the latch_set_name operand. Each latch set that has a name match will have its Latch_Obtain requests released. If the latch_set_token operand is non-zero this operand is ignored.
,return_code: A fullword integer that contains the return code from the Latch_Purge_By_Address_Space 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 Latch_Purge_by_Address_Space service returns control to your program, the 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. ISGLPBA Return Codes
Return code and Equate Symbol	Meaning and Action
00 (0) ISGLPRG_SUCCESS	Meaning: The Latch_Purge_by_Address_Space 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.