 |
HP OpenVMS System Services Reference Manual
The buffer length field in the item descriptor should specify 4 (bytes).
LKI$_CVTCOUNT
Returns the total number of locks that are currently on the conversion
queue of the resource associated with the lock. These locks are granted
at one mode and are waiting to be converted to another.
The buffer length field in the item descriptor should specify 4 (bytes).
LKI$_GRANTCOUNT
Returns the total number of locks that are currently on the grant queue
of the resource associated with the lock. Note that the total number of
granted locks on the resource is equal to the sum of LKI$_CVTCOUNT and
LKI$_GRANTCOUNT.
The buffer length field in the item descriptor should specify 4 (bytes).
LKI$_LCKREFCNT
Returns the number of locks that have this lock as a parent lock. When
these locks were created, the parid argument in the
call to $ENQ or $ENQW specified the lock ID of this lock.
The buffer length field in the item descriptor should specify 4 (bytes).
LKI$_LKID
Returns the lock ID of the lock on the system where the process owning
the lock resides. The lock ID returned by this item code is meaningful
only on the system specified in the value returned by the LKI$_CSID
item code.
The buffer length field in the item descriptor should specify 4 (bytes).
LKI$_LOCKID
Returns the lock ID of the current lock. The current lock is the one
specified by the lkidadr argument unless
lkidadr is specified as --1 or 0, which indicates a
wildcard operation. Thus, this item code is usually specified only in
wildcard operations where it is useful to know the lock IDs of the
locks that $GETLKI has discovered in the wildcard operation.
The lock ID is a longword value, so the buffer length field in the item
descriptor should specify 4 (bytes).
LKI$_LOCKS
Returns information about all locks on the resource associated with the
lock specified by lkidadr.
The $LKIDEF macro defines the following symbolic names that refer to
the eight items in the buffer:
| Symbolic Name |
Description |
|
LKI$L_MSTLKID
|
Lock ID of the blocked lock on the system maintaining the resource (4
bytes)
|
|
LKI$L_PID
|
Process ID (PID) of the process that took out the lock (4 bytes)
|
|
LKI$L_MSTCSID
|
OpenVMS Cluster system identifier (CSID) of the node maintaining the
resource that is locked by the lock (4 bytes)
|
|
LKI$B_RQMODE
|
Lock mode requested for the lock; this lock mode was specified by the
lkmode argument in the call to $ENQ (1 byte)
|
|
LKI$B_GRMODE
|
Lock mode granted to the lock; this lock mode is written to the lock
value block (1 byte)
|
|
LKI$B_QUEUE
|
Name of the queue on which the lock currently resides (1 byte)
|
|
LKI$L_LKID
|
Lock ID of the lock on the system where the lock was requested (4 bytes)
|
|
LKI$L_CSID
|
OpenVMS Cluster system identifier (CSID) of the system where the lock
was requested (4 bytes)
|
The values that $GETLKI can write into the LKI$B_RQMODE, LKI$B_GRMODE,
and LKI$B_QUEUE items have symbolic names; these symbolic names specify
the six lock modes and the three types of queue in which a lock can
reside. The Description section describes these names.
Thus, the buffer specified by the buffer address field in the item
descriptor will contain the eight items of information, repeated in
sequence, for each lock.
The length of the information returned for each lock is returned in
bits 16 to 30 of the longword specified by the return length address
field in the item descriptor, while the total length of information
returned for all locks is returned in bits 0 to 15. Therefore, to
determine the number of locks, you divide the value of bits 16 to 30
into the value of bits 0 to 15.
LKI$_MSTCSID
Returns the Cluster System ID (CSID) of the node currently mastering
the resource that is associated with the specified lock. Although the
resource can be locked by processes on any node in the cluster, the
resource itself is maintained on a single node. You can use the DCL
command SHOW CLUSTER or the $GETSYI service to determine which node in
the OpenVMS Cluster is identified by the CSID that $GETLKI returns.
Because the processor mastering the lock can change at any time,
multiple calls to $GETLKI for the same lock can produce different
values for this item code. LKI$_MSTCSID returns the CSID of the node
where the $GETLKI system service is issued when the resource is
mastered on that node. When the processor where the $GETLKI was issued
is not part of an OpenVMS Cluster, this item code returns 0.
The buffer length field in the item descriptor should specify 4 (bytes).
LKI$_MSTLKID
Returns the lock ID for the current master copy of the lock. Although
the resource can be locked by processes on any node in the cluster, the
resource itself is maintained on a single node. Because lock IDs are
unique to each processor on a cluster, the lock ID returned by this
item code has meaning only on the processor that is specified in the
value returned by the LKI$_MSTCSID item code.
Because the processor mastering the lock can change at any time,
multiple calls to $GETLKI for the same lock can produce different
values for this item code. When the lock is mastered on the node where
the $GETLKI system service is issued, or when the node is not a member
of a cluster, this item code returns the same information as LKI$_LKID.
The buffer length field in the item descriptor should specify 4 (bytes).
LKI$_NAMSPACE
Returns information about the resource name space. This information is
contained in a longword consisting of four bit fields; therefore, the
buffer length field in the item descriptor should specify 4 (bytes).
Each of the four bit fields can be referred to by its symbolic name;
the $LKIDEF macro defines the symbolic names. The following table
lists, in order, the symbolic name of each bit field:
| Symbolic Name |
Description |
|
LKI$W_GROUP
|
In this field (bits 0 to 15), $GETLKI writes the UIC group number of
the process that took out the first lock on the resource, thereby
creating the resource name. This process issued a call to $ENQ or $ENQW
specifying the name of the resource in the
resnam argument.
However, if this process specified the LCK$_SYSTEM flag in the call
to $ENQ or $ENQW, the resource name is systemwide. In this case, the
UIC group number of the process is not associated with the resource
name.
Consequently, this field (bits 0 to 15) is significant only if the
resource name is not systemwide. $GETLKI sets bit 31 if the resource
name is systemwide.
|
|
LKI$B_RMOD
|
In this field (bits 16 to 23), $GETLKI writes the access mode
associated with the first lock taken out on the resource.
|
|
LKI$B_STATUS
|
This field (bits 24 to 30) is not used. $GETLKI sets it to 0.
|
|
LKI$V_SYSNAM
|
This field (bit 31) indicates whether the resource name is systemwide.
$GETLKI sets this bit if the resource name is systemwide and clears it
if the resource name is qualified by the creating process's UIC group
number. The state of this bit determines the interpretation of bits 0
to 15.
|
LKI$_PARENT
Returns the lock ID of the parent lock for the lock, if a parent lock
was specified in the call to $ENQ or $ENQW. If the lock does not have a
parent lock, $GETLKI returns the value 0.
Because the parent lock ID is a longword, the buffer length field in
the item descriptor should specify 4 (bytes).
LKI$_PID
Returns the process identification (process ID) of the process that
owns the lock.
The process ID is a longword value, so the buffer length field in the
item descriptor should specify 4 (bytes).
LKI$_RESNAM
Returns the resource name string and its length, which must be from 1
to 31 bytes. The resource name string was specified in the
resnam argument in the initial call to $ENQ or $ENQW.
The $GETLKI service returns the length of the string in the return
length address field in the item descriptor. However, in the call to
$GETLKI, you do not know how long the string is; therefore, to avoid
buffer overflow, you should specify the maximum length (31 bytes) in
the buffer length field in the item descriptor.
LKI$_RSBREFCNT
Returns the number of subresources of the resource associated with the
lock. A subresource has the resource as a parent resource. Note,
however, that the number of subresources can differ from the number of
sublocks of the lock, because any number of processes can lock the
resource. If any of these processes then locks another resource, and in
doing so specifies the lock ID of the lock on the first resource as a
parent lock, then the second resource becomes a subresource of the
first resource.
Thus, the number of sublocks on a lock is limited to the number of
sublocks that a single process takes out, whereas the number of
subresources on a resource is determined by (potentially) multiple
processes.
The subresource reference count is a longword value, so the buffer
length field in the item descriptor should specify 4 (bytes).
LKI$_STATE
Returns the current state of the lock. The current state of the lock is
described by the following three 1-byte items (in the order specified):
(1) the lock mode requested (in the call to $ENQ or $ENQW) for the
lock, (2) the lock mode granted (by $ENQ or $ENQW) for the lock, and
(3) the name of the queue on which the lock currently resides.
The buffer length field in the item descriptor should
specify 3 (bytes). The $LKIDEF macro defines the following symbolic
names that refer to the three 1-byte items in the buffer.
| Symbolic Name |
Description |
|
LKI$B_STATE_RQMODE
|
Lock mode requested
|
|
LKI$B_STATE_GRMODE
|
Lock mode granted
|
|
LKI$B_STATE_QUEUE
|
Name of queue on which the lock resides
|
The values that $GETLKI can write into each 1-byte item have symbolic
names; these symbolic names specify the six lock modes and the three
types of queue in which a lock can reside. The Description section
describes these names.
LKI$_VALBLK
Returns the first 16 bytes of the lock value block of the locked
resource. This lock value block is the master copy that the lock
manager maintains for the resource, not the process-private copy.
The buffer length field in the item descriptor should specify 16.
LKI$_XVALBLK - Alpha and I64
Returns the entire 64 bytes of the lock value block of the locked
resource. This lock value block is the master copy that the lock
manager maintains for the resource, not the process-private copy.
The buffer length field in the item descriptor should specify 64.
LKI$_XVALNOTVALID - Alpha and I64
Returns a longword value of either zero or one:
- Zero (0) indicates that the extended value block is valid.
- One (1) indicates that the previous writer did not specify the
LCK$M_XVALBLK flag and wrote only the first 16 bytes.
The buffer length field in the item descriptor should specify 4 (bytes).
LKI$_WAITCOUNT
Returns the total number of locks that are currently on the wait queue
of the resource associated with the lock. These locks are waiting to be
granted.
The buffer length field in the item descriptor should specify 4 (bytes).
Description
The Get Lock Information service returns information about the lock
database on a system.
The access mode of the calling process must be equal to or more
privileged than the access mode at which the lock was initially granted.
When locking on a resource is clusterwide, a single master copy of the
resource is maintained on the node that owns the process that created
the resource by taking out the first lock on it. When a process on
another node locks that same resource, a local copy of the resource is
copied to the node and the lock is identified by a lock ID that is
unique to that node.
In a cluster environment, however, you cannot use $GETLKI to obtain
directly information about locks on other nodes in the cluster; that
is, you cannot specify in a call to $GETLKI the lock ID of a lock held
by a process on another node. The $GETLKI service interprets the
lkidadr argument as the lock ID of a lock on the
caller's node, even though the resource associated with a lock might
have its master copy on the caller's node.
However, because a process on another node in the cluster can have a
lock on the same resource as the caller of $GETLKI, the caller, in
obtaining information about the resource, can indirectly obtain some
information about locks on the resource that are held by processes on
other nodes. One example of information indirectly obtained about a
resource is the contents of lock queues; these queues contain
information about all locks on the resource, and some of these locks
can be held by processes on other nodes.
Another example of information more directly obtained is the remote
lock ID of a lock held by a process on another node. Specifically, if
the caller of $GETLKI on node A specifies a lock (by means of
lkidadr) and that lock is held by a process on node B,
$GETLKI returns the lock ID of the lock from node B's lock database if
the LKI$_REMLKID item code is specified in the call.
Item codes LKI$_BLOCKEDBY, LKI$_BLOCKING, LKI$_LOCKS, and LKI$_STATE
specify that $GETLKI return various items of information; some of these
items are the names of lock modes or the names of lock queues.
The $LCKDEF macro defines the following symbolic names:
| Symbolic Name |
Lock Mode |
|
LCK$K_NLMODE
|
Null mode
|
|
LCK$K_CRMODE
|
Concurrent read mode
|
|
LCK$K_CWMODE
|
Concurrent write mode
|
|
LCK$K_PRMODE
|
Protected read mode
|
|
LCK$K_PWMODE
|
Protected write mode
|
|
LCK$K_EXMODE
|
Exclusive mode
|
| Symbolic Name |
Queue Name |
|
LKI$C_GRANTED
|
Granted queue, holding locks that have been granted
|
|
LKI$C_CONVERT
|
Converting queue, holding locks that are currently being converted to
another lock mode
|
|
LKI$C_WAITING
|
Waiting queue, holding locks that are neither granted nor converting
(for example, a blocked lock)
|
Required Access or Privileges
Depending on the operation, the calling process might need one of the
following privileges to use $GETLKI:
- For locks held by other processes, you need to have joined the
resource domain for lock access or hold WORLD privileges.
You need
WORLD privilege to obtain information about locks held by processes in
other groups.
- To obtain information about system locks, either you need SYSLCK
privilege or the process must be executing in executive or kernel
access mode.
To establish a default resource domain, it is necessary to have
performed either a call to $SET_RESOURCE_DOMAIN or a previous call to
$ENQ[W].
Required Quota
The caller must have sufficient ASTLM or BYTLM quota.
Related Services
$DEQ, $ENQ, $ENQW, $GETLKIW, $SET_RESOURCE_DOMAIN
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The item list cannot be read; the areas specified by the buffer address
and return length address fields in the item descriptor cannot be
written; or the location specified by the
lkidadr argument cannot be written.
|
|
SS$_BADPARAM
|
You specified an invalid item code.
|
|
SS$_EXQUOTA
|
The caller has insufficient ASTLM or BYTLM quota.
|
|
SS$_ILLRSDM
|
The operation attempted is not allowed on the resource. Use SHOW
SECURITY to verify the access allowed to the specified resource domain.
|
|
SS$_INSFMEM
|
The nonpaged dynamic memory is insufficient for the operation.
|
|
SS$_IVLOCKID
|
The
lkidadr argument specified an invalid lock ID.
|
|
SS$_IVMODE
|
A more privileged access mode is required.
|
|
SS$_NOMORELOCK
|
The caller requested a wildcard operation by specifying a value of 0 or
--1 for the
lkidadr argument, and $GETLKI has exhausted the locks
about which it can return information to the caller; or no
lkidadr argument is specified. This is an alternate
success status.
|
|
SS$_NOSYSLCK
|
The caller attempted to acquire information about a systemwide lock and
did not have the required SYSLCK privilege.
|
|
SS$_NOWORLD
|
The caller attempted to acquire information about a lock held by a
process in another group and did not have the required WORLD privilege.
|
Condition Values Returned in the I/O Status Block
Same as those returned in R0.
$GETLKIW
Returns information about the lock database on a system.
The $GETLKIW service completes synchronously; that is, it returns to
the caller with the requested information.
For asynchronous completion, use the Get Lock Information ($GETLKI)
service; $GETLKI returns to the caller after queuing the information
request, without waiting for the information to be returned.
In all other respects, $GETLKIW is identical to $GETLKI. For all other
information about the $GETLKIW service, refer to the description of
$GETLKI in this manual.
The $GETLKI, $GETLKIW, $ENQ, $ENQW, and $DEQ services together provide
the user interface to the Lock Management facility. Refer to the
descriptions of these other services for additional information about
lock management.
Format
SYS$GETLKIW [efn] ,lkidadr ,itmlst [,iosb] [,astadr] [,astprm]
[,nullarg]
C Prototype
int sys$getlkiw (unsigned int efn, unsigned int *lkidadr, void *itmlst,
struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm,
unsigned int reserved);
$GETMSG
Returns message text associated with a given message identification
code into the caller's buffer. The message can be from the system
message file or a user-defined message.
On Alpha and I64 systems, this service accepts 64-bit addresses.
Format
SYS$GETMSG msgid ,msglen ,bufadr ,[flags] ,[outadr]
C Prototype
int sys$getmsg (unsigned int msgid, unsigned short int *msglen, void
*bufadr, unsigned int flags, unsigned char outadr [4]);
Arguments
msgid
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Identification of the message to be retrieved. The
msgid argument is a longword value containing the
message identification. Each message has a unique identification,
contained in bits 3 through 27 of system longword condition values.
msglen
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference (Alpha and I64) |
| mechanism: |
by 32-bit reference (VAX) |
Length of the message string returned by $GETMSG. The
msglen argument is the 32- or 64-bit address (on Alpha
and I64 systems) or the 32-bit address (on VAX systems) of a word into
which $GETMSG writes this length.
bufadr
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
write only |
| mechanism: |
by 32- or 64-bit descriptor--fixed-length string descriptor
(Alpha and I64) |
| mechanism: |
by 32-bit descriptor--fixed-length string descriptor
(VAX) |
Buffer to receive the message string. The bufadr
argument is the 32- or 64-bit address (on Alpha and I64 systems) or the
32-bit address (on VAX systems) of a character string descriptor
pointing to the buffer into which $GETMSG writes the message string.
The maximum size of any message string is 256 bytes.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Message components to be returned. The flags argument
is a longword bit vector wherein a bit, when set, specifies that the
message component is to be returned.
The following table describes the significant bits:
| Bit |
Value |
Description |
|
0
|
1
|
Include text of message
|
|
|
0
|
Do not include text of message
|
|
1
|
1
|
Include message identifier
|
|
|
0
|
Do not include message identifier
|
|
2
|
1
|
Include severity indicator
|
|
|
0
|
Do not include severity indicator
|
|
3
|
1
|
Include facility name
|
|
|
0
|
Do not include facility name
|
If you omit this argument in a VAX MACRO or BLISS-32 service call, it
defaults to a value of 15; that is, all flags are set and all
components of the message are returned. If you omit this argument in a
Fortran service call, it defaults to a value of 0; the value 0 causes
$GETMSG to use the process default flags.
outadr
| OpenVMS usage: |
vector_byte_unsigned |
| type: |
byte (unsigned) |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference (Alpha and I64) |
| mechanism: |
by 32-bit reference (VAX) |
Optional information to be returned by $GETMSG. The
outadr argument is the 32- or 64-bit address (on Alpha
and I64 systems) or the 32-bit address (on VAX systems) of a 4-byte
array into which $GETMSG writes the following information:
| Byte |
Contents |
|
0
|
Reserved
|
|
1
|
Count of FAO arguments associated with message
|
|
2
|
User-specified value in message, if any
|
|
3
|
Reserved
|
Description
The Get Message service locates and returns message text associated
with a given message identification code into the caller's buffer. The
message can be from the system message file or a user-defined message.
The operating system uses this service to retrieve messages based on
unique message identifications and to prepare to output the messages.
The message identifications correspond to the symbolic names for
condition values returned by system components; for example, SS$_code
from system services, RMS$_code for RMS messages, and so on.
When you set all bits in the flags argument, $GETMSG
returns a string in the following format:
facility-severity-ident, message-text
|
where:
|
facility
|
Identifies the component of the operating system
|
|
severity
|
Is the severity code (the low-order three bits of the condition value)
|
|
ident
|
Is the unique message identifier
|
|
message-text
|
Is the text of the message
|
For example, if you specify the MSGID=#SS$_DUPLNAM argument, the
$GETMSG service returns the following string:
%SYSTEM-F-DUPLNAM, duplicate process name
|
You can define your own messages with the Message utility. See the
HP OpenVMS System Management Utilities Reference Manual for additional information.
The message text associated with a particular 32-bit message
identification can be retrieved from one of several places. This
service takes the following steps to locate the message text:
- All message sections linked into the currently executing image are
searched for the associated information.
- If the information is not found, the process-permanent message file
is searched. (You can specify the process-permanent message file by
using the SET MESSAGE command.)
- If the information is not found, the systemwide message file is
searched.
- If the information is not found, the SS$_MSGNOTFND condition value
is returned in R0 and a message in the following form is returned to
the caller's buffer:
|
