OpenVMS System Services Reference Manual

Document revision date: 19 July 1999

OpenVMS System Services Reference Manual

Contents

Index

$GETDVIW

Returns information about an I/O device; this information consists of primary and secondary device characteristics.
The $GETDVIW service completes synchronously; that is, it returns to the caller with the requested information. Compaq recommends that you use an IOSB with this service. An IOSB prevents the service from completing prematurely. In addition, the IOSB contains additional status information.
For asynchronous completion, use the Get Device/Volume Information ($GETDVI) service; $GETDVI returns to the caller after queuing the information request, without waiting for the information to be returned. In all other respects, $GETDVIW is identical to $GETDVI. For all other information about the $GETDVIW service, refer to the description of $GETDVI.
For additional information about system service completion, refer to the Synchronize ($SYNCH) service.

Format

SYS$GETDVIW [efn] ,[chan] ,[devnam] ,itmlst [,iosb] [,astadr] [,astprm] [,nullarg]

C Prototype

int sys$getdviw (unsigned int efn, unsigned short int chan, void *devnam, void *itmlst, struct _iosb *iosb, void (*astadr)(__unknown_params), int astprm, unsigned __int64 *nullarg);

$GETENV (Alpha Only)

Returns the value(s) of the specified console environment variable(s).

Format

SYS$GETENV itmlst

C Prototype

int sys$getenv (void *itmlst);

Arguments

itmlst

OpenVMS usage: item_list_3

type: longword (unsigned)

access: read only

mechanism: by reference

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 service takes one argument as input, an item list. This item list has the following format for a single item descriptor:
63 31 0 +-------------------------------------+ | Buffer length | Item code | STENVDEF$L_ITEM_CODE/STENVDEF$L_BUF_LEN +-------------------------------------+ | Buffer address | STENVDEF$Q_BUF_ADDR +-------------------------------------+ | Return length address | STENVDEF$Q_RET_ADDR +-------------------------------------+
The following table defines the item descriptor fields.

Descriptor Field Definition

Item code A longword indicating which environment variable you want to retrieve. These codes are defined in $STENVDEF.

Buffer length A longword specifying the length of the buffer in which GETENV is to write the environment variable's value.

Buffer address A quadword indicating the address of the buffer in which GETENV is to write the environment variable's value.

Return length address A quadword indicating the return address in which to put the length of the value that GETENV retrieved.

Descriptor Field	Definition
Item code	A longword indicating which environment variable you want to retrieve. These codes are defined in $STENVDEF.
Buffer length	A longword specifying the length of the buffer in which GETENV is to write the environment variable's value.
Buffer address	A quadword indicating the address of the buffer in which GETENV is to write the environment variable's value.
Return length address	A quadword indicating the return address in which to put the length of the value that GETENV retrieved.

Description

This system service will return the value(s) of the specified console environment variable(s).
Required Access or Privileges

None
Required Quota

None
Related Services

None

Condition Values Returned

SS$_NORMAL Operation was successful; requested data was returned to caller.

SS$_ACCVIO This status is returned if the caller does not have write access to the two input buffers or if the probe for read access to the item list fails.

SS$_BADPARAM This status is returned if an empty item list is specified, or if the console callback to read the environment variable fails for any reason.

$GETJPI

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 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);

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).
pidadr

OpenVMS usage: process_id

type: longword (unsigned)

access: modify

mechanism: by 32- or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

Process identification (PID) of the process about which $GETJPI is to return information. The pidadr argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) 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 (Alpha)

mechanism: by 32-bit descriptor--fixed-length string descriptor (VAX)

Name of the process about which $GETJPI is to return information. The prcnam argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) 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 (Alpha)

mechanism: by 32-bit reference (VAX)

Item list specifying which information about the process or processes is to be returned. The itmlst argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) 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.
The following diagram depicts the 32-bit format of a single item descriptor.

The following table defines the item descriptor fields for 32-bit item list entries.

Descriptor Field Definition

Buffer length A word containing a user-supplied integer specifying the length (in bytes) of the buffer in which $GETJPI 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 buffer length is too small, $GETJPI truncates the data.

