|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
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.
LIB$FREE_VM_PAGE number-of-pages ,base-address
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
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.
LIB$FREE_VM_PAGE_64 number-of-pages ,base-address
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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.
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.
LIB$GETDVI item-code [,channel] [,device-name] [,longword-integer-value] [,resultant-string] [,resultant-length] [,pathname]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
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.
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).
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.
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.
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.
LIB$GETJPI item-code [,process-id] [,process-name] [,resultant-value] [,resultant-string] [,resultant-length]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
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.
| Previous | Next | Contents | Index |