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.