Item code A word containing a user-supplied symbolic code specifying the item of information that $GETJPI is to return. The $JPIDEF macro defines these codes. Each item code is described in the Item Codes section.

Buffer address A longword containing the user-supplied 32-bit address of the buffer in which $GETJPI is to write the information.

Return length address A longword containing the user-supplied 32-bit address of a word in which $GETJPI writes the length (in bytes) of the information it actually returned.

Descriptor Field	Definition
Buffer length	A word containing a user-supplied integer specifying the length (in bytes) of the buffer in which $GETJPI 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 buffer length is too small, $GETJPI truncates the data.
Item code	A word containing a user-supplied symbolic code specifying the item of information that $GETJPI is to return. The $JPIDEF macro defines these codes. Each item code is described in the Item Codes section.
Buffer address	A longword containing the user-supplied 32-bit address of the buffer in which $GETJPI is to write the information.
Return length address	A longword containing the user-supplied 32-bit address of a word in which $GETJPI writes the length (in bytes) of the information it actually returned.

The following diagram depicts the 64-bit format of a single item descriptor.

The following table defines the item descriptor fields for 64-bit item list entries.

Descriptor Field Definition

MBO The field must contain a 1. The MBO and MBMO fields are used to distinguish 32-bit and 64-bit item list entries.

Item code A word containing a symbolic code that describes the information in the buffer or the information to be returned to the buffer, pointed to by the buffer address field. The item codes are listed in the Item Codes section.

MBMO The field must contain a --1. The MBMO and MBO fields are used to distinguish 32-bit and 64-bit item list entries.

Buffer length A quadword containing a user-supplied integer specifying the length (in bytes) of the buffer in which $GETJPI 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 buffer length is too small, $GETJPI truncates the data.

Buffer address A quadword containing the user-supplied 64-bit address of the buffer in which $GETJPI is to write the information.

Return length address A quadword containing the user-supplied 64-bit address of a word in which $GETJPI writes the length (in bytes) of the information it actually returned.

Descriptor Field	Definition
MBO	The field must contain a 1. The MBO and MBMO fields are used to distinguish 32-bit and 64-bit item list entries.
Item code	A word containing a symbolic code that describes the information in the buffer or the information to be returned to the buffer, pointed to by the buffer address field. The item codes are listed in the Item Codes section.
MBMO	The field must contain a --1. The MBMO and MBO fields are used to distinguish 32-bit and 64-bit item list entries.
Buffer length	A quadword containing a user-supplied integer specifying the length (in bytes) of the buffer in which $GETJPI 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 buffer length is too small, $GETJPI truncates the data.
Buffer address	A quadword containing the user-supplied 64-bit address of the buffer in which $GETJPI is to write the information.
Return length address	A quadword containing the user-supplied 64-bit address of a word in which $GETJPI writes the length (in bytes) of the information it actually returned.

iosb

OpenVMS usage:	io_status_block
type:	quadword (unsigned)
access:	write only
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

I/O status block that is to receive the final completion status. The iosb argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) 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, Compaq 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 $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 (Alpha)
mechanism:	by 32-bit reference (VAX)

AST service routine to be executed when $GETJPI completes. The astadr argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) 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.

Item Codes

