VMS Help  —  TPU
    These routines are part of the callable VSI Text Processing
    Utility (TPU).

1  –  TPU$CLEANUP

    The TPU$CLEANUP routine cleans up internal data structures, frees
    memory, and restores terminals to their initial state.

    This is the final routine called in each interaction with TPU.

    Format

      TPU$CLEANUP  flags

1.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. The condition value that this routine
    can return is listed under Condition Value Returned.

1.2  –  Argument

 flags

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Flags (or mask) defining the cleanup options. The flags argument
    is the address of a longword bit mask defining the cleanup
    options or the address of a 32-bit mask defining the cleanup
    options. This mask is the logical OR of the flag bits you want to
    set. Following are the various cleanup options:

    Flag(1)              Function

    TPU$M_DELETE_        Closes and deletes the journal file if it is
    JOURNAL              open.
    TPU$M_DELETE_EXITH   Deletes the TPU exit handler.
    TPU$M_DELETE_        Deletes all text buffers. If this is not the
    BUFFERS              last time you are calling TPU, then all
                         variables referring to these data structures
                         are reset, as if by the built-in procedure
                         DELETE. If a buffer is deleted, then all
                         ranges and markers within that buffer, and
                         any subprocesses using that buffer, are also
                         deleted.
    TPU$M_DELETE_        Deletes all windows. If this is not the
    WINDOWS              last time you are calling TPU, then all
                         variables referring to these data structures
                         are reset, as if by the built-in procedure
                         DELETE.
    TPU$M_DELETE_CACHE   Deletes the virtual file manager's data
                         structures and caches. If this deletion
                         is requested, then all buffers are also
                         deleted. If the cache is deleted, the
                         initialization routine has to reinitialize
                         the virtual file manager the next time it is
                         called.
    TPU$M_PRUNE_CACHE    Frees up any virtual file manager caches
                         that have no pages allocated to buffers.
                         This frees up any caches that may have been
                         created during the session but are no longer
                         needed.
    TPU$M_EXECUTE_FILE   Reexecutes the command file if TPU$EXECUTE_
                         INIFILE is called again. You must set this
                         bit if you plan to specify a new file name
                         for the command file. This option is used
                         in conjunction with the option bit passed
                         to TPU$INITIALIZE indicating the presence of
                         the /COMMAND qualifier.
    TPU$M_EXECUTE_PROC   Looks up TPU$INIT_PROCEDURE and executes it
                         the next time TPU$EXECUTE_INIFILE is called.
    TPU$M_DELETE_        Deletes the entire context of TPU. If
    CONTEXT              this option is specified, then all other
                         options are implied, except for executing
                         the initialization file and initialization
                         procedure.
    TPU$M_RESET_         Resets the terminal to the state it was in
    TERMINAL             upon entry to TPU. The terminal mailbox
                         and all windows are deleted. If the terminal
                         is reset, then it is reinitialized the next
                         time TPU$INITIALIZE is called.
    TPU$M_KILL_          Deletes all subprocesses created during the
    PROCESSES            session.
    TPU$M_CLOSE_         Closes the section file and releases the
    SECTION(2)           associated memory. All buffers, windows, and
                         processes are deleted. The cache is purged
                         and the flags are set for reexecution of
                         the initialization file and initialization
                         procedure. If the section is closed and if
                         the option bit indicates the presence of
                         the SECTION qualifier, then the next call
                         to TPU$INITIALIZE attempts a new restore
                         operation.
    TPU$M_DELETE_        Deletes all miscellaneous preallocated data
    OTHERS               structures. Memory for these data structures
                         is reallocated the next time TPU$INITIALIZE
                         is called.
    TPU$M_LAST_TIME      This bit should be set only when you are
                         calling TPU for the last time. Note that
                         if you set this bit and then recall TPU,
                         the results are unpredictable.

    Footnotes:

    1. The flag prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask
       corresponding to the specific field in which the bit is set.
       TPU$V_ is a bit number.

    2. Using the simplified callable interface does not set TPU$_
       CLOSE_SECTION. This feature allows you to make multiple calls
       to TPU$TPU without requiring you to open and close the section
       file on each call.

1.3  –  Description

    The cleanup routine is the final routine called in each
    interaction with TPU. It tells TPU to clean up its internal
    data structures and prepare for additional invocations. You can
    control what is reset by this routine by setting or clearing the
    flags described previously.

    When you finish with TPU, call this routine to free the memory
    and restore the characteristics of the terminal to their original
    settings.

    If you intend to exit after calling TPU$CLEANUP, do not
    delete the data structures; the operating system does this
    automatically. Allowing the operating system to delete the
    structures improves the performance of your program.

    Notes

    1. When you use the simplified interface, TPU automatically
       sets the following flags:

       o  TPU$V_RESET_TERMINAL

       o  TPU$V_DELETE_BUFFERS

       o  TPU$V_DELETE_JOURNAL

       o  TPU$V_DELETE_WINDOWS

       o  TPU$V_DELETE_EXITH

       o  TPU$V_EXECUTE_PROC

       o  TPU$V_EXECUTE_FILE

       o  TPU$V_PRUNE_CACHE

       o  TPU$V_KILL_PROCESSES

    2. If this routine does not return a success status, no other
       calls to the editor should be made.

1.4  –  Condition Value Returned

    TPU$_SUCCESS       Normal successful completion.

2  –  TPU$CLIPARSE

    The TPU$CLIPARSE routine parses a command line and builds the
    item list for TPU$INITIALIZE.

    Format

      TPU$CLIPARSE  string ,fileio ,call_user

2.1  –  Returns

    OpenVMS usage:item_list
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    This routine returns the address of an item list.

2.2  –  Arguments

 string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor
    Command line. The string argument is the address of a descriptor
    of a TPU command.

 fileio

    OpenVMS usage:vector_longword_unsigned
    type:         bound procedure value
    access:       read only
    mechanism:    by descriptor
    File I/O routine. The fileio argument is the address of a
    descriptor of a file I/O routine.

 call_user

    OpenVMS usage:vector_longword_unsigned
    type:         bound procedure value
    access:       read only
    mechanism:    by descriptor
    Call-user routine. The call_user argument is the address of a
    descriptor of a call-user routine.

2.3  –  Description

    This routine calls CLI$DCL_PARSE to establish a command table and
    a command to parse. It then calls TPU$PARSEINFO to build an item
    list for TPU$INITIALIZE.

    If your application parses information that is not related to the
    operation of TPU, make sure the application obtains and uses
    all non-TPU parse information before the application calls
    TPU$CLIPARSE. You must do this because TPU$CLIPARSE destroys all
    parse information obtained and stored before TPU$CLIPARSE was
    called.

