VMS Help RTL Routines, LIB$, LIB$FIND_FILE  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    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 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 only) If set, LIB$FIND_FILE
         NAMES              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).