 |
HP OpenVMS System Services Reference Manual
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_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 Integrity server 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 Block1
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 Integrity server 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 Integrity server 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 |
Process identification (PID) of the process about which $GETJPI is to
return information. The pidadr argument is the 32- or
64-bit address 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 |
Name of the process about which $GETJPI is to return information. The
prcnam argument is the 32- or 64-bit address 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 |
Item list specifying which information about the process or processes
is to be returned. The itmlst argument is the 32- or
64-bit address 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 |
I/O status block that is to receive the final completion status. The
iosb argument is the 32- or 64-bit address 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 |
AST service routine to be executed when $GETJPI completes. The
astadr argument is the 32- or 64-bit address of this
routine.
|
