System Services, $ENQ
*Conan The Librarian (sorry for the slow response - running on an old VAX)
|
/sys$common/syshlp/helplib.hlb System Services, $ENQ *Conan The Librarian (sorry for the slow response - running on an old VAX) |
|
Queues a new lock or lock conversion on a resource.
The $ENQ, $ENQW, $DEQ (Dequeue Lock Request), and $GETLKI (Get
Lock Information) services together provide the user interface to
the Lock Management facility.
On Alpha systems, this service accepts 64-bit addresses.
For additional information about system service completion, see
the Synchronize ($SYNCH) service.
Format
SYS$ENQ [efn] ,lkmode ,lksb ,[flags] ,[resnam] ,[parid]
,[astadr] ,[astprm] ,[blkast] ,[acmode] ,[rsdm_id]
,[nullarg]
C Prototype
int sys$enq (unsigned int efn, unsigned int lkmode,
struct _lksb *lksb, unsigned int flags,
void *resnam, unsigned int parid, void
(*astadr)(__unknown_params), unsigned int acmode,
unsigned int rsdm_id,...);
Arguments
efn
OpenVMS usage:ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag to be set when the request has been
granted or canceled. Cancellation occurs if you use $DEQ with the
cancel modifier or if the waiting request is chosen to break a
deadlock. The efn argument is a longword containing this number;
however, $ENQ uses only the low-order byte.
Upon request initiation, $ENQ clears the specified event flag
(or event flag 0 if efn was not specified). Then, when the lock
request is granted, the specified event flag (or event flag 0)
is set unless you specified the LCK$M_SYNCSTS flag in the flags
argument.
lkmode
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Lock mode requested. The lkmode argument is a longword specifying
this lock mode.
Each lock mode has a symbolic name. The $LCKDEF macro defines
these symbolic names. The following table gives the symbolic name
and description for each lock mode:
Lock Mode Description
LCK$K_NLMODE Null mode. This mode grants no access to the
resource but serves as a placeholder and indicator
of future interest in the resource. The null mode
does not inhibit locking at other lock modes;
further, it prevents the deletion of the resource
and lock value block, which would otherwise occur
if the locks held at the other lock modes were
dequeued.
LCK$K_CRMODE Concurrent read. This mode grants the caller read
access to the resource while permitting write
access to the resource by other users. This mode is
used to read data from a resource in an unprotected
manner, because other users can modify that data as
it is being read. This mode is typically used when
additional locking is being performed at a finer
granularity with sublocks.
LCK$K_CWMODE Concurrent write. This mode grants the caller
write access to the resource while permitting write
access to the resource by other users. This mode is
used to write data to a resource in an unprotected
fashion, because other users can simultaneously
write data to the resource. This mode is typically
used when additional locking is being performed at
a finer granularity with sublocks.
LCK$K_PRMODE Protected read. This mode grants the caller read
access to the resource while permitting only read
access to the resource by other users. Write access
is not allowed. This is the traditional share lock.
LCK$K_PWMODE Protected write. This mode grants the caller write
access to the resource while permitting only read
access to the resource by other users; the other
users must have specified concurrent read mode
access. No other writers are allowed access to the
resource. This is the traditional update lock.
LCK$K_EXMODE Exclusive. The exclusive mode grants the caller
write access to the resource and allows no access
to the resource by other users. This is the
traditional exclusive lock.
Table SYS-2 Compatibility of Lock Modes
Mode of Mode of Currently Granted Locks
Requested
Lock NL CR CW PR PW EX
NL Yes Yes Yes Yes Yes Yes
CR Yes Yes Yes Yes Yes No
CW Yes Yes Yes No No No
PR Yes Yes No Yes No No
PW Yes Yes No No No No
EX Yes No No No No No
__________________________________________________________________
Key to Lock Modes:
NL-Null
CR-Concurrent read
CW-Concurrent write
PR-Protected read
PW-Protected write
EX-Exclusive
lksb
OpenVMS usage:lock_status_block
type: longword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Lock status block in which $ENQ writes the final completion
status of the operation. The lksb argument is the 32- or 64-bit
address (on Alpha systems) or the 32-bit address (on VAX systems)
of the 8-byte lock status block.
The lock status block can optionally contain a 16-byte lock value
block. The initial value of the lock value block is zero (0).
When you specify the LCK$M_VALBLK flag in the flags argument, the
lock status block contains a lock value block. In this case, the
16-byte lock value block appears at the beginning of the first
byte following the eighth byte of the lock status block, bringing
the total length of the lock status block to 24 bytes.
Refer to the OpenVMS System Services Reference Manual to view the
lock status block format diagram and status block fields table.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flags specifying options for the $ENQ operation. The flags
argument is a longword bit mask that is the logical OR of each
bit set, where each bit corresponds to an option.
The $LCKDEF macro defines a symbolic name for each flag bit.
Refer to the OpenVMS System Services Reference Manual to view the
table describing each flag.
resnam
OpenVMS usage:char_string
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor (Alpha)
mechanism: by 32-bit descriptor-fixed-length string descriptor
(VAX)
Name of the resource to be locked by this lock. The resnam
argument is the 32- or 64-bit address (on Alpha systems) or the
32-bit address (on VAX systems) of a character string descriptor
pointing to this name. The name string can be from 1 to 31 bytes
in length.
If you are creating a new lock, the resnam argument should be
specified because the default value for the resnam argument
produces an error when it is used to create a lock. The resnam
argument is ignored for lock conversions.
parid
OpenVMS usage:lock_id
type: longword (unsigned)
access: read only
mechanism: by value
Lock identification of the parent lock. The parid argument is a
longword containing this identification value.
If you do not specify this argument or specify it as 0, $ENQ
assumes that the lock does not have a parent lock. This argument
is optional for new locks and is ignored for lock conversions.
astadr
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
AST service routine to be executed when the lock is either
granted or converted. The astadr argument is the 32- or 64-
bit address (on Alpha systems) or the 32-bit address (on VAX
systems) of this routine. The AST is also delivered when the lock
or conversion request is canceled. Cancellation occurs if you use
$DEQ with the cancel modifier or if the waiting request is chosen
to break a deadlock.
If you specify the astadr argument, the AST routine executes at
the same access mode as the caller of $ENQ.
astprm
OpenVMS usage:user_arg
type: quadword (unsigned)
access: read only
mechanism: by value
AST parameter to be passed to the AST routine specified by the
astadr argument. The astprm argument specifies this quadword
parameter.
blkast
OpenVMS usage:ast_procedure
type: procedure value
access: call without stack unwinding
mechanism: by 32- or 64-bit reference (Alpha)
mechanism: by 32-bit reference (VAX)
Blocking AST routine to be called whenever this lock is granted
and is blocking any other lock requests. The blkast argument
is the 32- or 64-bit address (on Alpha systems) or the 32-
bit address (on VAX systems) of this routine. Locks that are
converting to a new mode, but that are not yet granted in the new
mode, do not receive blocking ASTs.
You can pass a parameter to this routine by using the astprm
argument.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to be associated with the resource name. The acmode
argument indicates the least privileged access mode from which
locks can be queued on the resource.
This argument does not affect the access mode associated with the
lock or its blocking and completion ASTs. The acmode argument is
a longword containing the access mode. The $PSLDEF macro defines
the following symbols for the four access modes:
Symbol Access Mode
PSL$C_KERNEL Kernel
PSL$C_EXEC Executive
PSL$C_SUPER Supervisor
PSL$C_USER User
The $ENQ service associates an access mode with the lock in the
following way:
o If you specified a parent lock (with the parid argument),
$ENQ uses the access mode associated with the parent lock and
ignores both the acmode argument and the caller's access mode.
o If the lock has no parent lock (you did not specify the parid
argument or specified it as 0), $ENQ uses the least privileged
of the caller's access mode and the access mode specified
by the acmode argument. If you do not specify the acmode
argument, $ENQ uses the caller's access mode.
rsdm_id
OpenVMS usage:longword
type: longword (unsigned)
access: read only
mechanism: by value
Resource domain identification. The rsdm_id argument is a
longword specifying the resource domain association through
which a new lock is to be taken. This argument is ignored for
lock conversions and sublocks (parid is nonzero). Valid resource
domain identifiers are returned from the $SET_RESOURCE_DOMAIN
service, or by the constants RSDM$K_SYSTEM_RSDM_ID or RSDM$K_
PROCESS_RSDM_ID, which are defined by the $RSDMDEF macro in
STARLET.
nullarg
OpenVMS usage:null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Placeholding argument reserved by Compaq.
|
|
