 |
OpenVMS System Services Reference Manual
Unless otherwise stated in the description of the item code, $GETDVI
returns information about the local node only.
Required Access or Privileges
None
Required Quota
Sufficient AST quota.
Related Services
$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC,
$DASSGN, $DELMBX, $DEVICE_SCAN, $DISMOU, $GETDVIW, $GETMSG, $GETQUI,
$GETQUIW, $INIT_VOL, $IO_FASTPATH, $MOUNT, $PUTMSG, $QIO, $QIOW,
$SNDERR, $SNDJBC, $SNDJBCW, $SNDOPR
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The device name string descriptor, device name string, or
itmlst argument cannot be read; or the buffer or
return length longword cannot be written by the caller.
|
|
SS$_BADPARAM
|
The item list contains an invalid item code, or the buffer address
field in an item descriptor specifies less than four bytes for the
return length information.
|
|
SS$_EXASTLM
|
The process has exceeded its AST limit quota.
|
|
SS$_IVCHAN
|
You specified an invalid channel number, that is, a channel number
larger than the number of channels.
|
|
SS$_IVDEVNAM
|
The device name string contains invalid characters, or neither the
devnam nor
chan argument was specified.
|
|
SS$_IVLOGNAM
|
The device name string has a length of 0 or has more than 63 characters.
|
|
SS$_NONLOCAL
|
The device is on a remote system.
|
|
SS$_NOPRIV
|
The specified channel is not assigned or was assigned from a more
privileged access mode.
|
|
SS$_NOSUCHDEV
|
The specified device does not exist on the host system.
|
Condition Values Returned in the I/O Status Block1
Same as those returned in R0.
$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:
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.
|
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.
|
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.
|
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
Returns the account name of the process, which is an 8-byte string,
filled with trailing blanks if necessary.
JPI$_APTCNT
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
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.
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
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$_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$_CLASS_NAME
Returns the name of the scheduling class (as a character string) that
this process belongs to. 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$_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 systems, returns the current explicit affinity mask for the
associated kernel thread.
JPI$_CURRENT_USERCAP_MASK
On Alpha systems, returns the current user capability mask for the
associated kernel thread.
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 pages (on VAX systems) or pagelets
(on Alpha systems).
JPI$_DFWSCNT
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
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$_FAST_VP_SWITCH
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
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 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.
|
