OpenVMS System Services Reference Manual

Document revision date: 15 July 2002

OpenVMS System Services Reference Manual

Contents

Index

Note

Shadow set members must have a nonzero allocation class to operate in an OpenVMS Cluster system. Refer to Volume Shadowing for OpenVMS for more information.

Because the shadow set virtual unit name can include up to 64 characters, the buffer length field of the item descriptor should specify 64 (bytes).

DVI$_SHDW_MEMBER

Returns a longword, which is interpreted as Boolean. The value 1 indicates that the device is a shadow set member.

DVI$_SHDW_MERGE_COPYING

Returns a longword, which is interpreted as Boolean. The value 1 indicates that the device is a merge member of the shadow set.

DVI$_SHDW_NEXT_MBR_NAME

Returns the device name of the next member in the shadow set. If you specify a virtual unit with the chan or devnam argument, DVI$_SHDW_NEXT_MBR_NAME returns the device name of a member of a shadow set. If you specify the name of a shadow set member unit with the chan or devnam argument, DVI$_SHDW_NEXT_MBR_NAME returns the name of the next member unit or a null string if there are no more members.

To determine all the members of a shadow set, first specify the virtual unit (DSAnnnn:) to $GETDVI. Then, on subsequent calls, specify the member name returned by the previous $GETDVI call until it returns a null member name.

When the shadow set members have a nonzero allocation class, the device name returned by $GETDVI contains the allocation class; the name has the form $allocation-class$device. For example, if a shadow set has an allocation class of 255 and the device name is DUA42, $GETDVI returns the string $255$DUA42.

Note

Shadow set members must have a nonzero allocation class to operate in an OpenVMS Cluster system. Refer to Volume Shadowing for OpenVMS for more information.

Because a device name can include up to 64 characters, the buffer length field of the item descriptor should specify 64 (bytes).

DVI$_STS

Returns the device unit status as a 4-byte bit vector. Each bit in the vector, when set, corresponds to a symbolic name that is defined by the $UCBDEF macro. The following table describes each name:

Symbol	Description
UCB$V_ALTBSY	Unit is busy via alternate startio path.
UCB$V_BSY	Unit is busy.
UCB$V_CANCEL	I/O on unit is canceled.
UCB$V_CLUTRAN	OpenVMS Cluster state transition in progress.
UCB$V_DEADMO	Deallocate at dismount.
UCB$V_DELETEUCB	Delete this UCB when reference count equals 0.
UCB$V_DISMOUNT	Dismount in progress.
UCB$V_ERLOGIP	Error log is in progress on unit.
UCB$V_EXFUNC_SUPP	Unit supports the EXFUNC bit.
UCB$V_FAST_PATH	Unit supports FAST PATH Affinity.
UCB$V_FP_HWINT	Unit supports FAST PATH hardware interrupt CPU Affinity.
UCB$V_INT	Interrupt is expected.
UCB$V_INTTYPE	Receiver interrupt.
UCB$V_IOPOST_LOCAL	Unit supports I/O post processing on the current CPU.
UCB$V_LCL_VALID	Volume is valid on the local node.
UCB$V_MNTVERIP	Mount verification is in progress.
UCB$V_MOUNTING	Device is being mounted.
UCB$V_MNTVERPND	Mount verification is pending on busy device.
UCB$V_NO_ASSIGN	Unit cannot have channels assigned to it.
UCB$V_ONLINE	Unit is on line.
UCB$V_PATHVERIP	Path verification is in progress for this device.
UCB$V_POWER	Power failed while unit busy.
UCB$V_SNAPSHOT	Restart validation is in progress.
UCB$V_SUPMVMSG	If set, suppress success type mount version messages.
UCB$V_SVPN_END	Last byte used from page mapped by system virtual page number (SVPN).
UCB$V_TEMPLATE	Template UCB from which other UCBs for this device type are made.
UCB$V_TIM	Timeout is enabled.
UCB$V_TIMOUT	Unit timed out.
UCB$V_UNLOAD	Unload volume at dismount.
UCB$V_VALID	Volume is software valid.
UCB$V_WRONGVOL	Wrong volume detected during mount verification.
UCB$V_WRTLOCKMV	Write-locked mount verification in progress.

DVI$_TRACKS

Returns the number of tracks per cylinder as an unsigned integer longword. This item code is applicable only to disks.

DVI$_TRANSCNT

Returns the transaction count for the volume as an unsigned integer longword.

DVI$_TT_ACCPORNAM

Returns the name of the remote access port associated with a channel number or with a physical or virtual terminal device number. If you specify a device that is not a remote terminal or a remote type that does not support this feature, $GETDVI returns a null string. The $GETDVI service returns the access port name as a 64-byte, zero-filled string.

