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

    The TPU$FILE_PARSE routine provides a simplified interface to
    the $PARSE system service. DECTPU calls this routine when the
    built-in procedure FILE_PARSE is executed from TPU code.

    Format

      TPU$FILE_PARSE  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 specified by
    the flags argument. The memory for the return string is allocated
    via the Run-Time Library routine LIB$SGET1_DD. Use the Run-Time
    Library routine LIB$SFREE1_DD to deallocate the memory for the
    return string.

 flags

    OpenVMS usage: longword_unsigned
    type:          longword (unsigned)
    access:        read only
    mechanism:     by reference
    Determine what file specification components should be returned.
    The following table shows the valid values for the flags
    argument:

    Flag Bit          Description

    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_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 signals the
                      error TPU$_INCKWDCOM and returns control to the
                      caller.
    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 signals the
                      error TPU$_INCKWDCOM and returns control to the
                      caller.

 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
    Contains the default file specification. The default file
    specification fields are used in the result string as substitutes
    for fields omitted in the filespec argument. You can also
    make substitutions in the result string using the related-spec
    argument.

    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 substituted in the result-string
    if a particular field is missing from both the filespec and
    default-spec arguments.

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

3 - Description

    The TPU$FILE_PARSE routine returns a string containing the fields
    requested of the file specified. The file is not required to
    exist when the parse is done. The intention of the TPU$FILE_
    PARSE routine is to construct a valid file specification from the
    information passed in through the file specification, the default
    file specification, and the related file specification.

    The routine uses the $PARSE system service to return the
    requested information.

    The TPU$FILE_PARSE routine is also called by DECTPU when the
    TPU built-in procedure FILE_PARSE 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, then the last
                       match of the search operations has occurred.
    TPU$_INCKWDCOM     The flags argument had an illegal combination
                       of values.
    TPU$_PARSEFAIL     The parse failed.