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

    Places one or more elements or groups in the specified group or
    groups.

       Format:

          INSERT ELEMENT  element-expression group-expression "remark"

1 - Restrictions

    o  You cannot insert an element into a group that has read-only
       access.
    o  You cannot insert an element into a group if the element
       already belongs to the group.
    o  You cannot insert an element into a group in another library
       (the element and group must be in the same library).

2 - Command Parameters

 element-expression

    Specifies one or more elements to be inserted into the group.
    An element expression can be an element name, a group name, a
    wildcard expression, or a list of these separated by commas.

 group-expression

    Specifies one or more groups into which the element or elements is
    to be inserted. A group expression can be a group name, a wildcard
    expression, or a list of these separated by commas.

 remark

    Specifies a character string to be logged in the history file
    with this command, usually used to explain why the command was
    entered. The remark is enclosed in quotation marks. If no remark
    was entered, a null remark ("") is logged.

3 - Description

    The INSERT ELEMENT command places one or more elements or groups
    into one or more groups. The groups must already exist. When you
    use the INSERT ELEMENT command with a group name, you insert the
    contents of the group. For example, if you insert group A into
    group B by using the INSERT ELEMENT command, group B will contain
    the contents of group A at the time of the insertion transaction.
    If the contents of group A change at a later time, the contents of
    group B are not affected. To insert a group into another group,
    use the INSERT GROUP command.

4 - Qualifiers

 4.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.

 4.2 - /IF_ABSENT

    Directs CMS to insert the element only if the group does not
    already contain that element. If the element already belongs to
    the group, CMS takes no action and does not return an error.

 4.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.

 4.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.

5 - Examples

    (1) CMS> INSERT ELEMENT INIT.FOR TIME_TST "for time tests"
        %CMS-S-INSERTED, element DISKX:[PROJECT.CMSLIB]INIT.FOR
        inserted into DISKX:[PROJECT.CMSLIB]group TIME_TST

      This command inserts the element INIT.FOR into the group named
      TIME_TST.

    (2) CMS> INSERT ELEMENT DBAS EXAMPLES "more examples for book"
        %CMS-I-INSERTED, element DISKX:[PROJECT.CMSLIB]ARTFIG.CXS
        inserted into DISKX:[PROJECT.CMSLIB]group EXAMPLES
        %CMS-I-INSERTED, element DISKX:[PROJECT.CMSLIB]SNAKE.TXT
        inserted into DISKX:[PROJECT.CMSLIB]group EXAMPLES

      This command inserts the contents of group DBAS into group
      EXAMPLES.