SETLOCK TEST

SETLOCK TEST

z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO
SA23-1375-00

Syntax

The TEST option of the SETLOCK macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede SETLOCK.

SETLOCK

␢	One or more blanks must follow SETLOCK.

TEST

,TYPE=CPU
,TYPE=CMS
,TYPE=LOCAL
,TYPE=ALOCAL
,TYPE=CML	Note: LOCKHLD or ASCB must be specified with TYPE=CML.

,LOCKHLD=`(reg)`	`reg`: Register (2) - (12)
	Note: LOCKHLD is valid only with TYPE=CML, TYPE=ALOCAL, and TYPE=CPU

,ASCB=`(reg)`	`reg`: Register (2) - (12)
	Note: ASCB is valid only with TYPE=CML.

,BRANCH=(HELD,`addr`)	`addr`: RX-type address.
,BRANCH=(NOTHELD,`addr`)

,RELATED=`value`	`value`: Any valid macro keyword specification.

Parameters

The parameters are explained as follows:

TEST

Specifies that the lock designated by the TYPE parameter is to be checked to determine if it is currently held on the requesting processor.

,TYPE=CPU

,TYPE=CMS

,TYPE=LOCAL

,TYPE=ALOCAL

,TYPE=CML

Specifies the type of lock. The types available are:

CPU: The processor lock. It is a pseudo spin lock providing MVS-recognized disablement. There is one CPU lock per processor, and no processor can request another processor's lock. The lock is always available. Users can obtain the CPU lock to become disabled for I/O and external interrupts.
CMS: The cross memory services lock. It is a global suspend lock used to serialize functions between address spaces.
LOCAL: The lock that serializes resources in the home address space pointed to by PSAAOLD. It is a local level suspend lock.
ALOCAL: Determines whether a local lock is held, either home's LOCAL lock or a CML lock. The LOCKHELD=(reg) parameter can be specified with TYPE=ALOCAL.
CML: The cross memory local lock. It is a local level suspend type lock used to serialize resources in an address space other than the home address space. TYPE=CML specifies that the caller wishes to determine whether a CML lock is held. Either the ASCB=(reg) or the LOCKHLD=(reg) parameter can be specified with TYPE=CML, but not both.

,LOCKHLD=(reg)

Specifies that the designated register is to be used as a return register by the macro. This parameter is valid only for TYPE=CML, TYPE=CPU, and TYPE=ALOCAL.

If TYPE=CML is specified and a CML lock is held, the system returns the ASCB address of the CML-locked address space in the specified register.

If TYPE=CPU is specified, the system returns the current CPU lock use count for this processor in the specified register.

If TYPE=ALOCAL is specified and the LOCAL lock is held, the system returns a zero in the specified register.

If TYPE=ALOCAL is specified and a CML lock is held, the system returns the ASCB address of the CML-locked address space in the specified register. If a local lock is held, the system returns a zero in the specified register.

,ASCB=(reg)

Specifies a register that contains the ASCB address. The system checks the ASCB to determine whether the requestor's local lock is a CML lock. This parameter is valid only with TYPE=CML.

Note: Unlike the OBTAIN and RELEASE options of the SETLOCK macro, ASCB=addr is not valid.

,BRANCH=(HELD,addr)

,BRANCH=(NOTHELD,addr)

If (HELD,addr) is specified, the specified address is branched to if the specified lock is held on the requesting processor.

If (NOTHELD,addr) is specified, the specified address is branched to if the specified lock is not currently held on the requesting processor.

,RELATED=value

Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user, and may be any valid coding values.

Return and reason codes

When control is returned, register 15 contains one of the following hexadecimal return codes (if the BRANCH= parameter was omitted):

Table 1. Return Codes for SETLOCK TEST
Return Code	Meaning and Action
00	Meaning: The lock was held by the requestor, or (if TYPE=CMS was specified) at least one lock was held. Action: None.
04	Meaning: The lock was available, or (if TYPE=CMS was specified) no lock was held. Action: None.

Note: TYPE=CMS is used to determine if at least one cross memory services lock is held, but cannot be used to determine which one, or to determine if all are held.

Example 1

If a local lock is not held, branch to DSRLLINT; otherwise, execute the next sequential instruction.

SETLOCK TEST,TYPE=LOCAL,BRANCH=(NOTHELD,DSRLLINT)

Example 2

Put the current CPU lock use count for this processor into register 3.

SETLOCK TEST,TYPE=CPU,LOCKHLD=(3)

Example 3

Determine whether the local lock of the address space specified in register 11 is held as a CML lock.

SETLOCK  TEST,TYPE=CML,ASCB=(11)