 |
OpenVMS RTL Library (LIB$) Manual
LIB$FILE_SCAN_END
The End-of-File Scan routine is called after each sequence of calls to
LIB$FILE_SCAN. LIB$FILE_SCAN_END deallocates any saved OpenVMS RMS
context and/or deallocates the virtual memory that had been allocated
for holding the related file specification information.
Format
LIB$FILE_SCAN_END [fab] [,context]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
fab
| OpenVMS usage: |
fab |
| type: |
unspecified |
| access: |
modify |
| mechanism: |
by reference |
File access block (FAB) used with LIB$FILE_SCAN. The optional
fab argument is the address of the FAB that contains
the address and length of the file specification.
context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Temporary default context used in LIB$FILE_SCAN. The optional
context argument is the address of a longword
containing this temporary default context.
Description
Your program should call LIB$FILE_SCAN_END after each sequence of calls
to LIB$FILE_SCAN. The function that LIB$FILE_SCAN_END performs depends
upon the arguments you specify. If you specify fab,
LIB$FILE_SCAN_END parses the null string to deallocate any saved RMS
context. If you specify context, LIB$FILE_SCAN_END
deallocates any virtual memory that was allocated for holding the
related file specification information. If you specify both
fab and context, LIB$FILE_SCAN_END
performs both functions. However, if you do not specify either
argument, LIB$FILE_SCAN_END does nothing.
If LIB$FILE_SCAN is directed to process the specifications for multiple
input files, LIB$FILE_SCAN_END is used to deallocate those saved file
specifications. If LIB$FILE_SCAN_END is called by your program after
each sequence of calls to LIB$FILE_SCAN, it will prevent the defaults
from the previous call from affecting context value in the next call to
LIB$FILE_SCAN. LIB$FILE_SCAN_END does this by replacing the context
value passed to it with a temporary context value that your program
passes to LIB$FILE_SCAN the next time it is called.
Condition Values Returned
|
SS$_NORMAL
|
Routine successfully completed.
|
|
RMS$_FAB
|
The
fab argument is not the address of a valid FAB.
|
LIB$FIND_FILE
The Find File routine is called with a file specification for which it
searches. LIB$FIND_FILE returns one file specification for each call.
The file specification may contain wildcards.
Format
LIB$FIND_FILE filespec ,resultant-filespec ,context [,default-filespec]
[,related-filespec] [,status-value] [,flags]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
filespec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
File specification, which may contain wildcards, that LIB$FIND_FILE
uses to search for the desired file. The filespec
argument is the address of a descriptor pointing to the file
specification. If running on Alpha and flag LIB$M_FIL_LONG_NAMES is
set, the maximum length of a file specification is specified by
NAML$C_MAXRSS, otherwise the maximum length of a file specification is
255 bytes.
The file specification used may also contain a search list logical
name. If present, the search list logical name elements can be used as
accumulative to related file specifications, so that portions of file
specifications not specified by the user are inherited from previous
file specifications.
resultant-filespec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
modify |
| mechanism: |
by descriptor |
Resultant file specification that LIB$FIND_FILE returns when it finds a
file that matches the specification in the filespec
argument. The resultant-filespec argument is the
address of a descriptor pointing to the resultant file specification.
context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
A longword integer variable into which the routine stores a context
value for use by future calls to LIB$FIND_FILE or LIB$FIND_FILE_END.
The context argument is an unsigned longword integer
containing the address of the context. This variable must be set to
zero before the first call to LIB$FIND_FILE. You can use the same
context argument from one LIB$FIND_FILE call to
another provided you have not called LIB$FIND_FILE_END for that
context first. LIB$FIND_FILE uses this argument to
retain the context when processing multiple input files. Portions of
file specifications that the user does not specify may be inherited
from the last files processed because the file contexts are retained in
this argument. You must not change the value of
context in subsequent calls to LIB$FIND_FILE.
default-filespec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Default file specification. The default-filespec
argument is the address of a descriptor pointing to the default file
specification. See the OpenVMS Record Management Services Reference Manual for information about default file
specifications.
related-filespec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Related file specification containing the context of the last file
processed. The related-filespec argument is the
address of a descriptor pointing to the related file specification.
The related file specification is useful when you are processing lists
of file specifications. Unspecified portions of the file specification
are inherited from the last file processed. For more information on
related file specifications, see the OpenVMS Record Management Services Reference Manual.
status-value
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
RMS secondary status value from a failing RMS operation. The
status-value argument is an unsigned longword
containing the address of a longword-length buffer to receive the RMS
secondary status value (usually returned in the file access block
field, FAB$L_STV).
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
User flags. The flags argument is the address of an
unsigned longword containing the user flags.
The flag bits and their corresponding symbols are described in the
following table:
| Bit |
Symbol |
Description |
|
0
|
LIB$M_FIL_NOWILD
|
If set, LIB$FIND_FILE returns an error if a wildcard character is input.
|
|
1
|
LIB$M_FIL_MULTIPLE
|
If set, this performs temporary defaulting for multiple input files and
the
related-filespec argument is ignored. See description
of
context in LIB$FILE_SCAN. Each time LIB$FIND_FILE is
called with a different file specification, the specification from the
previous call is automatically used as a related file specification.
This allows parsing of the elements of a search-list logical name such
as DISK2:[SMITH] FIL1.TYP,FIL*2.TYP, and so on. Use of this feature is
required to get the desired defaulting with search list logical name.
LIB$FIND_FILE_END must be called between each command line in
interactive use or the defaults from the previous command line affect
the current file specification.
|
|
2
|
LIB$M_FIL_LONG_NAMES
|
(Alpha only) If set, LIB$FIND_FILE can process file specifications with
a maximum length of NAML$C_MAXRSS. If clear, LIB$FIND_FILE can process
file specifications with a maximum length of 255 (default).
|
Description
LIB$FIND_FILE returns one file specification per call unless it fails
to find the target file specification. In this case, the routine
returns the condition value RMS$_NMF (no more files). Each successful
call to LIB$FIND_FILE results in a new
resultant-filespec.
When you call LIB$FIND_FILE repeatedly using the same
context, filespec is saved only if
you set the MULTIPLE bit. If you specify a different
filespec on your next call and set the MULTIPLE bit,
the file specification from the previous call defaults as the related
file specification.
For each LIB$FIND_FILE call, RMS first applies the defaults from
default-filespec and then uses the defaults from
related-filespec, if relevant. Default file
specifications are used only if components are missing from the
filespec argument and the needed components are found
in default-filespec. The
related-filespec argument is used when you process
lists of file specifications. Unspecified portions of the file
specification are inherited from the last file processed. This provides
an extra level of file specification defaults. For additional
information on related file specifications and input file parsing, see
the Guide to OpenVMS File Applications.
The filespec argument can contain wildcard characters.
LIB$FIND_FILE can be called repeatedly using the same
context argument until the error RMS$_NMF (no more
files) is returned.
LIB$FIND_FILE searches for a certain wildcard file specification and
returns all file specifications that satisfy that wildcard file
specification.
If you make multiple calls to LIB$FIND_FILE, be aware of the following
behavior:
- If the NOWILD bit is not set and the file specification does not
contain any wildcard characters, LIB$FIND_FILE returns the appropriate
file name on the first call and the condition value RMS$_NMF on the
next call.
- If the NOWILD bit is set and you use the same nonwildcard file
specification, LIB$FIND_FILE returns the file name on the first call as
well as each subsequent call.
On Alpha systems, support for file specifications longer than 255
characters is provided only when the LIB$M_FIL_LONG_NAMES flag is set
in the flags argument. When this flag is set, a NAML
block (rather than a NAM block) is part of the context, and file
specifications can have a maximum length of NAML$C_MAXRSS. See the
OpenVMS Record Management Services Reference Manual for information on NAML blocks.
You must call LIB$FIND_FILE_END before initiating a new sequence of
calls to LIB$FIND_FILE to properly deallocate all of the internal data
structures that were allocated in the calls to LIB$FIND_FILE. After you
call LIB$FIND_FILE_END, the context value is no longer valid and cannot
be used on any subsequent LIB$FIND_FILE calls.
If the error RMS$_CHN is returned, RMS has no more channels to assign.
There are two possible reasons for this:
- You did not call LIB$FIND_FILE_END before initiating a new call
with a context variable to LIB$FIND_FILE. (This is the most common
reason.)
- The system parameter CHANNELCNT is too low.
Condition Values Returned
|
RMS$_NORMAL
|
Routine successfully completed.
|
|
LIB$_NOWILD
|
A wildcard character was present in the file specification parsed, and
the wildcard flag bit was set to no wildcard. (This is actually the
SHR$_NOWILD error message after application of the LIB$ facility code.)
|
|
RMS$_CHN
|
No more channels.
|
|
RMS$_NMF
|
No more files.
|
Any condition value returned by RMS Parse and Search services,
LIB$GET_VM, LIB$GET_VM_64, LIB$FREE_VM, LIB$FREE_VM_64, LIB$SCOPY_R_DX,
or LIB$SCOPY_R_DX_64.
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 reference |
Control flags. The flags argument is the address of a
longword integer that contains the control flags.
| Bit |
Value |
Description |
|
0
|
Reserved to Compaq
|
|
|
1
|
Reserved to Compaq
|
|
|
2
|
Reserved to Compaq
|
|
|
3
|
Reserved to Compaq
|
|
|
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 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 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 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.
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.
|
