These routines are part of the callable VSI Text Processing
Utility (TPU).
1 – TPU$CLEANUP
The TPU$CLEANUP routine cleans up internal data structures, frees
memory, and restores terminals to their initial state.
This is the final routine called in each interaction with TPU.
Format
TPU$CLEANUP flags
1.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. The condition value that this routine
can return is listed under Condition Value Returned.
1.2 – Argument
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Flags (or mask) defining the cleanup options. The flags argument
is the address of a longword bit mask defining the cleanup
options or the address of a 32-bit mask defining the cleanup
options. This mask is the logical OR of the flag bits you want to
set. Following are the various cleanup options:
Flag(1) Function
TPU$M_DELETE_ Closes and deletes the journal file if it is
JOURNAL open.
TPU$M_DELETE_EXITH Deletes the TPU exit handler.
TPU$M_DELETE_ Deletes all text buffers. If this is not the
BUFFERS last time you are calling TPU, then all
variables referring to these data structures
are reset, as if by the built-in procedure
DELETE. If a buffer is deleted, then all
ranges and markers within that buffer, and
any subprocesses using that buffer, are also
deleted.
TPU$M_DELETE_ Deletes all windows. If this is not the
WINDOWS last time you are calling TPU, then all
variables referring to these data structures
are reset, as if by the built-in procedure
DELETE.
TPU$M_DELETE_CACHE Deletes the virtual file manager's data
structures and caches. If this deletion
is requested, then all buffers are also
deleted. If the cache is deleted, the
initialization routine has to reinitialize
the virtual file manager the next time it is
called.
TPU$M_PRUNE_CACHE Frees up any virtual file manager caches
that have no pages allocated to buffers.
This frees up any caches that may have been
created during the session but are no longer
needed.
TPU$M_EXECUTE_FILE Reexecutes the command file if TPU$EXECUTE_
INIFILE is called again. You must set this
bit if you plan to specify a new file name
for the command file. This option is used
in conjunction with the option bit passed
to TPU$INITIALIZE indicating the presence of
the /COMMAND qualifier.
TPU$M_EXECUTE_PROC Looks up TPU$INIT_PROCEDURE and executes it
the next time TPU$EXECUTE_INIFILE is called.
TPU$M_DELETE_ Deletes the entire context of TPU. If
CONTEXT this option is specified, then all other
options are implied, except for executing
the initialization file and initialization
procedure.
TPU$M_RESET_ Resets the terminal to the state it was in
TERMINAL upon entry to TPU. The terminal mailbox
and all windows are deleted. If the terminal
is reset, then it is reinitialized the next
time TPU$INITIALIZE is called.
TPU$M_KILL_ Deletes all subprocesses created during the
PROCESSES session.
TPU$M_CLOSE_ Closes the section file and releases the
SECTION(2) associated memory. All buffers, windows, and
processes are deleted. The cache is purged
and the flags are set for reexecution of
the initialization file and initialization
procedure. If the section is closed and if
the option bit indicates the presence of
the SECTION qualifier, then the next call
to TPU$INITIALIZE attempts a new restore
operation.
TPU$M_DELETE_ Deletes all miscellaneous preallocated data
OTHERS structures. Memory for these data structures
is reallocated the next time TPU$INITIALIZE
is called.
TPU$M_LAST_TIME This bit should be set only when you are
calling TPU for the last time. Note that
if you set this bit and then recall TPU,
the results are unpredictable.
Footnotes:
1. The flag prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask
corresponding to the specific field in which the bit is set.
TPU$V_ is a bit number.
2. Using the simplified callable interface does not set TPU$_
CLOSE_SECTION. This feature allows you to make multiple calls
to TPU$TPU without requiring you to open and close the section
file on each call.
1.3 – Description
The cleanup routine is the final routine called in each
interaction with TPU. It tells TPU to clean up its internal
data structures and prepare for additional invocations. You can
control what is reset by this routine by setting or clearing the
flags described previously.
When you finish with TPU, call this routine to free the memory
and restore the characteristics of the terminal to their original
settings.
If you intend to exit after calling TPU$CLEANUP, do not
delete the data structures; the operating system does this
automatically. Allowing the operating system to delete the
structures improves the performance of your program.
Notes
1. When you use the simplified interface, TPU automatically
sets the following flags:
o TPU$V_RESET_TERMINAL
o TPU$V_DELETE_BUFFERS
o TPU$V_DELETE_JOURNAL
o TPU$V_DELETE_WINDOWS
o TPU$V_DELETE_EXITH
o TPU$V_EXECUTE_PROC
o TPU$V_EXECUTE_FILE
o TPU$V_PRUNE_CACHE
o TPU$V_KILL_PROCESSES
2. If this routine does not return a success status, no other
calls to the editor should be made.
1.4 – Condition Value Returned
TPU$_SUCCESS Normal successful completion.
2 – TPU$CLIPARSE
The TPU$CLIPARSE routine parses a command line and builds the
item list for TPU$INITIALIZE.
Format
TPU$CLIPARSE string ,fileio ,call_user
2.1 – Returns
OpenVMS usage:item_list
type: longword (unsigned)
access: read only
mechanism: by reference
This routine returns the address of an item list.
2.2 – Arguments
string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Command line. The string argument is the address of a descriptor
of a TPU command.
fileio
OpenVMS usage:vector_longword_unsigned
type: bound procedure value
access: read only
mechanism: by descriptor
File I/O routine. The fileio argument is the address of a
descriptor of a file I/O routine.
call_user
OpenVMS usage:vector_longword_unsigned
type: bound procedure value
access: read only
mechanism: by descriptor
Call-user routine. The call_user argument is the address of a
descriptor of a call-user routine.
2.3 – Description
This routine calls CLI$DCL_PARSE to establish a command table and
a command to parse. It then calls TPU$PARSEINFO to build an item
list for TPU$INITIALIZE.
If your application parses information that is not related to the
operation of TPU, make sure the application obtains and uses
all non-TPU parse information before the application calls
TPU$CLIPARSE. You must do this because TPU$CLIPARSE destroys all
parse information obtained and stored before TPU$CLIPARSE was
called.
3 – TPU$CLOSE_TERMINAL
The TPU$CLOSE_TERMINAL routine closes the TPU channel to the
terminal.
Format
TPU$CLOSE_TERMINAL
3.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. The condition value that this routine
can return is listed under Condition Value Returned.
3.2 – Arguments
None.
3.3 – Description
This routine is used with the built-in procedure CALL_USER and
its associated call-user routine to control the TPU access
to the terminal. When a call-user routine invokes TPU$CLOSE_
TERMINAL, TPU closes its channel to the terminal and the
channel of the TPU associated mailbox.
When the call-user routine returns control to it, TPU
automatically reopens a channel to the terminal and redisplays
the visible windows.
A call-user routine can use TPU$CLOSE_TERMINAL at any point in
the program and as many times as necessary. If the terminal is
already closed to TPU when TPU$CLOSE_TERMINAL is used, the
call is ignored.
3.4 – Condition Value Returned
TPU$_SUCCESS Normal successful completion.
4 – TPU$CONTROL
The TPU$CONTROL routine is the main processing routine of the
TPU editor. It is responsible for reading the text and
commands and executing them. When you call this routine (after
calling TPU$INITIALIZE), control is turned over to TPU.
Format
TPU$CONTROL [integer]
4.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. Condition values that this routine can
return are listed under Condition Values Returned.
4.2 – Argument
integer
OpenVMS usage:integer
type: longword (unsigned)
access: read only
mechanism: by reference
Prevents TPU from displaying the message "Editing session is
not being journaled" when the calling program gives control to
TPU. Specify a true (odd) integer to preserve compatibility in
future releases. If you omit the parameter, TPU displays the
message if journaling is not enabled.
4.3 – Description
This routine controls the editing session. It is responsible for
reading the text and commands and for executing them. Windows on
the screen are updated to reflect the edits made. Your program
can regain control by interrupting TPU using the TPU$SPECIFY_
ASYNC_ACTION routine, together with the TPU$TRIGGER_ASYNC_ACTION
routine.
NOTE
Control is also returned to your program if an error occurs
or when you enter either the built-in procedure QUIT or the
built-in procedure EXIT.
4.4 – Condition Values Returned
TPU$_EXITING A result of EXIT (when the default condition
handler is established).
TPU$_NONANSICRT A result of operation termination - results
when you call TPU with TPU$DISPLAYFILE
set to nodisplay and you attempt to execute
screen-oriented commands.
TPU$_QUITTING A result of QUIT (when the default condition
handler is established).
TPU$_RECOVERFAIL A recovery operation was terminated
abnormally.
5 – TPU$EDIT
The TPU$EDIT routine builds a command string from its parameters
and passes it to the TPU$TPU routine.
TPU$EDIT is another entry point to the TPU simplified callable
interface.
Format
TPU$EDIT input ,output
5.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. Condition values that this routine can
return are listed under Condition Values Returned.
5.2 – Arguments
input
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Input file name. The input argument is the address for a
descriptor of a file specification.
output
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Output file name. The output argument is the address for a
descriptor of an output file specification. It is used with the
/OUTPUT command qualifier.
5.3 – Description
This routine builds a command string and passes it to TPU$TPU. If
the length of the output descriptor is nonzero, then the /OUTPUT
qualifier is added to the command string. The /OUTPUT qualifier
causes a file to be written to the specified file even if no
modifications are made to the input file. If the QUIT built-
in procedure is called, it prompts the user as if changes had
been made to the buffer. This allows applications to check for
the existence of the output file to see if the editing session
was terminated, which is consistent with other OpenVMS callable
editors.
If your application parses information that is not related to the
operation of TPU, make sure the application obtains and uses
all non-TPU parse information before the application calls
TPU$EDIT. Your application must do this because TPU$EDIT destroys
all parse information obtained and stored before TPU$EDIT is
called.
5.4 – Condition Values Returned
This routine returns the same values as TPU$TPU.
6 – TPU$EXECUTE_COMMAND
The TPU$EXECUTE_COMMAND routine allows your program to execute
TPU statements.
Format
TPU$EXECUTE_COMMAND string
6.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. Condition values that this routine can
return are listed under Condition Values Returned.
6.2 – Argument
string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by value
TPU statement. The string argument is the address of a
descriptor of a character string denoting one or more TPU
statements.
6.3 – Description
This routine performs the same function as the built-in procedure
EXECUTE described in the VSI Text Processing Utility Reference
Manual.
6.4 – Condition Values Returned
TPU$_SUCCESS Normal successful completion.
TPU$_EXECUTEFAIL Execution aborted. This could be because of
execution errors or compilation errors.
TPU$_EXITING EXIT built-in procedure was invoked.
TPU$_QUITTING QUIT built-in procedure was invoked.
7 – TPU$EXECUTE_INIFILE
The TPU$EXECUTE_INIFILE routine allows you to execute a user-
written initialization file.
This routine must be executed after the editor is initialized and
before any other commands are processed.
Format
TPU$EXECUTE_INIFILE
7.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. Condition values that this routine can
return are listed under Condition Values Returned.
7.2 – Arguments
None.
7.3 – Description
Calling the TPU$EXECUTE_INIFILE routine causes TPU to perform
the following steps:
1. The command file is read into a buffer. The default is
TPU$COMMAND.TPU. If you specified a file on the command line
that cannot be found, an error message is displayed and the
routine is aborted.
2. If you specified the /DEBUG qualifier on the command
line, the DEBUG file is read into a buffer. The default is
SYS$SHARE:TPU$DEBUG.TPU.
3. The DEBUG file is compiled and executed (if available).
4. TPU$INIT_PROCEDURE is executed (if available).
5. The Command buffer is compiled and executed (if available).
6. TPU$INIT_POSTPROCEDURE is executed (if available).
NOTE
If you call this routine after calling TPU$CLEANUP, you must
set the flags TPU$_EXECUTEPROCEDURE and TPU$_EXECUTEFILE.
Otherwise, the initialization file does not execute.
7.4 – Condition Values Returned
TPU$_SUCCESS Normal successful completion.
TPU$_COMPILEFAIL The compilation of the initialization file was
unsuccessful.
TPU$_EXECUTEFAIL The execution of the statements in the
initialization file was unsuccessful.
TPU$_EXITING A result of EXIT. If the default condition
handler is being used, the session is
terminated.
TPU$_FAILURE General code for all other errors.
TPU$_QUITTING A result of QUIT. If the default condition
handler is being used, the session is
terminated.
8 – TPU$FILEIO
The TPU$FILEIO routine handles all TPU file operations.
Your own file I/O routine can call this routine to perform some
operations for it. However, the routine that opens the file must
perform all operations for that file. For example, if TPU$FILEIO
opens the file, it must also close it.
Format
TPU$FILEIO code ,stream ,data
8.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. Condition values that this routine can
return are listed under Condition Values Returned.
8.2 – Arguments
code
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Item code specifying a TPU function. The code argument is
the address of a longword containing an item code from TPU
specifying a function to perform. Following are the item codes
that you can specify in the file I/O routine:
o TPU$K_OPEN-This item code specifies that the data parameter
is the address of an item list. This item list contains the
information necessary to open the file. The stream parameter
should be filled in with a unique identifying value to be used
for all future references to this file. The resultant file
name should also be copied with a dynamic string descriptor.
o TPU$K_CLOSE-The file specified by the stream argument is to
be closed. All memory being used by its structures can be
released.
o TPU$K_CLOSE_DELETE-The file specified by the stream argument
is to be closed and deleted. All memory being used by its
structures can be released.
o TPU$K_GET-The data parameter is the address of a dynamic
string descriptor to be filled with the next record from the
file specified by the stream argument. The routine should use
the routines provided by the Run-Time Library to copy text
into this descriptor. TPU frees the memory allocated for
the data read when the file I/O routine indicates that the end
of the file has been reached.
o TPU$K_PUT-The data parameter is the address of a descriptor
for the data to be written to the file specified by the stream
argument.
stream
OpenVMS usage:unspecified
type: longword (unsigned)
access: modify
mechanism: by reference
File description. The stream argument is the address of a data
structure consisting of four longwords. This data structure
describes the file to be manipulated.
This data structure is used to refer to all files. It is written
to when an open file request is made. All other requests use
information in this structure to determine which file is being
referenced.
The following figure shows the stream data structure:
----------------------------------------------
| File identifier |
----------------------------------------------
| RFM | | Allocation |
----------------------------------------------
| Class | Type | Length |
----------------------------------------------
The first longword holds a unique identifier for each file. The
user-written file I/O routine is restricted to values between 0
and 511. Thus, you can have up to 512 files open simultaneously.
The second longword is divided into three fields. The low word
is used to store the allocation quantity, that is, the number
of blocks allocated to this file from the FAB (FAB$L_ALQ).
This value is used later to calculate the output file size for
preallocation of disk space. The low-order byte of the second
word is used to store the record attribute byte (FAB$B_RAT)
when an existing file is opened. The high-order byte is used
to store the record format byte (FAB$B_RFM) when an existing file
is opened. The values in the low word and the low-order and high-
order bytes of the second word are used for creating the output
file in the same format as the input file. These three fields are
to be filled in by the routine opening the file.
The last two longwords are used as a descriptor for the resultant
or the expanded file name. This name is used later when TPU
processes EXIT commands. This descriptor is to be filled in with
the file name after an open operation. It should be allocated
with either the routine LIB$SCOPY_R_DX or the routine LIB$SCOPY_
DX from the Run-Time Library. This space is freed by TPU when
it is no longer needed.
data
OpenVMS usage:item_list_3
type: longword (unsigned)
access: modify
mechanism: by reference
Stream data. The data argument is either the address of an item
list or the address of a descriptor.
NOTE
The meaning of this parameter depends on the item code
specified in the code field.
When the TPU$K_OPEN item code is issued, the data parameter is
the address of an item list containing information about the
open request. The following TPU item codes are available for
specifying information about the open request:
o TPU$K_ACCESS item code lets you specify one of three item
codes in the buffer address field, as follows:
- TPU$K_IO
- TPU$K_INPUT
- TPU$K_OUTPUT
o TPU$K_FILENAME item code is used for specifying the address
of a string to use as the name of the file you are opening.
The length field contains the length of this string, and the
address field contains the address.
o TPU$K_DEFAULTFILE item code is used for assigning a default
file name to the file being opened. The buffer length field
contains the length, and the buffer address field contains the
address of the default file name.
o TPU$K_RELATEDFILE item code is used for specifying a related
file name for the file being opened. The buffer length field
contains the length, and the buffer address field contains the
address of a string to use as the related file name.
o TPU$K_RECORD_ATTR item code specifies that the buffer address
field contains the value for the record attribute byte in the
FAB (FAB$B_RAT) used for file creation.
o TPU$K_RECORD_FORM item code specifies that the buffer address
field contains the value for the record format byte in the FAB
(FAB$B_RFM) used for file creation.
o TPU$K_MAXIMIZE_VER item code specifies that the version number
of the output file should be one higher than the highest
existing version number.
o TPU$K_FLUSH item code specifies that the file should have
every record flushed after it is written.
o TPU$K_FILESIZE item code is used for specifying a value to be
used as the allocation quantity when creating the file. The
value is specified in the buffer address field.
8.3 – Description
By default, TPU$FILEIO creates variable-length files with
carriage-return record attributes (FAB$B_RFM = VAR, FAB$B_RAT
FORM item, that item is used instead.
The following combinations of formats and attributes are
acceptable:
Format Attributes
STM,STMLF,STMCR 0,BLK,CR,BLK+CR
VAR 0,BLK,FTN,CR,BLK+FTN,BLK+CR
All other combinations are converted to VAR format with CR
attributes.
This routine always puts values greater than 511 in the first
longword of the stream data structure. Because a user-written
file I/O routine is restricted to the values 0 through 511, you
can easily distinguish the file control blocks (FCB) this routine
fills in from the ones you created.
NOTE
TPU uses TPU$FILEIO by default when you use the
simplified callable interface. When you use the full
callable interface, you must explicitly invoke TPU$FILEIO
or provide your own file I/O routine.
8.4 – Condition Values Returned
The TPU$FILEIO routine returns an OpenVMS RMS status code to
TPU. The file I/O routine is responsible for signaling all
errors if any messages are desired.
9 – TPU$FILE_PARSE
The TPU$FILE_PARSE routine provides a simplified interface to
the $PARSE system service. TPU calls this routine when the
built-in procedure FILE_PARSE is executed from TPU code.
Format
TPU$FILE_PARSE result-string ,flags ,filespec ,default-spec
,related-spec
9.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. See Condition Values Returned.
9.2 – Arguments
result-string
OpenVMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Includes the components of the file specification specified by
the flags argument. The memory for the return string is allocated
via the Run-Time Library routine LIB$SGET1_DD. Use the Run-Time
Library routine LIB$SFREE1_DD to deallocate the memory for the
return string.
flags
OpenVMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Determine what file specification components should be returned.
The following table shows the valid values for the flags
argument:
Flag Bit(1) Description
TPU$M_NODE Returns the node component of the file
specification.
TPU$M_DEV Returns the device component of the file
specification.
TPU$M_DIR Returns the directory component of the file
specification.
TPU$M_NAME Returns the name component of the file
specification.
TPU$M_TYPE Returns the type component of the file
specification.
TPU$M_VER Returns the version component of the file
specification.
TPU$M_HEAD Returns NODE, DEVICE and DIRECTORY components
of the file specification. If the TPU$M_NODE,
TPU$M_DEV or TPU$M_DIR bits are set while
TPU$M_HEAD is set, the routine signals the
error TPU$_INCKWDCOM and returns control to the
caller.
TPU$M_TAIL Returns NAME, TYPE and VERSION components of
the file specification. If the TPU$M_NAME,
TPU$M_TYPE or TPU$M_VER bits are set while
TPU$M_TAIL is set, the routine signals the
error TPU$_INCKWDCOM and returns control to the
caller.
(1) TPU$M... indicates a mask. There is a corresponding value for
each mask in the form TPU$V...
filespec
OpenVMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
The object file specification.
default-spec
OpenVMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Contains the default file specification. The default file
specification fields are used in the result string as substitutes
for fields omitted in the filespec argument. You can also
make substitutions in the result string using the related-spec
argument.
Use the value 0 when no default-spec is to be applied to the file
specification.
related-spec
OpenVMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Contains the related file specification. The fields in the
related file specification are substituted in the result-string
if a particular field is missing from both the filespec and
default-spec arguments.
Use the value 0 when no default-spec is to be applied to the file
specification.
9.3 – Description
The TPU$FILE_PARSE routine returns a string containing the fields
requested of the file specified. The file is not required to
exist when the parse is done. The intention of the TPU$FILE_
PARSE routine is to construct a valid file specification from the
information passed in through the file specification, the default
file specification, and the related file specification.
The routine uses the $PARSE system service to return the
requested information.
The TPU$FILE_PARSE routine is also called by TPU when the
TPU built-in procedure FILE_PARSE is executed from TPU code. The
return value of the built-in procedure is the string returned in
the result-string argument.
9.4 – Condition Values Returned
TPU$_SUCCESS Normal successful completion. If the return
string contains a null-string, then the last
match of the search operations has occurred.
TPU$_INCKWDCOM The flags argument had an illegal combination
of values.
TPU$_PARSEFAIL The parse failed.
10 – TPU$FILE_SEARCH
The TPU$FILE_SEARCH routine provides a simplified interface to
the $SEARCH system service. TPU call this routine when TPU
code executes the FILE_SEARCH built-in procedure.
Format
TPU$FILE_SEARCH result-string ,flags ,filespec ,default-spec
,related-spec
10.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. See Condition Values Returned.
10.2 – Arguments
result-string
OpenVMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Includes the components of the file specification passed by the
flags argument. The memory for the return string is allocated via
the Run-Time Library routine LIB$SGET1_DD. To deallocate memory
for the string, use the Run-Time Library routine LIB$SFREE1_DD.
flags
OpenVMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Determines what file specification components should be returned.
The following table lists the valid flag values:
Flag(1) Function
TPU$M_NODE Returns the node component of the file
specification.
TPU$M_DEV Returns the device component of the file
specification.
TPU$M_DIR Returns the directory component of the file
specification.
TPU$M_NAME Returns the name component of the file
specification.
TPU$M_TYPE Returns the type component of the file
specification.
TPU$M_VER Returns the version component of the file
specification.
TPU$M_REPARSE Reparses the file specification before
processing. This is intended to be used to
reset the file search.
TPU$M_HEAD Returns NODE, DEVICE, and DIRECTORY components
of the file specification. If the TPU$M_NODE,
TPU$M_DEV or TPU$M_DIR bits are set while
TPU$M_HEAD is set, the routine will signal
the error TPU$_INCKWDCOM and return.
TPU$M_TAIL Returns NAME, TYPE and VERSION components of
the file specification. If the TPU$M_NAME,
TPU$M_TYPE or TPU$M_VER bits are set while
TPU$M_TAIL is set, the routine will signal the
error TPU$_INCKWDCOM and return.
(1) TPU$M... indicates a mask. There is a corresponding value for
each mask in the form TPU$V...
filespec
OpenVMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Object file specification.
default-spec
OpenVMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
The default file specification. The default file specification
fields are used to fill in the result-string when fields are
omitted in the filespec argument. Use the related-spec argument
to specify other substitutions.
Use the value 0 when no default-spec is to be applied to the file
specification.
related-spec
OpenVMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Contains the related file specification. The fields in the
related file specification are used in the result-string for
fields omitted in the filespec and default-spec arguments.
Use the value 0 when no default-spec is to be applied to the file
specification.
10.3 – Description
This routine allows an application to verify the existence
of, and return components of, a file specification. Wildcard
operations are permitted. The routine uses the $PARSE and $SEARCH
system services to seek the file specification.
If no wildcards are included in the file specification string
and the result-string returns a zero (0) length string, no
file was found. If wildcard characters were present in the file
specification and the result-string returns a zero (0) length
string, there are no more files that match the wildcards.
To find all the files that match a wildcard specification,
repeatedly call this routine, passing the same arguments, until
the routine returns a zero-length result string.
The TPU$FILE_SEARCH routine is called by TPU when the TPU
built-in procedure FILE_SEARCH is executed from TPU code. The
return value of the built-in procedure is the string returned in
the result-string argument.
10.4 – Condition Values Returned
TPU$_SUCCESS Normal successful completion. If the return
string contains a null string, the final match
operation was detected.
TPU$_INCKWDCOM The flags argument had an illegal combination
of values.
TPU$_PARSEFAIL The requested repeat parse failed.
TPU$_SEARCHFAIL An error occurred during the search operation.
11 – TPU$HANDLER
The TPU$HANDLER routine is the TPU condition handler.
The TPU condition handler invokes the $PUTMSG system service,
passing it the address of TPU$MESSAGE.
Format
TPU$HANDLER signal_vector ,mechanism_vector
11.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. See Condition Values Returned.
11.2 – Arguments
signal_vector
OpenVMS usage:arg_list
type: longword (unsigned)
access: modify
mechanism: by reference
Signal vector. See the VSI OpenVMS System Services Reference
Manual for information about the signal vector passed to a
condition handler.
mechanism_vector
OpenVMS usage:arg_list
type: longword (unsigned)
access: read only
mechanism: by reference
Mechanism vector. See the VSI OpenVMS System Services Reference
Manual for information about the mechanism vector passed to a
condition handler.
11.3 – Description
The TPU$MESSAGE routine performs the actual output of the
message. The $PUTMSG system service only formats the message.
It gets the settings for the message flags and facility name from
the variables described in the OpenVMS Utility Routines Manual in
the section about the TPU Shareable Image. Those values can be
modified only by the TPU built-in procedure SET.
If the condition value received by the handler has a FATAL status
or does not have the TPU facility code, the condition is
resignaled.
If the condition is TPU$_QUITTING, TPU$_EXITING, or TPU$_
RECOVERFAIL, a request to UNWIND is made to the establisher of
the condition handler.
After handling the message, the condition handler returns with
a continue status. TPU error message requests are made by
signaling a condition to indicate which message should be written
out. The arguments in the signal array are a correctly formatted
message argument vector. This vector sometimes contains multiple
conditions and formatted ASCII output (FAO) arguments for the
associated messages. For example, if the editor attempts to open
a file that does not exist, the TPU message TPU$_NOFILEACCESS
is signaled. The FAO argument to this message is a string for the
name of the file. This condition has an error status, followed by
the OpenVMS RMS status field (STS) and status value field (STV).
Because this condition does not have a fatal severity, the editor
continues after handling the error.
The editor does not automatically return from TPU$CONTROL. If
you call the TPU$CONTROL routine, you must explicitly establish a
way to regain control (for example, using the built-in procedure
CALL_USER). If you establish your own condition handler but call
the TPU handler for certain conditions, the default condition
handler must be established at the point in your program where
you want to return control. You can also interrupt TPU$CONTROL
by having your program specify and then trigger an asynchronous
routine via the TPU$SPECIFY_ASNYC_ACTION and TPU$TRIGGER_ASYNC_
ACTION routines.
See the VSI OpenVMS Calling Standard for details on writing a
condition handler.
12 – TPU$INITIALIZE
The TPU$INITIALIZE routine initializes TPU for text
processing. This routine allocates global data structures,
initializes global variables, and calls the appropriate setup
routines for each of the major components of the editor,
including the Screen Manager and the I/O subsystem.
Format
TPU$INITIALIZE callback [,user_arg]
12.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. Condition values that this routine can
return are listed under Condition Values Returned.
12.2 – Argument
callback
OpenVMS usage:vector_longword_unsigned
type: bound procedure value
access: read only
mechanism: by descriptor
Callback routine. The callback argument is the address of a
user-written routine that returns the address of an item list
containing initialization parameters or a routine for handling
file I/O operations. This callback routine must call a command
line parsing routine, which can be TPU$CLIPARSE or a user-written
parsing routine.
Callable TPU defines item codes that you can use to specify
initialization parameters. The following rules must be followed
when building the item list:
o If you use the TPU$_OTHER_FILENAMES item code, it must follow
the TPU$_FILENAME item code.
o If you use either the TPU$_CHAIN item code or the TPU$_ENDLIST
code, it must be the last item code in the list.
The following figure shows the general format of an item
descriptor. For information about how to build an item list,
refer to the programmer's manual associated with the language
you are using. Any reference to command line qualifiers refer
to those command line qualifiers that you use with the EDIT/TPU
command.
---------------------------------------------
| Item code | Buffer length |
---------------------------------------------
| Buffer address |
---------------------------------------------
| Return address |
---------------------------------------------
The return address in an item descriptor is usually 0.
The following item codes are available:
Item Code Description
TPU$_OPTIONS Enables the command qualifiers. The bits in
the bit mask specified by the buffer address
field correspond to the various TPU command
qualifiers.
TPU$_JOURNALFILE Passes the string specified with the /JOURNAL
qualifier. The buffer length field is the
length of the string, and the buffer address
field is the address of the string. This
string is available with GET_INFO (COMMAND_
LINE,"JOURNAL_FILE"). This string can be a null
string.
TPU$_SECTIONFILE Passes the string that is the name of the
binary initialization file (section file) to
be mapped in. The buffer length field is the
length of the string, and the buffer address
field is the address of the string. If the
TPU$V_SECTION bit is set, this item code must
be specified.
TPU$_OUTPUTFILE Passes the string specified with the /OUTPUT
qualifier. The buffer length field is the
length of the string, and the buffer address
field specifies the address of the string. This
string is returned by the built-in procedure
GET_INFO (COMMAND_LINE, "OUTPUT_FILE"). The
string can be a null string.
TPU$_DISPLAYFILE Passes the string specified with the /DISPLAY
qualifier. The buffer length field defines the
length of the string, and the buffer address
field defines the string address. The interface
between the TPUSHR image and the display file
image is not documented. Applications should
only use this option with documented display
files such as TPU$CCTSHR or TPU$MOTIFSHR.
TPU$_COMMANDFILE Passes the string specified with the /COMMAND
qualifier. The buffer length field is the
length of the string, and the buffer address
field is the address of the string. This string
is returned by the built-in procedure GET_INFO
(COMMAND_LINE, "COMMAND_FILE"). The string can
be a null string.
TPU$_FILENAME Passes the string that is the name of the first
input file specified on the command line.
The buffer length field specifies the length
of this string, and the buffer address field
specifies its address. This string is returned
by the built-in procedure GET_INFO (COMMAND_
LINE, "FIRST_FILE_NAME"). This file name can be
a null string.
TPU$_OTHER_ Passes a string that contains the name of an
FILENAMES input file that follows the first input file
on the command line. The buffer length field
specifies the length of this string, and the
buffer address field specifies its address.
Each additional file specified on the command
line requires its own TPU$_OTHER_FILENAMES item
entry. These strings are returned by the GET_
INFO (COMMAND_LINE,"NEXT_FILE_NAME") built-
in procedure in the order they appear in the
item list. This item code must appear after the
TPU$_FILENAME item in the item list.
TPU$_FILEIO Passes the bound procedure value of a routine
to be used for handling file operations.
You can provide your own file I/O routine,
or you can call TPU$FILEIO, the utility
routine provided by TPU for handling file
operations. The buffer address field specifies
the address of a two-longword vector. The first
longword of the vector contains the address of
the routine. The second longword specifies the
environment value that TPU loads into R1
before calling the routine.
TPU$_CALLUSER Passes the bound procedure value of the user-
written routine that the built-in procedure
CALL_USER is to call. The buffer address field
specifies the address of a two-longword vector.
The first longword of the vector contains the
address of the routine. The second longword
specifies the environment value that TPU
loads into R1 before calling the routine.
TPU$_INIT_FILE Passes the string specified with the
/INITIALIZATION qualifier. The buffer length
field is the length of the string, and the
buffer address field is the address of the
string. This string is returned by the built-in
procedure GET_INFO (COMMAND_LINE,"INIT_FILE").
TPU$_START_LINE Passes the starting line number for the edit.
The buffer address field contains the first of
the two integer values you specified as part
of the /START_POSITION command qualifier. The
value is available using the built-in procedure
GET_INFO (COMMAND_LINE,"LINE"). Usually an
initialization procedure uses this information
to set the starting position in the main
editing buffer. The first line in the buffer
is line 1.
TPU$_START_CHAR Passes the starting column position for the
edit. The buffer address field contains
the second of the two integer values you
specified as part of the /START_POSITION
command qualifier. The value is available
using the built-in procedure GET_INFO (COMMAND_
LINE, "CHARACTER"). Usually an initialization
procedure uses this information to set the
starting position in the main editing buffer.
The first column on a line to character 1.
TPU$_ Passes the string specified with the
CHARACTERSET /CHARACTER_SET qualifier. The buffer length
field specifies the string length and the
buffer address field specifies the string
address. Valid strings are "DEC_MCS" (the
default value), "ISO_LATIN1", and "GENERAL".
If the application tries to pass any other
string, the routine signals an error and passes
the default string (DEC_MCS).
TPU$_WORKFILE Passes the string specified with the /WORK
qualifier. The buffer length field specifies
the string length and the buffer address
specifies the string address. This string is
available with GET_INFO (COMMAND_LINE, "WORK_
FILE").
TPU$_CHAIN Passes the address of the next item list to the
process specified by the buffer address field.
TPU$_ENDLIST Signals the end of the item list.
TPU$_PARENT_ Passes the appropriate parent widget when
WIDGET invoking the DECwindows version of the
editor. This routine is not specified by the
application; TPU invokes its own application
shell. The widget address is passed in the
buffer address field. This item code is only
valid when using the DECwindows interface.
TPU$_ Passes the application context to use with the
APPLICATION_ TPU$_PARENT_WIDGET. TPU defaults to its own
CONTEXT application context. The buffer address field
specifies the application context address.
This item code is only valid when using the
DECwindows interface.
TPU$_ Specifies which file TPU uses to initialize
DEFAULTSFILE the X defaults database. The buffer length
field specifies the string length and the
buffer address field specifies the string
address. This item code is only valid when
using the DECwindows interface.
TPU$_CTRL_C_ Passes the bound procedure value of a routine
ROUTINE to be used for handling Ctrl/C asynchronous
system traps (ASTs). TPU calls the routine
when a Ctrl/C AST occurs. If the routine
returns a FALSE value, TPU assumes that
the Ctrl/C has been handled. If the routine
returns a TRUE value, TPU aborts any
currently executing TPU procedure. The
buffer address field specifies the address
of a two-longword vector. The first longword of
the vector contains the address of the routine.
The second longword specifies the environment
value that TPU loads into R1 before calling
the routine.
TPU$_DEBUGFILE Passes the string specified with the /DEBUG
command qualifier. The buffer length field
is the length of the string, and the buffer
address field is the address of the string.
TPU$_FILE_SEARCH Passes the bound procedure value of a routine
to be used to replace the TPU$FILE_SEARCH
routine which is called when the built-in
procedure FILE_SEARCH is called from TPU code.
See the description of the TPU$FILE_SEARCH
and the user routine FILE_SEARCH for more
information.
TPU$_FILE_PARSE Passes the bound procedure value of a routine
to be used to replace the TPU$FILE_PARSE
routine which is called when the built-
in procedure FILE_PARSE is called from TPU
code. See the description of the TPU$FILE_
PARSE and the user routine FILE_PARSE for more
information.
Valid Masks for the TPU$K_OPTIONS Item Code lists the bits and
corresponding masks enabled by the item code TPU$K_OPTIONS and
shows how each bit affects TPU$INITIALIZE operation. Several bits
in the TPU$_OPTIONS mask require additional item code entries in
the item list. An example of this is TPU$M_COMMAND which requires
a TPU$_COMMANDFILE entry in the item list.
Table 6-1 Valid Masks for the TPU$K_OPTIONS Item Code
GET_INFO
Request
Mask(1) String(2) Description
TPU$M_ COMMAND If TPU senses the presence of
COMMAND the TPU$_COMMANDFILE item, it tries
to read, compile and execute the
unbound TPU code.
TPU$M_ Not Specifies that TPU should use
COMMAND_ applicable the default command file name of
DFLTED TPU$COMMAND.TPU when reading in the
command file. No error is reported
if the default command file is not
found. TPU$INITIALIZE fails when the
TPU$M_COMMAND_DFLTED bit is set to 0
and no file is specified in the item
list.
TPU$M_CREATE CREATE The behavior of TPU is not
affected by this bit. Its
interpretation is left to the
application layered on TPU.
TPU$M_DEBUG Not If TPU senses the presence of
applicable the TPU$_DEBUGFILE item, it tries to
read the file, and then proceeds to
compile and execute its contents as
TPU statements.
TPU$M_ Not If TPU senses the presence of
DEFAULTS applicable the TPU$_DEFAULTSFILE item, it uses
the specified DECwindows X resource
file to initialize the DECwindows X
resource database.
TPU$M_ DISPLAY If TPU senses the presence of the
DISPLAY TPU$_DISPLAYFILE item, it tries to
image activate the specified image
as its screen manager. When the
bit is 0, TPU uses SYS$OUTPUT
for display and only the READ_LINE
built-in procedure may be used for
input.
TPU$M_INIT INITIALIZATIONIf TPU senses the presence of the
TPU$_INIT_FILE item, it returns the
specified string through the built-
in procedure GET_INFO (COMMAND_LINE,
"INITIALIZATION_FILE"). Processing
of the initialization file is left
to the application.
TPU$M_ JOURNAL If TPU senses the presence of the
JOURNAL TPU$_JOURNALFILE item, it outputs
the keystrokes entered during the
editing session to the specified
file.
Note: VSI recommends the use of
buffer change journaling in new
applications.
TPU$M_MODIFY MODIFY The behavior of TPU is not
affected by this bit. Its
interpretation is left to the
application layered on TPU.
TPU$M_ Not TPU initializes the DECwindows X
NODEFAULTS applicable resource database only with resource
files that the DECwindows toolkit
routine XtApplInitialize loads into
the database.
TPU$M_ NOMODIFY The behavior of TPU is not
NOMODIFY affected by this bit. Its
interpretation is left to the
application layered on TPU.
TPU$M_OUTPUT OUTPUT The behavior of TPU is not
affected by this bit. Its
interpretation is left to the
application layered on TPU.
TPU$M_READ READ_ONLY The behavior of TPU is not
affected by this bit. Its
interpretation is left to the
application layered on TPU.
TPU$M_ RECOVER The behavior of TPU is not
RECOVER affected by this bit. Its
interpretation is left to the
application layered on TPU.
TPU$M_ SECTION If TPU senses the presence of the
SECTION TPU$_SECTIONFILE item, it tries to
read the specified file as a binary
initialization file. TPU$INITIALIZE
fails if this bit is set to 1 and
the TPU$_SECTIONFILE item is not
present in the item list.
TPU$M_SEC_ Not If TPU senses the presence of the
LNM_MODE applicable TPU$M_SEC_LNM_MODE item, it looks
only at executive mode logical names
when attempting to read in a section
file.
TPU$M_WORK WORK If TPU senses the presence of
the TPU$_WORKFILE item, it uses the
specifed file for memory management.
If no item list entry is present,
and this bit is set to 1, a file is
created in SYS$LOGIN:.TPU$WORK.
TPU$M_WRITE WRITE The behavior of TPU is not
affected by this bit. Its
interpretation is left to the
application layered on TPU.
Footnotes:
1. The flag prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask
corresponding to the specific field in which the bit is set.
TPU$V_ is a bit number.
2. Most bits in the mask have a corresponding GET_INFO (COMMAND_
LINE) request string.
To create the bits, start with the value 0, then use the OR
operator on the mask (TPU$M . . . ) of each item you want to set.
Another way to create the bits is to treat the 32 bits as a bit
vector and set the bit (TPU$V . . . ) corresponding to the item
you want.
user_arg
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
User argument. The user_arg argument is passed to the user-
written initialization routine INITIALIZE.
The user_arg parameter is provided to allow an application to
pass information through TPU$INITIALIZE to the user-written
initialization routine. TPU does not interpret this data in
any way.
12.3 – Description
This is the first routine that must be called after establishing
a condition handler.
This routine initializes the editor according to the information
received from the callback routine. The initialization routine
defaults all file specifications to the null string and all
options to off. However, it does not default the file I/O or
call-user routine addresses.
12.4 – Condition Values Returned
TPU$_SUCCESS Initialization was completed successfully.
TPU$_FAILURE General code for all other errors during
initialization.
TPU$_INSVIRMEM Insufficient virtual memory exists for the
editor to initialize.
TPU$_ No routine has been established to perform
NOFILEROUTINE file operations.
TPU$_NONANSICRT The input device (SYS$INPUT) is not a
supported terminal.
TPU$_RESTOREFAIL An error occurred during the restore
operation.
TPU$_SYSERROR A system service did not work correctly.
13 – TPU$MESSAGE
The TPU$MESSAGE routine writes error messages and strings using
the built-in procedure, MESSAGE.
Call this routine to have messages written and handled in a
manner consistent with TPU. This routine should be used only
after TPU$EXECUTE_INIFILE.
Format
TPU$MESSAGE string
13.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value.
NOTE
The return status should be ignored because it is intended
for use by the $PUTMSG system service.
13.2 – Argument
string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Formatted message. The string argument is the address of
a descriptor of text to be written. It must be completely
formatted. This routine does not append the message prefixes.
However, the text is appended to the message buffer if one
exists. In addition, if the buffer is mapped to a window, the
window is updated.
14 – TPU$PARSEINFO
The TPU$PARSEINFO routine parses a command and builds the item
list for TPU$INITIALIZE.
Format
TPU$PARSEINFO fileio ,call_user
14.1 – Returns
OpenVMS usage:item_list
type: longword (unsigned)
access: read only
mechanism: by reference
The routine returns the address of an item list.
14.2 – Arguments
fileio
OpenVMS usage:vector_longword_unsigned
type: bound procedure value
access: read only
mechanism: by descriptor
File I/O routine. The fileio argument is the address for a
descriptor of a file I/O routine.
call_user
OpenVMS usage:vector_longword_unsigned
type: bound procedure value
access: read only
mechanism: by descriptor
Call-user routine. The call_user argument is the address for a
descriptor of a call-user routine.
14.3 – Description
The TPU$PARSEINFO routine parses a command and builds the item
list for TPU$INITIALIZE.
This routine uses the command language (CLI) routines to
parse the current command. It makes queries about the command
parameters and qualifiers that TPU expects. The results of
these queries are used to set up the proper information in an
item list. The addresses of the user routines are used for those
items in the list. The address of this list is the return value
of the routine.
If your application parses information that is not related to the
operation of TPU, make sure the application obtains and uses
all non-TPU parse information before the application calls the
TPU$PARSEINFO interface. This is because TPU$PARSEINFO destroys
all parse information obtained and stored before TPU$PARSEINFO
was called.
15 – TPU$SIGNAL
The TPU$SIGNAL routine allows applications and user-written TPU
routines such as FILEIO to easily signal error messages in order
for TPU error handlers to perform correctly.
Format
TPU$SIGNAL condition-code
15.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. In most cases, the routine returns
either the same signal passed to it in the condition value
argument, or the return value of LIB$SIGNAL. If the routine
fails, it signals TPU$_FAILURE and returns control to the caller.
15.2 – Argument
condition-code
OpenVMS usage: cond_value
type: longword (unsigned)
access: read only
mechanism: by value
The condition-code is an unsigned longword that contains the
condition code to be signaled. In most cases, this argument is a
TPU message code.
15.3 – Description
TPU$SIGNAL performs the same function as the Run-Time Library
routine LIB$SIGNAL, but it also processes TPU facility messages
to allow TPU language ON_ERROR handlers to be called.
For example, assume that a user-written file input/output routine
is designed to signal the error TPU$_OPENIN when it fails to
open a file. Calling the TPU$SIGNAL routine and passing the value
TPU$_OPENIN allows a case-style TPU ON_ERROR handler to receive
the error, thus preserving the documented return values for TPU
built-in procedures such as READ_FILE.
NOTE
You must call TPU$INITIALIZE before you call the TPU$SIGNAL
routine.
If TPU$_QUITTING, TPU$_EXITING, or TPU$_RECOVERFAIL are passed to
the routine, it calls the Run-Time Library routine LIB$SIGNAL.
If facility messages other than TPU messages are passed to the
TPU$SIGNAL routine, it calls the LIB$SIGNAL routine and passes
the appropriate condition value.
16 – TPU$SPECIFY_ASYNC_ACTION
The TPU$SPECIFY_ASYNC_ACTION routine allows applications using
the TPU full callable interface to register asynchronous
actions with TPU.
Format
TPU$SPECIFY_ASYNC_ACTION facility_index [,tpu_statement]
16.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. Condition values that this routine can
return are listed under Condition Values Returned.
16.2 – Argument
facility_index
OpenVMS usage:longword_unsigned
type: longword (signed)
access: read only
mechanism: by reference
Represents an index of the asynchronous action. This index is
used with the TPU$TRIGGER_ASYNC_ACTION routine to let TPU know
what action to perform. It may also be used to delete an action
routine (by omitting the tpu_statement). You may register several
asynchronous actions depending on your application's needs. This
facility index number may be any positive integer.
tpu_statement
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
The TPU statement you want executed when you call the
TPU$TRIGGER_ASYNC_ACTION routine. The statement is compiled and
then stored internally. If you omit the parameter, TPU removes
the action from its list of asynchronous events.
16.3 – Description
The TPU$SPECIFY_ASYNC_ACTION routine, along with TPU$TRIGGER_
ASYNC_ACTION, allow applications to interrupt TPU after
calling TPU$CONTROL. The specified TPU statement is compiled
and saved.
This routine must be called after TPU$INITIALIZE. It will not
complete successfully if keystroke journaling is enabled.
16.4 – Condition Values Returned
TPU$_SUCCESS Normal successful completion.
TPU$_COMPILEFAIL The code specified in tpu_statement did not
compile successfully.
TPU$_INVPARM An invalid parameter was passed.
TPU$_JNLACTIVE Keystroke journaling is active. This routine
requires that either journaling be turned off
or that buffer change journaling be used.
17 – TPU$TPU
The TPU$TPU routine invokes TPU and is equivalent to the DCL
command EDIT/TPU.
Format
TPU$TPU command
17.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. Condition values that this routine can
return are listed under Condition Values Returned.
17.2 – Argument
command
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Command string. Note that the verb is TPU instead of EDIT/TPU.
The command argument is the address for a descriptor of a command
line.
17.3 – Description
This routine takes the command string specified and passes it to
the editor. TPU uses the information from this command string
for initialization purposes, just as though you had entered the
command at the DCL level.
Using the simplified callable interface does not set TPU$CLOSE_
SECTION. This feature lets you make multiple calls to TPU$TPU
without requiring you to open and close the section file on each
call.
If your application parses information that is not related to the
operation of TPU, make sure the application obtains and uses
all non-TPU parse information before the application calls
TPU$TPU. This is because TPU$TPU destroys all parse information
obtained and stored before TPU$TPU was called.
17.4 – Condition Values Returned
This routine returns any condition value returned by
TPU$INITIALIZE, TPU$EXECUTE_INIFILE, TPU$CONTROL, and
TPU$CLEANUP.
18 – TPU$TRIGGER_ASYNC_ACTION
The TPU$TRIGGER_ASYNC_ACTION routine allows applications using
the TPU full callable interface to interrupt the TPU
TPU$CONTROL loop at an asynchronous level.
Format
TPU$TRIGGER_ASYNC_ACTION facility_index
18.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. Condition values that this routine can
return are listed under Condition Values Returned.
18.2 – Arguments
facility_index
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
The facility_index argument represents the asynchronous action to
be taken. This is the same index passed to the TPU$SPECIFY_ASYNC_
ACTION routine registering what TPU statements to execute.
18.3 – Description
The TPU$TRIGGER_ASYNC_ACTION routine, along with TPU$SPECIFY_
ASYNC_ACTION routine allow applications to interrupt TPU after
calling TPU$CONTROL. The command that was specified for this
facility_index is put on the TPU queue of work items and is
handled as soon as no other work items are present. This allows
TPU to complete and stabilize its environment before executing
the command. This routine must be called after control has been
passed to TPU via the TPU$CONTROL routine.
18.4 – Condition Values Returned
TPU$_SUCCESS Normal successful completion.
TPU$_UNKFACILITY The facility_index passed to this routine
does not match any facility index passed to
TPU$SPECIFY_ASYNC_ACTION.
19 – FILEIO
The user-written FILEIO routine is used to handle TPU file
operations. The name of this routine can be either your own
file I/O routine or the name of the TPU file I/O routine
(TPU$FILEIO).
Format
FILEIO code ,stream ,data
19.1 – Returns
OpenVMS usage:cond_value
type: longword (usigned)
access: write only
mechanism: by reference
Longword condition value. Most utility routines return a
condition value in R0. Condition values that this routine can
return are listed under Condition Values Returned.
19.2 – Arguments
code
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Item code specifying a TPU function. The code argument is the
address of a longword containing an item code from TPU, which
specifies a function to perform.
stream
OpenVMS usage:unspecified
type: longword (unsigned)
access: modify
mechanism: by reference
File description. The stream argument is the address of a data
structure containing four longwords. This data structure is used
to describe the file to be manipulated.
data
OpenVMS usage:item_list_3
type: longword (unsigned)
access: modify
mechanism: by reference
Stream data. The data argument is either the address of an item
list or the address of a descriptor.
NOTE
The value of this parameter depends on which item code you
specify.
19.3 – Description
The bound procedure value of this routine is specified in the
item list built by the callback routine. This routine is called
to perform file operations. Instead of using your own file I/O
routine, you can call TPU$FILEIO and pass it the parameters for
any file operation you do not want to handle. Note, however, that
TPU$FILEIO must handle all I/O requests for any file it opens.
Also, if it does not open the file, it cannot handle any I/O
requests for the file. In other words, you cannot mix the file
operations between your own file I/O routine and the one supplied
by TPU.
19.4 – Condition Values Returned
The condition values returned are determined by the user and
should indicate success or failure of the operation.
20 – FILE_PARSE
This is a user-written routine that can be used in place of the
TPU$FILE_PARSE routine.
Format
FILE_PARSE result-string ,flags ,filespec ,default-spec
,related-spec
20.1 – Returns
OpenVMS usage: cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. The return value is ignored by TPU.
User-written FILE_PARSE routines should include calls to the
TPU$SIGNAL routine to ensure proper error handling.
20.2 – Arguments
result-string
OpenVMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Return value for the built-in procedure FILE_PARSE. The calling
program should fill in this descriptor with a dynamic string
allocated by the string routines, such as the Run-Time Library
routine LIB$SGET1_DD. TPU frees this string when necessary.
flags
OpenVMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
The following table lists the valid flag values used to request
file specification components:
Flag(1) Function
TPU$M_NODE Requests for the node component of the file
specification.
TPU$M_DEV Requests for the device component of the file
specification.
TPU$M_DIR Requests for the directory component of the
file specification.
TPU$M_NAME Requests for the name component of the file
specification.
TPU$M_TYPE Requests for the type component of the file
specification.
TPU$M_VER Requests for the version component of the file
specification.
TPU$M_HEAD Requests for the NODE, DEVICE, and DIRECTORY
components of the file specification.
TPU$M_TAIL Requests for NAME, TYPE, and VERSION components
of the file specification.
(1) TPU$M... indicates a mask. There is a corresponding value for
each mask in the form TPU$V...
filespec
OpenVMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
The object file specification.
default-spec
OpenVMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Contains the default file specification. The value 0 is passed if
there is no default-spec argument.
related-spec
OpenVMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
The related-spec argument contains the related file
specification. The value 0 is passed if there is no related-spec.
20.3 – Description
This routine allows an application to replace the TPU$FILE_PARSE
routine with its own file-parsing routine. The calling program
passes the address of the file-parsing routine to TPU$INITIALIZE
using the TPU$_FILE_PARSE item code.
When the TPU built-in procedure FILE_PARSE is called from
TPU code, TPU calls either the user-written routine (if one
was passed to TPU$INITIALIZE) or the TPU$FILE_PARSE routine. The
return value of the built-in procedure is the string returned in
the result-string argument.
To ensure proper operation of the user's ON_ERROR error handlers,
errors should be signaled using the TPU$SIGNAL routine.
21 – FILE_SEARCH
This is a user-written routine that is used in place of the
TPU$FILE_SEARCH routine.
Format
FILE_SEARCH result-string ,flags ,filespec ,default-spec
,related-spec
21.1 – Returns
OpenVMS usage: cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. If an odd numeric value is returned,
the next call to the built-in procedure FILE_SEARCH automatically
sets the TPU$M_REPARSE bit in the flags longword. TPU$M_REPARSE
is also set if the result-string has a length of 0.
21.2 – Arguments
result-string
OpenVMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Return value for the built-in procedure FILE_SEARCH. Your program
should fill in this descriptor with a dynamic string allocated
by the string routines such as the Run-Time Library routine
LIB$SGET1_DD. TPU frees this string when necessary.
The TPU$M_REPARSE bit is set in the flags longword if the result-
string has a length of zero. The bit is intended to reset the
file search when wildcard searches are performed.
flags
OpenVMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
The following table shows the flags used for specifying the file
components:
Flag(1) Function
TPU$M_NODE Requests for the node component of the file
specification.
TPU$M_DEV Requests for the device component of the file
specification.
TPU$M_DIR Requests for the directory component of the
file specification.
TPU$M_NAME Requests for the name component of the file
specification.
TPU$M_TYPE Requests for the type component of the file
specification.
TPU$M_VER Requests for the version component of the file
specification.
TPU$M_REPARSE Reparses the file specification before
processing. This is intended as a way to
restart the file search. This flag will
automatically be set by TPU if on a previous
call to the FILE_SEARCH user routine the
result-string has a zero length or the routine
returns a odd (noneven) status.
TPU$M_HEAD Requests for the NODE, DEVICE, and DIRECTORY
components of the file specification.
TPU$M_TAIL Requests for the NAME, TYPE, and VERSION
component of the file specification.
(1) TPU$M... indicates a mask. There is a corresponding value for
each mask in the form TPU$V...
filespec
OpenVMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
The object file specification.
default-spec
OpenVMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
The default-spec argument contains the default file
specification.
The value 0 is passed if there is no default-spec.
related-spec
OpenVMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
The related-spec argument contains the related file
specification.
The value 0 is passed if there is no related-spec.
21.3 – Description
The FILE_SEARCH user routine allows an application to replace
the TPU$FILE_SEARCH routine with its own file-searching routine.
The calling program passes the address of the routine to the
TPU$INITIALIZE routine using the TPU$_FILE_SEARCH item code.
When the TPU built-in procedure FILE_SEARCH is called from TPU
code, TPU calls either the user-written FILE_SEARCH routine
(if one was passed to TPU$INITIALIZE) or the TPU$FILE_SEARCH
routine. The return value of the built-in procedure is the string
returned in the result-string argument.
To ensure proper operation of the user's ON_ERROR handlers,
errors in the user-written FILE_PARSE routine should be signaled
using the TPU$SIGNAL routine.
22 – HANDLER
The user-written HANDLER routine performs condition handling.
Format
HANDLER signal_vector ,mechanism_vector
22.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value.
22.2 – Arguments
signal_vector
OpenVMS usage:arg_list
type: longword (unsigned)
access: modify
mechanism: by reference
Signal vector. See the VSI OpenVMS System Services Reference
Manual for information about the signal vector passed to a
condition handler.
mechanism_vector
OpenVMS usage:arg_list
type: longword (unsigned)
access: read only
mechanism: by reference
Mechanism vector. See the VSI OpenVMS System Services Reference
Manual for information about the mechanism vector passed to a
condition handler.
22.3 – Description
If you need more information about writing condition handlers and
programming concepts, refer to VSI OpenVMS Programming Concepts
Manual.
Instead of writing your own condition handler, you can use the
default condition handler, TPU$HANDLER. If you want to write your
own routine, you must call TPU$HANDLER with the same parameters
that your routine received to handle TPU internal signals.
23 – INITIALIZE
The user-written initialization callback routine is passed to
TPU$INITIALIZE as a bound procedure value and called to supply
information needed to initialize TPU.
Format
INITIALIZE [user_arg]
23.1 – Returns
OpenVMS usage:item_list
type: longword (unsigned)
access: read only
mechanism: by reference
This routine returns the address of an item list.
23.2 – Arguments
user_arg
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
User argument.
23.3 – Description
The user-written initialization callback routine is passed to
TPU$INITIALIZE as a bound procedure value and called to supply
information needed to initialize TPU.
If the user_arg parameter was specified in the call to
TPU$INITIALIZE, the initialization callback routine is called
with only that parameter. If user_arg was not specified in the
call to TPU$INITIALIZE, the initialization callback routine is
called with no parameters.
The user_arg parameter is provided to allow an application to
pass information through TPU$INITIALIZE to the user-written
initialization routine. TPU does not interpret this data in
any way.
The user-written callback routine is expected to return the
address of an item list containing initialization parameters.
Because the item list is used outside the scope of the
initialization callback routine, it should be allocated in static
memory.
The item list entries are discussed in the TPU$INITIALIZE help
topic. Most of the initialization parameters have a default
value; strings default to the null string, and flags default to
false. The only required initialization parameter is the address
of a routine for file I/O. If an entry for the file I/O routine
address is not present in the item list, TPU$INITIALIZE returns
with a failure status.
24 – USER
The user-written USER routine allows your program to take control
during a TPU editing session (for example, to leave the editor
temporarily and perform a calculation).
Format
USER integer ,stringin ,stringout
24.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value.
24.2 – Arguments
integer
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
First parameter to the built-in procedure CALL_USER. This is an
input-only parameter and must not be modified.
stringin
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Second parameter to the built-in procedure CALL_USER. This is an
input-only parameter and must not be modified.
stringout
OpenVMS usage:char_string
type: character string
access: modify
mechanism: by descriptor
Return value for the built-in procedure CALL_USER. Your program
should fill in this descriptor with a dynamic string allocated by
the string routines (such as LIB$SGET1_DD) provided by the Run-
Time Library. The TPU editor frees this string when necessary.
24.3 – Description
This user-written routine is invoked by the TPU built-in
procedure CALL_USER. The built-in procedure CALL_USER passes
three parameters to this routine. These parameters are then
passed to the appropriate part of your application to be used
as specified. (For example, they can be used as operands in a
calculation within a Fortran program.) Using the string routines
provided by the Run-Time Library, your application fills in the
stringout parameter in the call-user routine, which returns the
stringout value to the built-in procedure CALL_USER.
The description of the built-in procedure CALL_USER in the DEC
Text Processing Utility Reference Manual shows an example of a
BASIC program that is a call-user routine.