/sys$common/syshlp/helplib.hlb CMS, REPLACE, Description  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    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.