JPI$_ACCOUNT
When you specify JPI$_ACCOUNT, $GETJPI returns the account name of the process, which is an 8-byte string, filled with trailing blanks if necessary.
JPI$_APTCNT
When you specify JPI$_APTCNT, $GETJPI returns, in pages (on VAX systems) or pagelets (on Alpha systems), the active page table count of the process, which is a longword integer value.
JPI$_ASTACT
When you specify JPI$_ASTACT, $GETJPI returns the names of the access modes having active ASTs. This information is returned in a longword bit vector. When bit 0 is set, an active kernel mode AST exists; bit 1, an executive mode AST; bit 2, a supervisor mode AST; and bit 3, a user mode AST.
JPI$_ASTCNT
When you specify JPI$_ASTCNT, $GETJPI returns a count of the remaining AST quota, which is a longword integer value.
JPI$_ASTEN
When you specify JPI$ASTEN, $GETJPI returns a longword bit vector that indicates for each access mode whether ASTs are enabled for that mode. When bit 0 is set, Kernel mode has ASTs enabled; bit 1, Executive mode; bit 2, Supervisor mode; and bit 3, User mode.
Note that this item code is only valid for the current process. If the service is called with a process name or PID other than the current process, it returns the value of zero (0) in the RETLEN output parameter.
JPI$_ASTLM
When you specify JPI$_ASTLM, $GETJPI returns the AST limit quota of the process, which is a longword integer value.
JPI$_AUTHPRI
When you specify JPI$_AUTHPRI, $GETJPI returns the authorized base priority of the process, which is a longword integer value. The authorized base priority is the highest priority a process without ALTPRI privilege can attain by means of the $SETPRI service.
JPI$_AUTHPRIV
When you specify JPI$_AUTHPRIV, $GETJPI returns the privileges that the process is authorized to enable. These privileges are returned in a quadword privilege mask and are defined by the $PRVDEF macro.
JPI$_BIOCNT
When you specify JPI$_BIOCNT, $GETJPI returns a count of the remaining buffered I/O quota, which is a longword integer value.
JPI$_BIOLM
When you specify JPI$_BIOLM, $GETJPI returns the buffered I/O limit quota of the process, which is a longword integer value.
JPI$_BUFIO
When you specify JPI$_BUFIO, $GETJPI returns a count of the buffered I/O operations of the process, which is a longword integer value.
JPI$_BYTCNT
When you specify JPI$_BYTCNT, $GETJPI returns the remaining buffered I/O byte count quota of the process, which is a longword integer value.
JPI$_BYTLM
When you specify JPI$_BYTLM, $GETJPI returns the buffered I/O byte count limit quota of the process, which is a longword integer value.
JPI$_CHAIN
When you specify JPI$_CHAIN, $GETJPI processes another item list immediately after processing the current one. The buffer address field in the item descriptor specifies the address of the next item list to be processed. You must specify the JPI$_CHAIN item code last in the item list.
You can chain together 32-bit and 64-bit item lists.
JPI$_CLINAME
When you specify JPI$_CLINAME, $GETJPI returns the name of the command language interpreter that the process is currently using. Because the CLI name can include up to 39 characters, the buffer length field in the item descriptor should specify 39 bytes.
JPI$_CPU_ID
When you specify JPI$_CPU_ID, $GETJPI returns, as a longword integer, the ID of the CPU on which the process is running or on which it last ran. This value is returned as --1 if the system is not a multiprocessor.
JPI$_CPULIM
When you specify JPI$_CPULIM, $GETJPI returns the CPU time limit of the process, which is a longword integer value.
JPI$_CPUTIM
When you specify JPI$_CPUTIM, $GETJPI returns the process's accumulated CPU time in 10-millisecond ticks, which is a longword integer value.
JPI$_CREPRC_FLAGS
When you specify JPI$_CREPRC_FLAGS, $GETJPI returns the flags specified by the stsflg argument in the $CREPRC call that created the process. The flags are returned as a longword bit vector.
JPI$_CURPRIV
When you specify JPI$_CURPRIV, $GETJPI returns the current privileges of the process. These privileges are returned in a quadword privilege mask and are defined by the $PRVDEF macro.
JPI$_CURRENT_AFFINITY_MASK
On Alpha systems, when you specify JPI$_CURRENT_AFFINITY_MASK, $GETJPI returns the current explicit affinity mask for the associated kernel thread.
JPI$_CURRENT_USERCAP_MASK
On Alpha systems, when you specify JPI$_CURRENT_USERCAP_MASK, $GETJPI returns the current user capability mask for the associated kernel thread.
JPI$_DFMBC
When you specify JPI$_DFMBC, $GETJPI returns the default multibuffer count for a process as a longword integer value.
JPI$_DFPFC
When you specify JPI$_DFPFC, $GETJPI returns the default page fault cluster size of the process, which is a longword integer value measured in pages (on VAX systems) or pagelets (on Alpha systems).
JPI$_DFWSCNT
When you specify JPI$_DFWSCNT, $GETJPI returns, in pages (on VAX systems) or pagelets (on Alpha systems), the default working set size of the process, which is a longword integer value.
JPI$_DIOCNT
When you specify JPI$_DIOCNT, $GETJPI returns the remaining direct I/O quota of the process, which is a longword integer value.
JPI$_DIOLM
When you specify JPI$_DIOLM, $GETJPI returns the direct I/O quota limit of the process, which is a longword integer value.
JPI$_DIRIO
When you specify JPI$_DIRIO, $GETJPI returns a count of the direct I/O operations of the process, which is a longword integer value.
JPI$_EFCS
When you specify JPI$_EFCS, $GETJPI returns the state of the process's local event flags 0 through 31 as a longword bit vector.
JPI$_EFCU
When you specify JPI$_EFCU, $GETJPI returns the state of the process's local event flags 32 through 63 as a longword bit vector.
JPI$_EFWM
When you specify JPI$_EFWM, $GETJPI returns the event flag wait mask of the process, which is a longword bit vector.
JPI$_ENQCNT
When you specify JPI$_ENQCNT, $GETJPI returns the remaining lock request quota of the process, which is a longword integer value.
JPI$_ENQLM
When you specify JPI$_ENQLM, $GETJPI returns the lock request quota of the process, which is a longword integer value.
JPI$_EXCVEC
When you specify JPI$_EXCVEC, $GETJPI returns the address of a list of exception vectors for the process. Each exception vector in the list is a longword. There are eight vectors in the list: these are, in order, a primary and a secondary vector for kernel mode access, for executive mode access, for supervisor mode access, and for user mode access.
The $GETJPI service cannot return this information for any process other than the calling process; if you specify this item code and the process is not the calling process, $GETJPI returns the value 0 in the buffer.
JPI$_FAST_VP_SWITCH
When you specify JPI$_FAST_VP_SWITCH, $GETJPI 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 without the expense of a vector context switch. In other words, this count reflects those instances where the process has reenabled a vector processor on which the process's vector context has remained intact.
JPI$_FILCNT
When you specify JPI$_FILCNT, $GETJPI returns the remaining open file quota of the process, which is a longword integer value.
JPI$_FILLM
When you specify JPI$_FILLM, $GETJPI returns the open file limit quota of the process, which is a longword value.
JPI$_FINALEXC
When you specify JPI$_FINALEXC, $GETJPI returns the address of a list of final exception vectors for the process. Each exception vector in the list is a longword. There are four vectors in the list, one for each access mode, in this order: kernel, executive, supervisor, and user.
The $GETJPI service cannot return this information for any process other than the calling process; if you specify this item code and the process is not the calling process, $GETJPI returns the value 0 in the buffer.
JPI$_FREP0VA
When you specify JPI$_FREP0VA, $GETJPI returns the address of the first free page at the end of the program region (P0 space) of the process.
JPI$_FREP1VA
When you specify JPI$_FREP1VA, $GETJPI returns the address of the first free page at the end of the control region (P1 space) of the process.
JPI$_FREPTECNT
When you specify JPI$_FREPTECNT, $GETJPI returns the number of pages (on VAX systems) or pagelets (on Alpha systems) that the process has available for virtual memory expansion.
On VAX systems, the value returned is a longword integer. On Alpha systems, the value returned requires a quadword of storage. If the buffer size supplied is not equal to 8 bytes, and the number of free pagelets exceeds the maximum value that can be represented in a longword, $GETJPI returns the largest positive 32-bit integer: 2147483647.
JPI$_GETJPI_CONTROL_FLAGS
The JPI$_GETJPI_CONTROL_FLAGS item code, which is specified in the $GETJPI item list, provides additional control over $GETJPI. Therefore, $GETJPI might be unable to retrieve all the data requested in an item list because JPI$_GETJPI_CONTROL_FLAGS requests that $GETJPI not perform certain actions that might be necessary to collect the data. For example, a $GETJPI control flag might instruct the calling program not to retrieve a process that has been swapped out of the balance set.
If $GETJPI is unable to retrieve any data item because of the restrictions imposed by the control flags, it returns the data length as 0. To verify that $GETJPI received a data item, examine the data length to be sure that it is not 0. To ensure the verification, be sure to specify the return length for each item in the $GETJPI item list when any of the JPI$_GETJPI_CONTROL_FLAGS flags is used.
Unlike other $GETJPI item codes, the JPI$_GETJPI_CONTROL_FLAGS item is an input item. The item list entry should specify a longword buffer. The desired control flags should be set in this buffer.
Because the JPI$_GETJPI_CONTROL_FLAGS item code tells $GETJPI how to interpret the item list, it must be the first entry in the $GETJPI item list. The error code SS$_BADPARAM is returned if it is not the first item in the list.
The JPI$_GETJPI_CONTROL_FLAGS item code includes the following flags.

