$GETJPI

From VSI OpenVMS Wiki
Jump to: navigation, search

SYS$GETJPI, or Get Job/Process Information, is a system service that 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.

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.

Syntax

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). 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: ef_number
Type: longword (unsigned)
Access: read only
Mechanism: by value

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.

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.

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.

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:

  • 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

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.

Item Codes

Item Code Description
JPI$_ACCOUNT Returns the account name of the process, which is an 8-byte string, filled with trailing blanks if necessary.
JPI$_APTCNT Returns, in pagelets, the active page table count of the process, which is a longword integer value.
JPI$_ASTACT 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 Returns a count of the remaining AST quota, which is a longword integer value.
JPI$_ASTEN 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.
JPI$_ASTLM Returns the AST limit quota of the process, which is a longword integer value.
JPI$_AUTHPRI 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 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 Returns a count of the remaining buffered I/O quota, which is a longword integer value.
JPI$_BIOLM Returns the buffered I/O limit quota of the process, which is a longword integer value.
JPI$_BUFIO Returns a count of the buffered I/O operations of the process, which is a longword integer value.
JPI$_BYTCNT Returns the remaining buffered I/O byte count quota of the process, which is a longword integer value.
JPI$_BYTLM Returns the buffered I/O byte count limit quota of the process, which is a longword integer value.
JPI$_CASE_LOOKUP_PERM On Alpha and Integrity server systems, returns information about the file name lookup case sensitivity of a specified process. This value is set for the life of the process unless the style is set again. Values are 0 (PPROP$K_CASE_BLIND) and 1 (PPROP$K_CASE_SENSITIVE).

For additional information, see the [Guide to OpenVMS File Applications].

JPI$_CASE_LOOKUP_TEMP On Alpha and Integrity server systems, returns information about the file name lookup case sensitivity of a specified process. This value is set only for the life of the image. Values are 0 (PPROP$K_CASE_BLIND) and 1 (PPROP$K_CASE_SENSITIVE).

For additional information, see the [Guide to OpenVMS File Applications].

JPI$_CHAIN 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$_CLASSIFICATION On Alpha and Integrity server systems, returns, as a 20-byte padded string, the current MAC classification stored in the PSB.
JPI$_CLINAME 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 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 Returns the CPU time limit of the process, which is a longword integer value.
JPI$_CPUTIM Returns the process's accumulated CPU time in 10-millisecond ticks, which is a longword integer value.
JPI$_CREPRC_FLAGS 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 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 and Integrity server systems, returns the current explicit affinity mask for the associated kernel thread.
JPI$_CURRENT_USERCAP_MASK On Alpha and Integrity server systems, returns the current user capability mask for the associated kernel thread.
JPI$_DEADLOCK_WAIT Returns the per-process deadlock wait ticks. This value is in 100-nsec units.
JPI$_DFMBC Returns the default multibuffer count for a process as a longword integer value.
JPI$_DFPFC Returns the default page fault cluster size of the process, which is a longword integer value measured in pagelets.
JPI$_DFWSCNT Returns, in pagelets , the default working set size of the process, which is a longword integer value.
JPI$_DIOCNT Returns the remaining direct I/O quota of the process, which is a longword integer value.
JPI$_DIOLM Returns the direct I/O quota limit of the process, which is a longword integer value.
JPI$_DIRIO Returns a count of the direct I/O operations of the process, which is a longword integer value.
JPI$_EFCS Returns the state of the process's local event flags 0 through 31 as a longword bit vector.
JPI$_EFCU Returns the state of the process's local event flags 32 through 63 as a longword bit vector.
JPI$_EFWM Returns the event flag wait mask of the process, which is a longword bit vector.
JPI$_ENQCNT Returns the remaining lock request quota of the process, which is a longword integer value.
JPI$_ENQLM Returns the lock request quota of the process, which is a longword integer value.
JPI$_EXCVEC 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$_FILCNT Returns the remaining open file quota of the process, which is a longword integer value.
JPI$_FILLM Returns the open file limit quota of the process, which is a longword value.
JPI$_FINALEXC 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 Returns the address of the first free page at the end of the program region (P0 space) of the process.
JPI$_FREP1VA Returns the address of the first free page at the end of the control region (P1 space) of the process.
JPI$_FREPTECNT Returns the number of pagelets that the process has available for virtual memory expansion.

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 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 Returns, in pagelets, the process's global page count in the working set, which is a longword integer value.
JPI$_GRP Returns, as a longword integer value, the group number of the process's UIC.
JPI$_HOME_RAD Returns the home RAD. RAD is supported on AlphaServer GS series systems and starting from OpenVMS Version 8.4, support is extended to NUMA capable Integrity servers.
JPI$_IMAGECOUNT Returns, as a longword integer value, the number of images that have been run down for the process.
JPI$_IMAGE_AUTHPRIV On Alpha and Integrity server systems, returns the authorized privilege mask of the installed image. These privileges are returned in a quadword privilege mask and are defined by the $PRVDEF macro.
JPI$_IMAGE_PERMPRIV On Alpha and Integrity server systems, returns the permanent (default) privilege mask of the installed image.

These privileges are returned in a quadword privilege mask and are defined by the $PRVDEF macro.

JPI$_IMAGE_RIGHTS 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 the table below. 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.

Attributes of an identifier

Symbolic name Description
KGB$M_DYNAMIC Identifiers can be enabled or disabled
KGB$M_RESOURCE Resources can be charged to the identifier
JPI$_IMAGE_WORKPRIV On Alpha and Integrity server systems, returns the working (active) privilege mask of the installed image.

