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

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

    Format

      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. The return value is ignored by DECTPU.
    User-written FILE_PARSE routines should include calls to the
    TPU$SIGNAL routine to ensure proper error handling.

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_PARSE. The calling
    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.

 flags

    OpenVMS usage: longword_unsigned
    type:          longword (unsigned)
    access:        read only
    mechanism:     by reference
    The following table lists the valid flag values used to request
    file specification 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_HEAD        Requests for the NODE, DEVICE, and DIRECTORY
                      components of the file specification.
    TPU$M_TAIL        Requests for NAME, TYPE, and VERSION components
                      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
    Contains the default file specification. The value 0 is passed if
    there is no default-spec argument.

 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

    This routine allows an application to replace the TPU$FILE_PARSE
    routine with its own file-parsing routine. The calling program
    passes the address of the file-parsing routine to TPU$INITIALIZE
    using the TPU$_FILE_PARSE item code.

    When the DECTPU built-in procedure FILE_PARSE is called from
    TPU code, DECTPU calls either the user-written routine (if one
    was passed to TPU$INITIALIZE) or the TPU$FILE_PARSE 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 error handlers,
    errors should be signaled using the TPU$SIGNAL routine.