HP OpenVMS System Services Reference Manual

$GETJPIW

Returns information about one or more processes on the system.
The $GETJPIW service completes synchronously; that is, it returns to the caller with the requested information. HP recommends that you use an IOSB with this service. An IOSB prevents the service from completing prematurely. In addition, the IOSB contains status information.
For asynchronous completion, use the Get Job/Process Information ($GETJPI) service; $GETJPI returns to the caller after queuing the information request, without waiting for the information to be returned.
In all other respects, $GETJPIW is identical to $GETJPI. For all other information about the $GETJPIW service, see the description of $GETJPI in this manual.
On Alpha and I64 systems, this service accepts 64-bit addresses.

Format

SYS$GETJPIW [efn] ,[pidadr] ,[prcnam] ,itmlst ,[iosb] ,[astadr] ,[astprm]

C Prototype

int sys$getjpiw (unsigned int efn, unsigned int *pidadr, void *prcnam, void *itmlst, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm);

$GETLKI

Returns information about the lock database on a system.
The $GETLKI service completes asynchronously; for synchronous completion, use the Get Lock Information and Wait ($GETLKIW) service.
The $GETLKI, $GETLKIW, $ENQ, $ENQW, and $DEQ services together provide the user interface to the Lock Management facility.

Format

SYS$GETLKI [efn] ,lkidadr ,itmlst [,iosb] [,astadr] [,astprm] [,nullarg]

C Prototype

int sys$getlki (unsigned int efn, unsigned int *lkidadr, void *itmlst, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm, unsigned int reserved);

Arguments

efn

OpenVMS usage: ef_number

type: longword (unsigned)

access: read only

mechanism: by value

Number of the event flag to be set when $GETLKI completes. The efn argument is a longword containing this number; however, $GETLKI uses only the low-order byte. If you do not specify efn, $GETLKI sets event flag 0.
HP strongly recommends the use of the EFN$C_ENF "no event flag" value as the event flag if you are not using an event flag to externally synchronize with the completion of this system service call. The $EFNDEF macro defines EFN$C_ENF. For more information, see the HP OpenVMS Programming Concepts Manual.
lkidadr

OpenVMS usage: lock_id

type: longword (unsigned)

access: modify

mechanism: by reference

Lock identification (lock ID) for the lock about which information is to be returned. The lock ID is the second longword in the lock status block, which was created when the lock was granted. The lkidadr argument is the address of this longword.
If the value specified by lkidadr is 0 or --1, $GETLKI assumes a wildcard operation and returns information about each lock to which the calling process has access, one lock per call.
To use the $GETLKI service, you must have read/write access to the lock ID.
itmlst

OpenVMS usage: item_list_3

type: longword (unsigned)

access: read only

mechanism: by reference

Item list specifying the lock information that $GETLKI is to return. 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:

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 buffer in which $GETLKI is to write the information. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor. If the value of the buffer length field is too small, $GETLKI truncates the data and returns the success condition value SS$_NORMAL.

Item code A word containing a user-specified symbolic code specifying the item of information that $GETLKI is to return. The $LKIDEF macro defines these codes. Each item code is described in the list of $GETLKI item codes that follows the argument descriptions.

Buffer address A longword containing a user-supplied address of the buffer in which $GETLKI is to write the information.

Return length address A longword containing the user-supplied address of a longword in which $GETLKI writes return length information. This longword contains the following three bit fields:

Bits 0 to 15 In this field, $GETLKI writes the length in bytes of the data actually written to the buffer specified by the buffer address field in the item descriptor.

Bits 16 to 30 $GETLKI uses this field only when the item code field of the item descriptor specifies LKI$_BLOCKEDBY, LKI$_BLOCKING, or LKI$_LOCKS, each of which requests information about a list of locks. $GETLKI writes in this field the length in bytes of the information returned for a single lock on the list.
You can divide this length into the total length returned for all locks (bits 0 to 15) to determine the number of locks located by that item code request.

Bit 31 $GETLKI sets this bit if the user-supplied buffer length argument specifies too small a buffer to contain the information returned. Note that in such a case, $GETLKI will return the SS$_NORMAL condition value in R0. Therefore, to locate any faulty item descriptor, you need to check the state of bit 31 in the longword specified by the return length field of each item descriptor.

iosb

OpenVMS usage:	io_status_block
type:	quadword (unsigned)
access:	write only
mechanism:	by reference

I/O status block that is to receive the final completion status. The iosb argument is the address of a quadword.

When $GETLKI is called, it sets the I/O status block to 0. When $GETLKI completes, it writes a condition value to the first longword in the quadword. The remaining two words in the quadword are unused.

