|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
The End of Find File routine is called once after each sequence of calls to LIB$FIND_FILE. LIB$FIND_FILE_END deallocates any saved OpenVMS RMS context and deallocates the virtual memory used to hold the allocated context block.
LIB$FIND_FILE_END context
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
context
OpenVMS usage: context type: longword (unsigned) access: read only mechanism: by reference
Zero or the address of a FAB/NAM buffer from a previous call to LIB$FIND_FILE. The context argument is the address of a longword that contains this context.
LIB$FIND_FILE_END should be called by your program after each sequence of calls to LIB$FIND_FILE. This will prevent the default values from the previous call from affecting the next file specification.LIB$FIND_FILE_END deallocates the context used in the last call to LIB$FIND_FILE so that the context retained will not be used in subsequent calls to LIB$FIND_FILE. If LIB$FIND_FILE was directed to process file specifications for multiple input files, the saved file specifications are also deallocated.
SS$_NORMAL Routine successfully completed. RMS$_FAB File access block argument is not the address of a valid FAB.
The Find Universal Symbol in Shareable Image File routine reads universal symbols from the shareable image file. This routine then dynamically activates a shareable image into the P0 address space of a process.
LIB$FIND_IMAGE_SYMBOL filename ,symbol ,symbol-value [,image-name] [,flags]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
filename
OpenVMS usage: char_string type: character string access: read only mechanism: by descriptor
Name of the file for which LIB$FIND_IMAGE_SYMBOL is searching. The filename argument is the address of a descriptor pointing to this file name string. This argument may contain only the file name. File type cannot be indicated. If any file specification punctuation characters (:, [, <, ;, .) are present, the error SS$_IVLOGNAM is returned.You can specify a file specification for the image name with the optional image-name argument. If you do not specify image-name, a default file specification of SYS$SHARE:.EXE is applied to the file name. If the file is not in SYS$SHARE:.EXE, a logical name must be used to direct this routine to locate the correct file. Only logical names defined in the system logical name table with the /EXEC attribute will be considered while the image activator is processing a request from an image that was installed with privileges. If the calling image was installed with privileges, the image being activated and any shareable images or message sections it references must be installed as a known image with the INSTALL utility. Running an image to which you have only Execute (not Read) access results in the same restrictions on logical names and shareable images as does running a privileged image.
On VAX systems, the filename descriptor must be class D, S, or Z.
symbol
OpenVMS usage: char_string type: character string access: read only mechanism: by descriptor
Symbol for which LIB$FIND_IMAGE_SYMBOL is searching in the filename file. The symbol argument is the address of a descriptor pointing to the symbol name string. The symbol name string can be input in uppercase, lowercase, or mixed case letters.symbol-value
OpenVMS usage: longword_signed type: longword (signed) access: write only mechanism: by reference
Symbol value that LIB$FIND_IMAGE_SYMBOL has located. The symbol-value argument is the address of a signed longword integer into which LIB$FIND_IMAGE_SYMBOL returns the symbol value. If the symbol is relocatable, the starting virtual address of the shareable image in memory is added to the symbol value.image-name
OpenVMS usage: char_string type: character string access: read only mechanism: by descriptor
Default file specification applied to the image name. The optional image-name argument is a string used as the RMS default file specification when parsing filename as the primary filename. If image-name is not supplied, then a default file specification of SYS$SHARE:.EXE is applied to the image name.On VAX systems, the image-name descriptor must be class D, S, or Z.
flags
OpenVMS usage: mask_longword type: longword (unsigned) access: read only mechanism: by value
Control flags. The flags argument is the address of a longword integer that contains the control flags.
Bit Value Description 0 Reserved to HP 1 Reserved to HP 2 Reserved to HP 3 Reserved to HP 4 LIB$M_FIS_MIXEDCASE Causes LIB$FIND_IMAGE_SYMBOL to look for the symbol without converting it to uppercase. This is an optional argument. If omitted, the default is 0. If omitted, or if LIB$M_FIS_MIXEDCASE (bit 4) is 0, LIB$FIND_IMAGE_SYMBOL converts the specified symbol to uppercase before it is used.
The shareable image that LIB$FIND_IMAGE_SYMBOL activates must have been already linked and must be position independent. You must have read access to the shareable image file to use this routine.LIB$FIND_IMAGE_SYMBOL writes the symbol value that it has located into the symbol-value argument.
After the first call to LIB$FIND_IMAGE_SYMBOL for a particular image, successive calls for that image are processed quickly. The image is activated only once and an in-memory database is maintained. There is no way to deallocate this database, nor is there any supported method to remove an activated image from the address space. All images are activated into P0 space.
LIB$FIND_IMAGE_SYMBOL locates the universal symbol in its database qualified by the file name exactly as given in the filename argument. Therefore, a reference to a lexically different but equivalent file name causes a new copy of the same shareable image to be loaded and searched. To avoid this situation, always specify the desired file name in the same form.
To work properly with translated VAX images on Alpha and I64 systems, LIB$FIND_IMAGE_SYMBOL may modify the name of the file being searched and may retry the search if the first search failed. If called from a translated image, LIB$FIND_IMAGE_SYMBOL appends "_TV" to the file name before searching. This locates the translated version of the image being searched. If the search fails to find the file or the file does not define the symbol, LIB$FIND_IMAGE_SYMBOL trys again with the unmodified original file name. This locates the native Alpha or I64 version of the image. If the second search also fails, an error is returned. If LIB$FIND_IMAGE_SYMBOL is called from a native Alpha or I64 program, the order of the searches is reversed. The first search is done with the unmodified original file name. If that fails, the second search is done with "_TV" appended to the file name. If the second search fails, an error is returned.
LIB$FIND_IMAGE_SYMBOL disables AST recognition while it is executing. AST recognition is reenabled before returning to the caller only if AST recognition was previously enabled.
LIB$FIND_IMAGE_SYMBOL signals all errors and returns the status in R0.
LIB$FIND_IMAGE_SYMBOL may signal a warning (LIB$EOMWARN) to indicate that the image being activated contains modules that had compilation warnings. A condition handler used with LIB$FIND_IMAGE_SYMBOL should probably handle this as a special case.
To allow LIB$FIND_IMAGE_SYMBOL to continue executing after signaling LIB$EOMWARN, the condition handler should exit with SS$CONTINUE. For this reason, you may choose not to use LIB$SIG_TO_RET as a condition handler for LIB$FIND_IMAGE_SYMBOL.
LIB$_BADCCC Illegal compilation code. LIB$_EOMERROR Compilation errors. LIB$_EOMFATAL Fatal compilation errors. LIB$_EOMWARN Compilation warnings. LIB$_GSDTYP Illegal universal symbol directory record type. LIB$_ILLFMLCNT Maximum argument count exceeds maximum for routine. LIB$_ILLMODNAM Illegal module name length. LIB$_ILLPSCLEN Illegal program section length. LIB$_ILLRECLEN Illegal record length in module. LIB$_ILLRECLN2 Illegal record length. LIB$_ILLRECTYP Illegal record type in module. LIB$_ILLRECTY2 Illegal record type. LIB$_ILLSYMLEN Illegal symbol length. LIB$_NOEOM No end of module record contained in the module. LIB$_RECTOOSML Record too small; data overflows object record in module. LIB$_SEQUENCE Illegal record sequence in module. LIB$_SEQUENCE2 Illegal record sequence. LIB$_STRVL Illegal object language structure level in module. Note that all of the above error messages indicate a format error in the shareable image. LIB$_INSVIRMEM Insufficient virtual memory. SS$_IVLOGNAM The filename argument contained more than just a file name; a device or directory specification was found in the string.
Any condition values returned by RTL routines LIB$INSERT_TREE or LIB$LOOKUP_TREE.
Any condition values returned by RMS.
The Return the Next Valid Zone Identifier routine returns the zone identifier of the next valid zone in the heap management 32-bit database.
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$FIND_VM_ZONE context ,zone-id
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
context
OpenVMS usage: context type: longword (unsigned) access: modify mechanism: by reference
Context specifier. The context argument is the address of an unsigned longword used to keep the scan context for finding the next valid zone. The context argument must be 0 to initialize the scan and to start with the first returnable zone identifier.zone-id
OpenVMS usage: identifier type: longword (unsigned) access: write only mechanism: by reference
Zone identifier. The zone-id argument is the address of an unsigned longword that receives the zone identifier for the next zone.
At each call, LIB$FIND_VM_ZONE scans the heap management 32-bit zone database and returns the zone-id of the next valid zone. (The first and second calls to LIB$FIND_VM_ZONE return the zone-id of the 32-bit default zone and the 32-bit string zone, respectively.) This capability allows a program to deal with each 32-bit VM zone created during the invocation, including those created outside of the program.
Note
LIB$FIND_VM_ZONE finds only 32-bit zones. You must use LIB$FIND_VM_ZONE and LIB$FIND_VM_ZONE_64 to loop through all VM zones.The context argument controls the state of the scan. It determines what zone to return (the first, the next, and so forth). On the initial call, specified by context=0, LIB$VERIFY_VM_ZONE is called to verify the heap management zone database. If the database is corrupt, further calls to this routine will produce no additional useful output.
When no more zones can be found, the routine returns the condition value LIB$_NOTFOU.
If a zone has been corrupted in some major way (for example, if the validity code has been changed), then this routine may not be able to locate it in the zone database.
Note that ASTs may be disabled while LIB$FIND_VM_ZONE is executing code that depends on the stability of the heap management zone database. In general it is the caller's responsibility to ensure that the calling program has exclusive access to the zone database while scanning for multiple zones with this routine. Results are unpredictable if another thread of control modifies the zone database or the associated areas during the scanning.
SS$_NORMAL Routine successfully completed. LIB$_BADZONE Invalid zone. LIB$_NOTFOU Zone identifier not found (alternate success status). LIB$_WRONUMARG Wrong number of arguments.
IMPLICIT NONE
INTEGER*4 status,context,zone_id
INTEGER*4 lib$find_vm_zone,lib$show_vm_zone
context = 0
status = lib$find_vm_zone (context, zone_id)
DO WHILE (status)
print *
status = lib$show_vm_zone (zone_id, 0)
status = lib$find_vm_zone (context, zone_id)
END DO
END
|
Sample output for this Fortran program is shown below:
Zone Id = 00020020, Zone name = "DEFAULT_ZONE" Zone Id = 000200B0, Zone name = "STRING_ZONE"
The Return the Next Valid Zone Identifier routine returns the zone identifier of the next valid zone in the heap management 64-bit database.
LIB$FIND_VM_ZONE_64 context ,zone-id
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
context
OpenVMS usage: context type: quadword (unsigned) access: modify mechanism: by reference
Context specifier. The context argument is the address of an unsigned quadword used to keep the scan context for finding the next valid zone. The context argument must be 0 to initialize the scan and to start with the first returnable zone identifier.zone-id
OpenVMS usage: identifier type: quadword (unsigned) access: write only mechanism: by reference
Zone identifier. The zone-id argument is the address of an unsigned quadword that receives the zone identifier for the next zone.
At each call, LIB$FIND_VM_ZONE_64 scans the heap management 64-bit zone database and returns the zone-id of the next valid zone. (The first and second calls to LIB$FIND_VM_ZONE_64 return the zone-id of the 64-bit default zone and the 64-bit string zone, respectively.) This capability allows a program to deal with each VM 64-bit zone created during the invocation, including those created outside of the program.
Note
LIB$FIND_VM_ZONE_64 finds only 64-bit zones. You must use LIB$FIND_VM_ZONE and LIB$FIND_VM_ZONE_64 to loop through all VM zones.The context argument controls the state of the scan. It determines what zone to return (the first, the next, and so forth). On the initial call, specified by context=0, LIB$VERIFY_VM_ZONE_64 is called to verify the heap management zone database. If the database is corrupt, further calls to this routine will produce no additional useful output.
When no more zones can be found, the routine returns the condition value LIB$_NOTFOU.
If a zone has been corrupted in some major way (for example, if the validity code has been changed), then this routine may not be able to locate it in the zone database.
Note that ASTs may be disabled while LIB$FIND_VM_ZONE_64 is executing code that depends on the stability of the heap management zone database. In general it is the caller's responsibility to ensure that the calling program has exclusive access to the zone database while scanning for multiple zones with this routine. Results are unpredictable if another thread of control modifies the zone database or the associated areas during the scanning.
SS$_NORMAL Routine successfully completed. LIB$_BADZONE Invalid zone. LIB$_NOTFOU Zone identifier not found (alternate success status). LIB$_WRONUMARG Wrong number of arguments.
IMPLICIT NONE
INTEGER*4 status
INTEGER*8 context,zone_id
INTEGER*4 lib$find_vm_zone_64,lib$show_vm_zone_64
context = 0
status = lib$find_vm_zone_64 (context, zone_id)
DO WHILE (status)
print *
status = lib$show_vm_zone_64 (zone_id, 0)
status = lib$find_vm_zone_64 (context, zone_id)
END DO
END
|
Sample output for this Fortran program is as follows:
Zone Id = 0000000000020040, Zone name = "DEFAULT_ZONE" Zone Id = 0000000000020140, Zone name = "STRING_ZONE"
| Previous | Next | Contents | Index |