 |
HP OpenVMS RTL Library (LIB$) Manual
LIB$FREE_VM_PAGE
The Free Virtual Memory Page routine deallocates a block of contiguous
pages on VAX systems or pagelets on Alpha and I64 systems that were
allocated by previous calls to LIB$GET_VM_PAGE.
Note
No support for arguments passed by 64-bit address reference or for use
of 64-bit descriptors, if applicable, is planned for this routine.
|
Format
LIB$FREE_VM_PAGE number-of-pages ,base-address
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
number-of-pages
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Number of pages on VAX systems or pagelets on Alpha and I64 systems.
The number-of-pages argument is the address of a
longword integer that specifies the number of contiguous pages on VAX
systems or pagelets on Alpha and I64 systems to be deallocated. The
value of number-of-pages must be greater than zero.
base-address
| OpenVMS usage: |
address |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Block address. The base-address argument is the
address of a longword that contains the address of the first byte of
the first VAX page or Alpha or I64 pagelet to be deallocated.
Description
LIB$FREE_VM_PAGE deallocates a block of contiguous 512-byte pages
starting at base-address. Each of the pages or
pagelets specified by number-of-pages and
base-address must have been allocated by previous
calls to LIB$GET_VM_PAGE. The pages or pagelets are returned to the
processwide pool and are available to satisfy subsequent calls to
LIB$GET_VM_PAGE.
You can free a smaller group of pages or pagelets than you allocated.
That is, if you allocated a group of contiguous pages or pagelets by a
single call to LIB$GET_VM_PAGE, you can deallocate them in several
calls to LIB$FREE_VM_PAGE. You can also combine contiguous groups of
pages or pagelets that were allocated in several calls to
LIB$GET_VM_PAGE into one large group that is freed by a single call to
LIB$FREE_VM_PAGE.
LIB$FREE_VM_PAGE is fully reentrant, so it may be called by routines
executing at AST level or in an Ada multitasking environment.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_BADBLOADR
|
Pages on VAX systems or pagelets on Alpha and I64 systems not allocated
by LIB$GET_VM_PAGE, the value of
base-address is not a page boundary, or the pages were
previously freed.
|
|
LIB$_BADBLOSIZ
|
The
number-of-pages argument is less than or equal to zero.
|
LIB$FREE_VM_PAGE_64 (Alpha and I64 Only)
The Free Virtual Memory Page routine deallocates a block of contiguous
Alpha or I64 pagelets that was allocated by previous calls to
LIB$GET_VM_PAGE_64.
Format
LIB$FREE_VM_PAGE_64 number-of-pages ,base-address
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
number-of-pages
| OpenVMS usage: |
quadword_signed |
| type: |
quadword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Number of Alpha or I64 pagelets. The address of a quadword integer that
specifies the number of contiguous Alpha or I64 pagelets to be
deallocated. The value of number-of-pages must be
greater than zero.
base-address
| OpenVMS usage: |
address |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Block address. The base-address argument is the
address of a quadword that contains the address of the first byte of
the first Alpha or I64 pagelet to be deallocated.
Description
LIB$FREE_VM_PAGE_64 deallocates a block of contiguous Alpha or I64
pagelets starting at base-address. Each of the
pagelets specified by number-of-pages and
base-address must have been allocated by previous
calls to LIB$GET_VM_PAGE_64. The pagelets are returned to the
processwide pool and are available to satisfy subsequent calls to
LIB$GET_VM_PAGE_64.
You can free a smaller group of pagelets than you allocated. That is,
if you allocated a group of contiguous pagelets by a single call to
LIB$GET_VM_PAGE_64, you can deallocate them in several calls to
LIB$FREE_VM_PAGE_64. You can also combine contiguous groups of pagelets
that were allocated in several calls to LIB$GET_VM_PAGE_64 into one
large group that is freed by a single call to LIB$FREE_VM_PAGE_64.
LIB$FREE_VM_PAGE_64 is fully reentrant, so it may be called by routines
executing at AST level or in an Ada multitasking environment.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_BADBLOADR
|
Alpha pagelets not allocated by LIB$GET_VM_PAGE_64, the value of
base-address is not a pagelet boundary, or the
pagelets were previously freed.
|
|
LIB$_BADBLOSIZ
|
The
number-of-pages argument is less than or equal to zero.
|
LIB$GETDVI
The Get Device/Volume Information routine provides a simplified
interface to the $GETDVI system service. It returns information about
the primary and secondary device characteristics of an I/O device. The
calling process need not have a channel assigned to the device about
which it wants information.
Format
LIB$GETDVI item-code [,channel] [,device-name]
[,longword-integer-value] [,resultant-string] [,resultant-length]
[,pathname]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
item-code
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference |
Code specifying the item of information you are requesting. The
item-code argument is the address of a signed longword
containing the item code. All valid $GETDVI item codes whose names
begin with DVI$_ are accepted.
See the Description section for more information on item codes.
channel
| OpenVMS usage: |
channel |
| type: |
word (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
OpenVMS I/O channel assigned to the device for which LIB$GETDVI returns
information. The channel argument is the address of an
unsigned word containing the channel specification. If
channel is not specified, device-name
is used instead. You must specify either channel or
device-name, but not both. If neither is specified,
the error status SS$_IVDEVNAM is returned.
device-name
| OpenVMS usage: |
device_name |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Name of the device for which LIB$GETDVI returns information. The
device-name argument is the address of a descriptor
pointing to the device name string. If this string contains a colon,
the colon and the characters that follow it are ignored.
The device-name may be either a physical device name
or a logical name. If the first character in the string is an
underscore character (_), the name is considered a physical device
name. Otherwise, the name is considered a logical name, and logical
name translation is performed until either a physical device name is
found or the system default number of translations has been performed.
If device-name is not specified,
channel is used instead. You must specify either
channel or device-name, but not both.
If neither is specified, the error status SS$_IVDEVNAM is returned. The
device name must not be longer than 255 characters.
longword-integer-value
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
write only |
| mechanism: |
by reference |
Numeric value of the information requested. The
longword-integer-value argument is the address of a
signed longword containing the numeric value. If an item is listed as
only returning a string value, this argument is ignored.
resultant-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
String representation of the information requested. The
resultant-string argument is the address of a
descriptor pointing to this information. If
resultant-string is not specified and if the value
returned has only a string representation, the error status LIB$_INVARG
is returned.
Refer to Table lib-4 for a description of the string representation
used for each item.
resultant-length
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Number of significant characters written to
resultant-string by LIB$GETDVI. The
resultant-length argument is the address of an
unsigned word containing this length.
pathname
| OpenVMS usage: |
path_name |
| type: |
character text string |
| access: |
read only |
| mechanism: |
by descriptor |
(I64 and Alpha only) The name of the path about which $GETDVI is to
return information. The pathname argument is the
address of a character string descriptor pointing to this name string.
The path name may be used with either the channel or
device-name arguments.
Check the definitions of the item codes to see if the
pathname argument is used. In general, item codes that
return information that may vary by path will make use of the
pathname argument. The paths for a multipath device
can be seen with the SHOW DEVICE /FULL command, the
SYS$DEVICE_PATH_SCAN system service, or the F$MULTIPATH DCL lexical
function.
If the pathname argument is used, it will be validated
against the existing paths for the device specified. If the path does
not exist, the error SS$_NOSUCHPATH will be returned, even if the item
codes(s) used do not make use of the pathname argument.
Description
LIB$GETDVI returns two categories of information:
- Primary device characteristics
- Secondary device characteristics
LIB$GETDVI does not allow you to get more than one item of information
in a single call.
LIB$GETDVI provides the following features in addition to those
provided by the $GETDVI system service.
- Instead of a list of item descriptors, which may be difficult to
construct in high-level languages, the single item desired is specified
as an integer code which is passed by reference. Results are written to
separate arguments.
- For items which return numeric values, LIB$GETDVI can optionally
provide a formatted string interpretation of the value. For example, if
the device owner UIC is requested, LIB$GETDVI can return the UIC
formatted as [identifier].
- For string arguments, LIB$GETDVI understands all string classes
supported by the Run-Time Library.
- Calls to LIB$GETDVI are synchronous; LIB$GETDVI calls LIB$GET_EF to
allocate a local event flag number for synchronization.
See the description of the $GETDVI system service in the HP OpenVMS System Services Reference Manual: A--GETUAI
for more detailed information.
Item Codes
All item codes that can be used with the $GETDVI system service may be
used as the item-code argument to LIB$GETDVI. These
codes have symbolic names beginning with DVI$_.
The use of a DVI$_ code by itself will return the primary device
characteristic associated with that code. To obtain the secondary
device characteristics, add 1 to the code. See the description of the
$GETDVI system service for a list of the defined item codes. The
symbolic names for these items are defined in HP supplied symbol
libraries in module $DVIDEF (where appropriate).
Value Formats
By using the longword-integer-value and
resultant-string arguments to LIB$GETDVI, the
information requested can be returned in two different fashions.
- For each item described as a "string" in the table of
Item Codes for the $GETDVI service, the value is returned in
resultant-string.
- For all other items---those that have numeric values---the numeric
representation is returned in longword-integer-value
(if specified), and a formatted string interpretation of the value is
returned in resultant-string.
Each formatted item is written left-justified;
resultant-length, if specified, gives the number of
characters used. Table lib-4 lists the formats used for the string
interpretations.
Table lib-4 Formats Used for LIB$GETDVI Strings
| Item or Format |
Description |
|
DVI$_ACPPID
|
The string value is returned as an 8-digit hexadecimal number.
|
|
DVI$_PID
|
The string value is returned as an 8-digit hexadecimal number.
|
|
DVI$_ACPTYPE
|
The ACP type string is one of the following:
|
NONE
|
No ACP
|
|
F11V1
|
Files-11 Level 1
|
|
F11V2
|
Files-11 Level 2
|
|
F11V3
|
Files-11 presentation of ISO 9660
|
|
F11V4
|
Files-11 presentation of High Sierra
|
|
F11V5
|
Files-11 structure level 5 (ODS-5)
|
|
F11V6
|
Files-11 structure level 5 (ODS-6)
|
|
F64
|
Files 64 support for Spiralog
|
|
HBS
|
Not currently defined
|
|
HBVS
|
ACP for Host Based Volume Shadowing
|
|
MTA
|
Magnetic Tape
|
|
NET
|
Networks
|
|
REM
|
Remote I/O
|
|
UCX
|
ACP for TCP/IP Services for OpenVMS
|
|
|
DVI$_OWNUIC
|
The standard UIC format [group,member] is used. If the format of a UIC
includes identifiers from the access rights database in place of the
octal group and member numbers, the UIC string returned will have these
identifiers, if available.
|
|
DVI$_VPROT
|
The volume protection string is in the following form:
SYSTEM=RWLP,OWNER=RWLP,GROUP=RWLP,WORLD=RWLP
If a category has no access, the equal sign is omitted. The string
will not contain any embedded spaces.
|
|
Boolean
|
The value string returned is TRUE if the low bit of the value is set,
or FALSE if the low bit is clear.
|
|
All others
|
The value string is returned in the form of an unsigned decimal integer.
|
Note
This routine calls LIB$GET_EF. Please read the note in the
Description section of that routine.
|
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
LIB$_STRTRU
|
String truncated. This is an alternate success return status. The
resultant-string argument could not contain all the
characters of the returned item.
|
|
SS$_BADPARAM
|
Unrecognized item code. The
item-code argument was not recognized as valid by
$GETDVI.
|
|
SS$_IVDEVNAM
|
The device name string contains invalid characters, or neither the
channel nor
device-name arguments were specified.
|
|
LIB$_INSEF
|
Insufficient event flags. A local event flag number could not be
allocated by a call to LIB$GET_EF.
|
|
LIB$_INVARG
|
Invalid arguments. The $GETDVI Item Code describes the item as a
"string", and no
resultant-string argument was specified.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor. The descriptor of the
resultant-string argument is not a valid descriptor.
|
|
LIB$_WRONUMARG
|
Wrong number of arguments. An incorrect number of arguments was passed
to LIB$GETDVI.
|
Any condition values returned by LIB$SCOPY_xxx, or the $GETDVI
system service.
LIB$GETJPI
The Get Job/Process Information routine provides a simplified interface
to the $GETJPI system service. It provides accounting, status, and
identification information about a specified process.
LIB$GETJPI obtains only one item of information in a single call.
Format
LIB$GETJPI item-code [,process-id] [,process-name] [,resultant-value]
[,resultant-string] [,resultant-length]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
item-code
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference |
Item identifier code specifying the item of information you are
requesting. The item-code argument is the address of a
signed longword containing the item code. You may request only one item
in each call to LIB$GETJPI.
LIB$GETJPI accepts all $GETJPI item codes. These names begin with JPI$_
and are defined in symbol libraries in module $JPIDEF supplied by HP.
process-id
| OpenVMS usage: |
process_id |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Process identifier of the process for which you are requesting
information. The process-id argument is the address of
an unsigned longword containing the process identifier. If you do not
specify process-id, process-name is
used.
The process-id is updated to contain the process
identifier actually used, which may be different from what you
originally requested if you specified process-name or
used wildcard process searching.
process-name
| OpenVMS usage: |
process_name |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
A 1- to 15-character string specifying the name of the process for
which you are requesting information. The process-name
argument is the address of a descriptor pointing to the process name
string. The name must correspond exactly to the name of the process for
which you are requesting information; LIB$GETJPI does not allow
trailing blanks or abbreviations.
If you do not specify process-name,
process-id is used. If you specify neither
process-name nor process-id, the
caller's process is used. Also, if you do not specify
process-name and you specify zero for
process-id, the caller's process is used. In this way,
you can fetch the item you want and the caller's PID in a single call
to LIB$GETJPI.
resultant-value
| OpenVMS usage: |
varying_arg |
| type: |
unspecified |
| access: |
write only |
| mechanism: |
by reference |
Numeric value of the information you request. The
resultant-value argument is the address of a longword
or quadword into which LIB$GETJPI writes the numeric value of this
information. Refer to Table lib-5 for information on which items
return longword values and which return quadword values. If the item
you request returns only a string value, this argument is ignored.
resultant-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
String representation of the information you request. The
resultant-string argument is the address of the
descriptor for a character string into which LIB$GETJPI writes the
string representation. Table lib-5 describes the string
representation used for each item.
If you do not include resultant-string, but the item
you request has only a string representation, the error status
LIB$_INVARG is returned.
resultant-length
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Number of significant characters written to
resultant-string by LIB$GETJPI. The
resultant-length argument is the address of an
unsigned word integer into which LIB$GETJPI writes the number of
characters.
|
