OpenVMS System Services Reference Manual

Updated: 11 December 1998

OpenVMS System Services Reference Manual

Contents

Index

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

When you specify JPI$_PPGCNT, $GETJPI returns the number of pages (on VAX systems) or pagelets (on Alpha systems) the process has in the working set. This is a longword integer value.

JPI$_PRCCNT

When you specify JPI$_PRCCNT, $GETJPI 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

When you specify JPI$_PRCLM, $GETJPI returns the subprocess quota of the process, which is a longword integer value.

JPI$_PRCNAM

When you specify JPI$_PRCNAM, $GETJPI 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

When you specify JPI$_PRI, $GETJPI returns the current priority of the process, which is a longword integer value.

JPI$_PRIB

When you specify JPI$_PRIB, $GETJPI returns the base priority of the process, which is a longword integer value.

JPI$_PROCESS_RIGHTS

When you specify JPI$_PROCESS_RIGHTS, $GETJPI 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-11. 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

When you specify JPI$_PROC_INDEX, $GETJPI returns, as a longword integer value, the process index number of the process. The process index number is a number between 1 and the SYSGEN 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

When you specify JPI$_PROCPRIV, $GETJPI returns the default privileges of the process in a quadword bit mask.

JPI$_RIGHTSLIST

When you specify JPI$_RIGHTSLIST, $GETJPI 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-11. 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

When you specify JPI$_RIGHTS_SIZE, $GETJPI 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$_SCHED_POLICY

On Alpha systems, when you specify JPI$_SCHED_POLICY, $GETJPI 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

When you specify JPI$_SHRFILLM, $GETJPI 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

When you specify JPI$_SITESPEC, $GETJPI returns the per-process, site-specific longword, which is a longword integer value.

JPI$_SLOW_VP_SWITCH

When you specify JPI$_SLOW_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 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

When you specify JPI$_STATE, $GETJPI 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. The $STATEDEF macro 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

When you specify JPI$_STS, $GETJPI returns the first longword of the process status flags, which are contained in a longword bit vector. The $PCBDEF macro defines 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

When you specify JPI$_STS2, $GETJPI returns the second longword of the process status flags, which are contained in a longword bit vector. The $PCBDEF macro defines the following symbol for these flags.

Symbol	Description
PCB$V_NOUNSHELVE	Process does not automatically unshelve files.

JPI$_SWPFILLOC

When you specify JPI$_SWPFILLOC, $GETJPI 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

When you specify JPI$_SYSTEM_RIGHTS, $GETJPI returns the system rights list as an array of quadword identifiers. Each entry consists of a longword identifier value and longword identifier attributes, shown in Table SYS-11. 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$_TABLENAME

When you specify JPI$_TABLENAME, $GETJPI 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

When you specify JPI$_TERMINAL, $GETJPI returns, for interactive users, the process's login terminal name as a character string. Because the terminal name can include up to 8 characters, the buffer length field in the item descriptor should specify at least 8 bytes. Trailing zeros are written to the output buffer if necessary.

JPI$_TMBU

When you specify JPI$_TMBU, $GETJPI returns the termination mailbox unit number, which is a longword integer value.

JPI$_TQCNT

When you specify JPI$_TQCNT, $GETJPI returns the remaining timer queue entry quota of the process, which is a longword integer value.

JPI$_TQLM

When you specify JPI$_TQLM, $GETJPI returns the process's limit on timer queue entries, which is a longword integer value.

JPI$_TT_ACCPORNAM

When you specify JPI$_TT_ACCPORNAM, $GETJPI returns the access port name for the terminal associated with the process. (The terminal name is returned by JPI$_TERMINAL.) 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. Otherwise, it returns a null string.

JPI$_TT_PHYDEVNAM

When you specify JPI$_TT_PHYDEVNAM, $GETJPI 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

When you specify JPI$_UAF_FLAGS, $GETJPI 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

When you specify JPI$_UIC, $GETJPI returns the UIC of the process in the standard longword format.

JPI$_USERNAME

When you specify JPI$_USERNAME, $GETJPI 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

When you specify JPI$_VIRTPEAK, $GETJPI returns the peak virtual address size---in pages for VAX or pagelets for Alpha---of the process.

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 virtual peak exceeds the maximum value that can be represented in a longword, $GETJPI returns the largest positive 32-bit integer: 2147483647.

JPI$_VOLUMES

When you specify JPI$_VOLUMES, $GETJPI returns the number of volumes that the process currently has mounted, which is a longword integer value.

JPI$_VP_CONSUMER

When you specify JPI$_VP_CONSUMER, $GETJPI returns a byte, the low-order bit of which, when set, indicates that the process is a vector consumer.

JPI$_VP_CPUTIM

