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).