VMS Help System Services, $DEQ  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    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 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 (Alpha)
    mechanism:    by 32-bit reference (VAX)
    Lock value block for the resource associated with the lock to be
    dequeued. The valblk argument is the 32- or 64-bit address (on
    Alpha systems) or the 32-bit (on VAX systems) of the 16-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. Refer to the description of the
                   lkid argument for details. The acmode argument is
                   ignored if the LCK$M_DQALL 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.