 |
HP OpenVMS System Services Reference Manual
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 I64 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-43. 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 I64 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 8
characters, the buffer length field in the item descriptor should
specify at least 8 bytes. Trailing zeros are written to the output
buffer if necessary.
JPI$_THREAD_INDEX
On Alpha and I64 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:
- If the terminal is on a terminal server, this item returns the
terminal server name and the name of the line port on the server.
- If the terminal is a DECnet for OpenVMS remote terminal, this item
returns the source system node name and the user name on the source
system.
- If the terminal is on TELNET, this item returns the originating
host address and port.
- If the terminal not on a terminal server, on DECnet, or on TELNET,
this item returns a null string.
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 pages for VAX or pagelets
for Alpha or I64---of the process.
On VAX systems, the value returned is a longword integer. On Alpha and
I64 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$_VP_CONSUMER
On VAX systems, returns a byte, the low-order bit of which, when set,
indicates that the process is a vector consumer.
JPI$_VP_CPUTIM
On VAX systems, returns an unsigned longword that contains the total
amount of time the process has accumulated as a vector consumer.
JPI$_WSAUTH
Returns the maximum authorized working set size, in pages (on VAX
systems) or pagelets (on Alpha and I64 systems), of the process. This
is a longword integer value.
JPI$_WSAUTHEXT
Returns, in pages (on VAX systems) or pagelets (on Alpha and I64
systems), the maximum authorized working set extent of the process as a
longword integer value.
JPI$_WSEXTENT
Returns, in pages (on VAX systems) or pagelets (on Alpha and I64
systems), the current working set extent of the process as a longword
integer value.
JPI$_WSPEAK
Returns, in pages (on VAX systems) or pagelets (on Alpha and I64
systems), the peak working set size of the process as a longword
integer value.
JPI$_WSQUOTA
Returns, in pages (on VAX systems) or pagelets (on Alpha and I64
systems), the working set size quota of the process as a longword
integer value.
JPI$_WSSIZE
Returns, in pages (on VAX systems) or pagelets (on Alpha and I64
systems), 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:
- The service executes faster because it does not have to search a
table of process names.
- For a process not in your group, you must use the process
identification number.
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-44 summarizes the
possible combinations of these arguments and explains how the services
interpret them.
Table SYS-44 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
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, refer to 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.
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.
|