Flag Description

JPI$M_NO_TARGET_INSWAP Does not retrieve a process that has been swapped out of the balance set. This control flag is used to avoid adding the load of swapping processes into a system. By using this control flag and requesting information from a process that has been swapped out, the following occurs:

Any data stored in the virtual address space of the process is not accessible.
Any data stored in the process header (PHD) might not be accessible.
Any data stored in resident data structures, such as the process control block (PCB) or the job information block (JIB), is accessible.

You must examine the return length of an item to verify that the item was retrieved.

JPI$M_NO_TARGET_AST Does not deliver a kernel mode AST to the target process. This control flag is used to avoid executing a target process to retrieve information. By using this control flag and not delivering an AST to a target process, the following occurs:

Any data stored in the virtual address space of the process is not accessible.
Any data stored in system data structures, such as the process header (PHD), the process control block (PCB), or the job information block (JIB), is accessible.

You must examine the return length of an item to verify that the item was retrieved.
The use of this control flag also implies that $GETJPI does not swap in a process, because $GETJPI would only bring a process into memory to deliver an AST to that process.

JPI$M_IGNORE_TARGET_STATUS Attempts to retrieve as much information as possible, even though the process might be suspended or is being deleted. This control flag is used to retrieve all possible information from a process.

JPI$M_THREAD Sets the wildcard mode to return information on all of the process's kernel threads beginning with the initial kernel thread.

