HP OpenVMS System Services Reference Manual
These privileges are returned in a quadword privilege mask and are
defined by the $PRVDEF macro.
JPI$_PERSONA_ID
On Alpha and I64 systems, returns, as a longword integer, the ID of the
persona.
JPI$_PERSONA_PERMPRIV
On Alpha and I64 systems, returns the permanent (default) privilege
mask of the persona. These privileges are returned in a quadword
privilege mask and are defined by the $PRVDEF macro.
JPI$_PERSONA_RIGHTS
On Alpha and I64 systems, returns the binary content of the persona
rights list as an array of quadword identifiers. Each entry consists of
a longword identifier value and longword identifier attributes, as
listed in Table SYS-43. The persona rights list is a set of
identifiers associated with the process.
JPI$_PERSONA_RIGHTS_SIZE
On Alpha and I64 systems, returns a longword integer containing the
number of bytes needed to store the persona rights.
JPI$_PERSONA_WORKPRIV
On Alpha and I64 systems, returns the privilege mask of the working
(active) persona. These privileges are returned in a quadword privilege
mask and are defined by the $PRVDEF macro.
JPI$_PGFLQUOTA
Returns the paging file quota (maximum virtual page count) of the
process, which is a longword integer value, measured in pages (on VAX
systems) or pagelets (on Alpha and I64 systems).
JPI$_PHDFLAGS
Returns the process header flags as a longword bit vector.
JPI$_PID
Returns the process identification (PID) of the process. The PID is a
longword hexadecimal value.
JPI$_P0_FIRST_FREE_VA_64
On Alpha and I64 systems, this item code returns the 64-bit virtual
address of the first free page at the end of the program region (P0
space) of the process.
Because this number is a quadword, the buffer length field in the item
descriptor should specify 8 (bytes).
JPI$_P1_FIRST_FREE_VA_64
On Alpha and I64 systems, this item code returns the 64-bit virtual
address of the first free page at the end of the control region (P1
space) of the process.
Because this number is a quadword, the buffer length field in the item
descriptor should specify 8 (bytes).
JPI$_P2_FIRST_FREE_VA_64
On Alpha and I64 systems, this item code returns the 64-bit virtual
address of the first free page at the end of P2 space of the process.
Because this number is a quadword, the buffer length field in the item
descriptor should specify 8 (bytes).
JPI$_PPGCNT
Returns the number of pages (on VAX systems) or pagelets (on Alpha and
I64 systems) the process has in the working set. This is a longword
integer value.
JPI$_PRCCNT
Returns, as a longword integer value, the number of subprocesses
created by the process. The number returned by JPI$_PRCCNT does not
include any subprocesses created by subprocesses of the process named
in the procnam argument.
JPI$_PRCLM
Returns the subprocess quota of the process, which is a longword
integer value.
JPI$_PRCNAM
Returns, as a character string, the name of the process. Because the
process name can include up to 15 characters, the buffer length field
of the item descriptor should specify at least 15 bytes.
JPI$_PRI
Returns the current priority of the process, which is a longword
integer value.
JPI$_PRIB
Returns the base priority of the process, which is a longword integer
value.
JPI$_PROCESS_RIGHTS
Returns the binary content of the process rights list as an array of
quadword identifiers. Each entry consists of a longword identifier
value and longword identifier attributes, as shown in Table SYS-43.
Allocate a buffer that is sufficient to hold the process rights list
because $GETJPI returns only as much of the list as will fit in the
buffer.
JPI$_PROC_INDEX
Returns, as a longword integer value, the process index number of the
process. The process index number is a number between 1 and the system
parameter MAXPROCESSCNT, which identifies the process. Although process
index numbers are reassigned to different processes over time, at any
one instant, each process in the system has a unique process index
number.
You can use the process index number as an index into system global
sections. Because the process index number is unique for each process,
its use as an index into system global sections guarantees no
collisions with other system processes accessing those sections.
The process index is intended to serve users who formerly used the
low-order word of the PID as an index number.
JPI$_PROCPRIV
Returns the default privileges of the process in a quadword bit mask.
JPI$_RIGHTSLIST
Returns, as an array of quadword identifiers, all identifiers
applicable to the process. This includes the process rights list
(JPI$_PROCESS_RIGHTS) and the system rights list (JPI$_SYSTEM_RIGHTS).
Each entry consists of a longword identifier value and longword
identifier attributes, shown in Table SYS-43. Allocate a buffer that
is sufficient to hold the rights list because $GETJPI returns only as
much of the list as will fit in the buffer.
JPI$_RIGHTS_SIZE
Returns the number of bytes required to buffer the rights list. The
rights list includes both the system rights list and the process rights
list. Because the space requirements for the rights list can change
between the time you request the size of the rights list and the time
you fetch the rights list with JPI$_RIGHTSLIST, you might want to
allocate a buffer that is 10 percent larger than this item indicates.
JPI$_RMS_DFMBC
Returns the default multiblock count.
JPI$_RMS_DFMBFIDX
Returns the default multibuffer count for local buffers for indexed
file operations.
JPI$_RMS_DFMBFREL
Returns the default multibuffer count for local buffers for relative
file operations.
JPI$_RMS_DFMBFSDK
Returns the default multibuffer count for local buffers for sequential
file operations on disk.
JPI$_RMS_DFMBFSMT
Returns the default multibuffer count for local buffers for sequential
file operations on magnetic tape.
JPI$_RMS_DFMBFSUR
Returns the default multibuffer count for file operation on unit record
devices.
JPI$_RMS_DFNBC
Returns the default block count for local buffers for network access to
remote files.
JPI$_RMS_EXTEND_SIZE
Returns the default number of blocks used to extend a sequential file.
JPI$_RMS_FILEPROT
Returns the default file protection.
JPI$_RMS_PROLOGUE
Returns the default prolog level for indexed files.
JPI$_SCHED_CLASS_NAME
Returns the name of the scheduling class (as a character string) to
which this process belongs. Because the class name can include up to 16
characters, the buffer length field of the item descriptor must specify
at least 16 bytes. If the process is not class scheduled, then a return
length of 0 is returned to the caller.
JPI$_SCHED_POLICY
On Alpha and I64 systems, returns the current scheduling policy of the
specified process. Definitions of the policy values are in the $JPIDEF
macro. The buffer length of the item descriptor should specify 4
(bytes).
JPI$_SHRFILLM
Returns the maximum number of open shared files allowed for the job to
which the process specified in the call to $GETJPI belongs. This limit
is set in the UAF record of the user who owns the process. The number
is returned as a word decimal value. A value of 0 means that there is
no limit on the number of open shared files for that job.
JPI$_SITESPEC
Returns the per-process, site-specific longword, which is a longword
integer value.
JPI$_SLOW_VP_SWITCH
On VAX systems, returns an unsigned longword containing the number of
times this process has issued a vector instruction that resulted in an
inactive vector processor being enabled with a full vector context
switch. This vector context switch involves the saving of the vector
context of the process that last used the vector processor and the
restoration of the vector context of the current process.
JPI$_STATE
Returns the state of the process, which is a longword integer value.
Each state has a symbolic representation. If the process is currently
executing, its state is always SCH$K_CUR. STATEDEF defines the
following symbols, which identify the various possible states:
| State |
Description |
|
SCH$C_CEF
|
Common event flag wait
|
|
SCH$C_COM
|
Computable
|
|
SCH$C_COMO
|
Computable, out of balance set
|
|
SCH$C_CUR
|
Current process
|
|
SCH$C_COLPG
|
Collided page wait
|
|
SCH$C_FPG
|
Free page wait
|
|
SCH$C_HIB
|
Hibernate wait
|
|
SCH$C_HIBO
|
Hibernate wait, out of balance set
|
|
SCH$C_LEF
|
Local event flag wait
|
|
SCH$C_LEFO
|
Local event flag wait, out of balance set
|
|
SCH$C_MWAIT
|
Mutex and miscellaneous resource wait
|
|
SCH$C_PFW
|
Page fault wait
|
|
SCH$C_SUSP
|
Suspended
|
|
SCH$C_SUSPO
|
Suspended, out of balance set
|
JPI$_STS
Returns the first longword of the process status flags, which are
contained in a longword bit vector. PCBDEF definitions include the
following symbols for these flags:
| Symbol |
Description |
|
PCB$V_ASTPEN
|
AST pending
|
|
PCB$V_BATCH
|
Process is a batch job
|
|
PCB$V_DELPEN
|
Delete pending
|
|
PCB$V_DISAWS
|
Disable automatic working set adjustment
|
|
PCB$V_FORCPEN
|
Force exit pending
|
|
PCB$V_HARDAFF
|
Process bound to a particular CPU
|
|
PCB$V_HIBER
|
Hibernate after initial image activate
|
|
PCB$V_INQUAN
|
Initial quantum in progress
|
|
PCB$V_INTER
|
Process is an interactive job
|
|
PCB$V_LOGIN
|
Log in without reading authorization file
|
|
PCB$V_NETWRK
|
Process is a network connect object
|
|
PCB$V_NOACNT
|
No accounting for process
|
|
PCB$V_NODELET
|
No delete
|
|
PCB$V_PHDRES
|
Process header resident
|
|
PCB$V_PREEMPTED
|
Kernel mode suspend has overridden supervisor mode suspend
|
|
PCB$V_PSWAPM
|
Process swap mode (1=noswap)
|
|
PCB$V_PWRAST
|
Power fail AST
|
|
PCB$V_RECOVER
|
Process can recover locks
|
|
PCB$V_RES
|
Resident, in balance set
|
|
PCB$V_RESPEN
|
Resume pending, skip suspend
|
|
PCB$V_SECAUDIT
|
Mandatory security auditing
|
|
PCB$V_SOFTSUSP
|
Process is in supervisor mode suspend
|
|
PCB$V_SSFEXC
|
System service exception enable (kernel)
|
|
PCB$V_SSFEXCE
|
System service exception enable (exec)
|
|
PCB$V_SSFEXCS
|
System service exception enable (super)
|
|
PCB$V_SSFEXCU
|
System service exception enable (user)
|
|
PCB$V_SSRWAIT
|
System service resource wait disable
|
|
PCB$V_SUSPEN
|
Suspend pending
|
|
PCB$V_WAKEPEN
|
Wake pending, skip hibernate
|
|
PCB$V_WALL
|
Wait for all events in mask
|
JPI$_STS2
Returns the second longword of the process status flags, which are
contained in a longword bit vector. PCBDEF defines the following symbol
for these flags:
| Symbol |
Description |
|
PCB$V_NOUNSHELVE
|
Process does not automatically unshelve files.
|
JPI$_SUBSYSTEM_RIGHTS
On Alpha and I64 systems, returns the binary content of the subsystem
rights list as an array of quadword identifiers. Each entry consists of
a longword identifier value and longword identifier attributes, as
listed in Table SYS-43. The subsystem rights list is a set of
identifiers associated with a protected subsystem image.
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 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 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
1
Same as those returned in R0.