3  –  TPU$CLOSE_TERMINAL

    The TPU$CLOSE_TERMINAL routine closes the TPU channel to the
    terminal.

    Format

      TPU$CLOSE_TERMINAL

3.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. The condition value that this routine
    can return is listed under Condition Value Returned.

3.2  –  Arguments

    None.

3.3  –  Description

    This routine is used with the built-in procedure CALL_USER and
    its associated call-user routine to control the TPU access
    to the terminal. When a call-user routine invokes TPU$CLOSE_
    TERMINAL, TPU closes its channel to the terminal and the
    channel of the TPU associated mailbox.

    When the call-user routine returns control to it, TPU
    automatically reopens a channel to the terminal and redisplays
    the visible windows.

    A call-user routine can use TPU$CLOSE_TERMINAL at any point in
    the program and as many times as necessary. If the terminal is
    already closed to TPU when TPU$CLOSE_TERMINAL is used, the
    call is ignored.

3.4  –  Condition Value Returned

    TPU$_SUCCESS       Normal successful completion.

4  –  TPU$CONTROL

    The TPU$CONTROL routine is the main processing routine of the
    TPU editor. It is responsible for reading the text and
    commands and executing them. When you call this routine (after
    calling TPU$INITIALIZE), control is turned over to TPU.

    Format

      TPU$CONTROL  [integer]

4.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. Condition values that this routine can
    return are listed under Condition Values Returned.

4.2  –  Argument

 integer

    OpenVMS usage:integer
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Prevents TPU from displaying the message "Editing session is
    not being journaled" when the calling program gives control to
    TPU. Specify a true (odd) integer to preserve compatibility in
    future releases. If you omit the parameter, TPU displays the
    message if journaling is not enabled.

4.3  –  Description

    This routine controls the editing session. It is responsible for
    reading the text and commands and for executing them. Windows on
    the screen are updated to reflect the edits made. Your program
    can regain control by interrupting TPU using the TPU$SPECIFY_
    ASYNC_ACTION routine, together with the TPU$TRIGGER_ASYNC_ACTION
    routine.

                                   NOTE

       Control is also returned to your program if an error occurs
       or when you enter either the built-in procedure QUIT or the
       built-in procedure EXIT.

4.4  –  Condition Values Returned

    TPU$_EXITING       A result of EXIT (when the default condition
                       handler is established).
    TPU$_NONANSICRT    A result of operation termination - results
                       when you call TPU with TPU$DISPLAYFILE
                       set to nodisplay and you attempt to execute
                       screen-oriented commands.
    TPU$_QUITTING      A result of QUIT (when the default condition
                       handler is established).
    TPU$_RECOVERFAIL   A recovery operation was terminated
                       abnormally.

5  –  TPU$EDIT

    The TPU$EDIT routine builds a command string from its parameters
    and passes it to the TPU$TPU routine.

    TPU$EDIT is another entry point to the TPU simplified callable
    interface.

    Format

      TPU$EDIT  input ,output

5.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. Condition values that this routine can
    return are listed under Condition Values Returned.

5.2  –  Arguments

 input

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor
    Input file name. The input argument is the address for a
    descriptor of a file specification.

 output

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor
    Output file name. The output argument is the address for a
    descriptor of an output file specification. It is used with the
    /OUTPUT command qualifier.

5.3  –  Description

    This routine builds a command string and passes it to TPU$TPU. If
    the length of the output descriptor is nonzero, then the /OUTPUT
    qualifier is added to the command string. The /OUTPUT qualifier
    causes a file to be written to the specified file even if no
    modifications are made to the input file. If the QUIT built-
    in procedure is called, it prompts the user as if changes had
    been made to the buffer. This allows applications to check for
    the existence of the output file to see if the editing session
    was terminated, which is consistent with other OpenVMS callable
    editors.

    If your application parses information that is not related to the
    operation of TPU, make sure the application obtains and uses
    all non-TPU parse information before the application calls
    TPU$EDIT. Your application must do this because TPU$EDIT destroys
    all parse information obtained and stored before TPU$EDIT is
    called.

5.4  –  Condition Values Returned

    This routine returns the same values as TPU$TPU.

6  –  TPU$EXECUTE_COMMAND

    The TPU$EXECUTE_COMMAND routine allows your program to execute
    TPU statements.

    Format

      TPU$EXECUTE_COMMAND  string

6.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. Condition values that this routine can
    return are listed under Condition Values Returned.

6.2  –  Argument

 string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by value
    TPU statement. The string argument is the address of a
    descriptor of a character string denoting one or more TPU
    statements.

6.3  –  Description

    This routine performs the same function as the built-in procedure
    EXECUTE described in the VSI Text Processing Utility Reference
    Manual.

6.4  –  Condition Values Returned

    TPU$_SUCCESS       Normal successful completion.
    TPU$_EXECUTEFAIL   Execution aborted. This could be because of
                       execution errors or compilation errors.
    TPU$_EXITING       EXIT built-in procedure was invoked.
    TPU$_QUITTING      QUIT built-in procedure was invoked.

7  –  TPU$EXECUTE_INIFILE

    The TPU$EXECUTE_INIFILE routine allows you to execute a user-
    written initialization file.

    This routine must be executed after the editor is initialized and
    before any other commands are processed.

    Format

      TPU$EXECUTE_INIFILE

7.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. Condition values that this routine can
    return are listed under Condition Values Returned.

7.2  –  Arguments

    None.

7.3  –  Description

    Calling the TPU$EXECUTE_INIFILE routine causes TPU to perform
    the following steps:

    1. The command file is read into a buffer. The default is
       TPU$COMMAND.TPU. If you specified a file on the command line
       that cannot be found, an error message is displayed and the
       routine is aborted.

    2. If you specified the /DEBUG qualifier on the command
       line, the DEBUG file is read into a buffer. The default is
       SYS$SHARE:TPU$DEBUG.TPU.

    3. The DEBUG file is compiled and executed (if available).

    4. TPU$INIT_PROCEDURE is executed (if available).

    5. The Command buffer is compiled and executed (if available).

    6. TPU$INIT_POSTPROCEDURE is executed (if available).

                                   NOTE

       If you call this routine after calling TPU$CLEANUP, you must
       set the flags TPU$_EXECUTEPROCEDURE and TPU$_EXECUTEFILE.
       Otherwise, the initialization file does not execute.

7.4  –  Condition Values Returned

    TPU$_SUCCESS       Normal successful completion.
    TPU$_COMPILEFAIL   The compilation of the initialization file was
                       unsuccessful.
    TPU$_EXECUTEFAIL   The execution of the statements in the
                       initialization file was unsuccessful.
    TPU$_EXITING       A result of EXIT. If the default condition
                       handler is being used, the session is
                       terminated.
    TPU$_FAILURE       General code for all other errors.
    TPU$_QUITTING      A result of QUIT. If the default condition
                       handler is being used, the session is
                       terminated.

