VMS Help DECTPU, TPU$CLEANUP  *Conan The Librarian (sorry for the slow response - running on an old VAX)

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

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

    Format

      TPU$CLEANUP  flags

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                 Function

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

3 - Description

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

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

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

    Notes

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

       o  TPU$V_RESET_TERMINAL

       o  TPU$V_DELETE_BUFFERS

       o  TPU$V_DELETE_JOURNAL

       o  TPU$V_DELETE_WINDOWS

       o  TPU$V_DELETE_EXITH

       o  TPU$V_EXECUTE_PROC

       o  TPU$V_EXECUTE_FILE

       o  TPU$V_PRUNE_CACHE

       o  TPU$V_KILL_PROCESSES

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

4 - Condition Value Returned

    TPU$_SUCCESS       Normal successful completion.