Returns information about one or more processes on the system or
across the OpenVMS Cluster system.
The $GETJPI service completes asynchronously. For synchronous
completion, use the Get Job/Process Information and Wait
($GETJPIW) service.
On Alpha and Integrity server systems, this service accepts 64-
bit addresses.
Format
SYS$GETJPI [efn] ,[pidadr] ,[prcnam] ,itmlst ,[iosb] ,[astadr]
,[astprm]
C Prototype
int sys$getjpi (unsigned int efn, unsigned int *pidadr, void
*prcnam, void *itmlst, struct _iosb *iosb, void
(*astadr)(__unknown_params), unsigned __int64
astprm);
1 – Arguments
efn
OpenVMS usage:ef_number
type: quadword (unsigned)
access: read only
mechanism: by value
Number of the event flag to be set when $GETJPI returns the
requested information. The efn argument is a quadword containing
this number; however, $GETJPI uses only the low-order byte.
Upon request initiation, $GETJPI clears the specified event flag
(or event flag 0 if efn was not specified). Then, when $GETJPI
returns the requested information, it sets the specified event
flag (or event flag 0).
VSI 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 VSI OpenVMS Programming Concepts Manual.
pidadr
OpenVMS usage:process_id
type: longword (unsigned)
access: modify
mechanism: by 32- or 64-bit reference
Process identification (PID) of the process about which $GETJPI
is to return information. The pidadr argument is the 32- or 64-
bit address of a longword containing the PID. The pidadr argument
can refer to a process running on the local node or a process
running on another node in the cluster.
If you give pidadr the value -1, $GETJPI assumes a wildcard
operation and returns the requested information for each process
on the system that it has the privilege to access, one process
per call. To perform a wildcard operation, you must call $GETJPI
in a loop, testing for the condition value SS$_NOMOREPROC after
each call and exiting from the loop when SS$_NOMOREPROC is
returned.
If you use $GETJPI with $PROCESS_SCAN, you can perform wildcard
searches across the cluster. In addition, with $PROCESS_SCAN
you can search for specific processes based on many different
selection criteria.
You cannot abbreviate a PID. All significant digits of a PID must
be specified; only leading zeros can be omitted.
prcnam
OpenVMS usage:process_name
type: character-coded text string
access: read only
mechanism: by 32- or 64-bit descriptor-fixed-length string
descriptor
Name of the process about which $GETJPI is to return information.
The prcnam argument is the 32- or 64-bit address of a character
string descriptor pointing to this name string.
A process running on the local node can be identified with a 1-
to 15-character string. To identify a process on a cluster, you
must specify the full process name, which includes the node name
as well as the process name. The full process name can contain up
to 23 characters.
A local process name can look like a remote process name;
therefore, if you specify ATHENS::SMITH, the system checks for
a process named ATHENS::SMITH on the local node before checking
node ATHENS for a process named SMITH.
You can use the prcnam argument only if the process identified
by prcnam has the same UIC group number as the calling process.
If the process has a different group number, $GETJPI returns
no information. To obtain information about processes in other
groups, you must use the pidadr argument.
itmlst
OpenVMS usage:32-bit item_list_3 or 64-bit item_list_64b
type: longword (unsigned) for 32-bit; quadword (unsigned)
for 64-bit
access: read only
mechanism: by 32- or 64-bit reference
Item list specifying which information about the process or
processes is to be returned. The itmlst argument is the 32-
or 64-bit address of a list of item descriptors, each of which
describes an item of information. An item list in 32-bit format
is terminated by a longword of 0; an item list in 64-bit format
is terminated by a quadword of 0. All items in an item list must
be of the same format-either 32-bit or 64-bit.
To view the item code diagrams and descriptor fields tables, see
the VSI OpenVMS System Services Reference Manual.
iosb
OpenVMS usage:io_status_block
type: quadword (unsigned)
access: write only
mechanism: by 32- or 64-bit reference
I/O status block that is to receive the final completion status.
The iosb argument is the 32- or 64-bit address of the quadword
I/O status block.
When you specify the iosb argument, $GETJPI sets the quadword to
0 upon request initiation. Upon request completion, a condition
value is returned to the first longword; the second longword is
reserved for future use.
Though this argument is optional, VSI strongly recommends that you
specify it, for the following reasons:
o 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.
o If you are using the $SYNCH service to synchronize completion
of the service, the I/O status block is a required argument
for $SYNCH.
o 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 $GETJPI 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 $GETJPI, 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 32- or 64-bit reference
AST service routine to be executed when $GETJPI completes. The
astadr argument is the 32- or 64-bit address of this routine.
If you specify astadr, the AST routine executes at the same
access mode as the caller of the $GETJPI 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.