JPI$_GPGCNT
When you specify JPI$_GPGCNT, $GETJPI returns, in pages (on VAX systems) or pagelets (on Alpha systems), the process's global page count in the working set, which is a longword integer value.
JPI$_GRP
When you specify JPI$_GRP, $GETJPI returns, as a longword integer value, the group number of the process's UIC.
JPI$_IMAGECOUNT
When you specify JPI$_IMAGECOUNT, $GETJPI returns, as a longword integer value, the number of images that have been run down for the process.
JPI$_IMAGE_RIGHTS
When you specify JPI$_IMAGE_RIGHTS, $GETJPI returns the binary content of the image 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-11. The image 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 image rights list, because $GETJPI returns only as much of the list as will fit in the buffer.

Table SYS-11 Attributes of an Identifier
Symbolic Name Description

KGB$M_DYNAMIC Identifier can be enabled or disabled.

+KGB$M_NOACCESS Rights of the identifier are null and void.

KGB$M_RESOURCE Resources can be charged to the identifier.

+KGB$M_SUBSYSTEM Identifier can be used to create protected subsystems.

Flag	Description
JPI$M_NO_TARGET_INSWAP	Does not retrieve a process that has been swapped out of the balance set. This control flag is used to avoid adding the load of swapping processes into a system. By using this control flag and requesting information from a process that has been swapped out, the following occurs: Any data stored in the virtual address space of the process is not accessible. Any data stored in the process header (PHD) might not be accessible. Any data stored in resident data structures, such as the process control block (PCB) or the job information block (JIB), is accessible. You must examine the return length of an item to verify that the item was retrieved.
JPI$M_NO_TARGET_AST	Does not deliver a kernel mode AST to the target process. This control flag is used to avoid executing a target process to retrieve information. By using this control flag and not delivering an AST to a target process, the following occurs: Any data stored in the virtual address space of the process is not accessible. Any data stored in system data structures, such as the process header (PHD), the process control block (PCB), or the job information block (JIB), is accessible. You must examine the return length of an item to verify that the item was retrieved. The use of this control flag also implies that $GETJPI does not swap in a process, because $GETJPI would only bring a process into memory to deliver an AST to that process.
JPI$M_IGNORE_TARGET_STATUS	Attempts to retrieve as much information as possible, even though the process might be suspended or is being deleted. This control flag is used to retrieve all possible information from a process.
JPI$M_THREAD	Sets the wildcard mode to return information on all of the process's kernel threads beginning with the initial kernel thread.