The $GETDVI service returns the name in the format of the remote system. If the remote system is a LAT terminal server, $GETDVI returns the name as server_name/port_name. The names are separated by the slash (/) character. If the remote system is an X.29 terminal, the name is returned as network.remote_DTE.

When writing applications, you should use the string returned by DVI$_ACCPORNAM, instead of the physical device name, to identify remote terminals.

DVI$_TT_CHARSET

Returns, as a 4-byte bit vector, the character sets supported by the terminal. Each bit in the vector, when set, corresponds to the name of a coded character set. The $TTCDEF macro defines the following coded character sets:

Symbol	Description
TTC$V_HANGUL	DEC Korean
TTC$V_HANYU	DEC Hanyu
TTC$V_HANZI	DEC Hanzi
TTC$V_KANA	DEC Kana
TTC$V_KANJI	DEC Kanji
TTC$V_THAI	DEC Thai

DVI$_TT_CS_HANGUL

Returns a longword, which is interpreted as Boolean. A value of 1 indicates that the device supports the DEC Korean coded character set; a value of 0 indicates that the device does not support the DEC Korean coded character set.

DVI$_TT_CS_HANYU

Returns a longword, which is interpreted as Boolean. A value of 1 indicates that the device supports the DEC Hanyu coded character set; a value of 0 indicates that the device does not support the DEC Hanyu coded character set.

DVI$_TT_CS_HANZI

Returns a longword, which is interpreted as Boolean. A value of 1 indicates that the device supports the DEC Hanzi coded character set; a value of 0 indicates that the device does not support the DEC Hanzi coded character set.

DVI$_TT_CS_KANA

Returns a longword, which is interpreted as Boolean. A value of 1 indicates that the device supports the DEC Kana coded character set; a value of 0 indicates that the device does not support the DEC Kana coded character set.

DVI$_TT_CS_KANJI

Returns a longword, which is interpreted as Boolean. A value of 1 indicates that the device supports the DEC Kanji coded character set; a value of 0 indicates that the device does not support the DEC Kanji coded character set.

DVI$_TT_CS_THAI

Returns a longword, which is interpreted as Boolean. A value of 1 indicates that the device supports the DEC Thai coded character set; a value of 0 indicates that the device does not support the DEC Thai coded character set.

DVI$_TT_PHYDEVNAM

Returns a string containing the physical device name of a terminal. If the caller specifies a disconnected virtual terminal or a device that is not a terminal, $GETDVI returns a null string. $GETDVI returns the physical device name as a 64-byte, zero-filled string.

DVI$_UNIT

Returns the unit number as an unsigned integer longword.

DVI$_VOLCOUNT

Returns the number of volumes in the volume set as an unsigned integer longword. This item code is applicable only to disks.

DVI$_VOLNAM

Returns the volume name as a 12-byte, zero-filled string.

DVI$_VOLNUMBER

Returns the volume number of this volume in the volume set as an unsigned integer longword. This item code is applicable only to disks.

DVI$_VOLSETMEM

Returns a longword value, which is interpreted as Boolean. A value of 1 indicates that the device is part of a volume set; a value of 0 indicates that it is not. This item code is applicable only to disks.

DVI$_VPROT

Returns the volume protection mask as a standard 4-byte protection mask.

DVI$_TT_xxxx

DVI$_TT_xxxx is the format for a series of item codes that return information about terminals. This information consists of terminal characteristics. The xxxx portion of the item code name specifies a single terminal characteristic.

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, refer to the description of the F$GETDVI lexical function in the 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$_WWID

Returns the World Wide Identifier (WWID) of Fibre Channel Disk and Tape devices as a zero-filled string of indeterminate length.

The maximum length of this string may change with new devices; therefore, Compaq recommends that a 380-byte buffer be passed to this function.

A return length address should also be passed with the call and examined when the function completes. If the return length is equal to the size of the buffer, then call $GETDVI again with a larger buffer to ensure that the complete name has been read.

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:

If the device has an associated mailbox, the primary characteristics are those of the assigned device and the secondary characteristics are those of the associated mailbox.
If the device is a spooled device, the primary characteristics are those of the intermediate device (such as the disk) and the secondary characteristics are those of the spooled device (such as the printer).
If the device represents a logical link on the network, the secondary characteristics contain information about the link.

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 Block

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.

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.

Contents

Index

privacy and legal statement

4527PRO_055.HTML

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

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.

OpenVMS usage:	item_list_3
type:	longword (unsigned)
access:	read only
mechanism:	by reference

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.