HELPLIB.HLB  —  CMS  REPLACE
    Returns each specified element reservation to the library and
    creates a new generation of the element.

       Format:

          REPLACE  element-expression "remark"

1  –  Command Parameters

 element-expression

    Specifies one or more reserved generations of an element to
    be replaced. An element expression can be an element name, a
    group name, a wildcard expression, or a list of these separated
    by commas. If you specify more than one element (with either a
    group name or a wildcard expression), each file indicated by the
    element expression must exist in the same directory. When you use
    wildcards, CMS creates an input element list based on the list of
    element generations that you have reserved.

 remark

    Specifies a character string to be associated with the newly
    created generations, to be logged in the history file with this
    command. The remark is enclosed in quotation marks. If no remark
    was entered, then the remark from the corresponding reservation is
    used for the new generation and the replacement transaction in the
    history file.

2  –  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.

3  –  Qualifiers

3.1    /CONFIRM

    Controls whether CMS prompts you for confirmation before each
    transaction.

    When you specify /CONFIRM and run CMS in interactive mode, CMS
    prompts you for confirmation. If you type YES, ALL, TRUE, or 1,
    CMS executes the transaction.  If you type NO, QUIT, FALSE, 0,
    or press RETURN or CTRL/Z, no action is performed. If you type
    any other character, CMS continues to prompt until you type an
    acceptable response.

    CMS does not prompt for confirmation in batch mode.

    The /NOCONFIRM qualifier does not override the confirmation prompt
    issued when you make a concurrent replacement or when you replace
    another user's reservation.

3.2    /GENERATION=generation-expression

    Specifies which reserved generation of the element is to be
    replaced. If you have more than one reservation of the same
    element generation, you must use the /IDENTIFICATION_NUMBER
    qualifier to replace the reservation.

3.3    /IDENTIFICATION_NUMBER=n

    Specifies which reservation is to be replaced. This qualifier
    is required when you have multiple reservations of the same
    generation of an element. This qualifier is also required
    when multiple users have reserved the same generation of an
    element and you have BYPASS privilege or have been granted
    BYPASS access to the element by an access control list entry.
    /IDENTIFICATION_NUMBER can be used instead of /GENERATION
    when you have multiple reservations. 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.

3.4    /IF_CHANGED

    Specifies that a new generation is to be created only if the
    input file is different from the generation that was reserved.
    If this qualifier is omitted, a new generation is always created.

3.5    /INPUT[=file-specification]

    Specifies a file to be used as input for the replacement
    transaction. If you use the /INPUT qualifier but you do not supply
    a file specification, CMS searches your current default directory
    for a file with the same name as the element specified on the
    command line. When you specify /INPUT, CMS deletes the input file
    from the specified location after the new generation is created
    (unless you specify the /KEEP or /RESERVE qualifier).

    CMS must be able to match the input element list with the list of
    elements indicated by the element expression parameter. Thus, if
    you use wildcards in the /INPUT file specification to generate
    more than one input file, you must also use wildcards in the
    element expression parameter.

3.6    /INSERT_INTO_CLASS=(class_expression)

    Specifies one or more classes into which newly created generations
    are to be inserted. The class expression can be a class name, a
    wildcard expression, or a list of these separated by commas. If a
    list is not used, the parentheses can be omitted.

    The new generation of each element replaced is inserted into the
    specified classes. If no new generation is created, no insertion
    takes place.

    This qualifier effectively combines the REPLACE and INSERT
    GENERATION commands. It ensures that the new generation is inserted
    into the specified class of classes, avoiding the potential problem
    of other users updating the library between a REPLACE command and a
    subsequent INSERT GENERATION command. It also deals effectively with
    variants.

    For each of the specified classes, provided there is INSERT access
    to the class and it is not set to READ_ONLY, new generations are
    always inserted, irrespective of whether or not the class already
    contains a generation of the element. Any old generation is removed
    from the class before the new generation is inserted. This is like
    using the /ALWAYS qualifier in an INSERT GENERATION command.

    If other insertion modes, for example /SUPERSEDE, are required,
    create a temporary class and use that in the REPLACE command. Then
    use the temporary class as the value of the /GENERATION qualifier in
    an INSERT GENERATION command with the required mode.

    The insert operation takes place in the library where the new
    generation was created, so class occlusion does not apply to
    classes specified in this qualifier (class occlusion applies to a
    class specified in the /GENERATION qualifier).

    Any actions specified in access control entries associated with the
    INSERT GENERATION command, or with the classes into which
    generations are inserted, will be executed after any actions
    associated with the REPLACE command or with elements being replaced.

    Use of this qualifier requires execute access to the INSERT
    GENERATION command.

3.7    /KEEP

    Controls whether the file used to create the new element
    generation is deleted from your directory. If you omit both /KEEP
    and /RESERVE, the files are deleted.

3.8    /LOG (D)

    Controls whether CMS displays success and informational messages
    on the default output device. By default, if the command executes
    successfully, CMS displays a success message. If you specify
    /NOLOG, success and informational messages are suppressed. Any
    warning, error, or fatal error messages are displayed regardless
    of whether /LOG or /NOLOG is specified.

3.9    /OCCLUDE[=option,...]

    Controls whether CMS selects the first instance of the specified
    object, or all instances of the specified object in the library
    search list. The options field contains one or more keywords
    associated with the name of the object. The options field can
    contain the following keywords:

       ALL--equivalent to (ELEMENT, GROUP, CLASS)
       ELEMENT (D)
       NOELEMENT
       GROUP (D)
       NOGROUP
       CLASS (D)
       NOCLASS
       NONE--equivalent to (NOELEMENT, NOGROUP, NOCLASS)

    You can specify either ALL or NONE, or any combination of the
    [NO]ELEMENT, [NO]GROUP, and [NO]CLASS keywords.

    By default, CMS performs occlusion for all objects; that is, CMS
    selects only the first occurrence of a specified object.

3.10    /RESERVE

    Controls whether the new generation of the element created by the
    replacement is reserved. If you specify the /RESERVE qualifier,
    the generation is reserved and the element files are not deleted
    from your current default directory. The list of concurrent
    replacements is updated as if /RESERVE had been omitted.

3.11    /VARIANT=variant-name

    Controls whether a variant generation is created. If you specify
    the /VARIANT=variant-name qualifier, the number of the created
    generation is the predecessor's number, followed by the variant
    name, followed by the number 1.

    The Variant Generation Names are limited to
    alphabetic characters (A through Z) and underscore
    characters with a maximum length of 255 characters.

    If two or more users have concurrently reserved the same element
    generation, the replaced generations cannot be on the same line of
    descent. Thus, one can be replaced as a main line generation and
    the rest must be replaced as variants.

4  –  Example

    CMS> REPLACE FILEIO.BLI
    _Remark: descriptor bug fixed
    %CMS-S-GENCREATED, generation 14 of element
    DISKX:[PROJECT.CMSLIB]FILEIO.BLI created

      This command creates a new generation on the main line of
      descent of element FILEIO.BLI.
Close Help