VMS Help CMS, COPY, ELEMENT  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    Copies one or more existing elements to form one or more new
    elements. If you copy an element to the same library, the new
    element must have a different name. The COPY ELEMENT transaction
    preserves all element attributes, data, and generation/variant
    information.

       Format:

          COPY ELEMENT  old-element-expression new-element-name "remark"

1 - Command Parameters

 old-element-expression

    Specifies one or more existing elements to be copied. If you
    specify more than one element to be copied, you must use a
    wildcard character for the new element name. An old element
    expression can be an element name, a group name, a wildcard
    expression, or a list of these separated by commas.

 new-element-name

    Specifies the name for the new element. The name cannot be the
    same as any existing element name in the target library. The file
    name component cannot be 00CMS because this name is reserved for
    CMS. Wildcards are allowed. If you specify more than one element
    with COPY ELEMENT, you must use a wildcard character for the new
    element name.

 remark

    Specifies a character string for the creation remark of the new
    element 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 old element is used for the creation
    remark of the new element, but a null remark ("") is logged in
    the history file.

2 - Description

    The COPY ELEMENT command uses an existing library element to
    copy and create a new element in the same library or in another
    library. The original element is left unchanged. The generation
    history, file characteristics, and element attributes are copied
    in full.

    If the existing element has the reference copy attribute enabled
    (that is, if it was created or modified with /REFERENCE_COPY),
    the reference copy attribute is also enabled for the new element
    (assuming the reference copy attribute is established for the
    library).

    If the existing element is reserved when you issue COPY ELEMENT,
    CMS informs you of the condition, then proceeds with the
    transaction. The new element is not reserved, regardless of
    whether the original element is reserved at the time of the copy
    transaction.

    If a generation of the element is marked pending review, CMS
    informs you of the condition, then asks whether you want to
    proceed. If you type YES, CMS records the transaction as an
    unusual occurrence and proceeds with the command. The new element
    is not marked as pending review, regardless of whether the
    original element is marked at the time of the copy. If you type NO
    or press RETURN, no further action is taken.

    CMS must be able to create one new element for each old element.
    When you use wildcards, a group name, or a comma list in the
    input element specification, CMS builds a list of elements to
    be copied. CMS uses this list as the point of reference during the
    copy transactions. If the output element specification does not
    allow CMS to create a new element for each element in the input
    list, the results may not be what you intend. For example, the
    following combination of wildcard expressions produces only one
    new element:

      input element specification -  *.FOR
      output element specification - NDATA.*

    The first element that matches the input specification (*.FOR)
    produces one new element named NDATA.FOR. Each successive element
    that matches the input specification generates an error message
    because CMS can create only one unique element name from the given
    combination of wildcard expressions.

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.

 3.2 - /LIBRARY[=directory-specification]

    Identifies a valid CMS library that is the location of the element
    specified by the old-element-expression parameter. When you
    specify an alternative library, the new-element-name parameter is
    optional. If you do not specify a value for /LIBRARY, the current
    CMS library is used.

 3.3 - /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.4 - /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)
       ELEMENT (D)
       NOELEMENT
       GROUP (D)
       NOGROUP
       NONE--equivalent to (NOELEMENT, NOGROUP)

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

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

