HP OpenVMS Systems Documentation

Content starts here

HP OpenVMS System Services Reference Manual


Previous Contents Index


$GETDVIW

Returns information about an I/O device; this information consists of primary and secondary device characteristics.

The $GETDVIW service completes synchronously; that is, it returns to the caller with the requested information. HP 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.

Note

All pathname-related information pertains only to Alpha and I64 systems.

For additional information about system service completion, refer to the Synchronize ($SYNCH) service.


Format

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


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.

$GET_GALAXY_LOCK_INFO (Alpha Only)

Returns "interesting" fields from the specified lock.

Note that this system service is supported only in an OpenVMS Alpha Galaxy environment. For more information about programming with OpenVMS Galaxy system services, refer to the HP OpenVMS Alpha Partitioning and Galaxy Guide.


Format

SYS$GET_GALAXY_LOCK_INFO handle ,name ,timeout ,size ,ipl ,rank ,flags [,name_length]


C Prototype

int sys$get_galaxy_lock_info (unsigned __int64 lock_handle, char *name, unsigned int *timeout, unsigned int *size, unsigned int *ipl, unsigned int *rank, unsigned short int *flags unsigned short int *name_length);


Arguments

handle


OpenVMS usage: handle for the galaxy lock
type: quadword (unsigned)
access: read
mechanism: input by value

The 64-bit lock handle that identifies the lock on which to return information. This value is returned by SYS$CREATE_GALAXY_LOCK.

name


OpenVMS usage: address
type: zero-terminated string
access: write
mechanism: output by reference

Pointer to a buffer. This buffer must be large enough to receive the name of the lock. Locks names are zero-terminated strings with a maximum size of 16 bytes.

timeout


OpenVMS usage: address
type: longword (unsigned)
access: write
mechanism: output by reference

Pointer to a longword. The value returned is the timeout value of the lock.

size


OpenVMS usage: address
type: longword (unsigned)
access: write
mechanism: output by reference

Pointer to a longword. The value returned is the size of the lock in bytes.

ipl


OpenVMS usage: address
type: longword (unsigned)
access: write
mechanism: output by reference

Pointer to a longword. The value returned is the IPL of the lock.

rank


OpenVMS usage: address
type: longword (unsigned)
access: write
mechanism: output by reference

Pointer to a longword. The value returned is the rank of the lock.

flags


OpenVMS usage: address
type: word (unsigned)
access: write
mechanism: output by reference

Pointer to a word. The value returned is the word mask of lock flags.

name_length


OpenVMS usage: address
type: word (unsigned)
access: write
mechanism: output by reference

Length of the string returned in the name argument.

Description

This service returns all "interesting" fields from the specified lock. See the $CREATE_GALAXY_LOCK service for detailed information regarding these values.

Required Access or Privileges

Read access to lock.

Required Quota

None

Related Services

$ACQUIRE_GALAXY_LOCK, $CREATE_GALAXY_LOCK, $CREATE_GALAXY_LOCK_TABLE, $DELETE_GALAXY_LOCK, $DELETE_GALAXY_LOCK_TABLE, $GET_GALAXY_LOCK_SIZE, $RELEASE_GALAXY_LOCK


Condition Values Returned

SS$_NORMAL Normal completion.
SS$_IVLOCKID Invalid lock id.
SS$_IVLOCKTBL Invalid lock table.

$GET_GALAXY_LOCK_SIZE (Alpha Only)

Returns the minimum and maximum size of an OpenVMS Galaxy lock.

Note that this system service is supported only in an OpenVMS Alpha Galaxy environment.

For more information about programming with OpenVMS Galaxy system services, refer to the HP OpenVMS Alpha Partitioning and Galaxy Guide.


Format

SYS$GET_GALAXY_LOCK_SIZE min_size ,max_size


C Prototype

int sys$get_galaxy_lock_size (unsigned int *min_size, unsigned int *max_size);


Arguments

min_size


OpenVMS usage: address
type: longword (unsigned)
access: write
mechanism: output by reference

Pointer to a longword. The value returned is minimum legal size of a galaxy lock structure.

max_size


OpenVMS usage: address
type: longword (unsigned)
access: write
mechanism: output by reference

Pointer to a longword. The value returned is maximum legal size of a galaxy lock structure.

Description

This service returns the minimum and maximum size of an OpenVMS Galaxy lock. If a lock is created with the maximum size, the locking services will record acquire and release information in the lock.

The lock sizes can be used to determine the value of the section_size parameter to the $CREATE_GALAXY_LOCK_TABLE service.

Required Access or Privileges

Read access to lock.

Required Quota

None

Related Services

$ACQUIRE_GALAXY_LOCK, $CREATE_GALAXY_LOCK, $CREATE_GALAXY_LOCK_TABLE, $DELETE_GALAXY_LOCK, $DELETE_GALAXY_LOCK_TABLE, $GET_GALAXY_LOCK_INFO, $RELEASE_GALAXY_LOCK


Condition Values Returned

SS$_NORMAL Normal completion.

$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 and I64 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).

If you are not using event flags, you can specify this as EFN$C_ENF (this is defined in EFNDEF). Refer to the OpenVMS Programming Concepts Manual for additional information.

pidadr


OpenVMS usage: process_id
type: longword (unsigned)
access: modify
mechanism: by 32- or 64-bit reference (Alpha and I64)
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 and I64 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 and I64)
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 and I64 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 and I64)
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 and I64 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 and I64)
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 and I64 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, HP 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 and I64)
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 and I64 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 and I64 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.

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

Refer to the Guide to OpenVMS File Applications for additional information.

JPI$_CASE_LOOKUP_TEMP

On Alpha and I64 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).

Refer to the Guide to OpenVMS File Applications for additional information.

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 I64 systems, returns, as a 20-byte padded string, the current MAC classification stored in the PSB.

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 and I64 systems, returns the current explicit affinity mask for the associated kernel thread.

JPI$_CURRENT_USERCAP_MASK

On Alpha and I64 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 and I64 systems).

JPI$_DFWSCNT

Returns, in pages (on VAX systems) or pagelets (on Alpha and I64 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.


Previous Next Contents Index