 |
OpenVMS System Services Reference Manual
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:
- A request for a new lock
- A request to convert an existing lock
When canceling a new lock request, the following action is taken:
- 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:
- 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.
- 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_INVVALBLK
|
When you specify this flag, $DEQ marks the lock 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.
|
Description
The Dequeue Lock Request service dequeues (unlocks) granted locks and
waiting lock requests. The calling process must have previously
acquired the lock or queued the lock request by calling the Enqueue
Lock Request ($ENQ) service.
Action taken by the $DEQ service depends on the current state (granted
or waiting) and the type of lock request (new lock or conversion
request) to be dequeued.
When dequeuing a granted lock, the $DEQ service returns the condition
value SS$_NORMAL and the following specific action is taken:
- Any queued blocking ASTs that have not been delivered are removed
from the process's AST queues.
There are two types of waiting requests that can be dequeued:
- A request for a new lock
- A request to convert an existing lock
When dequeuing a new lock request, the $DEQ service returns the
condition value SS$_NORMAL and the following specific action is taken:
- If a completion AST was requested, the completion AST is queued for
delivery with SS$_ABORT stored in the lock status block.
When dequeuing a lock for which there is a conversion request waiting,
the existing lock and its conversion request are dequeued. The $DEQ
service returns the condition value SS$_NORMAL and the following
specific actions are taken:
- If a blocking AST was queued to the process, it is removed from the
process's AST queue.
- If a completion AST was specified by the conversion request, the
completion AST is queued for delivery with SS$_ABORT status stored in
the lock status block that was specified by the conversion request.
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.
If you specify the LCK$M_INVVALBLK flag in the flags
argument and the lock mode of the lock being dequeued is PW or EX, the
lock value block in the lock database is marked as invalid whether or
not a lock value block was specified in the valblk
argument.
The $DEQ, $ENQ, $ENQW, and $GETLKI services together provide the user
interface to the lock management facility. For additional information
about lock management, refer to the descriptions of these other
services and to the OpenVMS Programming Concepts Manual.
Required Access or Privileges
None
Required Quota
None
Related Services
$ENQ, $ENQW, $GETLKI, $GETLKIW
Condition Values Returned
|
SS$_NORMAL
|
The lock was dequeued successfully.
|
|
SS$_ACCVIO
|
The value block specified by the
valblk argument cannot be accessed by the caller.
|
|
SS$_CANCELGRANT
|
The LCK$M_CANCEL flag in the
flags argument was specified, but the lock request
that $DEQ was to cancel had already been granted.
|
|
SS$_ILLRSDM
|
An illegal attempt to modify a value block was made.
|
|
SS$_IVLOCKID
|
An invalid or nonexistent lock identification was specified or the
process does not have the privilege to dequeue a lock at the specified
access mode.
|
|
SS$_SUBLOCKS
|
The lock has sublocks and cannot be dequeued.
|
$DEVICE_PATH_SCAN
Returns the displayable pathname for a given I/O channel or device
name. Can be used to return all displayable paths to an I/O device.
Format
SYS$DEVICE_PATH_SCAN [chan] [,devnam] ,itmlst [,contxt] [,nullarg]
C Prototype
int sys$device_path_scan (unsigned short int chan, void *devnam, void
*itmlst, unsigned int *contxt, struct_generic_64 *nullarg);
Arguments
chan
| OpenVMS usage: |
channel |
| type: |
word (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Number of the I/O channel assigned to the device about which
information is desired. The chan argument is a word
containing this number.
To identify a device to $DEVICE_PATH_SCAN, you can specify either the
chan or devnam parameters, but you
should not specify both. If you specify both arguments, the
chan argument is used.
If you specify neither chan nor
devnam, $DEVICE_PATH_SCAN uses a default value of 0
for chan.
devnam
| OpenVMS usage: |
device_name |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
The name of the device about which $DEVICE_PATH_SCAN is to return path
information. The devnam argument is the address of a
character string descriptor pointing to this name string.
The device name string can be either a physical device name or a
logical name. If the first character in the string is an underscore
(_), the string is considered a physical device name; otherwise, the
string is considered a logical name and logical name translation is
performed until either a physical device name is found or the system
default number of translations has been performed.
If the device name string contains a colon (:), the colon and the
characters that follow it are ignored.
To identify a device to $DEVICE_PATH_SCAN, you can specify either the
chan or devnam argument, but you
should not specify both. If both arguments are specified, the
chan argument is used.
If you specify neither chan nor
devnam, $DEVICE_PATH_SCAN uses a default value of 0
for chan.
itmlst
| OpenVMS usage: |
item_list_3 |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Item list specifying which information about the device is to be
returned. The itmlst argument is the address of a list
of item descriptors, each of which describes an item of information.
The list of item descriptors is terminated by a longword of 0. The
following diagram depicts the format of a single item descriptor:
See the itmlst argument in the $GETDVI system service
description for information on the meaning of these fields in the item
list.
contxt
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Value used to indicate the current position of a $DEVICE_PATH_SCAN
search. The contxt argument is the address of the
longword that receives this information. On the initial call, the
longword should contain 0.
nullarg
| OpenVMS usage: |
null_arg |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Placeholding argument reserved to Compaq.
Item Code
DPS$_MP_PATHNAME
When you specify DPS$_MP_PATHNAME, $DEVICE_PATH_SCAN returns the name
of one of the Multipath I/O paths connecting to the device named in the
devnam argument. When the value of the
contxt argument is 0, the path name for the first
established path will be returned. On subsequent calls, with a non-zero
contxt value, the path names of the remaining
available paths to the device will be returned.
In the item code, the Buffer Address field must point to the buffer
that will hold the path name to be returned by the service. The Return
Length Address field must be point to the buffer that will hold the
return length returned by the service.
Upon completion of the command, the buffer pointed to by the Buffer
Address field will hold a string identifying the requested path name.
The Return Length Address field will point to the length in bytes of
the path name being returned. The bytes in the path name buffer beyond
the end of the path string will remain in the state they were set by
the caller of the service.
The DPSDEF macro contains this item code.
Description
The Scan for Device Paths service returns I/O path information for a
given I/O channel or device name. Each call to $DEVICE_PATH_SCAN will
return information on a different I/O path connecting with the device
specified in the chan or devnam
arguments.
If the contxt argument is handled appropriately, the
service will return information on the paths in the order in which they
were established. On the first call, the contxt
argument should be set to zero. The contxt value will
be changed by the service during this call and a new value will be
written into contxt and returned to the caller. The
caller must use this same value in the next call to the service.
Following this convention will result in a different path name being
returned on each call.
Once the service has returned information on all paths to the named
device, any further calls that use the final contxt
value will result in SS$_NOMOREPATH status being returned.
Required Access or Privileges
None
Required Quota
None.
Related Services
$ASSIGN, $DASSGN, $DEVICE_SCAN, $GETDVI, $GETDVIW, $SET_DEVICE
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The device name string descriptor, device name string, or
itmlst argument cannot be read; or the buffer or
return length longword cannot be written.
|
|
SS$_BADPARAM
|
The item list contains an invalid item code, or the buffer length field
in an item descriptor specified insufficient space for the return
length information.
|
|
SS$_IVCHAN
|
You specified an invalid channel number, that is, a channel number
larger than the number of channels.
|
|
SS$_IVDEVNAM
|
The device name string contains invalid characters, or neither the
devnam nor
chan argument was specified.
|
|
SS$_NOPRIV
|
The specified channel is not assigned or was assigned from a more
privileged access mode.
|
|
SS$_NOMOREPATH
|
No more device paths exist for this device.
|
|
SS$_NOSUCHDEV
|
The specified device does not exist on the host system.
|
$DEVICE_SCAN
Returns the names of all devices that match a specified set of search
criteria.
Format
SYS$DEVICE_SCAN return_devnam ,retlen ,[search_devnam] ,[itmlst]
,[contxt]
C Prototype
int sys$device_scan (void *return_devnam, unsigned short int *retlen,
void *search_devnam, void *itmlst, struct _generic_64 *contxt);
Arguments
return_devnam
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
write only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Buffer to receive the device name. The return_devnam
argument is the address of a character string descriptor pointing to a
buffer into which $DEVICE_SCAN writes the name of the first or next
device that matches the specified search criteria. The maximum size of
any device name is 64 bytes.
retlen
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Length of the device name string returned by $DEVICE_SCAN. The
retlen argument is the address of a word into which
$DEVICE_SCAN writes the length of the device name string.
search_devnam
| OpenVMS usage: |
device_name |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Name of the device for which $DEVICE_SCAN is to search. The
search_devnam argument accepts the standard wildcard
characters, the asterisk (*), which matches any sequence of characters,
and the percent sign (%), which matches any one character. If the
search_devnam argument does not include a wildcard
character, an exact match is used for comparison. For example, to match
all unit 0 DU devices on any controller, specify
*DU%0. This string is compared to the most complete device
name (DVI$_ALLDEVNAM). Only uppercase characters are accepted.
itmlst
| OpenVMS usage: |
item_list_3 |
| type: |
longword_unsigned |
| access: |
read only |
| mechanism: |
by reference |
Item list specifying search criteria used to identify the device names
for return by $DEVICE_SCAN. The itmlst argument is the
address of a list of item descriptors, each of which describes one
search criterion. The list of item descriptors is terminated by a
longword of 0.
The following diagram depicts the format of a single item descriptor:
The following table defines the item descriptor fields:
| Descriptor Field |
Definition |
|
Buffer length
|
A word containing a user-supplied integer specifying the length (in
bytes) of the longword from which $DEVICE_SCAN is to read the
information. The length of the buffer needed depends on the item code
specified in the item code field of the item descriptor.
|
|
Item code
|
A word containing a user-specified symbolic code specifying the item of
information that $DEVICE_SCAN is to return. The $DVSDEF macro defines
these codes. Each item code is described in the Item Codes section.
|
|
Buffer address
|
A longword containing the address of a longword value that contains
item code information. Examples include DC$_DISK and DC$_MAILBOX.
|
|
Return length address
|
A longword containing the address of a word to receive the length (in
bytes) of information returned for the output value item code.
For the input value item code, this field is not used. Compaq
recommends the placeholder value be 0.
|
contxt
| OpenVMS usage: |
quadword_unsigned |
| type: |
quadword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Value used to indicate the current position of a $DEVICE_SCAN search.
The contxt argument is the address of the quadword
that receives this information. On the initial call, the quadword
should contain 0.
Item Codes
DVS$_DEVCLASS
An input value item code that specifies, as an unsigned longword, the
device class being searched. The $DCDEF macro defines these classes.
The DVS$_DEVCLASS argument is a longword containing this number;
however, DVS$_DEVCLASS uses only the low-order byte of the longword.
DVS$_DEVTYPE
An input value item code that specifies, as an unsigned longword, the
device type for which $DEVICE_SCAN is going to search. The $DCDEF macro
defines these types.
The DVS$_DEVTYPE argument is a longword containing this number;
however, DVS$_DEVTYPE uses only the low-order byte of the longword.
DVS$_DEVTYPE should be used in conjunction with $DVS_DEVCLASS to
specify the device type being searched for.
Description
The Scan for Devices system service returns the names of all devices
that match a specified set of search criteria. The names returned by
$DEVICE_SCAN can then be passed to another service; for example,
$GETDVI or $MOUNT.
The device names are returned for one process per call. A context value
is used to continue multiple calls to $DEVICE_SCAN.
$DEVICE_SCAN allows wildcard searches based on device names, device
classes, and device types. It also provides the ability to perform a
wildcard search on other device-related services.
$DEVICE_SCAN makes it possible to combine search criteria. For example,
to find only RA82 devices, use the following selection criteria:
DVS$_DEVCLASS = DC$_DISK and DVS$_DEVTYPE = DT$_RA82
|
To find all mailboxes with MB as part of the device name
(excluding mailboxes such as NLA0), use the following selection
criteria:
DVS$_DEVCLASS = DC$_MAILBOX and DEVNAM = *MB*
|
Required Access or Privileges
None
Required Quota
None
Related Services
$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC,
$DASSGN, $DELMBX, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUI,
$GETQUIW, $INIT_VOL, $MOUNT, $PUTMSG, $QIO, $QIOW, $SNDERR, $SNDJBC,
$SNDJBCW, $SNDOPR
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The
search_devnam,
itmlst, or
contxt argument cannot be read by the caller, or the
retlen,
return_devnam, or
contxt argument cannot be written by the caller.
|
|
SS$_BADPARAM
|
The
contxt argument contains an invalid value, or the item
list contains an invalid item code.
|
|
SS$_NOMOREDEV
|
No more devices match the specified search criteria.
|
|
SS$_NOSUCHDEV
|
The specified device does not exist on the host system.
|
|
