RECOVER_BUFFER

     Reconstructs the work done in the buffer whose name you specify.
     DECTPU 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 DECTPU to
                          use to recover your buffer.  If you did not set a
                          journal file name using SET (JOURNALING), in most
                          cases DECTPU 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 DEC
                          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 DECTPU 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 DECTPU 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, DECTPU aborts the recovery,
     closes the journal file, and deletes the newly created buffer.

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

  Example

     1.  RECOVER_BUFFER ("junk.txt")

         Directs DECTPU 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 recovering 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)