**Table SYS-11 Attributes of an Identifier**
Symbolic Name	Description
KGB$M_DYNAMIC	Identifier can be enabled or disabled.
+KGB$M_NOACCESS	Rights of the identifier are null and void.
KGB$M_RESOURCE	Resources can be charged to the identifier.
+KGB$M_SUBSYSTEM	Identifier can be used to create protected subsystems.

+VAX specific

JPI$_IMAGNAME

When you specify JPI$_IMAGNAME, $GETJPI returns, as a character string, the directory specification and the image file name.

JPI$_IMAGPRIV

When you specify JPI$_IMAGPRIV, $GETJPI returns a quadword mask of the privileges with which the current image was installed. If the current image was not installed, $GETJPI returns the value 0 in the buffer.

JPI$_JOBPRCCNT

When you specify JPI$_JOBPRCCNT, $GETJPI returns the total number of subprocesses owned by the job, which is a longword integer value.

JPI$_JOBTYPE

When you specify JPI$_JOBTYPE, $GETJPI returns the execution mode of the process at the root of the job tree, which is a longword integer value. The symbolic name and value for each execution mode are listed in the following table. The $JPIDEF macro defines the symbolic names.

Mode Name	Value
JPI$K_DETACHED	0
JPI$K_NETWORK	1
JPI$K_BATCH	2
JPI$K_LOCAL	3
JPI$K_DIALUP	4
JPI$K_REMOTE	5

JPI$_LAST_LOGIN_I

When you specify JPI$_LAST_LOGIN_I, $GETJPI returns, as a quadword absolute time value, the date of the last successful interactive login prior to the current session. It returns a quadword of 0 when processes have not executed the LOGINOUT image.

JPI$_LAST_LOGIN_N

When you specify JPI$_LAST_LOGIN_N, $GETJPI returns, as a quadword absolute time value, the date of the last successful noninteractive login prior to the current session. It returns a quadword of 0 when processes have not executed the LOGINOUT image.

JPI$_LOGIN_FAILURES

When you specify JPI$_LOGIN_FAILURES, $GETJPI returns the number of login failures that occurred prior to the current session. It returns a longword of 0 when processes have not executed the LOGINOUT image.

JPI$_LOGIN_FLAGS

When you specify JPI$_LOGIN_FLAGS, $GETJPI returns a longword bitmask containing information related to the login sequence. It returns a longword of 0 when processes have not executed the LOGINOUT image. The following bits are defined.

Symbolic Name	Description
JPI$M_NEW_MAIL_AT_LOGIN	User had new mail messages waiting at login.
JPI$M_PASSWORD_CHANGED	User changed the primary password during login.
JPI$M_PASSWORD_EXPIRED	User's primary password expired during login.
JPI$M_PASSWORD_WARNING	System gave the user a warning at login that the account's primary password would expire within 5 days.
JPI$M_PASSWORD2_CHANGED	Account's secondary password was changed during login.
JPI$M_PASSWORD2_EXPIRED	Account's secondary password expired during login.
JPI$M_PASSWORD2_WARNING	System gave the user a warning at login that the account's secondary password would expire within 5 days.

JPI$_LOGINTIM

When you specify JPI$_LOGINTIM, $GETJPI returns the time at which the process was created, which is a standard 64-bit absolute time.

JPI$_MASTER_PID

When you specify JPI$_MASTER_PID, $GETJPI returns the process identification (PID) of the master process in the job. The PID is a longword hexadecimal value.

JPI$_MAXDETACH

When you specify JPI$_MAXDETACH, $GETJPI returns the maximum number of detached processes allowed for the user who owns the process specified in the call to $GETJPI. This limit is set in the UAF record of the user. The number is returned as a word decimal value. A value of 0 means that there is no limit on the number of detached processes for that user name.

JPI$_MAXJOBS

When you specify JPI$_MAXJOBS, $GETJPI returns the maximum number of active processes allowed for the user who owns the process specified in the call to $GETJPI. This limit is set in the UAF record of the user. The number is returned as a word decimal value. A value of 0 means that there is no limit on the number of active processes for that user name.

