/sys$common/syshlp/helplib.hlb System Services, $GETJPI  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    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.

    Refer to the OpenVMS System Services Reference Manual to view the
    item code diagrams and descriptor fields tables.

 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:

    o  If you are using an event flag to signal the completion of
       the service, you can test the I/O status block for a condition
       value to be sure that the event flag was not set by an event
       other than service completion.

    o  If you are using the $SYNCH service to synchronize completion
       of the service, the I/O status block is a required argument
       for $SYNCH.

    o  The condition value returned in R0 and the condition value
       returned in the I/O status block provide information about
       different aspects of the call to the $GETJPI service. The
       condition value returned in R0 gives you information about the
       success or failure of the service call itself; the condition
       value returned in the I/O status block gives you information
       about the success or failure of the service operation.
       Therefore, to accurately assess the success or failure of the
       call to $GETJPI, you must check the condition values returned
       in both R0 and the I/O status block.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by 32- or 64-bit reference (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.