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

    The TPU$FILE_SEARCH routine provides a simplified interface to
    the $SEARCH system service. DECTPU call this routine when TPU
    code executes the FILE_SEARCH built-in procedure.

    Format

      TPU$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. Most utility routines return a
    condition value in R0. See Condition Values Returned.

2 - Arguments

 result-string

    OpenVMS usage: char_string
    type:          character string
    access:        write only
    mechanism:     by descriptor
    Includes the components of the file specification passed by the
    flags argument. The memory for the return string is allocated via
    the Run-Time Library routine LIB$SGET1_DD. To deallocate memory
    for the string, use the Run-Time Library routine LIB$SFREE1_DD.

 flags

    OpenVMS usage: longword_unsigned
    type:          longword (unsigned)
    access:        read only
    mechanism:     by reference
    Determines what file specification components should be returned.
    The following table lists the valid flag values:

    Flag              Function

    TPU$M_NODE        Returns the node component of the file
                      specification.
    TPU$M_DEV         Returns the device component of the file
                      specification.
    TPU$M_DIR         Returns the directory component of the file
                      specification.
    TPU$M_NAME        Returns the name component of the file
                      specification.
    TPU$M_TYPE        Returns the type component of the file
                      specification.
    TPU$M_VER         Returns the version component of the file
                      specification.
    TPU$M_REPARSE     Reparses the file specification before
                      processing. This is intended to be used to
                      reset the file search.
    TPU$M_HEAD        Returns NODE, DEVICE, and DIRECTORY components
                      of the file specification. If the TPU$M_NODE,
                      TPU$M_DEV or TPU$M_DIR bits are set while
                      TPU$M_HEAD is set, the routine will signal
                      the error TPU$_INCKWDCOM and return.
    TPU$M_TAIL        Returns NAME, TYPE and VERSION components of
                      the file specification. If the TPU$M_NAME,
                      TPU$M_TYPE or TPU$M_VER bits are set while
                      TPU$M_TAIL is set, the routine will signal the
                      error TPU$_INCKWDCOM and return.

 filespec

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

 default-spec

    OpenVMS usage: char_string
    type:          character string
    access:        read only
    mechanism:     by descriptor
    The default file specification. The default file specification
    fields are used to fill in the result-string when fields are
    omitted in the filespec argument. Use the related-spec argument
    to specify other substitutions.

    Use the value 0 when no default-spec is to be applied to the file
    specification.

 related-spec

    OpenVMS usage: char_string
    type:          character string
    access:        read only
    mechanism:     by descriptor
    Contains the related file specification. The fields in the
    related file specification are used in the result-string for
    fields omitted in the filespec and default-spec arguments.

    Use the value 0 when no default-spec is to be applied to the file
    specification.

3 - Description

    This routine allows an application to verify the existence
    of, and return components of, a file specification. Wildcard
    operations are permitted. The routine uses the $PARSE and $SEARCH
    system services to seek the file specification.

    If no wildcards are included in the file specification string
    and the result-string returns a zero (0) length string, no
    file was found. If wildcard characters were present in the file
    specification and the result-string returns a zero (0) length
    string, there are no more files that match the wildcards.

    To find all the files that match a wildcard specification,
    repeatedly call this routine, passing the same arguments, until
    the routine returns a zero-length result string.

    The TPU$FILE_SEARCH routine is called by DECTPU when the TPU
    built-in procedure FILE_SEARCH is executed from TPU code. The
    return value of the built-in procedure is the string returned in
    the result-string argument.

4 - Condition Values Returned

    TPU$_SUCCESS       Normal successful completion. If the return
                       string contains a null string, the final match
                       operation was detected.
    TPU$_INCKWDCOM     The flags argument had an illegal combination
                       of values.
    TPU$_PARSEFAIL     The requested repeat parse failed.
    TPU$_SEARCHFAIL    An error occurred during the search operation.