When you specify JPI$_VP_CPUTIM, $GETJPI returns an unsigned longword that contains the total amount of time the process has accumulated as a vector consumer.

JPI$_WSAUTH

When you specify JPI$_WSAUTH, $GETJPI returns the maximum authorized working set size, in pages (on VAX systems) or pagelets (on Alpha systems), of the process. This is a longword integer value.

JPI$_WSAUTHEXT

When you specify JPI$_WSAUTHEXT, $GETJPI returns, in pages (on VAX systems) or pagelets (on Alpha systems), the maximum authorized working set extent of the process as a longword integer value.

JPI$_WSEXTENT

When you specify JPI$_WSEXTENT, $GETJPI returns, in pages (on VAX systems) or pagelets (on Alpha systems), the current working set extent of the process as a longword integer value.

JPI$_WSPEAK

When you specify JPI$_WSPEAK, $GETJPI returns, in pages (on VAX systems) or pagelets (on Alpha systems), the peak working set size of the process as a longword integer value.

JPI$_WSQUOTA

When you specify JPI$_WSQUOTA, $GETJPI returns, in pages (on VAX systems) or pagelets (on Alpha systems), the working set size quota of the process as a longword integer value.

JPI$_WSSIZE

When you specify JPI$_WSSIZE, $GETJPI returns, in pages (on VAX systems) or pagelets (on Alpha systems), the current working set size 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.
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$_NONEXPR The specified process does not exist, or an invalid process identification was specified.

SS$_NOPRIV The process does not have the privilege to obtain information about the specified process.

SS$_NOSUCHNODE The specified node is not currently a member of the cluster.

SS$_REMRSRC The remote node has insufficient resources to respond to the request. (Bring this error to the attention of your system manager.)

SS$_SUSPENDED The specified process is suspended or in a miscellaneous wait state, and the requested information cannot be obtained.

SS$_UNREACHABLE The remote node is a member of the cluster but is not accepting requests. This is normal for a brief period early in the system boot process.

Condition Values Returned in the I/O Status Block

Same as those returned in R0.

Example


/ / Defining __NEW_STARLET enables the program to benefit from better type checking for prototypes and structures provided by OpenVMS. / #define __NEW_STARLET 1 #include <efndef> / No Event Flag Event Flag / #include <iledef> / Item List Entry Definitions / #include <iosbdef> / I/O Status Block Structure Definition / #include <jpidef> / $GETJPI Item Code Definitions / #include <ssdef> / SS Message Codes / #include <starlet> / Function Prototypes for System Services / #include <stdio> / C Standard I/O Functions / #include <string> / MEMSET Prototype / #include <stsdef> / Status Block Definitions / #define NUM_ILE 5 #define NAME_LENGTH 16 #define IMAGE_LENGTH 255 / Macro to initialize a 32-bit item_list_3. / #define init_ile32(ile, length, code, bufaddr, retlen_addr) \ { (ile)->ile3$w_length = (length); \ (ile)->ile3$w_code = (code); \ (ile)->ile3$ps_bufaddr = (bufaddr); \ (ile)->ile3$ps_retlen_addr = (retlen_addr); } main () { char imagename [IMAGE_LENGTH], procname [NAME_LENGTH], username [NAME_LENGTH]; int count = 0, retpid, status; unsigned int pid = -1; unsigned short imagename_length, procname_length, username_length; ILE3 jpi_ile [NUM_ILE]; IOSB iosb; / Zeroing the item list has the effect of creating the terminating entry. / memset (jpi_ile, 0, ILE3$K_LENGTHNUM_ILE); /* Initialize the item list entries to fetch the user name, the process name, the image name and the PID. / init_ile32 ( &jpi_ile [0], NAME_LENGTH, JPI$_USERNAME, username, &username_length); init_ile32 ( &jpi_ile [1], NAME_LENGTH, JPI$_PRCNAM, procname, &procname_length); init_ile32 ( &jpi_ile [2], IMAGE_LENGTH, JPI$_IMAGNAME, imagename, &imagename_length); init_ile32 ( &jpi_ile [3], sizeof (int), JPI$_PID, &retpid, NULL); / Initial wildcard $GETJPI. / status = sys$getjpiw ( EFN$C_ENF, &pid, NULL, &jpi_ile, &iosb, NULL, 0); / Loop for all processes on this node. / while (status != SS$_NOMOREPROC) { if (status & STS$M_SUCCESS) { / Zero terminate process and image name strings. / imagename [imagename_length] = '\0'; username [username_length] = '\0'; procname [procname_length] = '\0'; / Print header if this is the first. / if (count == 0) printf (" PID User Name Process Name Image\n"); / Count process and print process data. / count++; printf ("%08X %-15s %-15s %s\n", retpid, username, procname, imagename); } / Skip process if suspended or no privilege to see process. Return any other error. / else if ((status != SS$_NOPRIV) && (status != SS$_SUSPENDED)) return (status); / Find next process. */ status = sys$getjpiw ( EFN$C_ENF, &pid, NULL, &jpi_ile, &iosb, NULL, 0); } return (SS$_NORMAL); }