Although this argument is optional, HP strongly recommends that you specify it, for the following reasons:

If you are using an event flag to signal the completion of the service, you can test the I/O status block for a condition value to be sure that the event flag was not set by an event other than service completion.
If you are using the $SYNCH service to synchronize completion of the service, the I/O status block is a required argument for $SYNCH.
The condition value returned in R0 and the condition value returned in the I/O status block provide information about different aspects of the call to the $GETLKI service. The condition value returned in R0 gives you information about the success or failure of the service call itself; the condition value returned in the I/O status block gives you information about the success or failure of the service operation. Therefore, to accurately assess the success or failure of the call to $GETLKI, you must check the condition values returned in both R0 and the I/O status block.

astadr

OpenVMS usage:	ast_procedure
type:	procedure value
access:	call without stack unwinding
mechanism:	by reference

AST service routine to be executed when the service completes. The astadr argument is the address of this routine.

If you specify this argument, the AST routine executes at the same access mode as the caller of the $GETLKI service.

astprm

OpenVMS usage:	user_arg
type:	longword (unsigned)
access:	read only
mechanism:	by value

AST parameter to be passed to the AST service routine specified by the astadr argument. The astprm argument is the longword parameter.

nullarg

OpenVMS usage:	null_arg
type:	longword (unsigned)
access:	read only
mechanism:	by value

Placeholding argument reserved by HP.

Item Codes

LKI$_BLOCKEDBY
Returns information about all locks that are currently blocked by the lock specified by lkidadr. The $GETLKI service returns eight items of information about each blocked lock.
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 blocking lock on the system maintaining the resource (4 bytes)

LKI$L_PID Process ID (PID) of the process that took out the blocked lock (4 bytes)

LKI$L_MSTCSID OpenVMS Cluster system identifier (CSID) of the node maintaining the resource that is locked by the blocked lock (4 bytes)

LKI$B_RQMODE Lock mode requested for the blocked 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 blocked lock; this lock mode is written to the lock value block (1 byte)

LKI$B_QUEUE Name of the queue on which the blocked 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 blocked lock.
The length of the information returned for each blocked 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 blocked locks is returned in bits 0 to 15. Therefore, to determine the number of blocked locks, you divide the value of bits 16 to 30 into the value of bits 0 to 15.
LKI$_BLOCKING
Returns information about all locks that are currently blocking the lock specified by lkidadr. The $GETLKI service returns eight items of information about each blocking lock.
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 blocking lock (4 bytes)

LKI$L_MSTCSID OpenVMS Cluster system identifier (CSID) of the node maintaining the resource that is locked by the blocking lock (4 bytes)

LKI$B_RQMODE Lock mode requested for the blocking 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 blocking lock; this lock mode is written to the lock value block (1 byte)

LKI$B_QUEUE Name of the queue on which the blocking 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 blocking lock.
The length of the information returned for each blocking 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 blocking locks is returned in bits 0 to 15. Therefore, to determine the number of blocking locks, you divide the value of bits 16 to 30 into the value of bits 0 to 15.
LKI$_CSID
Returns the Cluster System ID (CSID) of the system where the process owning the lock resides. LKI$_CSID returns the CSID of the node where the $GETLKI system service is issued when the resource is mastered on that node. When the processor is not part of a cluster, LKI$_CSID returns 0.
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.

Previous Next Contents Index

OpenVMS usage:	ef_number
type:	longword (unsigned)
access:	read only
mechanism:	by value

OpenVMS usage:	lock_id
type:	longword (unsigned)
access:	modify
mechanism:	by reference

OpenVMS usage:	item_list_3
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Symbolic Name	Description
LKI$L_MSTLKID	Lock ID of the blocking lock on the system maintaining the resource (4 bytes)
LKI$L_PID	Process ID (PID) of the process that took out the blocked lock (4 bytes)
LKI$L_MSTCSID	OpenVMS Cluster system identifier (CSID) of the node maintaining the resource that is locked by the blocked lock (4 bytes)
LKI$B_RQMODE	Lock mode requested for the blocked 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 blocked lock; this lock mode is written to the lock value block (1 byte)
LKI$B_QUEUE	Name of the queue on which the blocked 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)

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 blocking lock (4 bytes)
LKI$L_MSTCSID	OpenVMS Cluster system identifier (CSID) of the node maintaining the resource that is locked by the blocking lock (4 bytes)
LKI$B_RQMODE	Lock mode requested for the blocking 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 blocking lock; this lock mode is written to the lock value block (1 byte)
LKI$B_QUEUE	Name of the queue on which the blocking 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)

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.

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