RECOVER_BUFFER

    Reconstructs the work done in the buffer whose name you specify.
    VAXTPU creates a new buffer using the specified buffer name and, using
    the information in the original buffer's journal file, recovers all the
    changes made to records in the original file.  The resulting recovery
    is written to the newly created buffer.

 Syntax

    new_buffer := RECOVER_BUFFER (old_buffer_name, [, [journal_file_name]
                                                    template_buffer]])

 Parameters

    old_buffer_name      The name of the buffer you are trying to recover.

    journal_file_name    The name of the journal file you want VAXTPU to
                         use to recover your buffer.  If you did not set a
                         journal file name using SET (JOURNALING), in most
                         cases VAXTPU will have created the journal file
                         using its default journal file naming algorithm.
                         If the journal file was named by default, you need
                         not specify a journal file name with
                         RECOVER_BUFFER.  If you specified a journal file
                         name using SET (JOURNALING), use the same name
                         with RECOVER_BUFFER.

    template_buffer      The buffer whose attributes you want applied to
                         the newly created buffer.  For more information on
                         using a buffer as a template, see HELP or the VAX
                         Text Processing Utility Manual on the
                         CREATE_BUFFER built-in.

 Comments


    Only the first parameter (the old buffer name) is required.  If you
    want to specify the third parameter but not the second, you must use a
    comma as a placeholder, as follows:

    RECOVER_BUFFER ("junk.txt", , template_buffer);

    The third parameter is completely optional.

    If VAXTPU returns a message that it cannot find the journal file, and
    if the buffer you are trying to recover is small, the reason may be
    that records from the buffer were never written to the journal file
    because there were not enough records to trigger the first write
    operation to the journal file.  Similarly, if some text is missing
    after recovery, the reason may be that the last few operations did not
    trigger a write operation.  For more information on how VAXTPU manages
    write operations to a journal file, see HELP on the SET (JOURNALING)
    built-in.

    Buffer change journaling does not journal changes in buffer attributes
    (such as modifiability of the buffer or visibility of tabs).  Buffer
    change journaling only tracks changes to records in the buffer, such as
    addition, deletion, or modification of a record, or changes in a
    record's attributes.

    If you press CTRL/C during a recovery, VAXTPU aborts the recovery,
    closes the journal file, and deletes the newly created buffer.

    After a successful recovery, VAXTPU continues journaling new changes
    into the journal file that was used during the recovery.

 Example


    1.  RECOVER_BUFFER ("junk.txt")

        Directs VAXTPU to find the buffer-change journal file associated
        with the original buffer JUNK.TXT.  Creates a new buffer called
        JUNK.TXT.  Using the information from the journal file, recovers
        the changes made in the original JUNK.TXT buffer and places the
        results of the recovery in the new JUNK.TXT buffer.

    2.  The following code fragment creates a defaults buffer, changes an
        attribute of the defaults buffer, and creates a user buffer.  The
        fourth statement turns on buffer-change journaling and designates
        the file named USER1_JOURNAL.TPU$JOURNAL as the journaling file.
        At some later point in the session (represented by the elipses) the
        RECOVER_BUFFER statement is used to recover the contents of the old
        USER1.TXT by calling the contents of the journal file,
        USER1_JOURNAL.TPU$JOURNAL.  The attributes of the defaults buffer
        are applied to the newly created buffer USER1.TXT.  In this case,
        the new buffer has the end-of-buffer text "[That's all, folks!]".


           defaults_buffer := CREATE_BUFFER ("Defaults");

           SET (EOB_TEST, defaults_buffer, "[That's all, folks!]");

           user_buffer := CREATE_BUFFER ("User1.txt", "", defaults_buffer);

           SET (JOURNALING, user_buffer, ON, "user1_journal.tpu$journal");
            .
            .
            .
           RECOVER_BUFFER ("User1.txt", "user1_journal.tpu$journal",
                         defaults_buffer);



 Related Topics

    CREATE_BUFFER               GET_INFO(BUFFER_VARIABLE)
    GET_INFO(STRING_VARIABLE)   JOURNAL_OPEN
    JOURNAL_CLOSE               SET(JOURNALING)