HP OpenVMS System Services Reference Manual


Previous Contents Index

When a process runs a protected subsystem, the subsystem rights are automatically added to the process's image rights list. These identifiers are subsequently removed during image rundown. Allocate a buffer that is sufficient to hold the subsystem rights list, because $GETJPI returns only as much of the list as will fit in the buffer.

JPI$_SUBSYSTEM_RIGHTS_SIZE

On Alpha and Integrity server systems, returns a longword integer containing the number of bytes needed to store the subsystem rights.

JPI$_SWPFILLOC

Returns the location of the process's swapping file, which is a longword hexadecimal value. If the number returned is positive, the fourth byte of this value identifies a specific swapping file, and the lower three bytes contain the VBN within the swapping file. If the number returned is 0 or negative, the swap file location information is not currently available for the process.

JPI$_SYSTEM_RIGHTS

Returns the system rights list as an array of quadword identifiers. Each entry consists of a longword identifier value and longword identifier attributes, listed in Table SYS-42. Allocate a buffer that is sufficient to hold the system rights list because $GETJPI only returns as much of the list as will fit in the buffer.

JPI$_SYSTEM_RIGHTS_SIZE

On Alpha and Integrity server systems, returns a longword integer containing the number of bytes needed to store the system rights.

JPI$_TABLENAME

Returns the file specification of the process's current command language interpreter (CLI) table. Because the file specification can include up to 255 characters, the buffer length field in the item descriptor should specify 255 bytes.

JPI$_TERMINAL

Returns, for interactive users, the process's login terminal name as a character string. Because the terminal name can include up to 16 characters, the buffer length field in the item descriptor should specify at least 16 bytes. Trailing zeros are written to the output buffer if necessary.

JPI$_THREAD_INDEX

On Alpha and Integrity server systems, returns the kernel thread index for the target thread or process, which is a longword integer value.

JPI$_TMBU

Returns the termination mailbox unit number, which is a longword integer value.

JPI$_TQCNT

Returns the remaining timer queue entry quota of the process, which is a longword integer value.

JPI$_TQLM

Returns the process's limit on timer queue entries, which is a longword integer value.

JPI$_TT_ACCPORNAM

Returns the access port name for the terminal associated with the process. (The terminal name is returned by JPI$_TERMINAL.) This item code can return the following information:

JPI$_TT_PHYDEVNAM

Returns the physical device name of the terminal associated with the process. This name is the same as JPI$_TERMINAL unless virtual terminals are enabled, in which case JPI$_TERMINAL returns the name of the virtual terminal and JPI$_TT_PHYDEVNAM returns the name of the physical terminal. If JPI$_TERMINAL is null or if the virtual terminal is disconnected from the physical terminal, JPI$_TT_PHYDEVNAM returns a null string.

JPI$_UAF_FLAGS

Returns the UAF flags from the UAF record of the user who owns the process. The flags are returned as a longword bit vector. For a list of the symbolic names of these flags, see the UAI$_FLAGS item code under the $GETUAI system service.

JPI$_UIC

Returns the UIC of the process in the standard longword format.

JPI$_USERNAME

Returns the user name of the process as a 12-byte string. If the name is less than 12 bytes, $GETJPI fills out the 12 bytes with trailing blanks and always returns 12 as the string length.

JPI$_VIRTPEAK

Returns the peak virtual address size---in pagelets for Alpha or Integrity servers --of the process.

On Alpha and Integrity server systems, the value returned requires a quadword of storage. If the buffer size supplied is not equal to 8 bytes, and the virtual peak exceeds the maximum value that can be represented in a longword, $GETJPI returns the largest positive 32-bit integer: 2147483647.

JPI$_VOLUMES

Returns the number of volumes that the process currently has mounted, which is a longword integer value.

JPI$_WSAUTH

Returns the maximum authorized working set size, in pagelets , of the process. This is a longword integer value.

JPI$_WSAUTHEXT

Returns, in pagelets , the maximum authorized working set extent of the process as a longword integer value.

JPI$_WSEXTENT

Returns, in pagelets , the current working set extent of the process as a longword integer value.

JPI$_WSPEAK

