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

    The File Scan routine searches an area, such as a directory, for
    all files matching the file specification given and transfers
    program execution to the specified user-written routine.
    Wildcards are acceptable. An action routine is called for each
    file and/or error found. LIB$FILE_SCAN allows the search sequence
    to continue even if an error occurs while processing a particular
    file.

    Format

      LIB$FILE_SCAN  fab ,user-success-procedure

                     ,user-error-procedure [,context]

1 - Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

2 - Arguments

 fab

    OpenVMS usage:fab
    type:         unspecified
    access:       read only
    mechanism:    by reference

    File Access Block (FAB) referencing a valid NAM block or NAML
    block. The fab argument is the address of the FAB that contains
    the address and length of the file specification being searched
    for by LIB$FILE_SCAN. On Alpha systems, NAML blocks support the
    use of file specifications with a maximum length of NAML$C_
    MAXRSS. See the OpenVMS Record Management Services Reference
    Manual for information on NAML blocks.

 user-success-procedure

    OpenVMS usage:procedure
    type:         procedure value
    access:       function call (before return)
    mechanism:    by value

    User-supplied success routine that LIB$FILE_SCAN calls when
    a file is found. The success routine is invoked with the FAB
    address that was passed to LIB$FILE_SCAN. The user context may be
    pased to this routine using the FAB$L_CTX field in the FAB.

 user-error-procedure

    OpenVMS usage:procedure
    type:         procedure value
    access:       function call (before return)
    mechanism:    by value

    User-supplied error routine that LIB$FILE_SCAN calls when it
    encounters an error. The error routine is called with the FAB
    argument that was passed to LIB$FILE_SCAN.

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference

    Default file context used in processing file specifications for
    multiple input files. The context argument is the address of
    a longword, which must be initialized to zero by your program
    before the first call to LIB$FILE_SCAN. After the first call,
    LIB$FILE_SCAN maintains this longword. You must not change the
    value of context in subsequent calls to LIB$FILE_SCAN.

    Name blocks and file specification strings are allocated by
    LIB$FILE_SCAN, and context is used to retain their addresses
    so they may be deallocated later. If the context argument is not
    passed, unspecified portions of the file specification will be
    inherited from the previous file specification processed, rather
    than from multiple input file specifications.