8  –  TPU$FILEIO

    The TPU$FILEIO routine handles all TPU file operations.
    Your own file I/O routine can call this routine to perform some
    operations for it. However, the routine that opens the file must
    perform all operations for that file. For example, if TPU$FILEIO
    opens the file, it must also close it.

    Format

      TPU$FILEIO  code ,stream ,data

8.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. Condition values that this routine can
    return are listed under Condition Values Returned.

8.2  –  Arguments

 code

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item code specifying a TPU function. The code argument is
    the address of a longword containing an item code from TPU
    specifying a function to perform. Following are the item codes
    that you can specify in the file I/O routine:

    o  TPU$K_OPEN-This item code specifies that the data parameter
       is the address of an item list. This item list contains the
       information necessary to open the file. The stream parameter
       should be filled in with a unique identifying value to be used
       for all future references to this file. The resultant file
       name should also be copied with a dynamic string descriptor.

    o  TPU$K_CLOSE-The file specified by the stream argument is to
       be closed. All memory being used by its structures can be
       released.

    o  TPU$K_CLOSE_DELETE-The file specified by the stream argument
       is to be closed and deleted. All memory being used by its
       structures can be released.

    o  TPU$K_GET-The data parameter is the address of a dynamic
       string descriptor to be filled with the next record from the
       file specified by the stream argument. The routine should use
       the routines provided by the Run-Time Library to copy text
       into this descriptor. TPU frees the memory allocated for
       the data read when the file I/O routine indicates that the end
       of the file has been reached.

    o  TPU$K_PUT-The data parameter is the address of a descriptor
       for the data to be written to the file specified by the stream
       argument.

 stream

    OpenVMS usage:unspecified
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    File description. The stream argument is the address of a data
    structure consisting of four longwords. This data structure
    describes the file to be manipulated.

    This data structure is used to refer to all files. It is written
    to when an open file request is made. All other requests use
    information in this structure to determine which file is being
    referenced.

    The following figure shows the stream data structure:

    ----------------------------------------------
    |               File identifier              |
    ----------------------------------------------
    |     RFM      |              |  Allocation  |
    ----------------------------------------------
    |    Class     |    Type      |    Length    |
    ----------------------------------------------

    The first longword holds a unique identifier for each file. The
    user-written file I/O routine is restricted to values between 0
    and 511. Thus, you can have up to 512 files open simultaneously.

    The second longword is divided into three fields. The low word
    is used to store the allocation quantity, that is, the number
    of blocks allocated to this file from the FAB (FAB$L_ALQ).
    This value is used later to calculate the output file size for
    preallocation of disk space. The low-order byte of the second
    word is used to store the record attribute byte (FAB$B_RAT)
    when an existing file is opened. The high-order byte is used
    to store the record format byte (FAB$B_RFM) when an existing file
    is opened. The values in the low word and the low-order and high-
    order bytes of the second word are used for creating the output
    file in the same format as the input file. These three fields are
    to be filled in by the routine opening the file.

    The last two longwords are used as a descriptor for the resultant
    or the expanded file name. This name is used later when TPU
    processes EXIT commands. This descriptor is to be filled in with
    the file name after an open operation. It should be allocated
    with either the routine LIB$SCOPY_R_DX or the routine LIB$SCOPY_
    DX from the Run-Time Library. This space is freed by TPU when
    it is no longer needed.

 data

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Stream data. The data argument is either the address of an item
    list or the address of a descriptor.

                                   NOTE

       The meaning of this parameter depends on the item code
       specified in the code field.

    When the TPU$K_OPEN item code is issued, the data parameter is
    the address of an item list containing information about the
    open request. The following TPU item codes are available for
    specifying information about the open request:

    o  TPU$K_ACCESS item code lets you specify one of three item
       codes in the buffer address field, as follows:

       -  TPU$K_IO

       -  TPU$K_INPUT

       -  TPU$K_OUTPUT

    o  TPU$K_FILENAME item code is used for specifying the address
       of a string to use as the name of the file you are opening.
       The length field contains the length of this string, and the
       address field contains the address.

    o  TPU$K_DEFAULTFILE item code is used for assigning a default
       file name to the file being opened. The buffer length field
       contains the length, and the buffer address field contains the
       address of the default file name.

    o  TPU$K_RELATEDFILE item code is used for specifying a related
       file name for the file being opened. The buffer length field
       contains the length, and the buffer address field contains the
       address of a string to use as the related file name.

    o  TPU$K_RECORD_ATTR item code specifies that the buffer address
       field contains the value for the record attribute byte in the
       FAB (FAB$B_RAT) used for file creation.

    o  TPU$K_RECORD_FORM item code specifies that the buffer address
       field contains the value for the record format byte in the FAB
       (FAB$B_RFM) used for file creation.

    o  TPU$K_MAXIMIZE_VER item code specifies that the version number
       of the output file should be one higher than the highest
       existing version number.

    o  TPU$K_FLUSH item code specifies that the file should have
       every record flushed after it is written.

    o  TPU$K_FILESIZE item code is used for specifying a value to be
       used as the allocation quantity when creating the file. The
       value is specified in the buffer address field.

