HP 3000 Manuals HP 3000 Manuals
HPVOLINFO Intrinsic
by Lalitha Pejavar--Commercial Systems Division
The HPVOLINFO intrinsic can be used to retrieve volume information for
either a device (disc drive) or a class of devices (number of disc drives
logically grouped as a class) or a set (consisting of many devices or
many classes).
Syntax
_____________________________________________________________________
| |
| HPVOLINFO |
| ( status, |
| volspecifiernum, volspecifier [,itemnum, item][...]|
| ); |
| |
_____________________________________________________________________
Up to six items of information can be retrieved by specifying one or more
itemnum/item pairs. The itemnum/item parameters must appear in pairs.
Note, some of the itemnums to HPVOLINFO are MPE V/E specific while others
are MPE XL specific.
Parameters
status 32-bit signed integer (optional)
Returns the status of the HPVOLINFO call. If no errors
or warnings are encountered, status returns 32 bits of
zero. If errors or warnings are encountered, status is
interpreted as two 16 bit fields.
Bits (0:16) comprise status.info. A negative value
indicates an error condition, and a positive value
indicates a warning condition.
Bits (16:16) comprise status.subsys. The value
represented by these bits, defines the subsystem that
set the status information. On MPE XL, the volume
management identification number is 163. On MPE V/E,
this field will contain a 0.
Though 'status' parameter is an optional parameter, it
is strongly recommended that this parameter is used in
pratice. Failure to do so will cause the calling
program to abort if call was unsuccessful. The values
of status.info that can be returned from a call to
HPVOLINFO are listed below.
Error Number Meaning
0 No errors or warnings (successful call).
-150 Invalid itemnum.
-151 Itemnum or item missing (not paired).
-152 Required parameter omitted.
-153 Parameter address out of bounds
-154 Split stack calls not allowed.
-155 Ldev, volume set/class, volume not
mounted.
-156 Invalid volume specifier number.
-157 Invalid volume specifier.
-158 Ldev not a disc ldev.
-159 Device class not configured for volumes.
-160 Device class does not map into a volume
class.
-161 Free space range sizes not in ascending
order.
-162 Invalid number of free space ranges
specified.
-163 Volume class cannot be specified with
system set.
-164 Error while scanning the directory.
-165 Volume label is unreadable.
-166 Disc free space map is bad.
-167 Allocation is disabled for disc free space
map.
-168 Defective tracks table is unreadable.
-169 Disc I/O error.
-170 Virtual memory is only valid on system
volumes.
-171 Directory size is not valid for specified
volume.
-172 Spool files are only valid on system
volumes.
-173 Item number is only valid on MPE XL
systems.
-174 Item number is only valid on MPE V/E
systems.
-175 List length specified is invalid.
-176 Item number/volume specifier number
combination is illegal.
-177 Item is not yet implemented.
-178 Volume table is in an inconsistent state.
-179 Unrecognized drive type.
150 Array passed in cannot hold all names -
List truncated.
151 File label is unreadable.
In addition, the following warnings/errors may be
returned by the XL version of HPVOLINFO:
-180 Physical I/O error.
-181 An unexpected error was detected. The
error stack should be checked to determine
the exact error.
-182 An error was detected in the label
management subsystem. The error stack
should be checked to determine the exact
error.
-183 Disc access error. The error stack should
be checked to determine the exact error.
-184 A mirrored volume that was specified is
disabled.
-185 The volume set specified is not a volume
set on the system.
-186 The volume class specified is not present
in the volume set specified.
-187 The member volume specified is not present
in the volume set specified.
152 Parts of the set or class are not mounted.
Data was only gathered on the portion of
the set or class that was mounted so the
data may be incomplete.
volspecifiernum 16-bit signed integer by value (optional)
A 16-bit integer indicating which volume specifier is to
be used to obtain information from HPVOLINFO. The
default value for this parameter is 0 if it is not
included by the caller. This parameter is used in
conjunction with the volspecifier parameter. The
following are valid volume specifier numbers:
0 volume specifier is ignored. Using this
specifier number is equivalent to
specifying all the volumes on the system.
1 volume specifier is the logical device
number of the volume for which information
is to be obtained.
2 volume specifier is a volume set name.
3 volume specifier is a volume set/volume
class name pair.
4 volume specifier is a volume set/volume
name pair.
5 volume specifier is a device class name.
volspecifier type varies (optional)
The volspecifier is optional when the volspecifiernum is 0
since the volspecifier is ignored. However, for
volspecifiernums 1 through 5, the volspecifier parameter
must be specified. On MPE V/E, volspecifier must be
declared as a byte array. The data type of the
volspecifier depends on the volspecifiernum:
volspecifiernum volspecifier
0 ignored
1 16-bit signed integer
2,3,4,5 character array
When a 0 is used as the volspecifiernum, the volspecifier
is ignored. When a volspecifiernum of 0 is used, it refers
to all the volumes on the system. This includes all the
system and nonsystem volumes.
When a 1 is used as the volspecifiernum, the volspecifier
must be a ldev number which corresponds to a configured and
mounted volume. An ldev number can be any number between 1
and 999.
For the character specifiers, the first character
determines the delimiter character for the parameter. The
delimiter must be printable, cannot be alphanumeric, and
cannot be one of the special characters ".", ":", or "_" as
explained below. For example, to pass the volume set FOO,
the following array is a valid way to pass FOO using '%' as
the delimiter: %FOO%.
For specifiers 3 and 4, the volume set name and the volume
class or volume name must be separated by a colon. For
example, %SET1:CLASS0% or %SET2:VOLUME8% may be used. A
colon (:) cannot be used as a delimiter character.
Since a volume set or class can be fully qualified on MPE
V/E, periods (.) are allowed in the name. Because periods
(.) and underscores (_) are allowed in a MPE XL name,
these characters (period and underscore) cannot be used as
delimiters.
With specifiers 2 and 3 on MPE V/E, for private volumes, a
volume set/class name may be partially or fully qualified
(e.g. VSETNAME.GROUP.ACCNT or CLASSNAM.GROUP.ACCNT). Each
field of the name must be one to eight alphanumeric
characters (beginning with a letter) for a possible total
of 55 characters, e.g.:
%SETxxxxx.GROUPxxx.ACCOUNTx:CLASSxxx.GROUPxxx.ACCOUNTx%
has six eight-character fields, four periods, a colon, and
two delimiters. When the volume set or class name is not
fully qualified, it refers to the volume set or class in
the logon group and/or account.
On MPE XL, a valid volume set or class name consists of as
many as 32 characters, where the first character is
alphabetic, followed by any combination of alphanumeric
characters. The MPE XL name may include the underscore (_)
and the period (.).
On MPE XL, the name of the system volume set is
"MPEXL_SYSTEM_VOLUME_SET". Since the system volume set on
MPE V/E does not have a predefined name, the name
"MPEXL_SYSTEM_VOLUME_SET" is used to be compatible with MPE
XL. On both MPE V/E and MPE XL, for items that return
volume set names (i.e., item #3 and item #12), this name is
returned when returning the system volume set name.
Note that when the system volume set name is used on MPE
V/E, it cannot be followed by a class name (see discussion
of volume specifier number 5 below). Also, on MPE V/E
group and account names cannot be used to partially or
fully qualify the set or volume name when the system volume
set name is specified.
For specifier 4 on MPE V/E, a volume name consists of up to
8 alphanumeric characters, beginning with a letter. For
private volumes, names may be partially or fully qualified
(e.g. VNAME.GROUP.ACCNT). Each field of the name must be
one to eight alphanumeric characters (beginning with a
letter) for a possible total of 55 characters, e.g.:
%SETxxxxx.GROUPxxx.ACCOUNTx:NAMExxxx.GROUPxxx.ACCOUNTx%
has six eight-character fields, four periods, a colon, and
two delimiters. When the volume name is not fully
qualified, it refers to the volume name in the logon group
and/or account.
On MPE XL for specifier 4, the volume name consists of any
string consisting of 1 to 16 alphanumeric characters,
underscores, or periods, where the first character is
alphabetic.
On MPE V/E, the concept of a volume class does not exist
for the system volume set, therefore, in order to access a
subset of the system volume set, device classes are used.
But, on MPE XL, the concept of volume classes is valid for
both system and nonsystem volume sets and therefore, volume
classes take the place of device classes. Specifier 5, for
Item# 6 and 7 provides compatibility between MPE V/E and
MPE XL. Specifier 5 passes the device class of a group of
volumes as they apply to the I/O configuration. The
maximum number of characters allowed in the string is 8.
On MPE V/E, when this specifier is used, it must refer to a
device class that is configured to a group of volumes.
On MPE XL, when a device class name is specified, a
configured and mounted volume class with the same name must
exist in the system volume set. Data will be returned
based on this volume class in the system volume set if it
exists; otherwise an error will result.
itemnum 16-bit signed integer by value (optional)
Cardinal number of the item desired. This specifies which
item value is to be returned. Refer to Item# in Table 1.
item type varies (optional)
On MPE V/E, item must be declared as a byte array. The
actual type of the item specified by the corresponding item
number. Refer to Item in Table 1.
SPECIAL CONSIDERATIONS
No special capabilities are required in order to use the HPVOLINFO
intrinsic.
Split-stack calls are not permitted.
When an error is returned, the values in the item parameters are all
undefined. It is not guaranteed that the data returned in an item is
meaningful if any status value less than 0 is returned.
On MPE V/E, real values are accepted from the caller and returned to the
caller in 64-bit HP3000 format. This is the default format for MPE V/E.
On MPE XL, real values are accepted from the caller and returned to the
caller in the format that is the default for the mode of the caller. If
the intrinsic is called from compatibility mode, then any real values
specified to HPVOLINFO must be in 64-bit HP3000 format and any real
values returned by HPVOLINFO will be in that format. If the intrinsic is
called from native mode, then any real values specified to HPVOLINFO must
be in 64-bit IEEE format and any real values returned by HPVOLINFO will
be returned in that format. Since the format used is always the default
for the mode of the caller, this difference will have no impact on
porting between MPE V/E and MPE XL.
If a lot of activity is occurring on the system while this intrinsic is
called, some of the item values returned may not reflect the expected
result. For example, when HPVOLINFO is called to return the disc space
used by permanent files, a value is returned. But, if immediately after
the value is returned, a process on the system purges a file (FCLOSEs a
file with disposition 4), the value will not reflect this difference.
On MPE V/E, a set or class is considered to be logically mounted if all
of its members are logically mounted (i.e., LMOUNT or MOUNT command was
used).
On MPE XL, if the volume specifier is a set or class then at least the
master volume must be logically mounted (i.e., volume must be in a master
or member state). If the volume specifier is a logical device number or
a volume name then both the volume specified and the master volume (of
the set enclosing the volume specified) must be logically mounted.
If the volume specifier is a logical device number then it must be a
member of a set or class that is logically mounted. If the volume
specifier is a volume set name then the set must be logically mounted.
If the volume specifier is a volume class name then the class must be
logically mounted. If the volume specifier is a volume name then that
volume must be a member of a set or class that is logically mounted.
When the volume specifier is a device class name, all of the logical
device numbers in the specified device class must be members of logically
mounted sets/classes. Finally, all the volumes on the system (whether
they are logically mounted or not) may be specified by using volume
specifier number 0.
If the volumes for volume specifier numbers 1 through 5 are not logically
mounted as specified above then the HPVOLINFO intrinsic will return a
"volume not mounted" error. If the caller chooses to continue with the
same specifier, the LMOUNT (on MPE V/E) or VSOPEN (on MPE XL) command can
be used with the COMMAND or HPCICOMMAND intrinsic to logically mount the
appropriate volume sets/classes. If a volume is taken offline while the
intrinsic is accessing it, the process will hang (because IOs cannot
complete to the disc) until the volume is back online.
On MPE XL, since mirrored discs maintain identical copies of the same
information on two discs, the values that are returned by this intrinsic
reflect information from only one of the volumes in a mirrored disc pair.
When retrieving an ldev number (Item# 13) using a volume name that is
associated with a mirrored disc pair, only one of the ldev numbers of the
mirrored pair will be returned. Which one of the two ldev numbers will
be returned is random and therefore, it should be noted that the ldev
number returned in this case may be different across system start ups.
Subsequent use of the ldev numbers returned for mirrored discs are
guaranteed to provide accurate information for the mirrored volume set.
On MPE XL, if information is requested for the split backup volume set
the information returned will be for the split user volume set.
ITEM NUMBER, ITEM SUMMARY
Table 1 lists information returned by the HPVOLINFO intrinsic. The
itemnum and item parameters are paired such that nth itemnum corresponds
to the nth item. An itemnum contains the option number of the desired
information. The information is returned in the corresponding item. The
itemnum/item parameters are used the same way as in other intrinsics like
FFILEINFO and JOBINFO.
For more details, refer to the MPE XL Intrinsics Reference Manual (P/N
32650-60013).
_________________________________________________________________________
| |
| ITEM# ITEM TYPE APPLICABLE VOLUME|
| SPECIFIERS |
| |
| 2 Number of volume sets I32 0 |
| |
| 3 List of volume set names CA 0 |
| |
| 4 Number of volume class names I32 1,2,4 |
| |
| 5 List of volume class names CA 1,2,4 |
| |
| 6 Number of member volumes I32 2,3,5 |
| |
| 7 List of member volume names CA 2,3,5 |
| |
| 8 Drive type CA 1,4 |
| |
| 9 Sector size (bytes) I32 1,4 |
| |
| 10 Volume type I32 1,4 |
| |
| 11 Volume name CA 1 |
| |
| 12 Volume set name CA 1 |
| |
| 13 Logical device number I16 4 |
| |
| 14 Volume Capacity (sectors) I64 1,2,3,4 |
| 15 Volume Capacity (sectors) R64 1,2,3,4 |
| |
| 16 Total MPE overhead (sectors) I64 1,2,3,4 |
| 17 Total MPE overhead (sectors) R64 1,2,3,4 |
| |
| 18 MPE XL transient space overhead (sectors) |
| I64 1,2,3,4 |
| 19 MPE XL transient space overhead (sectors) |
| R64 1,2,3,4 |
| |
| 20 Configured maximum MPE XL transient space (sectors) |
| I64 1,2,3,4 |
| 21 Configured maximum MPE XL transient space (sectors) |
| R64 1,2,3,4 |
_________________________________________________________________________
Table 1. Item Values Returned by HPVOLINFO
_________________________________________________________________________
| |
| ITEM# ITEM TYPE APPLICABLE VOLUME|
| SPECIFIERS |
| |
| 22 MPE V virtual memory overhead (sectors) |
| I64 1,2,4 |
| 23 MPE V virtual memory overhead (sectors) |
| R64 1,2,4 |
| |
| 24 Directory space overhead (sectors) I64 1,2,3,4 |
| 25 Directory space overhead (sectors) R64 1,2,3,4 |
| |
| 26 MPE XL file label overhead (sectors) |
| I64 1,2,3,4 |
| 27 MPE XL file label overhead (sectors) |
| R64 1,2,3,4 |
| |
| 28 MPE XL transaction management overhead (sectors) |
| I64 1,2,3,4 |
| 29 MPE XL transaction management overhead (sectors) |
| R64 1,2,3,4 |
| |
| 30 Spool file disc space usage (sectors) |
| I64 1,2,3,4 |
| 31 Spool file disc space usage (sectors) |
| R64 1,2,3,4 |
| |
| 32 Disc space used by perm files (sectors) |
| I64 1,2,3,4 |
| 33 Disc space used by perm files (sectors) |
| R64 1,2,3,4 |
| |
| 34 (Reserved for) Disc space used by temp files (sectors) |
| I64 1,2,3,4 |
| 35 (Reserved for) Disc space used by temp files (sectors) |
| R64 1,2,3,4 |
| |
| 36 Free space distribution array I64A 1,2,3,4 |
| 37 Free space distribution array R64A 1,2,3,4 |
| |
| 38 Free space distribution sectors per range |
| I64A 1,2,3,4 |
| 39 Free space distribution sectors per range |
| R64A 1,2,3,4 |
_________________________________________________________________________
Table 1. Item Values Returned by HPVOLINFO (Continued)
_________________________________________________________________________
| |
| ITEM# ITEM TYPE APPLICABLE VOLUME|
| SPECIFIERS |
| |
| 40 Total free space (sectors) I64 1,2,3,4 |
| 41 Total free space (sectors) R64 1,2,3,4 |
| |
| 42 Largest contiguous free space area (sectors) |
| I64 1,2,3,4 |
| 43 Largest contiguous free space area (sectors) |
| R64 1,2,3,4 |
| |
| **** I16 = 16-bit signed integer |
| I32 = 32-bit signed integer |
| I64 = 64-bit signed integer |
| R64 = 64-bit real |
| CA = character array |
| I64A = 64-bit signed integer array |
| R64A = 64-bit real array |
_________________________________________________________________________
Table 1. Item Values Returned by HPVOLINFO (Continued)