JPI$_MEM

When you specify JPI$_MEM, $GETJPI returns the member number of the process's UIC, which is a longword integer value.

JPI$_MODE

When you specify JPI$_MODE, $GETJPI returns the mode of the process, which is a longword integer value. The symbolic name and value for each mode are listed in the following table; the $JPIDEF macro defines the symbolic names.

Mode Name	Value
JPI$K_OTHER	0
JPI$K_NETWORK	1
JPI$K_BATCH	2
JPI$K_INTERACTIVE	3

JPI$_MSGMASK

When you specify JPI$_MSGMASK, $GETJPI returns the default message mask of the process, which is a longword bit mask.

JPI$_NODENAME

When you specify JPI$_NODENAME, $GETJPI returns, as a character string, the name of the OpenVMS Cluster node on which the process is running.

JPI$_NODE_CSID

When you specify JPI$_NODE_CSID, $GETJPI returns, as a longword hexadecimal integer, the cluster ID of the OpenVMS Cluster node on which the process is running.

JPI$_NODE_VERSION

When you specify JPI$_NODE_VERSION, $GETJPI returns, as a character string, the operating system version number of the OpenVMS Cluster node on which the process is running.

JPI$_OWNER

When you specify JPI$_OWNER, $GETJPI returns the process identification (PID) of the process that created the specified process. The PID is a longword hexadecimal value.

JPI$_PAGEFLTS

When you specify JPI$_PAGEFLTS, $GETJPI returns the total number of page faults incurred by the process. This is a longword integer value.

JPI$_PAGFILCNT

When you specify JPI$_PAGFILCNT, $GETJPI returns the remaining paging file quota of the process, which is a longword integer value, measured in pages (on VAX systems) or pagelets (on Alpha systems).

JPI$_PAGFILLOC

When you specify JPI$_PAGFILLOC, $GETJPI returns the current paging file assignment of the process. The fourth byte of the returned longword value is the index of the system page file to which the process is currently assigned.

JPI$_PARSE_STYLE_IMAGE

Set by $SET_PROCESS_PROPERTIES, and can be either PARSE_STYLE$C_TRADITIONAL or PARSE_STYLE$C_EXTENDED. The return length is one byte.

JPI$_PARSE_STYLE_PERM

Set by $SET_PROCESS_PROPERTIES, and can be either PARSE_STYLE$C_TRADITIONAL or PARSE_STYLE$C_EXTENDED. The return length is one byte.

JPI$_PERMANENT_AFFINITY_MASK

On Alpha systems, when you specify JPI$_PERMANENT_AFFINITY_MASK, $GETJPI returns the permanent explicit affinity mask for the associated kernel thread.

JPI$_PERMANENT_USERCAP_MASK

On Alpha systems, when you specify JPI$_PERMANENT_USERCAP_MASK, $GETJPI returns the permanent user capability mask for the associated kernel thread.

JPI$_PGFLQUOTA

When you specify JPI$_PGFLQUOTA, $GETJPI 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 systems).

JPI$_PHDFLAGS

When you specify JPI$_PHDFLAGS, $GETJPI returns the process header flags as a longword bit vector.

JPI$_PID

When you specify JPI$_PID, $GETJPI returns the process identification (PID) of the process. The PID is a longword hexadecimal value.

JPI$_P0_FIRST_FREE_VA_64

On Alpha 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.

Contents

Index

privacy and legal statement

4527PRO_043.HTML

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

SS$_NORMAL	Operation was successful; requested data was returned to caller.
SS$_ACCVIO	This status is returned if the caller does not have write access to the two input buffers or if the probe for read access to the item list fails.
SS$_BADPARAM	This status is returned if an empty item list is specified, or if the console callback to read the environment variable fails for any reason.

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

OpenVMS usage:	process_id
type:	longword (unsigned)
access:	modify
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

OpenVMS usage:	process_name
type:	character-coded text string
access:	read only
mechanism:	by 32- or 64-bit descriptor--fixed-length string descriptor (Alpha)
mechanism:	by 32-bit descriptor--fixed-length string descriptor (VAX)

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 (Alpha)
mechanism:	by 32-bit reference (VAX)