CREATE_BUFFER

     Creates a new buffer -- a work space for editing text, storing data,
     and other purposes.

  Syntax

     [buffer :=] CREATE_BUFFER (string1 [, [string2] [, [buffer]
                               [, string3]]])

  Parameters

     string1    The name of the buffer you want to create.

     string2    Optionally, specifies the input file for the buffer.  If you
                do not specify an input file, you create an empty buffer.

     buffer     The buffer you want to use as a template for the buffer
                being created.  The new buffer has the same attributes (such
                as tabs, margins, etc.) as the template buffer.  For a list
                of all the attributes inherited by the new buffer, see the
                VSI Text Processing Utility Manual's description of the
                CREATE_BUFFER built-in.

     string3    The name of the journal file to be used with the buffer.
                Note that TPU does not copy the journal file name from
                the template buffer.  Instead, CREATE_BUFFER uses string3 as
                the new journal file name.  If you do not specify string3,
                TPU names the journal file using its journal file naming
                algorithm.  EVE turns on buffer-change journaling by default
                for each new buffer.  However, the CREATE_BUFFER built-in
                does not automatically turn on journaling; if you are
                layering directly on TPU, your application must use SET
                (JOURNALING) to turn journaling on.

  Comments

     If you want to skip an optional parameter and specify a subsequent
     optional parameter, you must use a comma as a placeholder for the
     skipped parameter.

  Examples

     1.  newb := CREATE_BUFFER ("new_buffer");

         Creates a buffer called "NEW_BUFFER" and stores a pointer to the
         buffer in the variable NEWB.

     2.  CREATE_BUFFER ("second_buffer", "login.com");

         Creates a buffer named "SECOND_BUFFER" and reads the file called
         "LOGIN.COM" into the buffer.

     3.  buf1 := CREATE_BUFFER ("scratch",,,"scratch_jl.jl");

         Creates a buffer named "SCRATCH" and directs TPU to name the
         associated buffer-change journal file "SCRATCH_JL.JL".  Note that
         you must use commas as placeholders for the two unspecified
         optional parameters.  Note, too, that by default TPU puts
         journal files in the directory defined by the logical name
         TPU$JOURNAL.  By default, TPU$JOURNAL points to the same directory
         that SYS$SCRATCH points to.  You can reassign TPU$JOURNAL to point
         to a different directory.

     4.  The following code fragment creates a template buffer called
         "DEFAULTS", changes the end-of-buffer text for the template buffer,
         and then creates a user buffer.  The user buffer is created with
         the same end-of-buffer text that the defaults buffer has.

            defaults_buffer := CREATE_BUFFER ("defaults");

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

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

  Related topics

     CREATE_WINDOW    DELETE           GET_INFO(BUFFER_VARIABLE)
     READ_FILE        SET(JOURNALING)  SHOW