Dequeues (unlocks) granted locks; dequeues the sublocks of a
lock; or cancels an ungranted lock request. The calling process
must have previously acquired the lock or queued the lock request
by calling the Enqueue Lock Request ($ENQ) service.
On Alpha and Integrity server systems, this service accepts 64-
bit addresses.
Format
SYS$DEQ [lkid] ,[valblk] ,[acmode] ,[flags]
C Prototype
int sys$deq (unsigned int lkid, void *valblk, unsigned int
acmode, unsigned int flags);
1 – Arguments
lkid
OpenVMS usage:lock_id
type: longword (unsigned)
access: read only
mechanism: by value
Lock identification of the lock to be dequeued. The lkid argument
specifies this lock identification.
Note that if you do not specify the lkid argument, you must
specify the LCK$M_DEQALL flag in the flags argument.
When you specify the LCK$M_DEQALL flag in the flags argument,
different values (or no value) for the lkid argument produce
varying behavior:
o When you do not specify the lkid argument (or specify it as
0) and you do specify the LCK$M_DEQALL flag, $DEQ dequeues all
locks held by the process, at access modes equal to or less
privileged than the effective access mode, on all resources.
The effective access mode is the least privileged of the
caller's access mode and the access mode specified in the
acmode argument.
o When you specify the lkid argument as a nonzero value together
with the LCK$M_DEQALL flag, $DEQ dequeues all sublocks of
the lock identified by lkid; it does not dequeue the lock
identified by lkid. For this operation, $DEQ ignores the
LCK$M_CANCEL flag if it is set. A sublock of a lock is a lock
that was created when the parid argument in the call to $ENQ
was specified, where parid is the lock ID of the parent lock.
If you omit the lkid argument (or specify it as 0) and the LCK$M_
DEQALL flag is not set, the $DEQ service returns the invalid lock
ID condition value (SS$_IVLOCKID).
valblk
OpenVMS usage:lock_value_block
type: longword (unsigned)
access: modify
mechanism: by 32- or 64-bit reference
Lock value block for the resource associated with the lock to
be dequeued. The valblk argument is the 32- or 64-bit address of
the 16-byte lock value block, or, if LCK$M_XVALBLK is specified
(on Alpha or Integrity server systems), of the 64-byte lock value
block. When you specify the LCK$M_DEQALL flag, you cannot use
this argument.
When a protected write (PW) or exclusive (EX) mode lock is
being dequeued and you specify a lock value block in the valblk
argument, the contents of that lock value block are written to
the lock value block in the lock database. Further, if the lock
value block in the lock database was marked as invalid, that
condition is cleared; the block becomes valid.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode of the lock to be dequeued. The acmode argument is a
longword containing the access mode.
The acmode argument is valid only if the LCK$M_DEQALL flag of the
flags argument is set. 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
When dequeuing locks, $DEQ maximizes the access mode of the
caller and the specified acmode argument. The maximized access
mode is the less privileged of the caller's access mode and the
acmode argument. If you do not specify the acmode argument, $DEQ
uses the caller's access mode. Only those locks with an access
mode that is equal to or less than the maximized access mode are
dequeued.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flags specifying options for the $DEQ 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.
Note that if you do not specify the lkid argument, you must
specify the LCK$M_DEQALL flag in the flags argument.
A symbolic name for each flag bit is defined by the $LCKDEF
macro. The following table describes each flag:
Flag Description
LCK$M_DEQALL When you specify this flag, $DEQ dequeues
multiple locks, depending on the value of the lkid
argument. For details, see the description of the
lkid argument. The acmode argument is ignored if
the LCK$M_DEQALL flag is not set. If you specify
LCK$M_DEQALL, the LCK$M_CANCEL flag, if set, is
ignored.
LCK$M_CANCEL When you specify this flag, $DEQ attempts to
cancel a lock request that was queued by $ENQ.
You can cancel only a waiting request. When the
request is canceled, $DEQ returns the condition
value SS$_NORMAL.
If you attempt to cancel a granted lock, the
request fails and $DEQ returns the condition value
SS$_CANCELGRANT. There are two types of waiting
requests that can be canceled:
o A request for a new lock
o A request to convert an existing lock
When canceling a new lock request, the following
action is taken:
o If a completion asynchronous system trap (AST)
was requested, the AST is queued for delivery
and SS$_ABORT is stored in the lock status
block.
When canceling a request to convert an existing
lock, the conversion request is canceled. The
existing granted lock remains unchanged. The
following specific actions are taken:
o The blocking AST address specified for the
existing granted lock is queued for delivery
if the granted mode of the existing lock is
blocking other waiting requests.
o If a completion AST was specified by the
conversion request, the completion AST is
queued for delivery with SS$_CANCEL status
stored in the lock status block that was
specified by the conversion request.
If you specify the LCK$M_DEQALL flag, the LCK$M_
CANCEL flag is ignored.
LCK$M_ When you specify this flag, $DEQ marks the lock
INVVALBLK value block, which is maintained for the resource
in the lock database, as invalid. The lock value
block remains marked as invalid until it is again
written to. The Description section of the $ENQ
service provides additional information about lock
value block invalidation.
This flag is ignored if (1) the lock mode of the
lock being dequeued is not protected write or
exclusive, or (2) you specify the LCK$M_CANCEL
flag.
LCK$M_ When you specify this flag, you must provide a
XVALBLK 64-byte lock value block as the valblk argument.
If you do not specify this flag, only the first
16 bytes of the buffer specified in the valblk
argument will be written.
If the value block is written without this flag,
the value block will be flagged so that a future
reader who specifies the LCK$M_XVALBLK flag in the
$ENQ system service call will receive the warning
status SS$_XVALNOTVALID until a future writer
writes to the value block specifying this flag.
This flag is valid only on Alpha and Integrity
server systems.