1  DECTPU
   These routines are part of the callable DEC Text Processing
   Utility (DECTPU).
 

2  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 DECTPU.

   Format

     TPU$CLEANUP  flags
 

3  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  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 DECTPU exit handler.
   TPU$M_DELETE_        Deletes all text buffers. If this is not the
   BUFFERS              last time you are calling DECTPU, 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 DECTPU, 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 DECTPU. 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 DECTPU. 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 DECTPU for the last time. Note that
                        if you set this bit and then recall DECTPU,
                        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.
 

3  Description
   The cleanup routine is the final routine called in each
   interaction with DECTPU. It tells DECTPU 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 DECTPU, 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, DECTPU 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.
 

3  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
 

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

   This routine returns the address of an item list.
 

3  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 DECTPU 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.
 

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 DECTPU, make sure the application obtains and uses
   all non-DECTPU 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.
 

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

   Format

     TPU$CLOSE_TERMINAL
 

3  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  Arguments
   None.
 

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

   When the call-user routine returns control to it, DECTPU
   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 DECTPU when TPU$CLOSE_TERMINAL is used, the
   call is ignored.
 

3  Condition_Value_Returned

   TPU$_SUCCESS       Normal successful completion.
 

2  TPU$CONTROL
   The TPU$CONTROL routine is the main processing routine of the
   DECTPU 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 DECTPU.

   Format

     TPU$CONTROL  [integer]
 

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

3  Argument
 

integer

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

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

3  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 DECTPU 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.
 

2  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 DECTPU simplified callable
   interface.

   Format

     TPU$EDIT  input ,output
 

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

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

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 DECTPU, make sure the application obtains and uses
   all non-DECTPU 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.
 

3  Condition_Values_Returned
   This routine returns the same values as TPU$TPU.
 

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

   Format

     TPU$EXECUTE_COMMAND  string
 

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

3  Argument
 

string

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

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

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

2  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
 

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

3  Arguments
   None.
 

3  Description
   Calling the TPU$EXECUTE_INIFILE routine causes DECTPU 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.
 

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

2  TPU$FILEIO
   The TPU$FILEIO routine handles all DECTPU 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
 

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

3  Arguments
 

code

   OpenVMS usage:longword_unsigned
   type:         longword (unsigned)
   access:       read only
   mechanism:    by reference
   Item code specifying a DECTPU function. The code argument is
   the address of a longword containing an item code from DECTPU
   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. DECTPU 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 DECTPU
   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 DECTPU 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 DECTPU 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.
 

3  Description
   By default, TPU$FILEIO creates variable-length files with
   carriage-return record attributes (FAB$B_RFM = VAR, FAB$B_RAT
   = CR). If you pass to it the TPU$K_RECORD_ATTR or TPU$K_RECORD_
   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

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

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

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

   Format

     TPU$FILE_PARSE  result-string ,flags ,filespec ,default-spec

                     ,related-spec
 

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

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

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

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

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

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

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

   Format

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

                      ,related-spec
 

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

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

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

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

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

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

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

2  TPU$HANDLER
   The TPU$HANDLER routine is the DECTPU condition handler.

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

   Format

     TPU$HANDLER  signal_vector ,mechanism_vector
 

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

3  Arguments
 

signal_vector

   OpenVMS usage:arg_list
   type:         longword (unsigned)
   access:       modify
   mechanism:    by reference
   Signal vector. See the HP 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 HP OpenVMS System Services Reference
   Manual for information about the mechanism vector passed to a
   condition handler.
 

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 DECTPU Shareable Image. Those values can be
   modified only by the DECTPU built-in procedure SET.

   If the condition value received by the handler has a FATAL status
   or does not have the DECTPU 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. DECTPU 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 DECTPU 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 DECTPU 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 HP OpenVMS Calling Standard for details on writing a
   condition handler.
 

2  TPU$INITIALIZE
   The TPU$INITIALIZE routine initializes DECTPU 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]
 

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