*/ 
 
/*  Defining __NEW_STARLET enables the program to benefit from better type 
    checking for prototypes and structures provided by OpenVMS.             
*/ 
 
#define     __NEW_STARLET       1 
 
#include    <efndef>            /*  No Event Flag Event Flag  */ 
#include    <iledef>            /*  Item List Entry Definitions  */ 
#include    <iosbdef>           /*  I/O Status Block Structure Definition  */ 
#include    <jpidef>            /*  $GETJPI Item Code Definitions  */ 
#include    <ssdef>             /*  SS Message Codes  */ 
#include    <starlet>           /*  Function Prototypes for System Services */ 
#include    <stdio>             /*  C Standard I/O Functions  */ 
#include    <string>            /*  MEMSET Prototype  */ 
#include    <stsdef>            /*  Status Block Definitions  */ 
 
#define     NUM_ILE               5 
#define     NAME_LENGTH          16 
#define     IMAGE_LENGTH        255 
 
 
/*  Macro to initialize a 32-bit item_list_3.                 */ 
 
#define init_ile32(ile, length, code, bufaddr, retlen_addr) \
{   (ile)->ile3$w_length = (length);           \
    (ile)->ile3$w_code = (code);         \
    (ile)->ile3$ps_bufaddr = (bufaddr); \
    (ile)->ile3$ps_retlen_addr = (retlen_addr); } 
main () 
{ 
char 
    imagename [IMAGE_LENGTH], 
    procname [NAME_LENGTH], 
    username [NAME_LENGTH]; 
 
int 
    count = 0, 
    retpid, 
    status; 
 
unsigned int 
    pid = -1; 
 
unsigned short 
    imagename_length, 
    procname_length, 
    username_length; 
 
ILE3 
    jpi_ile [NUM_ILE]; 
 
IOSB 
    iosb; 
 
 
/*  Zeroing the item list has the effect of creating the terminating entry. */ 
 
    memset (jpi_ile, 0, ILE3$K_LENGTH*NUM_ILE); 
 
 
/*  Initialize the item list entries to fetch the user name, the process 
    name, the image name and the PID.                                     */ 
 
    init_ile32 ( 
        &jpi_ile [0], 
        NAME_LENGTH, 
        JPI$_USERNAME, 
        username, 
        &username_length); 
 
    init_ile32 ( 
        &jpi_ile [1], 
        NAME_LENGTH, 
        JPI$_PRCNAM, 
        procname, 
        &procname_length); 
 
    init_ile32 ( 
        &jpi_ile [2], 
        IMAGE_LENGTH, 
        JPI$_IMAGNAME, 
        imagename, 
        &imagename_length); 
 
    init_ile32 ( 
        &jpi_ile [3], 
        sizeof (int), 
        JPI$_PID, 
        &retpid, 
        NULL); 
 
 
/*  Initial wildcard $GETJPI.                                               
*/ 
 
    status = sys$getjpiw ( 
        EFN$C_ENF, 
        &pid, 
        NULL, 
        &jpi_ile, 
        &iosb, 
        NULL, 
        0); 
/*  Loop for all processes on this node.                        */ 
 
    while (status != SS$_NOMOREPROC) 
    { 
        if (status & STS$M_SUCCESS) 
        { 
 
 
/*  Zero terminate process and image name strings.               */ 
 
            imagename [imagename_length] = '\0'; 
            username [username_length] = '\0'; 
            procname [procname_length] = '\0'; 
 
 
/*  Print header if this is the first.                           */ 
 
            if (count == 0) 
                printf ("   PID   User Name       Process Name 
Image\n"); 
 
 
/*  Count process and print process data.                          */ 
 
            count++; 
            printf ("%08X %-15s %-15s %s\n", 
                retpid, 
                username, 
                procname, 
                imagename); 
        } 
 
 
/*  Skip process if suspended or no privilege to see process.  Return any 
    other error.                                                         */ 
 
        else if ((status != SS$_NOPRIV) && (status != SS$_SUSPENDED)) 
            return (status); 
 
 
/*  Find next process.                                                    */ 
 
        status = sys$getjpiw ( 
            EFN$C_ENF, 
            &pid, 
            NULL, 
            &jpi_ile, 
            &iosb, 
            NULL, 
            0); 
    } 
    return (SS$_NORMAL); 
}

This example C program demonstrates how to use $GETJPIW to obtain the PID, process name, and current image being executed for every process for which the caller has the privilege to obtain information.

Contents

Index

Legal

 
4527PRO_044.HTML

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$_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.