ISGLREL — Release a latch

Description

Call the Latch_Release service to release ownership of an owned latch or a pending request to obtain a latch. Requestors should call Latch_Release when the use of a resource associated with a latch is no longer required. The following callable services are related to Latch_Release:
ISGLCRT
Creates a latch set that an application can use to serialize resources.
ISGLOBT
Requests exclusive or shared control of a latch.
ISGLPRG
Purges all granted and pending requests for a particular requestor within a specific latch set.
In the following description of Latch_Release:
  • The term requestor describes a program that calls the Latch_Release service to release ownership of an owned latch or a pending request to obtain a latch.
  • Equate symbols defined in the ISGLMASM macro are followed by their numeric equivalents; you may specify either when coding calls to Latch_Obtain. For example, "ISGLREL_COND (value of 1)" indicates the equate symbol ISGLREL_COND and its associated value, 1.

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_Release service, include the ISGLMASM macro to obtain assembler declaration statements for Latch_Release. ISGLMASM provides the following equate symbols for use when calling Latch_Release: 
*
*   Latch Release Option Equate Symbols
*
ISGLREL_UNCOND                EQU   0
ISGLREL_COND                  EQU   1
*
*   Latch Release Return Codes
*
ISGLREL_SUCCESS               EQU   0
ISGLREL_NOT_OWNED_ECB_REQUEST EQU   4
ISGLREL_STILL_SUSPENDED       EQU   8
ISGLREL_INCORRECT_LATCH_TOKEN EQU  12
*

Restrictions

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

Input register information

Before calling the Latch_Release 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

See the information about releasing latches in z/OS MVS Programming: Authorized Assembler Services Guide for performance implications related to the Latch_Release service.

Syntax

Write the CALL as shown on the syntax diagram, coding all parameters in the specified order.

Assign values to the following parameters:
  • latch_set_token
  • latch_token
  • release_option
Latch_Release returns a value in the following parameter:
  • return_code
Latch_Release uses the following parameter for temporary storage:
  • work_area
Syntax Description

CALL ISGLREL

 
,(latch_set_token
,latch_token
,release_option
,work_area
,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 returned to the caller of the Latch_Create service. The latch set token identifies the latch set that contains the latch to be released.
,latch_token
Specifies an 8-byte area that contains the latch token returned to the caller of the Latch_Obtain service. The latch token identifies the request to be released.
,release_option
Specifies a fullword integer that tells the latch manager what to do when the requestor either no longer owns the latch to be released or still has a pending request to obtain the latch to be released:
ISGLREL_UNCOND (value of 0)
Abend the requestor:
  • If a requestor originally specified an obtain_option of ISGLOBT_SYNC (value of 0) and is suspended while waiting to obtain the latch, the latch manager does not release the latch. The system abends the caller of Latch_Release with abend X'9C6', reason code xxxx0009.
  • If a requestor originally specified an obtain_option of ISGLOBT_ASYNC_ECB (value of 2) and is suspended while waiting to obtain the latch, the latch manager does not release the latch. The system abends the caller of Latch_Release with abend X'9C6', reason code xxxx0007.
  • If the latch manager does not find a previous Latch_Obtain request for the specified latch, the system abends the caller of Latch_Release with abend X'9C6', reason code xxxx000A.
ISGLREL_COND (value of 1)
Return control to the requestor:
  • If a requestor originally specified an obtain_option of ISGLOBT_ASYNC_ECB (value of 2) and the latch has been obtained, but the ECB has not been posted, the latch manager releases the request for ownership of the latch. The system returns control to the caller of Latch_Release with a return code of ISGLREL_NOT_OWNED_ECB_REQUEST (value of 4).
  • If a requestor originally specified an obtain_option of ISGLOBT_SYNC (value of 0) but is suspended while waiting to obtain the latch, the latch manager does not release the request for ownership of the latch. The system returns control to the caller of Latch_Release with a return code of ISGLREL_STILL_SUSPENDED (value of 8).
  • If the latch manager does not find a previous Latch_Obtain request for the specified latch, the system returns control to the caller of Latch_Release with a return code of ISGLREL_INCORRECT_LATCH_TOKEN (value of 12).
,work_area
Specifies a 256-byte work area that provides temporary storage for the Latch_Release service. The work area should begin on a doubleword boundary to optimize performance. The work area must be in the same storage key as the caller of Latch_Release.
,return_code
Specifies a fullword integer that is to contain the return code from the Latch_Release 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_Release 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. ISGLREL Return Codes
Return code and Equate Symbol Meaning and Action

00
(0)
ISGLREL_SUCCESS

 Meaning: The Latch_Release service completed successfully. The caller released ownership of the specified latch request.

Action: None.

04
(4)
ISGLREL_NOT_OWNED_ECB_REQUEST

 Meaning: The requestor that originally called the Latch_Obtain service is still expecting the system to post an ECB (to indicate that the requestor has obtained the latch). The call to the Latch_Release service specified a release_option of ISGLREL_COND (value of 1). The latch manager does not post the ECB at the address specified on the original call to Latch_Obtain. The latch manager releases the latch.

Action: Validate the integrity of the resource associated with the latch (the requestor might have used the resource without waiting on the ECB). If the resource is undamaged, no action is necessary (a requestor routine may have been in the process of cancelling the request to obtain the latch).

08
(8)
ISGLREL_STILL_SUSPENDED

 Meaning: Program error. The request specified a correct latch token, but the program that originally requested the latch is still suspended and waiting to obtain the latch.

The latch requestor originally specified an obtain_option of ISGLOBT_SYNC on the call to the Latch_Obtain service. The call to the Latch_Release service specified a release_option of ISGLREL_COND (value of 1). The latch manager does not release the latch. The latch requestor remains suspended.

Action:
  • Wait for the latch requestor to obtain the latch and receive control back from the system; then call the Latch_Release service again, or
  • End the program that originally requested the latch.

0C
(12)
ISGLREL_INCORRECT_LATCH_TOKEN

 Meaning: The latch manager could not find a granted or pending request associated with the value on the latch token parameter. The latch manager does not release a latch.

This return code does not indicate an error if a routine calls Latch_Release to ensure that a latch is released. For example, if an error occurs when a requestor calls the Latch_Obtain service, the requestor's recovery routine might call Latch_Release to ensure that the requested latch is released. If the error prevented the requestor from obtaining the latch, the recovery routine receives this return code.

Action: If the return code is not expected, validate that the latch token is the same latch token returned to the caller of Latch_Obtain.

Example

See LATCHX31 - How to call AMODE 31 latch devices for an example of how to call Latch_Release in assembler language.