8.3  –  Description

    By default, TPU$FILEIO creates variable-length files with
    carriage-return record attributes (FAB$B_RFM = VAR, FAB$B_RAT
    FORM item, that item is used instead.

    The following combinations of formats and attributes are
    acceptable:

    Format           Attributes

    STM,STMLF,STMCR  0,BLK,CR,BLK+CR
    VAR              0,BLK,FTN,CR,BLK+FTN,BLK+CR

    All other combinations are converted to VAR format with CR
    attributes.

    This routine always puts values greater than 511 in the first
    longword of the stream data structure. Because a user-written
    file I/O routine is restricted to the values 0 through 511, you
    can easily distinguish the file control blocks (FCB) this routine
    fills in from the ones you created.

                                   NOTE

       TPU uses TPU$FILEIO by default when you use the
       simplified callable interface. When you use the full
       callable interface, you must explicitly invoke TPU$FILEIO
       or provide your own file I/O routine.

8.4  –  Condition Values Returned

    The TPU$FILEIO routine returns an OpenVMS RMS status code to
    TPU. The file I/O routine is responsible for signaling all
    errors if any messages are desired.

9  –  TPU$FILE_PARSE

    The TPU$FILE_PARSE routine provides a simplified interface to
    the $PARSE system service. TPU 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

9.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.

9.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(1)       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.

    (1) TPU$M... indicates a mask. There is a corresponding value for
    each mask in the form TPU$V...

 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.

9.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 TPU 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.

9.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.

10  –  TPU$FILE_SEARCH

    The TPU$FILE_SEARCH routine provides a simplified interface to
    the $SEARCH system service. TPU 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

10.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.

10.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(1)           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.

    (1) TPU$M... indicates a mask. There is a corresponding value for
    each mask in the form TPU$V...

 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.

10.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 TPU 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.

10.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.

11  –  TPU$HANDLER

    The TPU$HANDLER routine is the TPU condition handler.

    The TPU condition handler invokes the $PUTMSG system service,
    passing it the address of TPU$MESSAGE.

    Format

      TPU$HANDLER  signal_vector ,mechanism_vector

11.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.

11.2  –  Arguments

 signal_vector

    OpenVMS usage:arg_list
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Signal vector. See the VSI OpenVMS System Services Reference
    Manual for information about the signal vector passed to a
    condition handler.

 mechanism_vector

    OpenVMS usage:arg_list
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Mechanism vector. See the VSI OpenVMS System Services Reference
    Manual for information about the mechanism vector passed to a
    condition handler.

11.3  –  Description

    The TPU$MESSAGE routine performs the actual output of the
    message. The $PUTMSG system service only formats the message.
    It gets the settings for the message flags and facility name from
    the variables described in the OpenVMS Utility Routines Manual in
    the section about the TPU Shareable Image. Those values can be
    modified only by the TPU built-in procedure SET.

    If the condition value received by the handler has a FATAL status
    or does not have the TPU facility code, the condition is
    resignaled.

    If the condition is TPU$_QUITTING, TPU$_EXITING, or TPU$_
    RECOVERFAIL, a request to UNWIND is made to the establisher of
    the condition handler.

    After handling the message, the condition handler returns with
    a continue status. TPU error message requests are made by
    signaling a condition to indicate which message should be written
    out. The arguments in the signal array are a correctly formatted
    message argument vector. This vector sometimes contains multiple
    conditions and formatted ASCII output (FAO) arguments for the
    associated messages. For example, if the editor attempts to open
    a file that does not exist, the TPU message TPU$_NOFILEACCESS
    is signaled. The FAO argument to this message is a string for the
    name of the file. This condition has an error status, followed by
    the OpenVMS RMS status field (STS) and status value field (STV).
    Because this condition does not have a fatal severity, the editor
    continues after handling the error.

    The editor does not automatically return from TPU$CONTROL. If
    you call the TPU$CONTROL routine, you must explicitly establish a
    way to regain control (for example, using the built-in procedure
    CALL_USER). If you establish your own condition handler but call
    the TPU handler for certain conditions, the default condition
    handler must be established at the point in your program where
    you want to return control. You can also interrupt TPU$CONTROL
    by having your program specify and then trigger an asynchronous
    routine via the TPU$SPECIFY_ASNYC_ACTION and TPU$TRIGGER_ASYNC_
    ACTION routines.

    See the VSI OpenVMS Calling Standard for details on writing a
    condition handler.

12  –  TPU$INITIALIZE

    The TPU$INITIALIZE routine initializes TPU for text
    processing. This routine allocates global data structures,
    initializes global variables, and calls the appropriate setup
    routines for each of the major components of the editor,
    including the Screen Manager and the I/O subsystem.

    Format

      TPU$INITIALIZE  callback [,user_arg]

12.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. Condition values that this routine can
    return are listed under Condition Values Returned.

12.2  –  Argument

 callback

    OpenVMS usage:vector_longword_unsigned
    type:         bound procedure value
    access:       read only
    mechanism:    by descriptor
    Callback routine. The callback argument is the address of a
    user-written routine that returns the address of an item list
    containing initialization parameters or a routine for handling
    file I/O operations. This callback routine must call a command
    line parsing routine, which can be TPU$CLIPARSE or a user-written
    parsing routine.

    Callable TPU defines item codes that you can use to specify
    initialization parameters. The following rules must be followed
    when building the item list:

    o  If you use the TPU$_OTHER_FILENAMES item code, it must follow
       the TPU$_FILENAME item code.

    o  If you use either the TPU$_CHAIN item code or the TPU$_ENDLIST
       code, it must be the last item code in the list.

    The following figure shows the general format of an item
    descriptor. For information about how to build an item list,
    refer to the programmer's manual associated with the language
    you are using. Any reference to command line qualifiers refer
    to those command line qualifiers that you use with the EDIT/TPU
    command.

    ---------------------------------------------
    |      Item code      |    Buffer length    |
    ---------------------------------------------
    |              Buffer address               |
    ---------------------------------------------
    |              Return address               |
    ---------------------------------------------

    The return address in an item descriptor is usually 0.

    The following item codes are available:

    Item Code         Description

    TPU$_OPTIONS      Enables the command qualifiers. The bits in
                      the bit mask specified by the buffer address
                      field correspond to the various TPU command
                      qualifiers.
    TPU$_JOURNALFILE  Passes the string specified with the /JOURNAL
                      qualifier. The buffer length field is the
                      length of the string, and the buffer address
                      field is the address of the string. This
                      string is available with GET_INFO (COMMAND_
                      LINE,"JOURNAL_FILE"). This string can be a null
                      string.
    TPU$_SECTIONFILE  Passes the string that is the name of the
                      binary initialization file (section file) to
                      be mapped in. The buffer length field is the
                      length of the string, and the buffer address
                      field is the address of the string. If the
                      TPU$V_SECTION bit is set, this item code must
                      be specified.
    TPU$_OUTPUTFILE   Passes the string specified with the /OUTPUT
                      qualifier. The buffer length field is the
                      length of the string, and the buffer address
                      field specifies the address of the string. This
                      string is returned by the built-in procedure
                      GET_INFO (COMMAND_LINE, "OUTPUT_FILE"). The
                      string can be a null string.
    TPU$_DISPLAYFILE  Passes the string specified with the /DISPLAY
                      qualifier. The buffer length field defines the
                      length of the string, and the buffer address
                      field defines the string address. The interface
                      between the TPUSHR image and the display file
                      image is not documented. Applications should
                      only use this option with documented display
                      files such as TPU$CCTSHR or TPU$MOTIFSHR.
    TPU$_COMMANDFILE  Passes the string specified with the /COMMAND
                      qualifier. The buffer length field is the
                      length of the string, and the buffer address
                      field is the address of the string. This string
                      is returned by the built-in procedure GET_INFO
                      (COMMAND_LINE, "COMMAND_FILE"). The string can
                      be a null string.
    TPU$_FILENAME     Passes the string that is the name of the first
                      input file specified on the command line.
                      The buffer length field specifies the length
                      of this string, and the buffer address field
                      specifies its address. This string is returned
                      by the built-in procedure GET_INFO (COMMAND_
                      LINE, "FIRST_FILE_NAME"). This file name can be
                      a null string.
    TPU$_OTHER_       Passes a string that contains the name of an
    FILENAMES         input file that follows the first input file
                      on the command line. The buffer length field
                      specifies the length of this string, and the
                      buffer address field specifies its address.
                      Each additional file specified on the command
                      line requires its own TPU$_OTHER_FILENAMES item
                      entry. These strings are returned by the GET_
                      INFO (COMMAND_LINE,"NEXT_FILE_NAME") built-
                      in procedure in the order they appear in the
                      item list. This item code must appear after the
                      TPU$_FILENAME item in the item list.
    TPU$_FILEIO       Passes the bound procedure value of a routine
                      to be used for handling file operations.
                      You can provide your own file I/O routine,
                      or you can call TPU$FILEIO, the utility
                      routine provided by TPU for handling file
                      operations. The buffer address field specifies
                      the address of a two-longword vector. The first
                      longword of the vector contains the address of
                      the routine. The second longword specifies the
                      environment value that TPU loads into R1
                      before calling the routine.
    TPU$_CALLUSER     Passes the bound procedure value of the user-
                      written routine that the built-in procedure
                      CALL_USER is to call. The buffer address field
                      specifies the address of a two-longword vector.
                      The first longword of the vector contains the
                      address of the routine. The second longword
                      specifies the environment value that TPU
                      loads into R1 before calling the routine.
    TPU$_INIT_FILE    Passes the string specified with the
                      /INITIALIZATION qualifier. The buffer length
                      field is the length of the string, and the
                      buffer address field is the address of the
                      string. This string is returned by the built-in
                      procedure GET_INFO (COMMAND_LINE,"INIT_FILE").
    TPU$_START_LINE   Passes the starting line number for the edit.
                      The buffer address field contains the first of
                      the two integer values you specified as part
                      of the /START_POSITION command qualifier. The
                      value is available using the built-in procedure
                      GET_INFO (COMMAND_LINE,"LINE"). Usually an
                      initialization procedure uses this information
                      to set the starting position in the main
                      editing buffer. The first line in the buffer
                      is line 1.
    TPU$_START_CHAR   Passes the starting column position for the
                      edit. The buffer address field contains
                      the second of the two integer values you
                      specified as part of the /START_POSITION
                      command qualifier. The value is available
                      using the built-in procedure GET_INFO (COMMAND_
                      LINE, "CHARACTER"). Usually an initialization
                      procedure uses this information to set the
                      starting position in the main editing buffer.
                      The first column on a line to character 1.
    TPU$_             Passes the string specified with the
    CHARACTERSET      /CHARACTER_SET qualifier. The buffer length
                      field specifies the string length and the
                      buffer address field specifies the string
                      address. Valid strings are "DEC_MCS" (the
                      default value), "ISO_LATIN1", and "GENERAL".
                      If the application tries to pass any other
                      string, the routine signals an error and passes
                      the default string (DEC_MCS).
    TPU$_WORKFILE     Passes the string specified with the /WORK
                      qualifier. The buffer length field specifies
                      the string length and the buffer address
                      specifies the string address. This string is
                      available with GET_INFO (COMMAND_LINE, "WORK_
                      FILE").
    TPU$_CHAIN        Passes the address of the next item list to the
                      process specified by the buffer address field.
    TPU$_ENDLIST      Signals the end of the item list.
    TPU$_PARENT_      Passes the appropriate parent widget when
    WIDGET            invoking the DECwindows version of the
                      editor. This routine is not specified by the
                      application; TPU invokes its own application
                      shell. The widget address is passed in the
                      buffer address field. This item code is only
                      valid when using the DECwindows interface.
    TPU$_             Passes the application context to use with the
    APPLICATION_      TPU$_PARENT_WIDGET. TPU defaults to its own
    CONTEXT           application context. The buffer address field
                      specifies the application context address.
                      This item code is only valid when using the
                      DECwindows interface.
    TPU$_             Specifies which file TPU uses to initialize
    DEFAULTSFILE      the X defaults database. The buffer length
                      field specifies the string length and the
                      buffer address field specifies the string
                      address. This item code is only valid when
                      using the DECwindows interface.
    TPU$_CTRL_C_      Passes the bound procedure value of a routine
    ROUTINE           to be used for handling Ctrl/C asynchronous
                      system traps (ASTs). TPU calls the routine
                      when a Ctrl/C AST occurs. If the routine
                      returns a FALSE value, TPU assumes that
                      the Ctrl/C has been handled. If the routine
                      returns a TRUE value, TPU aborts any
                      currently executing TPU procedure. The
                      buffer address field specifies the address
                      of a two-longword vector. The first longword of
                      the vector contains the address of the routine.
                      The second longword specifies the environment
                      value that TPU loads into R1 before calling
                      the routine.
    TPU$_DEBUGFILE    Passes the string specified with the /DEBUG
                      command qualifier. The buffer length field
                      is the length of the string, and the buffer
                      address field is the address of the string.
    TPU$_FILE_SEARCH  Passes the bound procedure value of a routine
                      to be used to replace the TPU$FILE_SEARCH
                      routine which is called when the built-in
                      procedure FILE_SEARCH is called from TPU code.
                      See the description of the TPU$FILE_SEARCH
                      and the user routine FILE_SEARCH for more
                      information.
    TPU$_FILE_PARSE   Passes the bound procedure value of a routine
                      to be used to replace the TPU$FILE_PARSE
                      routine which is called when the built-
                      in procedure FILE_PARSE is called from TPU
                      code. See the description of the TPU$FILE_
                      PARSE and the user routine FILE_PARSE for more
                      information.

    Valid Masks for the TPU$K_OPTIONS Item Code lists the bits and
    corresponding masks enabled by the item code TPU$K_OPTIONS and
    shows how each bit affects TPU$INITIALIZE operation. Several bits
    in the TPU$_OPTIONS mask require additional item code entries in
    the item list. An example of this is TPU$M_COMMAND which requires
    a TPU$_COMMANDFILE entry in the item list.

    Table 6-1 Valid Masks for the TPU$K_OPTIONS Item Code

                   GET_INFO
                   Request
    Mask(1)        String(2)     Description

    TPU$M_         COMMAND       If TPU senses the presence of
    COMMAND                      the TPU$_COMMANDFILE item, it tries
                                 to read, compile and execute the
                                 unbound TPU code.
    TPU$M_         Not           Specifies that TPU should use
    COMMAND_       applicable    the default command file name of
    DFLTED                       TPU$COMMAND.TPU when reading in the
                                 command file. No error is reported
                                 if the default command file is not
                                 found. TPU$INITIALIZE fails when the
                                 TPU$M_COMMAND_DFLTED bit is set to 0
                                 and no file is specified in the item
                                 list.
    TPU$M_CREATE   CREATE        The behavior of TPU is not
                                 affected by this bit. Its
                                 interpretation is left to the
                                 application layered on TPU.
    TPU$M_DEBUG    Not           If TPU senses the presence of
                   applicable    the TPU$_DEBUGFILE item, it tries to
                                 read the file, and then proceeds to
                                 compile and execute its contents as
                                 TPU statements.
    TPU$M_         Not           If TPU senses the presence of
    DEFAULTS       applicable    the TPU$_DEFAULTSFILE item, it uses
                                 the specified DECwindows X resource
                                 file to initialize the DECwindows X
                                 resource database.
    TPU$M_         DISPLAY       If TPU senses the presence of the
    DISPLAY                      TPU$_DISPLAYFILE item, it tries to
                                 image activate the specified image
                                 as its screen manager. When the
                                 bit is 0, TPU uses SYS$OUTPUT
                                 for display and only the READ_LINE
                                 built-in procedure may be used for
                                 input.
    TPU$M_INIT     INITIALIZATIONIf TPU senses the presence of the
                                 TPU$_INIT_FILE item, it returns the
                                 specified string through the built-
                                 in procedure GET_INFO (COMMAND_LINE,
                                 "INITIALIZATION_FILE"). Processing
                                 of the initialization file is left
                                 to the application.
    TPU$M_         JOURNAL       If TPU senses the presence of the
    JOURNAL                      TPU$_JOURNALFILE item, it outputs
                                 the keystrokes entered during the
                                 editing session to the specified
                                 file.

                                 Note: VSI recommends the use of
                                 buffer change journaling in new
                                 applications.
    TPU$M_MODIFY   MODIFY        The behavior of TPU is not
                                 affected by this bit. Its
                                 interpretation is left to the
                                 application layered on TPU.
    TPU$M_         Not           TPU initializes the DECwindows X
    NODEFAULTS     applicable    resource database only with resource
                                 files that the DECwindows toolkit
                                 routine XtApplInitialize loads into
                                 the database.
    TPU$M_         NOMODIFY      The behavior of TPU is not
    NOMODIFY                     affected by this bit. Its
                                 interpretation is left to the
                                 application layered on TPU.
    TPU$M_OUTPUT   OUTPUT        The behavior of TPU is not
                                 affected by this bit. Its
                                 interpretation is left to the
                                 application layered on TPU.
    TPU$M_READ     READ_ONLY     The behavior of TPU is not
                                 affected by this bit. Its
                                 interpretation is left to the
                                 application layered on TPU.
    TPU$M_         RECOVER       The behavior of TPU is not
    RECOVER                      affected by this bit. Its
                                 interpretation is left to the
                                 application layered on TPU.
    TPU$M_         SECTION       If TPU senses the presence of the
    SECTION                      TPU$_SECTIONFILE item, it tries to
                                 read the specified file as a binary
                                 initialization file. TPU$INITIALIZE
                                 fails if this bit is set to 1 and
                                 the TPU$_SECTIONFILE item is not
                                 present in the item list.
    TPU$M_SEC_     Not           If TPU senses the presence of the
    LNM_MODE       applicable    TPU$M_SEC_LNM_MODE item, it looks
                                 only at executive mode logical names
                                 when attempting to read in a section
                                 file.
    TPU$M_WORK     WORK          If TPU senses the presence of
                                 the TPU$_WORKFILE item, it uses the
                                 specifed file for memory management.
                                 If no item list entry is present,
                                 and this bit is set to 1, a file is
                                 created in SYS$LOGIN:.TPU$WORK.
    TPU$M_WRITE    WRITE         The behavior of TPU is not
                                 affected by this bit. Its
                                 interpretation is left to the
                                 application layered on TPU.

    Footnotes:

    1. The flag prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask
       corresponding to the specific field in which the bit is set.
       TPU$V_ is a bit number.

    2. Most bits in the mask have a corresponding GET_INFO (COMMAND_
       LINE) request string.

    To create the bits, start with the value 0, then use the OR
    operator on the mask (TPU$M . . . ) of each item you want to set.
    Another way to create the bits is to treat the 32 bits as a bit
    vector and set the bit (TPU$V . . . ) corresponding to the item
    you want.

 user_arg

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    User argument. The user_arg argument is passed to the user-
    written initialization routine INITIALIZE.

    The user_arg parameter is provided to allow an application to
    pass information through TPU$INITIALIZE to the user-written
    initialization routine. TPU does not interpret this data in
    any way.

12.3  –  Description

    This is the first routine that must be called after establishing
    a condition handler.

    This routine initializes the editor according to the information
    received from the callback routine. The initialization routine
    defaults all file specifications to the null string and all
    options to off. However, it does not default the file I/O or
    call-user routine addresses.

12.4  –  Condition Values Returned

    TPU$_SUCCESS       Initialization was completed successfully.
    TPU$_FAILURE       General code for all other errors during
                       initialization.
    TPU$_INSVIRMEM     Insufficient virtual memory exists for the
                       editor to initialize.
    TPU$_              No routine has been established to perform
    NOFILEROUTINE      file operations.
    TPU$_NONANSICRT    The input device (SYS$INPUT) is not a
                       supported terminal.
    TPU$_RESTOREFAIL   An error occurred during the restore
                       operation.
    TPU$_SYSERROR      A system service did not work correctly.

13  –  TPU$MESSAGE

    The TPU$MESSAGE routine writes error messages and strings using
    the built-in procedure, MESSAGE.

    Call this routine to have messages written and handled in a
    manner consistent with TPU. This routine should be used only
    after TPU$EXECUTE_INIFILE.

    Format

      TPU$MESSAGE  string

13.1  –  Returns

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

    Longword condition value.

                                   NOTE

       The return status should be ignored because it is intended
       for use by the $PUTMSG system service.

13.2  –  Argument

 string

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor
    Formatted message. The string argument is the address of
    a descriptor of text to be written. It must be completely
    formatted. This routine does not append the message prefixes.
    However, the text is appended to the message buffer if one
    exists. In addition, if the buffer is mapped to a window, the
    window is updated.

14  –  TPU$PARSEINFO

    The TPU$PARSEINFO routine parses a command and builds the item
    list for TPU$INITIALIZE.

    Format

      TPU$PARSEINFO  fileio ,call_user

14.1  –  Returns

    OpenVMS usage:item_list
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    The routine returns the address of an item list.

14.2  –  Arguments

 fileio

    OpenVMS usage:vector_longword_unsigned
    type:         bound procedure value
    access:       read only
    mechanism:    by descriptor
    File I/O routine. The fileio argument is the address for a
    descriptor of a file I/O routine.

 call_user

    OpenVMS usage:vector_longword_unsigned
    type:         bound procedure value
    access:       read only
    mechanism:    by descriptor
    Call-user routine. The call_user argument is the address for a
    descriptor of a call-user routine.

14.3  –  Description

    The TPU$PARSEINFO routine parses a command and builds the item
    list for TPU$INITIALIZE.

    This routine uses the command language (CLI) routines to
    parse the current command. It makes queries about the command
    parameters and qualifiers that TPU expects. The results of
    these queries are used to set up the proper information in an
    item list. The addresses of the user routines are used for those
    items in the list. The address of this list is the return value
    of the routine.

    If your application parses information that is not related to the
    operation of TPU, make sure the application obtains and uses
    all non-TPU parse information before the application calls the
    TPU$PARSEINFO interface. This is because TPU$PARSEINFO destroys
    all parse information obtained and stored before TPU$PARSEINFO
    was called.

15  –  TPU$SIGNAL

    The TPU$SIGNAL routine allows applications and user-written TPU
    routines such as FILEIO to easily signal error messages in order
    for TPU error handlers to perform correctly.

    Format

      TPU$SIGNAL  condition-code

15.1  –  Returns

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

    Longword condition value. In most cases, the routine returns
    either the same signal passed to it in the condition value
    argument, or the return value of LIB$SIGNAL. If the routine
    fails, it signals TPU$_FAILURE and returns control to the caller.

15.2  –  Argument

 condition-code

    OpenVMS usage: cond_value
    type:          longword (unsigned)
    access:        read only
    mechanism:     by value
    The condition-code is an unsigned longword that contains the
    condition code to be signaled. In most cases, this argument is a
    TPU message code.

15.3  –  Description

    TPU$SIGNAL performs the same function as the Run-Time Library
    routine LIB$SIGNAL, but it also processes TPU facility messages
    to allow TPU language ON_ERROR handlers to be called.

    For example, assume that a user-written file input/output routine
    is designed to signal the error TPU$_OPENIN when it fails to
    open a file. Calling the TPU$SIGNAL routine and passing the value
    TPU$_OPENIN allows a case-style TPU ON_ERROR handler to receive
    the error, thus preserving the documented return values for TPU
    built-in procedures such as READ_FILE.

                                   NOTE

       You must call TPU$INITIALIZE before you call the TPU$SIGNAL
       routine.

    If TPU$_QUITTING, TPU$_EXITING, or TPU$_RECOVERFAIL are passed to
    the routine, it calls the Run-Time Library routine LIB$SIGNAL.

    If facility messages other than TPU messages are passed to the
    TPU$SIGNAL routine, it calls the LIB$SIGNAL routine and passes
    the appropriate condition value.

16  –  TPU$SPECIFY_ASYNC_ACTION

    The TPU$SPECIFY_ASYNC_ACTION routine allows applications using
    the TPU full callable interface to register asynchronous
    actions with TPU.

    Format

      TPU$SPECIFY_ASYNC_ACTION  facility_index [,tpu_statement]

16.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. Condition values that this routine can
    return are listed under Condition Values Returned.

16.2  –  Argument

 facility_index

    OpenVMS usage:longword_unsigned
    type:         longword (signed)
    access:       read only
    mechanism:    by reference
    Represents an index of the asynchronous action. This index is
    used with the TPU$TRIGGER_ASYNC_ACTION routine to let TPU know
    what action to perform. It may also be used to delete an action
    routine (by omitting the tpu_statement). You may register several
    asynchronous actions depending on your application's needs. This
    facility index number may be any positive integer.

 tpu_statement

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor
    The TPU statement you want executed when you call the
    TPU$TRIGGER_ASYNC_ACTION routine. The statement is compiled and
    then stored internally. If you omit the parameter, TPU removes
    the action from its list of asynchronous events.

16.3  –  Description

    The TPU$SPECIFY_ASYNC_ACTION routine, along with TPU$TRIGGER_
    ASYNC_ACTION, allow applications to interrupt TPU after
    calling TPU$CONTROL. The specified TPU statement is compiled
    and saved.

    This routine must be called after TPU$INITIALIZE. It will not
    complete successfully if keystroke journaling is enabled.

16.4  –  Condition Values Returned

    TPU$_SUCCESS       Normal successful completion.
    TPU$_COMPILEFAIL   The code specified in tpu_statement did not
                       compile successfully.
    TPU$_INVPARM       An invalid parameter was passed.
    TPU$_JNLACTIVE     Keystroke journaling is active. This routine
                       requires that either journaling be turned off
                       or that buffer change journaling be used.

17  –  TPU$TPU

    The TPU$TPU routine invokes TPU and is equivalent to the DCL
    command EDIT/TPU.

    Format

      TPU$TPU  command

17.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. Condition values that this routine can
    return are listed under Condition Values Returned.

17.2  –  Argument

 command

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor
    Command string. Note that the verb is TPU instead of EDIT/TPU.
    The command argument is the address for a descriptor of a command
    line.

17.3  –  Description

    This routine takes the command string specified and passes it to
    the editor. TPU uses the information from this command string
    for initialization purposes, just as though you had entered the
    command at the DCL level.

    Using the simplified callable interface does not set TPU$CLOSE_
    SECTION. This feature lets you make multiple calls to TPU$TPU
    without requiring you to open and close the section file on each
    call.

    If your application parses information that is not related to the
    operation of TPU, make sure the application obtains and uses
    all non-TPU parse information before the application calls
    TPU$TPU. This is because TPU$TPU destroys all parse information
    obtained and stored before TPU$TPU was called.

17.4  –  Condition Values Returned

    This routine returns any condition value returned by
    TPU$INITIALIZE, TPU$EXECUTE_INIFILE, TPU$CONTROL, and
    TPU$CLEANUP.

18  –  TPU$TRIGGER_ASYNC_ACTION

    The TPU$TRIGGER_ASYNC_ACTION routine allows applications using
    the TPU full callable interface to interrupt the TPU
    TPU$CONTROL loop at an asynchronous level.

    Format

      TPU$TRIGGER_ASYNC_ACTION  facility_index

18.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. Condition values that this routine can
    return are listed under Condition Values Returned.

18.2  –  Arguments

 facility_index

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    The facility_index argument represents the asynchronous action to
    be taken. This is the same index passed to the TPU$SPECIFY_ASYNC_
    ACTION routine registering what TPU statements to execute.

18.3  –  Description

    The TPU$TRIGGER_ASYNC_ACTION routine, along with TPU$SPECIFY_
    ASYNC_ACTION routine allow applications to interrupt TPU after
    calling TPU$CONTROL. The command that was specified for this
    facility_index is put on the TPU queue of work items and is
    handled as soon as no other work items are present. This allows
    TPU to complete and stabilize its environment before executing
    the command. This routine must be called after control has been
    passed to TPU via the TPU$CONTROL routine.

18.4  –  Condition Values Returned

    TPU$_SUCCESS       Normal successful completion.
    TPU$_UNKFACILITY   The facility_index passed to this routine
                       does not match any facility index passed to
                       TPU$SPECIFY_ASYNC_ACTION.

19  –  FILEIO

    The user-written FILEIO routine is used to handle TPU file
    operations. The name of this routine can be either your own
    file I/O routine or the name of the TPU file I/O routine
    (TPU$FILEIO).

    Format

      FILEIO  code ,stream ,data

19.1  –  Returns

    OpenVMS usage:cond_value
    type:         longword (usigned)
    access:       write only
    mechanism:    by reference

    Longword condition value. Most utility routines return a
    condition value in R0. Condition values that this routine can
    return are listed under Condition Values Returned.

19.2  –  Arguments

 code

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Item code specifying a TPU function. The code argument is the
    address of a longword containing an item code from TPU, which
    specifies a function to perform.

 stream

    OpenVMS usage:unspecified
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    File description. The stream argument is the address of a data
    structure containing four longwords. This data structure is used
    to describe the file to be manipulated.

 data

    OpenVMS usage:item_list_3
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Stream data. The data argument is either the address of an item
    list or the address of a descriptor.

                                   NOTE

       The value of this parameter depends on which item code you
       specify.

19.3  –  Description

    The bound procedure value of this routine is specified in the
    item list built by the callback routine. This routine is called
    to perform file operations. Instead of using your own file I/O
    routine, you can call TPU$FILEIO and pass it the parameters for
    any file operation you do not want to handle. Note, however, that
    TPU$FILEIO must handle all I/O requests for any file it opens.
    Also, if it does not open the file, it cannot handle any I/O
    requests for the file. In other words, you cannot mix the file
    operations between your own file I/O routine and the one supplied
    by TPU.

19.4  –  Condition Values Returned

    The condition values returned are determined by the user and
    should indicate success or failure of the operation.

20  –  FILE_PARSE

    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

20.1  –  Returns

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

    Longword condition value. The return value is ignored by TPU.
    User-written FILE_PARSE routines should include calls to the
    TPU$SIGNAL routine to ensure proper error handling.

20.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. TPU 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(1)           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.

    (1) TPU$M... indicates a mask. There is a corresponding value for
    each mask in the form TPU$V...

 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.

20.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 TPU built-in procedure FILE_PARSE is called from
    TPU code, TPU 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.

21  –  FILE_SEARCH

    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

21.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.

21.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. TPU 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(1)           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 TPU 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.

    (1) TPU$M... indicates a mask. There is a corresponding value for
    each mask in the form TPU$V...

 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.

21.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 TPU built-in procedure FILE_SEARCH is called from TPU
    code, TPU 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.

22  –  HANDLER

    The user-written HANDLER routine performs condition handling.

    Format

      HANDLER  signal_vector ,mechanism_vector

22.1  –  Returns

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

    Longword condition value.

22.2  –  Arguments

 signal_vector

    OpenVMS usage:arg_list
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Signal vector. See the VSI OpenVMS System Services Reference
    Manual for information about the signal vector passed to a
    condition handler.

 mechanism_vector

    OpenVMS usage:arg_list
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Mechanism vector. See the VSI OpenVMS System Services Reference
    Manual for information about the mechanism vector passed to a
    condition handler.

22.3  –  Description

    If you need more information about writing condition handlers and
    programming concepts, refer to VSI OpenVMS Programming Concepts
    Manual.

    Instead of writing your own condition handler, you can use the
    default condition handler, TPU$HANDLER. If you want to write your
    own routine, you must call TPU$HANDLER with the same parameters
    that your routine received to handle TPU internal signals.

23  –  INITIALIZE

    The user-written initialization callback routine is passed to
    TPU$INITIALIZE as a bound procedure value and called to supply
    information needed to initialize TPU.

    Format

      INITIALIZE  [user_arg]

23.1  –  Returns

    OpenVMS usage:item_list
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference

    This routine returns the address of an item list.

23.2  –  Arguments

 user_arg

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    User argument.

23.3  –  Description

    The user-written initialization callback routine is passed to
    TPU$INITIALIZE as a bound procedure value and called to supply
    information needed to initialize TPU.

    If the user_arg parameter was specified in the call to
    TPU$INITIALIZE, the initialization callback routine is called
    with only that parameter. If user_arg was not specified in the
    call to TPU$INITIALIZE, the initialization callback routine is
    called with no parameters.

    The user_arg parameter is provided to allow an application to
    pass information through TPU$INITIALIZE to the user-written
    initialization routine. TPU does not interpret this data in
    any way.

    The user-written callback routine is expected to return the
    address of an item list containing initialization parameters.
    Because the item list is used outside the scope of the
    initialization callback routine, it should be allocated in static
    memory.

    The item list entries are discussed in the TPU$INITIALIZE help
    topic. Most of the initialization parameters have a default
    value; strings default to the null string, and flags default to
    false. The only required initialization parameter is the address
    of a routine for file I/O. If an entry for the file I/O routine
    address is not present in the item list, TPU$INITIALIZE returns
    with a failure status.

24  –  USER

    The user-written USER routine allows your program to take control
    during a TPU editing session (for example, to leave the editor
    temporarily and perform a calculation).

    Format

      USER  integer ,stringin ,stringout

24.1  –  Returns

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

    Longword condition value.

24.2  –  Arguments

 integer

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    First parameter to the built-in procedure CALL_USER. This is an
    input-only parameter and must not be modified.

 stringin

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor
    Second parameter to the built-in procedure CALL_USER. This is an
    input-only parameter and must not be modified.

 stringout

    OpenVMS usage:char_string
    type:         character string
    access:       modify
    mechanism:    by descriptor
    Return value for the built-in procedure CALL_USER. Your program
    should fill in this descriptor with a dynamic string allocated by
    the string routines (such as LIB$SGET1_DD) provided by the Run-
    Time Library. The TPU editor frees this string when necessary.

24.3  –  Description

    This user-written routine is invoked by the TPU built-in
    procedure CALL_USER. The built-in procedure CALL_USER passes
    three parameters to this routine. These parameters are then
    passed to the appropriate part of your application to be used
    as specified. (For example, they can be used as operands in a
    calculation within a Fortran program.) Using the string routines
    provided by the Run-Time Library, your application fills in the
    stringout parameter in the call-user routine, which returns the
    stringout value to the built-in procedure CALL_USER.

    The description of the built-in procedure CALL_USER in the DEC
    Text Processing Utility Reference Manual shows an example of a
    BASIC program that is a call-user routine.
Close Help