| Previous | Contents | Index |
The buffer length field in the item descriptor should specify 4 (bytes).
The buffer length field in the item descriptor should specify 4 (bytes).
The buffer length field in the item descriptor should specify 4 (bytes).
The buffer length field in the item descriptor should specify 4 (bytes).
The buffer length field in the item descriptor should specify 4 (bytes).
The lock ID is a longword value, so the buffer length field in the item descriptor should specify 4 (bytes).
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.
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).
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).
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. |
Because the parent lock ID is a longword, the buffer length field in the item descriptor should specify 4 (bytes).
The process ID is a longword value, so the buffer length field in the item descriptor should specify 4 (bytes).
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.
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).
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.
The buffer length field in the item descriptor should specify 16.
The buffer length field in the item descriptor should specify 64.
The buffer length field in the item descriptor should specify 4 (bytes).
The buffer length field in the item descriptor should specify 4 (bytes).
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) 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].
The caller must have sufficient ASTLM or BYTLM quota.
$DEQ, $ENQ, $ENQW, $GETLKIW, $SET_RESOURCE_DOMAIN
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.
Same as those returned in R0.
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, see 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. For additional information about lock management, see the descriptions of these other services.
SYS$GETLKIW [efn] ,lkidadr ,itmlst [,iosb] [,astadr] [,astprm] [,nullarg]
int sys$getlkiw (unsigned int efn, unsigned int *lkidadr, void *itmlst, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm, unsigned int reserved);
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 Integrity server systems, this service accepts 64-bit addresses.
SYS$GETMSG msgid ,msglen ,bufadr ,[flags] ,[outadr]
int sys$getmsg (unsigned int msgid, unsigned short int *msglen, void *bufadr, unsigned int flags, unsigned char outadr [4]);
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
Length of the message string returned by $GETMSG. The msglen argument is the 32- or 64-bit address 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
Buffer to receive the message string. The bufadr argument is the 32- or 64-bit address 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
Optional information to be returned by $GETMSG. The outadr argument is the 32- or 64-bit address 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
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 nameYou 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:
Previous Next Contents Index