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]
1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2 – 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 or I64 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_ If set, this performs temporary
MULTIPLE 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_ (Alpha and I64 only) If set, LIB$FIND_
NAMES 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).