4 - Examples

    (1) CMS> COPY ELEMENT INIT.FOR INITX.FOR "experimental version"
        %CMS-S-COPIED, element DISKX:[PROJECT.CMSLIB]INIT.FOR copied
        to INITX.FOR

      This command creates a new element named INITX.FOR in the same
      library as the old element.

    (2) $ CREATE/DIRECTORY [RELEASE.CMSLIB]
        $ CMS
        CMS> CREATE LIBRARY [RELEASE.CMSLIB] "follows development library"
        %CMS-S-CREATED, CMS Library DISKX:[RELEASE.CMSLIB] created

        CMS> COPY ELEMENT *.*/LIBRARY=[PROJECT.CMSLIB] *.* "loading
        elements"
        %CMS-I-COPIED, element DISKX:[PROJECT.CMSLIB]INIT.FOR copied to
        DISKX:[RELEASE.CMSLIB]INIT.FOR
        %CMS-I-COPIED, element DISKX:[PROJECT.CMSLIB]INITX.FOR copied to
        DISKX:[RELEASE.CMSLIB]INITX.FOR
        %CMS-I-COPIED, element DISKX:[PROJECT.CMSLIB]MSGDOC.FOR copied to
        DISKX:[RELEASE.CMSLIB]MSGDOC.FOR
        %CMS-I-COPIED, element DISKX:[PROJECT.CMSLIB]OUTPUT.FOR copied to
        DISKX:[RELEASE.CMSLIB]OUTPUT.FOR
        %CMS-I-COPIED, element DISKX:[PROJECT.CMSLIB]SEARCH.FOR copied to
        DISKX:[RELEASE.CMSLIB]SEARCH.FOR
        %CMS-I-COPIED, element DISKX:[PROJECT.CMSLIB]ARGCHK.FOR copied to
        DISKX:[RELEASE.CMSLIB]ARGCHK.FOR
        %CMS-S-COPIES, 6 copies completed

        CMS> SHOW HISTORY
        History of CMS Library DISKX:[RELEASE.CMSLIB]
          9-MAY-1988 11:23:43 SMITH CREATE LIBRARY DISKX:[RELEASE.CMSLIB]
                "follows development library"
          9-MAY-1988 11:26:00 SMITH COPY
                ELEMENT/LIBRARY=DISKX:[PROJECT.CMSLIB]
                INIT.FOR INIT.FOR "loading elements"
          9-MAY-1988 11:26:04 SMITH COPY
                ELEMENT/LIBRARY=DISKX:[PROJECT.CMSLIB]
                INITX.FOR INITX.FOR "loading elements"
          9-MAY-1988 11:26:07 SMITH COPY
                ELEMENT/LIBRARY=DISKX:[PROJECT.CMSLIB]
                MSGDOC.FOR MSGDOC.FOR "loading elements"
          9-MAY-1988 11:26:15 SMITH COPY
                ELEMENT/LIBRARY=DISKX:[PROJECT.CMSLIB]
                OUTPUT.FOR OUTPUT.FOR "loading elements"
          9-MAY-1988 11:26:17 SMITH COPY
                ELEMENT/LIBRARY=DISKX:[PROJECT.CMSLIB]
                SEARCH.FOR SEARCH.FOR "loading elements"
          9-MAY-1988 11:26:19 SMITH COPY
                ELEMENT/LIBRARY=DISKX:[PROJECT.CMSLIB]
                ARGCHK.FOR ARGCHK.FOR "loading elements"
        CMS> SHOW GENERATION/DESCENDANTS INIT.FOR
        Element generations in CMS Library DISKX:[RELEASE.CMSLIB]
        INIT.FOR
          2      6-MAR-1988 17:34:04 SMITH "header offset and additional
                     free space added"
          1      6-MAR-1988 17:26:10 SMITH "initialization routines"

      This example creates a new directory for a new library,
      and then copies all of the elements from the library
      [PROJECT.CMSLIB] into the new library [RELEASE.CMSLIB].
      Because the new elements are being created in a separate
      library, CMS can create new elements with the same names as
      the old elements; thus, a null string may be entered for the
      second parameter (for the new element name). In this case,
      CMS supplies the value *.*.

      The SHOW HISTORY command that is executed after the copy
      transaction indicates that the library history contains only
      records of transactions performed on the new library (CREATE
      LIBRARY and COPY transactions). The SHOW GENERATION/DESCENDANTS
      command shows the generation history for one of the elements.
      The COPY ELEMENT transaction preserves the generation history
      for each element; thus, the record of replacement transactions
      (also the CREATE ELEMENT transaction that produced generation 1
      of the element) is maintained from the old element to the new.