Returns, in pagelets , the peak working set size of the process as a longword integer value.

JPI$_WSQUOTA

Returns, in pagelets , the working set size quota of the process as a longword integer value.

JPI$_WSSIZE

Returns, in pagelets , the current working set limit of the process as a longword integer value.

Description

The Get Job/Process Information service returns information about one or more processes on the system or across the cluster. Using $GETJPI with $PROCESS_SCAN, you can perform selective or clusterwide searches.

Getting information about another process is an asynchronous operation because the information might be contained in the virtual address space of the target process, and that process might be running at a lower priority, be outswapped, or be suspended in a miscellaneous or resource wait state. To allow your program to overlap other functions with the time needed to access the data in the other process, $GETJPI returns immediately after it has queued its information-gathering request to the other process. You can use the JPI$_GETJPI item code to control the processing of the $GETJPI call and the information-gathering interprocess request itself.

When performing an asynchronous system service call such as $GETJPI, the specifications of the iosb argument and a unique event flag are used in conjunction with mechanisms such as the $SYNCH system service to synchronize the final completion of the asynchronous system service call.

Required Access or Privileges

The calling process must have GROUP privilege to obtain information about other processes with the same group UIC number as the calling process. The calling process must have WORLD privilege to obtain information about other processes on the system that are not in the same group as the calling process.

Using prcnam and pidadr Arguments

Most process control services accept the prcnam or the pidadr argument or both. However, you should identify a process by its process identification number for the following reasons:

If you specify the PID address, the service uses the PID address. If you specify the process name without a PID address, the service uses the process name. If you specify both---the process name and PID address---it uses the PID address unless the contents of the PID is 0. In that case, the service uses the process name. If you specify a PID address of 0 without a process name, then the service is performed for the calling process.

If you specify neither the process name argument nor the process identification number argument, the service is performed for the calling process. If the PID address is specified, the service returns the PID of the target process in it. Table SYS-43 summarizes the possible combinations of these arguments and explains how the services interpret them.

Table SYS-43 Process Identification
Process
Name
Specified?
PID
Address
Specified?
Contents of
PID
Resultant
Action
by Services
No No -- The process identification of the calling process is used, but is not returned.
No Yes 0 The process identification of the calling process is used and returned.
No Yes PID The process identification is used and returned.
Yes No -- The process name is used. The process identification is not returned.
Yes Yes 0 The process name is used and the process identification is returned.
Yes Yes PID The process identification is used and returned; the process name is ignored.

Required Quota

None

Related Services

$GETJPIW, $HIBER, $PROCESS_SCAN, $RESUME, $SYNCH


Condition Values Returned

SS$_NORMAL The service completed successfully.
SS$_ACCVIO The item list cannot be read by the caller, or the buffer length or buffer cannot be written by the caller.
SS$_BADPARAM The item list contains an invalid identifier. Or, an item list containing both 32-bit and 64-bit item list entries was found.
SS$_INCOMPAT The remote node is running an incompatible version of the operating system.
SS$_IVLOGNAM The process name string has a length of 0 or has more than 15 characters.
SS$_NOMOREPROC In a wildcard operation, $GETJPI found no more processes.
SS$_NOMORETHREAD The search for kernel threads within a process is complete. This condition value is returned by $GETJPIW if you set the JPI$M_THREAD bit in JPI$_GETJPI_CONTROL_FLAGS.
SS$_NONEXPR The specified process does not exist, or an invalid process identification was specified.
SS$_NOPRIV The process does not have the privilege to obtain information about the specified process.
SS$_NOSUCHNODE The specified node is not currently a member of the cluster.
SS$_REMRSRC The remote node has insufficient resources to respond to the request. (Bring this error to the attention of your system manager.)
SS$_SUSPENDED The specified process is suspended or in a miscellaneous wait state, and the requested information cannot be obtained.
SS$_UNREACHABLE The remote node is a member of the cluster but is not accepting requests. This is normal for a brief period early in the system boot process.

Condition Values Returned in the I/O Status Block

1
Same as those returned in R0.

$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 Integrity server 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:

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.


Previous Next Contents Index