NIL — Provide a lock via an AND IMMEDIATE (NI) instruction

Description

The NIL macro is used to provide a lock on a byte of storage on which an AND immediate (NI) instruction is to be executed. Because the byte of storage exists in a multiprocessing environment, the possibility exists that the byte might be changed by another processor at the same time. Storage modification during NIL processing is accomplished by using the compare and swap (CS) instruction.

For details on the AND immediate and compare and swap instructions, see Principles of Operation.

Environment

These are the requirements for the caller:

Environmental factor	Requirement
Minimum authorization:	Problem or supervisor state, any key
Dispatchable unit mode:	Task or SRB
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	24- or 31-bit
ASC mode:	Primary or access register (AR)
Interrupt status:	None
Locks:	The caller may hold locks, but is not required to hold any.
Control parameters:	None

Programming requirements

None.

Restrictions

None.

Input register information

Before issuing the NIL macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Output register information

When control returns to the caller, the GPRs are unchanged except for the three work registers that are used by the system. If WREGS is not specified, these will be registers 0-2.

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

The NIL macro is written as follows:

Syntax	Description

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

␢	One or more blanks must precede NIL.

NIL

␢	One or more blanks must follow NIL.

`byte addr`	`byte addr`: RX-type address.

`,mask`	`mask`: Symbol or self-defining term.

,REF=`stor addr`	`stor addr`: RX-type address.

,WREGS=`(reg1,reg2,reg3)`	`reg1`: Symbol or decimal digits 0-15.
,WREGS=`(reg1,reg2)`	`reg2`: Symbol or decimal digits 1-15.
,WREGS=`(reg1,,reg3)`	`reg3`: Symbol or decimal digits 0-15.
,WREGS=`(,reg2,reg3)`	Default for `reg1`: 0
,WREGS=`(reg1)`	Default for `reg2`: 1
,WREGS=`(,reg2)`	Default for `reg3`: 2
,WREGS=`(,,reg3)`

Parameters

The parameters are explained as follows:

byte addr: Specifies the address of the byte to which the AND function is to be applied.
,mask: Specifies the value to be ANDed to the byte at the address specified above.
,REF=stor addr: Specifies the address of a storage location on a fullword boundary. This address provides the means by which the compare and swap instruction may be executed. The address must be less than or equal to the byte address specified above, and the difference between the addresses must be less than 4095. The two addresses must be addressable via the same base register.
,WREGS=(reg1,reg2,reg3)
,WREGS=(reg1,reg2)
,WREGS=(reg1,,reg3)
,WREGS=(,reg2,reg3)
,WREGS=(reg1)
,WREGS=(,reg2)
,WREGS=(,,reg3): Specifies the work registers to be used to perform the compare and swap instruction. reg1 is used to contain the “old” byte; reg2 is used to contain the “updated” byte; and reg3 is used to contain the mask.

ABEND codes

None.

Return and reason codes

None.

Example

Turn off bit TNVLXMET in byte TNVLCS1. The reference field, TNVLFW3, specifies the word being updated.

NIL TNVLCS1,X'FF'-TNVLXMET,REF=TNVLFW3