Places one or more element generations in the specified class or
classes.
Format:
INSERT GENERATION element-expression class-expression "remark"
1 – Restrictions
o You cannot insert an element generation into a class that has
read-only access.
o A class can contain only one generation of any particular
element.
o You cannot insert a generation into a class in another library
(the generation and class must be in the same library).
2 – Command Parameters
element-expression
Specifies one or more elements whose generations are to be
inserted into the class. An element expression can be an element
name, a group name, a wildcard expression, or a list of these
separated by commas. By default, the most recent generation on the
main line of descent is inserted.
class-expression
Specifies an established class into which the element generation
is being placed. The class must not have the read-only attribute.
A class expression can be a class 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 GENERATION command places the specified element
generation into one or more classes. The class or classes must
already exist. (See the description of the CREATE CLASS command.)
A class can contain only one generation of an element. You
cannot insert any generations into a class that has the read-only
attribute. (See the description of the MODIFY CLASS command.)
4 – Qualifiers
4.1 /ALWAYS
Directs CMS to insert the element generation into the class in
all cases. If the class already contains a generation from the
specified element, that generation is removed before the new one
is inserted.
4.2 /BEFORE=date-time
Directs CMS to insert the element generation based on the
/GENERATION qualifier or the latest generation on the main line
of descent if there is no qualifier. The generation inserted is
the latest ancestor of the generation determined above that
pre-dates the specified time. If no generation pre-dates that
time (i.e. generation 1 is later) then no generation is inserted.
The time value can be an absolute, delta, or combination time
value, or one of the following keywords: TODAY, TOMORROW, or
YESTERDAY. If the time value is a future value, CMS uses the
current time. If no time value is supplied, CMS used TODAY.
4.3 /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.4 /GENERATION[=generation-expression]
Specifies a particular generation of the element that is to be
inserted into the class. If you omit /GENERATION, the INSERT
command uses the latest generation on the main line of descent.
4.5 /IF_ABSENT
Directs CMS to insert the element generation into the class only
if a generation of that element is not already in the class. If a
generation of the element is already in the class, CMS takes no
action and does not return an error.
4.6 /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.7 /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.
4.8 /SUPERSEDE
4.9 /NOSUPERSEDE (D)
Controls whether CMS removes a generation of the element that
exists in the class and replaces it with the specified generation.
(Using /SUPERSEDE is the equivalent of using the REMOVE command
before the INSERT command.)
If you specify /SUPERSEDE and there is no generation of the
specified element already in the class, an error message is
issued and the generation is not inserted into the class. You
cannot use the /IF_ABSENT qualifier on the same command line as
the /SUPERSEDE qualifier to override this action.
If you omit the /SUPERSEDE qualifier and a generation of the
element already exists in the class, an error message is issued
and no change is made to the library.
5 – Examples
(1) CMS> INSERT GENERATION INIT.FOR PRE_RELEASE_V3 "internal version"
%CMS-S-GENINSERTED, generation 2 of element
DISKX:[PROJECT.CMSLIB]INIT.FOR inserted into class
DISKX:[PROJECT.CMSLIB] PRE_RELEASE_V3
This command inserts the default generation of element INIT.FOR
into the class PRE_RELEASE_V3.
(2) CMS> INSERT GENERATION INIT.FOR,SPEC.TXT/GENERATION=3 -
_CMS> /IF_ABSENT/CONFIRM
_Class name: BASELEVEL_1 "inserting generation 3 for final baselevel
Insert generation 3 of element INIT.FOR into class BASELEVEL_1?
[Y/N] (N): Y
%CMS-I-GENINSERTED, generation 3 of element
DISKX:[PROJECT.CMSLIB]INIT.FOR inserted into class
DISKX:[PROJECT.CMSLIB]BASELEVEL_1
Insert generation 3 of element SPEC.TXT into class BASELEVEL_1?
[Y/N] (N): Y
%CMS-I-GENINSERTED, generation 3 of element
DISKX:[PROJECT.CMSLIB]SPEC.TXT inserted into class
DISKX:[PROJECT.CMSLIB]BASELEVEL_1
CMS-I-INSERTIONS, 2 insertions completed
This example inserts generation 3 of both elements INIT.FOR
and SPEC.TXT into the class BASELEVEL_1. The /IF_ABSENT
qualifier indicates that the generations should be inserted
only if they are not already present in the class. The /CONFIRM
qualifier directs CMS to prompt you for confirmation before
each insertion.