 |
HP OpenVMS RTL Library (LIB$) Manual
LIB$FIND_FILE_END
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.
Format
LIB$FIND_FILE_END context
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Argument
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.
Description
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.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
RMS$_FAB
|
File access block argument is not the address of a valid FAB.
|
LIB$FIND_IMAGE_SYMBOL
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.
Format
LIB$FIND_IMAGE_SYMBOL filename ,symbol ,symbol-value [,image-name]
[,flags]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
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.
Description
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.
Condition Values Returned
|
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.
LIB$FIND_VM_ZONE
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.
|
Format
LIB$FIND_VM_ZONE context ,zone-id
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
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.
Description
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.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_BADZONE
|
Invalid zone.
|
|
LIB$_NOTFOU
|
Zone identifier not found (alternate success status).
|
|
LIB$_WRONUMARG
|
Wrong number of arguments.
|
Example
|
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"
|
LIB$FIND_VM_ZONE_64 (Alpha and I64 Only)
The Return the Next Valid Zone Identifier routine returns the zone
identifier of the next valid zone in the heap management 64-bit
database.
Format
LIB$FIND_VM_ZONE_64 context ,zone-id
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
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.
Description
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.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_BADZONE
|
Invalid zone.
|
|
LIB$_NOTFOU
|
Zone identifier not found (alternate success status).
|
|
LIB$_WRONUMARG
|
Wrong number of arguments.
|
Example
|
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"
|
|