3  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 DECTPU 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 DECTPU 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 DECTPU 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 DECTPU 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 DECTPU
                     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; DECTPU 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. DECTPU 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 DECTPU 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). DECTPU calls the routine
                     when a Ctrl/C AST occurs. If the routine
                     returns a FALSE value, DECTPU assumes that
                     the Ctrl/C has been handled. If the routine
                     returns a TRUE value, DECTPU aborts any
                     currently executing DECTPU 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 DECTPU 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 DECTPU 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 DECTPU 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 DECTPU is not
                                affected by this bit. Its
                                interpretation is left to the
                                application layered on DECTPU.
   TPU$M_DEBUG    Not           If DECTPU 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 DECTPU 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 DECTPU 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, DECTPU uses SYS$OUTPUT
                                for display and only the READ_LINE
                                built-in procedure may be used for
                                input.
   TPU$M_INIT     INITIALIZATIONIf DECTPU 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 DECTPU senses the presence of the
   JOURNAL                      TPU$_JOURNALFILE item, it outputs
                                the keystrokes entered during the
                                editing session to the specified
                                file.

                                Note: HP recommends the use of
                                buffer change journaling in new
                                applications.
   TPU$M_MODIFY   MODIFY        The behavior of DECTPU is not
                                affected by this bit. Its
                                interpretation is left to the
                                application layered on DECTPU.
   TPU$M_         Not           DECTPU 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 DECTPU is not
   NOMODIFY                     affected by this bit. Its
                                interpretation is left to the
                                application layered on DECTPU.
   TPU$M_OUTPUT   OUTPUT        The behavior of DECTPU is not
                                affected by this bit. Its
                                interpretation is left to the
                                application layered on DECTPU.
   TPU$M_READ     READ_ONLY     The behavior of DECTPU is not
                                affected by this bit. Its
                                interpretation is left to the
                                application layered on DECTPU.
   TPU$M_         RECOVER       The behavior of DECTPU is not
   RECOVER                      affected by this bit. Its
                                interpretation is left to the
                                application layered on DECTPU.
   TPU$M_         SECTION       If DECTPU 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 DECTPU 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 DECTPU 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 DECTPU is not
                                affected by this bit. Its
                                interpretation is left to the
                                application layered on DECTPU.

   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. DECTPU does not interpret this data in
   any way.
 

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.
 

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

2  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 DECTPU. This routine should be used only
   after TPU$EXECUTE_INIFILE.

   Format

     TPU$MESSAGE  string
 

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

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

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

   Format

     TPU$PARSEINFO  fileio ,call_user
 

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

   The routine returns the address of an item list.
 

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

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 DECTPU 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 DECTPU, make sure the application obtains and uses
   all non-DECTPU 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.
 

2  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
 

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

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

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.
 

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

   Format

     TPU$SPECIFY_ASYNC_ACTION  facility_index [,tpu_statement]
 

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

3  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 DECTPU 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 DECTPU 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, DECTPU removes
   the action from its list of asynchronous events.
 

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

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

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

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

   Format

     TPU$TPU  command
 

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

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

3  Description
   This routine takes the command string specified and passes it to
   the editor. DECTPU 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 DECTPU, make sure the application obtains and uses
   all non-DECTPU 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.
 

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

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

   Format

     TPU$TRIGGER_ASYNC_ACTION  facility_index
 

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

3  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 DECTPU statements to execute.
 

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

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

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

   Format

     FILEIO  code ,stream ,data
 

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

3  Arguments
 

code

   OpenVMS usage:longword_unsigned
   type:         longword (unsigned)
   access:       read only
   mechanism:    by reference
   Item code specifying a DECTPU function. The code argument is the
   address of a longword containing an item code from DECTPU, 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.
 

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

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

2  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
 

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

3  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(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.
 

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.
 

2  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
 

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

3  Arguments
 

result-string

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

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

flags

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

   Flag(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 DECTPU if on a previous
                     call to the FILE_SEARCH user routine the
                     result-string has a zero length or the routine
                     returns a odd (noneven) status.
   TPU$M_HEAD        Requests for the NODE, DEVICE, and DIRECTORY
                     components of the file specification.
   TPU$M_TAIL        Requests for the NAME, TYPE, and VERSION
                     component of the file specification.

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

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

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

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

2  HANDLER
   The user-written HANDLER routine performs condition handling.

   Format

     HANDLER  signal_vector ,mechanism_vector
 

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

   Longword condition value.
 

3  Arguments
 

signal_vector

   OpenVMS usage:arg_list
   type:         longword (unsigned)
   access:       modify
   mechanism:    by reference
   Signal vector. See the HP 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 HP OpenVMS System Services Reference
   Manual for information about the mechanism vector passed to a
   condition handler.
 

3  Description
   If you need more information about writing condition handlers and
   programming concepts, refer to HP 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 DECTPU internal signals.
 

2  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 DECTPU.

   Format

     INITIALIZE  [user_arg]
 

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

   This routine returns the address of an item list.
 

3  Arguments
 

user_arg

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

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

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

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

   Format

     USER  integer ,stringin ,stringout
 

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

   Longword condition value.
 

3  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 DECTPU editor frees this string when necessary.
 

3  Description
   This user-written routine is invoked by the DECTPU 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.