HP OpenVMS System Services Reference Manual


Previous Contents Index

Each of these item codes requires that the buffer specify a longword into which $GETDVI will write a 0 or 1: 0 if the terminal does not have the specified characteristic, and 1 if the terminal does have it. The one exception is the DVI$_TT_PAGE item code, which when specified causes $GETDVI to return a decimal longword value that is the page size of the terminal.

You can also obtain this terminal-specific information by using the DVI$_DEVDEPEND and DVI$_DEVDEPEND2 item codes. Each of these two item codes specifies a longword bit vector wherein each bit corresponds to a terminal characteristic; $GETDVI sets the corresponding bit for each characteristic possessed by the terminal.

Following is a list of the item codes that return information about terminal characteristics. For information about these characteristics, see the description of the F$GETDVI lexical function in the HP OpenVMS DCL Dictionary.
DVI$_TT_NOECHO DVI$_TT_NOTYPEAHD
DVI$_TT_HOSTSYNC DVI$_TT_TTSYNC
DVI$_TT_ESCAPE DVI$_TT_LOWER
DVI$_TT_MECHTAB DVI$_TT_WRAP
DVI$_TT_LFFILL DVI$_TT_SCOPE
DVI$_TT_CRFILL DVI$_TT_SETSPEED
DVI$_TT_EIGHTBIT DVI$_TT_MBXDSABL
DVI$_TT_READSYNC DVI$_TT_MECHFORM
DVI$_TT_NOBRDCST DVI$_TT_HALFDUP
DVI$_TT_MODEM DVI$_TT_OPER
DVI$_TT_LOCALECHO DVI$_TT_AUTOBAUD
DVI$_TT_PAGE DVI$_TT_HANGUP
DVI$_TT_MODHANGUP DVI$_TT_BRDCSTMBX
DVI$_TT_DMA DVI$_TT_ALTYPEAHD
DVI$_TT_ANSICRT DVI$_TT_REGIS
DVI$_TT_AVO DVI$_TT_EDIT
DVI$_TT_BLOCK DVI$_TT_DECCRT
DVI$_TT_EDITING DVI$_TT_INSERT
DVI$_TT_DIALUP DVI$_TT_SECURE
DVI$_TT_FALLBACK DVI$_TT_DISCONNECT
DVI$_TT_PASTHRU DVI$_TT_SIXEL
DVI$_TT_PRINTER DVI$_TT_APP_KEYPAD
DVI$_TT_DRCS DVI$_TT_SYSPWD
DVI$_TT_DECCRT2  
DVI$_TT_DECCRT3  
DVI$_TT_DECCRT4  

DVI$_WRITETHRU_CACHE_ENABLED

On Alpha and I64 systems, returns an unsigned longword, which is interpreted as Boolean. A value of 1 indicates the volume is mounted with write-through caching enabled.

DVI$_WWID

On Alpha and I64 systems, returns the World Wide Identifier (WWID) of Fibre Channel Disk and Tape devices as a string. The maximum length of this string might change with new devices; therefore, HP recommends that a 380-byte buffer be passed to this function.

DVI$_yyyy

DVI$_yyyy is the format for a series of item codes that return device-independent characteristics of a device. There is an item code for each device characteristic returned in the longword bit vector specified by the DVI$_DEVCHAR item code.

In the description of the DVI$_DEVCHAR item code is a list of symbol names in which each symbol represents a device characteristic. To construct the $GETDVI item code for each device characteristic, substitute for yyyy that portion of the symbol name that follows the underscore character. For example, the DVI$_REC item code returns the same information as the DEV$V_REC bit in the DVI$_DEVCHAR longword bit vector.

The buffer for each of these item codes must specify a longword value, which is interpreted as Boolean. The $GETDVI service writes the value 1 into the longword if the device has the specified characteristic and the value 0 if it does not.


Description

The Get Device/Volume Information service returns primary and secondary device characteristics information about an I/O device. You can use the chan argument only if (1) the channel has already been assigned, and (2) the caller's access mode is equal to or more privileged than the access mode from which the original channel assignment was made.

The caller of $GETDVI does not need to have a channel assigned to the device about which information is desired.

The $GETDVI service returns information about both primary device characteristics and secondary device characteristics. By default, $GETDVI returns information about the primary device characteristics only.

To obtain information about secondary device characteristics, you must perform a logical OR operation on the item code specifying the information desired with the code DVI$C_SECONDARY.

You can obtain information about primary and secondary devices in a single call to $GETDVI.

In most cases, the two sets of characteristics (primary and secondary) returned by $GETDVI are identical. However, the two sets provide different information in the following cases:

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_PATH_SCAN, $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.
SS$_NOSUCHPATH On Alpha and I64 systems, the specified path does not exist for the device, even though the device itself does exist.
SS$_UNSUPPORTED One or more of the item codes are not supported on the device specified.

Condition Values Returned in the I/O Status Block

1
The condition values returned are the 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. 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, see 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).

HP 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 HP OpenVMS Programming Concepts Manual.

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.


Previous Next Contents Index