Description

   The REPLACE command transfers a file from your default directory
   to the current CMS library, thus creating a new generation. You
   can direct CMS to use a file other than the one located in your
   default directory by specifying the /INPUT qualifier. After the
   reserved generation is replaced, CMS deletes the file used to
   create the new generation (and any earlier versions of the file
   in the same directory). If you specify either the /KEEP or the
   /RESERVE qualifier, CMS does not delete the file. You cannot
   replace a reserved generation held by another user unless you hold
   BYPASS process privilege or unless you are granted BYPASS access
   to the element by an access control entry. After the replace 
   transaction is completed, the reservation is ended.

   By default, the number of the new generation is the number of
   its predecessor with the rightmost level number increased by 1.
   For example, if you reserved generation 1A1, CMS would create
   generation 1A2 when you replaced it. CMS also stores the creation
   date and time, the revision date and time, and the file revision
   number of the file used to create the new generation. When you
   fetch or reserve a generation of an element, CMS restores the
   times and file revision number associated with the file used
   to create the element generation. You can also display this
   information by using the SHOW GENERATION/FULL command.

   CMS reports an error if you attempt to create a generation that
   is already in the library (see the description of the /VARIANT
   qualifier).

   The REPLACE command checks for other current reservations and
   concurrent replacements of the element, and whether you are
   replacing another user's reservation. If any of these situations
   occur, CMS prompts whether you want to proceed with the command.
   If you type NO or press RETURN, the command is not executed. If
   you type YES, CMS executes the command and records the transaction
   as an unusual occurrence.

   If you have more than one reservation of an element, or if 
   you are replacing a concurrent reservation made by another user,
   (that is, if there is any ambiguity), you must specify the exact
   reservation to be replaced.  You do this by using either the 
   /GENERATION qualifier or the /IDENTIFICATON_NUMBER qualifier.

   You can use /GENERATION as long as the concurrent reservations are
   not on the same generation. If you have more than one concurrent
   reservation for the same generation, you must identify the
   specific reservation to be replaced. Each reservation is assigned
   an identification number. Use the SHOW RESERVATIONS command to
   determine the identification number of each reservation. The
   identification number appears in parentheses at the beginning
   of each line. If you use the /IDENTIFICATION_NUMBER qualifier, you
   do not need to also use the /GENERATION qualifier; when both are
   used, CMS ignores the /GENERATION qualifier.  

   If the reference copy attribute is enabled for an element and
   REPLACE creates the new generation on the main line of descent,
   CMS creates a new reference copy in the reference copy directory
   for the element and deletes the old copy from the reference copy
   directory.

   Replacing an Element with Defined Attributes

   If you reserve a generation of an element with an embedded history
   and then replace it, the REPLACE command ignores the history; that
   is, CMS does not copy the history into your CMS library. If you
   add text to the file in or above the history (relative to #B),
   or in or below the history (relative to #H), the REPLACE command
   issues an error message and the command is not executed.

   If you reserve a file with embedded notes and then replace it,
   the REPLACE command does not copy the notes to the CMS library.
   If, while editing the file, you insert text that looks like an
   embedded note, it is deleted when the file is replaced.