These privileges are returned in a quadword privilege mask and are defined by the $PRVDEF macro.

JPI$_IMAGNAME Returns, as a character string, the directory specification and the image file name.
JPI$_IMAGPRIV 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$_INITIAL_THREAD_PID On Alpha and Integrity server systems, returns the PID of the initial thread for the target process. The PID is a longword hexadecimal value.
JPI$_INSTALL_RIGHTS On Alpha and Integrity server systems, returns the binary content of the install rights list as an array of quadword identifiers. Each entry consists of a longword identifier value and longword identifier attributes, as shown in the table for JPI$_IMAGE_RIGHTS above. The install rights list is a set of identifiers associated with an installed image.
JPI$_INSTALL_RIGHTS_SIZE On Alpha and Integrity server systems, returns a longword integer containing the number of bytes needed to store the install rights.
JPI$_JOBPRCCNT Returns the total number of subprocesses owned by the job, which is a longword integer value.
JPI$_JOBTYPE 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$_KT_COUNT On Alpha and Integrity server systems, returns the current count of kernel threads for the target process, which is a longword integer value.
JPI$_KT_LIMIT On Alpha and Integrity server systems, returns the maximum number of kernel threads that can be created in the process. A value of 0 indicates that the process does not have a process-specific limit set, and the systemwide limit specified by the SYSGEN parameter MULTITHREAD is used.
JPI$_LAST_LOGIN_I 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 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 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 Returns a longword bit mask 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 Returns the time at which the process was created, which is a standard 64-bit absolute time.
JPI$_MASTER_PID Returns the process identification (PID) of the master process in the job. The PID is a longword

hexadecimal value.

JPI$_MAXDETACH 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 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 Returns the member number of the process's UIC, which is a longword integer value.
JPI$_MODE 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 Returns the default message mask of the process, which is a longword bit mask.
JPI$_MULTITHREAD On Alpha and Integrity server systems, returns the maximum kernel thread count allowed for the target process, which is a longword integer value.
JPI$_NODENAME Returns, as a character string, the name of the OpenVMS Cluster node on which the process is running.
JPI$_NODE_CSID Returns, as a longword hexadecimal integer, the cluster ID of the OpenVMS Cluster node on which the process is running.
JPI$_NODE_VERSION Returns, as a character string, the operating system version number of the OpenVMS Cluster node on which the process is running.
JPI$_OWNER Returns the process identification (PID) of the process that created the specified process. The PID is a longword hexadecimal value.
JPI$_PAGEFLTS Returns the total number of page faults incurred by the process. This is a longword integer value.
JPI$_PAGFILCNT Returns the remaining paging file quota of the process, which is a longword integer value, measured in pages pagelets.
JPI$_PAGFILLOC 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 On Alpha and Integrity server systems, set by $SET_PROCESS_PROPERTIESW, and can be either PARSE_STYLE$C_TRADITIONAL or PARSE_STYLE$C_EXTENDED (located in PPROPDEF).

The return length is one byte.

JPI$_PARSE_STYLE_PERM On Alpha and Integrity server systems, set by $SET_PROCESS_PROPERTIESW, and can be either PARSE_STYLE$C_TRADITIONAL or PARSE_STYLE$C_EXTENDED (located in PPROPDEF).

The return length is one byte.

JPI$_PERMANENT_AFFINITY_MASK On Alpha and Integrity server systems, returns the permanent explicit affinity mask for the associated kernel thread.
JPI$_PERMANENT_USERCAP_MASK On Alpha and Integrity server systems, returns the permanent explicit affinity mask for the associated kernel thread.
JPI$_PERSONA_AUTHPRIV On Alpha and Integrity server systems, returns the authorized privilege mask of the persona.

These privileges are returned in a quadword privilege mask and are defined by the $PRVDEF macro.

JPI$_PERSONA_ID On Alpha and Integrity server systems, returns, as a longword integer, the ID of the persona.
JPI$_PERSONA_PERMPRIV On Alpha and Integrity server 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 Integrity server 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 42. The persona rights list is a set of identifiers associated with the process.
JPI$_PERSONA_RIGHTS_SIZE On Alpha and Integrity server systems, returns a longword integer containing the number of bytes needed to store the persona rights.
JPI$_PERSONA_WORKPRIV On Alpha and Integrity server 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 pagelets.
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 Integrity server 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 Integrity server 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 Integrity server 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 pagelets 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 the table for JPI$_IMAGE_RIGHTS above.

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 the table for JPI$_IMAGE_RIGHTS above. 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 Integrity server 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$_SEARCH_SYMLINK_PERM On Alpha and Integrity server systems, returns the permanent process symlink search modes.

Values are JPI$K_SEARCH_SYMLINK_NONE, JPI$K_SEARCH_SYMLINK_ALL, and JPI$K_SEARCH_SYMLINK_NOELLIPS.

JPI$_SEARCH_SYMLINK_TEMP On Alpha and Integrity server systems, returns the temporary process symlink search modes.

Values are JPI$K_SEARCH_SYMLINK_NONE, JPI$K_SEARCH_SYMLINK_ALL, and JPI$K_SEARCH_SYMLINK_NOELLIPS.

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$_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 Integrity server 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 the table for JPI$_IMAGE_RIGHTS above. 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 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 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:
  • 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 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 count of volume mount operations that the process has done, 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.


Condition Values Returned

Value Description
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 theattention 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.

Privileges Required

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.

Quota Required

None

See also

Retrieved from "https://wiki.vmssoftware.com/index.php?title=$GETJPI&oldid=1439"