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 – 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.
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.
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.
4 – Condition Value Returned
TPU$_SUCCESS Normal successful completion.