Syntax
The OBTAIN option of 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. |
|
|
OBTAIN |
|
|
|
,TYPE=CPU |
|
,TYPE=CMS |
|
,TYPE=LOCAL |
|
,TYPE=CML,ASCB=(11) |
|
,TYPE=CML,ASCB=addr |
addr: A-type address |
|
|
,MODE=COND |
Note: MODE cannot be specified with TYPE=CPU. |
,MODE=UNCOND |
|
|
|
,REGS=SAVE |
|
,REGS=USE |
|
,REGS=STDSAVE |
|
|
|
,RELATED=value |
value: Any valid macro keyword
specification. |
|
|
Parameters
The parameters are explained as follows:
- OBTAIN
- Specifies that the lock designated by the TYPE parameter is to
be obtained on the caller's behalf.
- ,TYPE=CPU
- ,TYPE=CMS
- ,TYPE=LOCAL
- ,TYPE=CML,ASCB=(11)
- ,TYPE=CML,ASCB=addr
- 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.
- 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.
The requestor of a CML lock must have authority
to access the specified address space before requesting the lock.
To establish authority, the requestor sets the primary or secondary
address space to the one specified by the ASCB=(11) or ASCB=addr parameter.
Register 11 or addr must contain the address of
the ASCB whose local lock is requested. This address space must be
nonswappable before the SETLOCK request.
Note: If the requestor
specifies OBTAIN,TYPE=CML and the ASCB parameter points to the home
address space, the request is treated as though the LOCAL lock were
being obtained.
- ,MODE=COND
- ,MODE=UNCOND
- Specifies whether the lock is to be conditionally or unconditionally
obtained.
- COND
- Specifies that the lock is to be conditionally obtained. That
is, if the lock is not owned on another processor, it is acquired
on the caller's behalf. If the lock is already held, control is returned
indicating that the caller holds the lock or that another unit of
work on another processor owns the lock.
- UNCOND
- Specifies that the lock is to be unconditionally obtained. That
is, if the lock is not owned on another processor, it is acquired
on the caller's behalf. If the lock is already held by the caller,
control is returned to the calling program indicating that it already
owns the lock. If the lock is held on another processor, the system
suspends the SETLOCK caller until the lock is available.
The system
does not permit an unconditional OBTAIN request for a CML lock if
the lock is held by a unit of work that is set nondispatchable.
- ,REGS=SAVE
- ,REGS=USE
- ,REGS=STDSAVE
- Specifies the use of general purpose registers by the SETLOCK
macro.
- SAVE
- Specifies that the contents of registers 11 through 14 are saved
in the area pointed to by register 13 and are restored upon completion
of the SETLOCK request. This save area must be at least 20 bytes,
and must not be the same area as the standard linkage save area used
by the program.
Upon completion of the SETLOCK macro with REGS=SAVE,
the register contents are as follows: - Register
- Contents
- 0-14
- Unchanged
- 15
- Return code
- USE
- Specifies that the contents of registers 11 through 13 are saved
in work registers 0, 1, and 15.
Upon completion of the SETLOCK
macro with REGS=USE, the register contents are as follows: - Register
- Contents
- 0-1
- Used as work registers by the system
- 2-13
- Unchanged
- 14
- Used as a work register by the system
- 15
- Return code
- STDSAVE
- Specifies that the contents of registers 2 through 12 are saved
in a standard 72-byte save area pointed to by register 13.
Upon
completion of the SETLOCK macro with REGS=STDSAVE, the register contents
are as follows: - Register
- Contents
- 0-1
- Unchanged
- 2-13
- Unchanged
- 14
- Used as a work register by the system
- 15
- Return code
- ,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.
ABEND codes
SETLOCK might abnormally terminate with abend code X'073'.
See z/OS MVS System Codes for
an explanation and programmer response for this code.
Return and reason codes
When control returns to the caller, register 15 (or register 13,
if the REGS parameter is not specified) contains one of the following
hexadecimal return codes:
Table 1. Return Codes for the
SETLOCK MacroReturn Code |
Meaning and Action |
---|
00 |
Meaning: The lock was successfully obtained. Action:
None.
|
04 |
Meaning: The lock was already held by the
caller. Action: None.
|
08 |
Meaning: The conditional obtain process
was unsuccessful. The lock is owned by another processor. Action:
None required. However, you might try to take some action based upon
your application.
|
When the SETLOCK OBTAIN request is for the CPU lock, the system
returns only return code 0. You do not need to check the return code
because once control is returned to you after the SETLOCK OBTAIN,TYPE=CPU
request, you will have the CPU lock.
Example 1
Obtain the CPU lock, saving registers 2 through 12 in the standard
save area whose address is in register 13. SETLOCK OBTAIN,TYPE=CPU,REGS=STDSAVE
Example 2
Obtain the CMS lock. Because the caller must hold the LOCAL or
CML lock to obtain the CMS lock, the caller must first obtain the
LOCAL lock unconditionally, saving registers 2 through 12 in the save
area pointed to by register 13. The caller then issues the request
to obtain the CMS lock. SETLOCK OBTAIN,TYPE=LOCAL,MODE=UNCOND,REGS=STDSAVE
SETLOCK OBTAIN,TYPE=CMS,MODE=UNCOND,REGS=STDSAVE
Example 3
Obtain the LOCAL lock unconditionally, saving registers 11 through
14 in the save area pointed to by register 13. The save area pointed
to by register 13 is not the same area as the standard linkage save
area. LR 5,13 SAVE STANDARD SAVE AREA POINTER
LA 13,SETLOCK_SAVEAREA
SETLOCK OBTAIN,TYPE=LOCAL,MODE=UNCOND,REGS=SAVE
LR 13,5 RESTORE STANDARD SAVE AREA POINTER
.
.
.
SETLOCK_SAVEAREA DS 5F SAVE AREA FOR SETLOCK REQUESTS
|