VMS Help DECTPU, FILE_SEARCH  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    This is a user-written routine that is used in place of the
    TPU$FILE_SEARCH routine.

    Format

      FILE_SEARCH  result-string ,flags ,filespec ,default-spec

                   ,related-spec

1 - Returns

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

    Longword condition value. If an odd numeric value is returned,
    the next call to the built-in procedure FILE_SEARCH automatically
    sets the TPU$M_REPARSE bit in the flags longword. TPU$M_REPARSE
    is also set if the result-string has a length of 0.

2 - Arguments

 result-string

    OpenVMS usage: char_string
    type:          character string
    access:        write only
    mechanism:     by descriptor
    Return value for the built-in procedure FILE_SEARCH. Your program
    should fill in this descriptor with a dynamic string allocated
    by the string routines such as the Run-Time Library routine
    LIB$SGET1_DD. DECTPU frees this string when necessary.

    The TPU$M_REPARSE bit is set in the flags longword if the result-
    string has a length of zero. The bit is intended to reset the
    file search when wildcard searches are performed.

 flags

    OpenVMS usage: longword_unsigned
    type:          longword (unsigned)
    access:        read only
    mechanism:     by reference
    The following table shows the flags used for specifying the file
    components:

    Flag              Function

    TPU$M_NODE        Requests for the node component of the file
                      specification.
    TPU$M_DEV         Requests for the device component of the file
                      specification.
    TPU$M_DIR         Requests for the directory component of the
                      file specification.
    TPU$M_NAME        Requests for the name component of the file
                      specification.
    TPU$M_TYPE        Requests for the type component of the file
                      specification.
    TPU$M_VER         Requests for the version component of the file
                      specification.
    TPU$M_REPARSE     Reparses the file specification before
                      processing. This is intended as a way to
                      restart the file search. This flag will
                      automatically be set by DECTPU if on a previous
                      call to the FILE_SEARCH user routine the
                      result-string has a zero length or the routine
                      returns a odd (noneven) status.
    TPU$M_HEAD        Requests for the NODE, DEVICE, and DIRECTORY
                      components of the file specification.
    TPU$M_TAIL        Requests for the NAME, TYPE, and VERSION
                      component of the file specification.

 filespec

    OpenVMS usage: char_string
    type:          character string
    access:        read only
    mechanism:     by descriptor
    The object file specification.

 default-spec

    OpenVMS usage: char_string
    type:          character string
    access:        read only
    mechanism:     by descriptor
    The default-spec argument contains the default file
    specification.

    The value 0 is passed if there is no default-spec.

 related-spec

    OpenVMS usage: char_string
    type:          character string
    access:        read only
    mechanism:     by descriptor
    The related-spec argument contains the related file
    specification.

    The value 0 is passed if there is no related-spec.

3 - Description

    The FILE_SEARCH user routine allows an application to replace
    the TPU$FILE_SEARCH routine with its own file-searching routine.
    The calling program passes the address of the routine to the
    TPU$INITIALIZE routine using the TPU$_FILE_SEARCH item code.

    When the DECTPU built-in procedure FILE_SEARCH is called from TPU
    code, DECTPU calls either the user-written FILE_SEARCH routine
    (if one was passed to TPU$INITIALIZE) or the TPU$FILE_SEARCH
    routine. The return value of the built-in procedure is the string
    returned in the result-string argument.

    To ensure proper operation of the user's ON_ERROR handlers,
    errors in the user-written FILE_PARSE routine should be signaled
    using the TPU$SIGNAL routine.