Code Management System for OpenVMS (CMS) is a library system
for software development and maintenance. CMS stores source
files in a library, keeps track of changes made to the files,
and records user access to the files.
If you have installed DECwindows on your system, you can also
use the CMS DECwindows interface (CMS Version 3.2 and higher).
See the /INTERFACE qualifier for information on invoking the
CMS DECwindows interface.
1 – Qualifiers
1.1 /INTERFACE[=interface]
Invokes CMS in either the character cell (terminal) or
DECwindows environment. You must have CMS installed on your
system. You can specify one of the following interfaces:
o CHARACTER_CELL
o DECWINDOWS
Specify the CHARACTER_CELL keyword to invoke CMS as a sub-
system in the command-line interface. Whether you type the
CMS command, the CMS/INTERFACE command, or the
CMS/INTERFACE=CHARACTER_CELL command, the default is to invoke
the CMS command-line interface.
Specify the DECWINDOWS keyword to invoke the CMS DECwindows
interface (CMS Version 3.2 or higher). You must have
DECwindows installed on your system. The DECwindows interface
is a graphical interface to CMS, and runs on a terminal or
terminal emulator on a DECwindows workstation.
2 – ACCEPT
2.1 – GENERATION
Changes the review status of each specified element generation
from "pending" to "accepted" and removes it from the review
pending list.
Format:
ACCEPT GENERATION element-expression "remark"
2.1.1 – Command Parameters
element-expression
Specifies one or more elements. An element expression can be an
element name, a group name, a wildcard expression, or a list of
these separated by commas.
remark
Specifies a 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.
2.1.2 – Description
The ACCEPT GENERATION command changes the review status of each
specified element generation from "pending" to "accepted" and
removes it from the review pending list.
Use this command only on element generations that have reviews
pending (see the description of the REVIEW GENERATION command for
more information). If you access the generation once it has been
accepted, CMS no longer informs you of any review status.
2.1.3 – Qualifiers
2.1.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.
2.1.3.2 /GENERATION[=generation-expression]
Specifies a particular generation of the element to be accepted.
If you omit /GENERATION, CMS accepts the most recently created
generation with a review pending. You specify this qualifier only
if more than one generation of an element is under review.
2.1.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.
2.1.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, 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.
2.1.4 – Example
CMS> ACCEPT GENERATION EXAMPLE.SDML "this example cleared for
publication"
%CMS-S-ACCEPTED, generation 3 of element
DISKX:[PROJECT.CMSLIB]EXAMPLE.SDML accepted
This command accepts the most recently created generation of
the element EXAMPLE.SDML. The generation is removed from the
review pending list.
3 – ANNOTATE
Creates an output file that contains an annotated listing of the
changes made to each specified element generation and places it
in your current default directory or a specified directory.
Format:
ANNOTATE element-expression
3.1 – Command Parameters
element-expression
Specifies one or more elements. 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 a group name, CMS
annotates each element in the group. If you use wildcards, CMS
produces one annotated listing file for each matching element. By
default, the most recent generation of an element on the main line
of descent is annotated.
3.2 – Description
The ANNOTATE command documents the development of an element. This
command creates an output file that contains an annotated listing;
by default, the file name is the same as the element name and the
file type is .ANN. The annotated listing file contains two parts:
o A history
o A source file listing
The history includes the generation number, date, time, user,
and remark associated with each generation of the element (and
other file-related information when you use the /FULL qualifier).
The generations are listed in reverse chronological order. The
generation numbers of the specified generation and its ancestors
are marked with an asterisk (*).
The source file listing contains all the lines inserted or
modified from generation 1 to the specified generation. The
listing does not show lines deleted from the file. CMS inserts
consecutive line numbers in the listing unless editor-assigned
line numbers already exist. (The line numbers start with 1 for the
first line and increase by 1 for each line.) The generation field
starts at the first character position of each line. It contains
the generation number of the most recent generation in which the
line was inserted or modified. The generation field is blank if a
line is unchanged since generation 1.
3.3 – Qualifiers
3.3.1 /APPEND
Controls whether CMS appends the history and source file listing
to an existing file, or creates a new file. If you specify /APPEND
and the output file does not exist, CMS creates a new file. If you
do not provide an output file specification (see the description
for /OUTPUT), CMS searches your default directory for a file with
the element file name and the file type .ANN.
3.3.2 /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.3.3 /FORMAT=(data-format,data-partition)
Controls whether the history and source file listing is formatted,
and specifies the type of formatting. You can specify one or both
formatting parameters in any order.
data-format
Specifies the type of format. Possible values for data formats
include: ASCII (Default), DECIMAL, HEXADECIMAL, and OCTAL.
data-partition
Specifies the type of data partition. Possible values for data
partitions include: BYTE, LONGWORD, RECORDS (Default), and WORD.
3.3.4 /FULL
Directs CMS to include the following information about the file
used to create each generation:
o Creation time
o Revision time
o Revision number
o Record format
o Record attributes
CMS also indicates deleted lines in the source listing. Each
set of one or more deleted lines is identified by a count of the
deleted lines.
3.3.5 /GENERATION[=generation-expression]
Specifies a particular generation of the element to be annotated.
If you omit /GENERATION, CMS annotates the most recent generation
on the main line of descent.
The history contains a description of every generation of the
element, including those created after the specified generation.
(Generations created after the specified generation are not marked
with an asterisk.)
3.3.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.
3.3.7 /MERGE=generation-expression
Combines two generations of an element and creates a single
file that contains the annotated listing. The parameter on the
/MERGE qualifier specifies the generation that is merged into the
retrieved generation. This command creates a file that contains
the text common to both generations and the changes made to both
generations. When changes that are not identical are made in
the same position of the common ancestor, the changes from both
generations are included in the resulting file and are marked as a
conflict. By default, generations are not merged.
3.3.8 /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.3.9 /OUTPUT[=file-specification]
Directs CMS to write output to the specified file. CMS creates a
new file if you do not specify /APPEND. If you omit the /OUTPUT
qualifier (or if you specify /OUTPUT but do not provide a file
specification), CMS creates a file with the element file name and
the file type .ANN. Wildcards are allowed.
If you annotate more than one element (by specifying wildcards or
a group name for the element expression parameter), and you do not
specify wildcards in the output file specification, CMS creates
successive versions of the file indicated by /OUTPUT.
3.4 – Example
CMS> ANNOTATE TIMECVT.BAS/GENERATION=3
%CMS-S-ANNOTATED, element DISKX:[WORK.CMSLIB]TIMECVT.BAS annotated
This command produces a file named TIMECVT.ANN, which contains
the annotated listing of generation 3 of TIMECVT.BAS. The
contents of TIMECVT.ANN are as follows:
Annotated listing for element TIMECVT.BAS in CMS Library
DISKX:[WORK.CMSLIB] 25-APR-1988 15:50:29
4 15-APR-1988 10:01:55 JAMES "additional error checks"
*3 12-APR-1988 15:49:01 JAMES "add check for invalid delta time"
*2 27-MAR-1988 12:39:58 JAMES "jp - fixed length string required"
*1 25-MAR-1988 15:37:11 JAMES "time conversion program"
Annotated listing for element TIMECVT.BAS in CMS Library
DISKX:[WORK.CMSLIB] 25-APR-1988 15:50:29
1 10 rem Program to compute an absolute time given the
present time
2 rem and a delta time. The result is written to a file.
3
4 20 OPTION TYPE = EXPLICIT
5 DECLARE STRING DELTA_TIME
2 6 MAP (STRING_LEN) STRING ASC_TIME = 80
7 DECLARE LONG RETCODE
8 DIM LONG BINARY_DELTA(1)
9 DIM LONG NOW(1)
10 DIM LONG BINARY_CVT_TIME(1)
11
12 100 EXTERNAL LONG CONSTANT SS$_NORMAL
3 13 EXTERNAL LONG CONSTANT SS$_IVTIME
14 EXTERNAL LONG FUNCTION LIB$ADDX
15 EXTERNAL LONG FUNCTION LIB$SUBX
16 EXTERNAL LONG FUNCTION LIB$INT_OVER
17 EXTERNAL INTEGER FUNCTION SYS$BINTIM (STRING
BY DESC, LONG BY REF)
18 EXTERNAL INTEGER FUNCTION SYS$GETTIM (LONG
BY REF)
19 EXTERNAL INTEGER FUNCTION SYS$ASCTIM (LONG
BY REF, STRING BY DESC, &
20 LONG BY REF,
LONG BY REF)
21 150 LET RETCODE = LIB$INT_OVER(0)
22 PRINT "Input delta time"
23 INPUT DELTA_TIME
24 LET RETCODE = SYS$BINTIM ( DELTA_TIME,
BINARY_DELTA(0) )
3 25 175 IF (RETCODE = SS$_NORMAL) THEN GOTO 200
3 26 ELSE IF RETCODE = SS$_IVTIME THEN &
3 27 PRINT ,"INVALID TIME"
3 28 GOTO DONE
3 29 END IF
3 30 END IF
3 31 200 LET retcode = SYS$GETTIM(NOW(0))
3 32 IF (VAL( DELTA_TIME ) > 0 ) THEN &
33 retcode=LIB$ADDX(NOW(0),BINARY_DELTA (0) ,
BINARY_CVT_TIME(0))
34 END IF
35 LET retcode = SYS$ASCTIM(,ASC_TIME,BINARY_
CVT_TIME(0),)
36 OPEN "TIME.TMP" FOR OUTPUT AS FILE #1
37 PRINT #1,ASC_TIME
38 CLOSE #1
39 32767 Done: END
40
The element's history appears at the beginning of the
file TIMECVT.ANN. The history lists the records of the
transactions that created each of the four generations.
However, because the third generation was annotated (ANNOTATE
TIMECVT.BAS/GENERATION=3), changes made after generation 3
are not shown in the annotated listing. Generation 3 and its
ancestors are marked with an asterisk in the history.
The source file listing shows each line of the file, including
line numbers. The numbers farthest to the left are the
generation numbers in which the line was most recently inserted
or modified; the lines with no generation numbers have not
changed since generation 1. The next column of numbers is
assigned by CMS. The third column of numbers is included in
the program itself.
4 – CANCEL
4.1 – REVIEW
The CANCEL REVIEW command changes the review status of each
specified element generation from "pending" to "none" and removes
it from the review pending list.
Format:
CANCEL REVIEW element-expression "remark"
4.1.1 – Command Parameters
element-expression
Specifies one or more elements. An element expression can be an
element name, a group name, a wildcard expression, or a list of
these separated by commas.
remark
Specifies a 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.
4.1.2 – Description
The CANCEL REVIEW command changes the review status of each
specified element generation from "pending" to "none" and removes
it from the review pending list.
Use this command only on element generations that have reviews
pending (see the description of the REVIEW GENERATION command for
more information).
4.1.3 – Qualifiers
4.1.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.
4.1.3.2 /GENERATION[=generation-expression]
Specifies which generation of the element is to have its review
pending status canceled. If you omit /GENERATION, CMS cancels
the review of the most recently created generation with a
review pending. You specify this qualifier only if more than one
generation of an element is under review.
4.1.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.
4.1.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, 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.1.4 – Example
$ CMS CANCEL REVIEW EXAMPLE.SDML "review the final version only"
%CMS-S-CANCELED, review of generation 2 of element
DISKX:[PROJECT.CMSLIB]EXAMPLE.SDML canceled
This command cancels the review of the element EXAMPLE.SDML,
and removes it from the review pending list.
5 – CONVERT
5.1 – LIBRARY
Converts libraries that were created with Version 2.n of CMS for
use with Version 3.n of CMS.
Format:
CONVERT LIBRARY V2-library-directory-specification
V3-library-directory-specification
5.1.1 – Command Parameters
V2-library-directory-specification
Specifies the directory specification of the existing CMS library
you want to convert.
V3-library-directory-specification
Specifies the directory specification of the new CMS library you
want to create. This directory must be empty.
5.1.2 – Description
The CONVERT LIBRARY command creates a copy of an existing CMS
library and converts the copy for use with this version of
CMS. Libraries created with CMS Version 3.0 do not need to be
converted.
To convert a library, you must first create an empty directory
to contain the new, converted library. Conversion maintains
everything in your existing library, including the reference
copy directory. After the library is converted, CMS automatically
executes the VERIFY/REPAIR command to ensure that any existing
reference copy directory is valid and current.
The CONVERT LIBRARY command causes an unusual occurrence to be
logged in the history file.
5.1.3 – Example
$ CREATE/DIRECTORY [PROJECT.CMSLIB_V3]
$ CMS
CMS> CONVERT LIBRARY
_V2 library: [PROJECT.CMSLIB_V2]
_Directory for V3 library: [PROJECT.CMSLIB_V3]
%CMS-S-CREATED, CMS Library DISKX:[PROJECT.CMSLIB_V3] created
%CMS-I-LIBINSLIS, Library DISKX:[PROJECT.CMSLIB_
V3] inserted into the library list
%CMS-I-CONELE, element DATAPROG.BAS converted
%CMS-I-CONGRP, group TESTGRP converted
%CMS-I-CONCLS, class ETMETAL converted
%CMS-I-CONRES, all reservations converted
%CMS-I-CONHIS, history file converted
%CMS-S-CONVERTED, Version 2 library converted to Version 3 format
%CMS-I-VERCLS, class list verified
%CMS-I-VERCMD, command list verified
%CMS-I-VERELE, element list verified
%CMS-I-VERGRP, group list verified
%CMS-I-VERRES, reservation list verified
%CMS-I-VERFRE, internal free space list verified
%CMS-I-VERFRE, internal free space list verified
%CMS-I-VERFRE, internal free space list verified
%CMS-I-VERFRE, internal free space list verified
%CMS-I-VERFRE, internal free space list verified
%CMS-I-VERFRE, internal free space list verified
%CMS-I-VERFRE, internal free space list verified
%CMS-I-VERARC, archive control block verified
%CMS-I-VER2, internal contiguous space verified
%CMS-I-VERCON, control file verified
%CMS-I-VEREDF, element DATAPROG.BAS verified
%CMS-I-VEREDFS, element data files verified
%CMS-I-REPAIRED, library [PROJECT.CMSLIB_V3] repaired
This example first creates a new directory to contain the
converted library, and then converts the old library.
CMS automatically issues VERIFY/REPAIR to ensure that both
the library and any reference copies are valid. If there are
invalid reference copies, VERIFY/REPAIR repairs them. Even
if you receive reference copy errors, your library is still
converted and available for use.
6 – COPY
6.1 – CLASS
Copies one or more existing classes to form one or more new
classes. If you copy a class to the same library, the new
class must have a different name. The COPY CLASS transaction
preserves all class attributes and inserts element generations
that belong to each input class. The elements to be inserted
into the new class must already exist in the target library.
Format:
COPY CLASS old-class-expression new-class-name "remark"
6.1.1 – Command Parameters
old-class-expression
Specifies one or more existing classes to be copied. If you
specify more than one class to be copied, you must use a
wildcard character for the new class name. An old class
expression can be a class name, a wildcard expression, or a
list of these separated by commas.
new-class-name
Specifies the name for the new class. The name cannot be the
same as any existing class name in the target library. Wildcards
are allowed. If you specify more than one class with COPY CLASS,
you must use a wildcard character for the new class name.
remark
Specifies a character string for the creation remark of the new
class 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 class is used for the creation
remark of the new class, but a null remark ("") is logged in
the history file.
6.1.2 – Description
The COPY CLASS command uses an existing library class to copy
and create a new class in the same library or in another library.
The original class is left unchanged. The class attributes are
copied in full and an identical set of element generations are
inserted into the new class. The elements to be inserted into
the new class must already exist in the target library.
CMS must be able to create one new class for each old class.
When you use wildcards, or a comma list in the input class
specification you must specify a wildcard ("*") as the output
class specification.
6.1.3 – Qualifiers
6.1.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.
6.1.3.2 /LIBRARY[=directory-specification]
Identifies a valid CMS library that is the location of the class
specified by the old-class-expression parameter. When you
specify an alternative library, the new-class-name parameter is
optional. If you do not specify a value for /LIBRARY, the current
CMS library is used.
6.1.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.
6.1.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 CLASS
CLASS (D)
NOCLASS
NONE--equivalent to CLASS
You can specify either ALL, NONE, or the [NO]CLASS keyword.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object.
6.1.4 – Example
CMS> COPY CLASS INIT_CLASS INITX_CLASS "experimental version"
%CMS-S-COPIED, class DISKX:[PROJECT.CMSLIB]INIT_CLASS copied
to INITX_CLASS
This command creates a new class named INITX_CLASS in the same
library as the old class.
6.2 – ELEMENT
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"
6.2.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.
6.2.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.
6.2.3 – Qualifiers
6.2.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.
6.2.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.
6.2.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.
6.2.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.
6.2.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.
6.3 – GROUP
Copies one or more existing groups to form one or more new
groups. If you copy a group to the same library, the new
group must have a different name. The COPY GROUP transaction
preserves all group attributes and inserts elements and groups
that belong to each input group. The elements to be inserted
into the new group must already exist in the target library.
Format:
COPY GROUP old-group-expression new-group-name "remark"
6.3.1 – Command Parameters
old-group-expression
Specifies one or more existing groups to be copied. If you
specify more than one group to be copied, you must use a
wildcard character for the new group name. An old group
expression can be a group name, a wildcard expression, or a
list of these separated by commas.
new-group-name
Specifies the name for the new group. The name cannot be the
same as any existing group name in the target library. Wildcards
are allowed. If you specify more than one group with COPY GROUP,
you must use a wildcard character for the new group name.
remark
Specifies a character string for the creation remark of the new
group 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 group is used for the creation
remark of the new group, but a null remark ("") is logged in
the history file.
6.3.2 – Description
The COPY GROUP command uses an existing library group to copy
and create a new group in the same library or in another library.
The original group is left unchanged. The group attributes are
copied in full and an identical set of elements and groups are
inserted into the new group. The elements to be inserted into
the new group must already exist in the target library.
CMS must be able to create one new group for each old group.
When you use wildcards, or a comma list in the input group
specification you must specify a wildcard ("*") as the output
group specification.
6.3.3 – Qualifiers
6.3.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.
6.3.3.2 /LIBRARY[=directory-specification]
Identifies a valid CMS library that is the location of the group
specified by the old-group-expression parameter. When you
specify an alternative library, the new-group-name parameter is
optional. If you do not specify a value for /LIBRARY, the current
CMS library is used.
6.3.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.
6.3.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 GROUP
GROUP (D)
NOGROUP
NONE--equivalent to GROUP
You can specify either ALL, NONE, or the [NO]GROUP keyword.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object.
6.3.4 – Example
CMS> COPY GROUP INIT_GROUP INITX_GROUP "experimental version"
%CMS-S-COPIED, class DISKX:[PROJECT.CMSLIB]INIT_GROUP copied
to INITX_GROUP
This command creates a new group named INITX_GROUP in the same
library as the old group.
7 – CREATE
7.1 – CLASS
Creates one or more empty classes.
Format:
CREATE CLASS class-name[,...] "remark"
7.1.1 – Command Parameters
class-name
Specifies a name for the class. CMS reports an error if you
specify a name that is already used for an existing class or
group. (Class and group names must be unique.) If a previously
used class or group name has been removed with the DELETE CLASS or
DELETE GROUP command, you can reuse that name with CREATE CLASS. A
class name can also be a list of class names separated by commas.
Wildcards are not allowed.
remark
Specifies a character string for the creation remark of the class
to be logged in the history file with this command. The remark
is enclosed in quotation marks. If no remark was entered, a null
remark ("") is logged.
7.1.2 – Description
The CREATE CLASS command establishes a class. After a class is
created, you can place any related set of element generations
in that class by using the INSERT GENERATION command. The CREATE
CLASS command does not automatically place any generations in the
created class.
7.1.3 – Qualifiers
7.1.3.1 /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.
7.1.3.2 /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 CLASS
CLASS (D)
NOCLASS
NONE--equivalent to NOCLASS
You can specify either ALL, NONE, or the [NO]CLASS keyword.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object. If you
specify /OCCLUDE=NOCLASS, CMS creates a class in every library in
the search list.
7.1.4 – Examples
(1) CMS> CREATE CLASS INTERNAL_RELEASE "for internal use only"
%CMS-S-CREATED, class DISKX:[PROJECT.CMSLIB]INTERNAL_RELEASE created
This command creates a class named INTERNAL_RELEASE. Once the
class name is established, element generations can be placed in
the class with the INSERT GENERATION command.
(2) CMS> CREATE CLASS FTEST1,FTEST2,V1 "for external release"
%CMS-I-CREATED, class DISKX:[PROJECT.CMSLIB]FTEST1 created
%CMS-I-CREATED, class DISKX:[PROJECT.CMSLIB]FTEST2 created
%CMS-I-CREATED, class DISKX:[PROJECT.CMSLIB]V1 created
%CMS-S-CREATES, 3 creations completed
This command creates the three classes FTEST1, FTEST2, and V1.
7.2 – ELEMENT
Creates one or more new elements in a CMS library from an existing
file.
Format:
CREATE ELEMENT element-expression "remark"
7.2.1 – Restrictions
o If you specify the /NOTES qualifier, you must also specify the
/POSITION qualifier on the same command line.
7.2.2 – Command Parameters
element-expression
Specifies one or more elements to be created. If you do not
specify the /INPUT qualifier (or if you specify /INPUT without
a value), the element name must correspond to an existing file
in your current default directory. The name cannot be the same as
any existing element name in the library. Do not use the file name
00CMS because this name is reserved for library control files.
Generation 1 of the new element is created. An element expression
can also be a list of element names separated by commas, or a
wildcard expression.
remark
Specifies a character string for the creation remark of the
element to be logged in the history file with this command. The
remark is stored with both the element and its first generation.
The remark is enclosed in quotation marks. If no remark was
entered, a null remark ("") is logged.
7.2.3 – Description
The CREATE ELEMENT command creates the first generation of a new
element by moving the input file into a CMS library. By default,
CMS searches for the file in your current default directory.
You can direct CMS to use a file in a different directory by
specifying the /INPUT qualifier. After the element is created, CMS
deletes all versions of the file used to create the new element.
If you specify either the /KEEP or /RESERVE qualifiers, CMS does
not delete the file.
When you create an element, you can also define the history,
concurrent, notes, position, reference copy, and review attributes
for the element or establish a reservation.
CMS stores the creation date and time, the revision date and time,
file attributes, and the file revision number of the file used to
create generation 1 of the new element. When you fetch or reserve
a generation of an element, CMS restores the times, attributes,
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.
To change the creation remark associated with the element or
generation 1 of the element, use the MODIFY ELEMENT or MODIFY
GENERATION command, respectively.
7.2.4 – Qualifiers
7.2.4.1 /CONCURRENT (D)
Specifies whether this element can have multiple reservations.
After you have created the element, you grant or deny concurrent
access by using the MODIFY ELEMENT command.
7.2.4.2 /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.
7.2.4.3 /HISTORY="string"
Establishes the history attribute for the element. If an element
has the history attribute, its history is included in the file
when you retrieve it with the FETCH or RESERVE command.
The quoted string specifies the format of the history. The quoted
string must contain the characters #H or #B (lowercase is allowed)
and can contain other printing characters. To include a quotation
mark in the output history string, type it twice (""). To include
a number sign (#) in the output history string, type it twice
(##).
7.2.4.4 /INPUT[=file-specification]
Specifies the file to be used to create the element. When you
specify an alternative location for the input file, CMS deletes
the file from the alternative location (unless you specify /KEEP
or /RESERVE). If you do not specify this qualifier, CMS searches
your current default directory for a file with the same name as
specified with the element expression parameter on the command
line. Wildcards are allowed.
CMS must be able to create a unique element for each file in the
input file list. Thus, if you use wildcards in the /INPUT file
specification to specify more than one input file, you must also
use wildcards in the element-name parameter.
7.2.4.5 /KEEP
Controls whether CMS deletes all versions of the file used to
create the new element. If you specify /KEEP, CMS does not delete
the file.
7.2.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.
7.2.4.7 /NOTES="string"
Establishes the notes attribute for the element. If an element has
the notes attribute, notes are appended to the lines of the file
when it is retrieved by the FETCH or RESERVE command.
The quoted string specifies the format of the note. The quoted
string can contain text or the characters #G (or #g), or both. If
you specify /NOTES, you must also specify /POSITION.
7.2.4.8 /POSITION=n
Establishes the position attribute; that is, the character
position where the note generated by the /NOTES qualifier begins
on the line. The value n is required and must be an integer in
the range 1 to 511. The /NOTES qualifier is required with the
/POSITION qualifier.
The note is placed to the right of the text of the line. If the
length of the line is less than n, the note appears at position n.
If the length of the line is greater than or equal to n, the note
is placed at the next tab stop after the end of the line. (Tab
stops are at position 9 and every eight characters thereafter.)
7.2.4.9 /REFERENCE_COPY
7.2.4.10 /NOREFERENCE_COPY
Controls whether CMS maintains a reference copy of the element.
You must have established a reference copy directory.
The presence of the reference copy attribute for an element is
inherited from the library, that is, if a reference copy directory
is established for the library, by default, the attribute is
enabled for the element. You can override the reference copy
attribute by specifying /NOREFERENCE_COPY.
If a reference copy directory has been established for the CMS
library, CMS creates a reference copy of the new element and
updates the reference copy directory each time you create a new
main line generation of that element. When CMS places a file in
the reference copy directory, it also deletes any earlier versions
of that file in the reference copy directory.
7.2.4.11 /RESERVE
Controls whether the new element is to be reserved after it is
created. When you specify /RESERVE, CMS does not delete the file
used to create the element. Generation 1 of the newly created
element is automatically reserved.
If you omit both the /RESERVE and the /KEEP qualifiers, CMS
deletes all versions of the file used to create the element.
7.2.4.12 /REVIEW
Specifies that new generations of the element are marked for
review. By default, new generations of the element are marked
for review only if the reserved generation was either rejected
or has a review pending. If you specify CREATE ELEMENT/REVIEW,
generation 1 of the element is also marked for review.
You can change the review attribute with the MODIFY ELEMENT
command.
7.2.4.13 /BINARY
Controls whether CMS has to create an element of type binary
or text. When you specify this qualifier, CMS creates the element
in binary format irrespective of file properties.
If you do not specify this qualifier, CMS decides on its own
whether to create binary element or text element depending on
file properties.
7.2.5 – Example
CMS> CREATE ELEMENT INIT.FOR "initialization routines"
%CMS-S-CREATED, element DISKX:[PROJECT.CMSLIB]INIT.FOR created
This command creates an element named INIT.FOR from a file
with the same name in the current default directory, and
then deletes all versions of that file in the current default
directory.
7.3 – GROUP
Creates one or more empty groups.
Format:
CREATE GROUP group-name[,...] "remark"
7.3.1 – Command Parameters
group-name
Specifies a name for the group. CMS reports an error if you
specify an existing group or class name. (Group and class names
must be unique.) However, if a previously used group or class name
has been removed with the DELETE GROUP or DELETE CLASS command,
you can reuse that name with CREATE GROUP. A group name can also
be a list of group names separated by commas. Wildcards are not
allowed.
remark
Specifies a character string for the creation remark of the group
to be logged in the history file with this command. The remark
is enclosed in quotation marks. If no remark was entered, a null
remark ("") is logged.
7.3.2 – Description
The CREATE GROUP command establishes a group. After a group is
created, you can place any related set of elements or groups in
that group by using the INSERT ELEMENT or INSERT GROUP command.
The CREATE GROUP command does not automatically place any elements
or groups in the created group.
7.3.3 – Qualifiers
7.3.3.1 /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.
7.3.3.2 /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 GROUP
GROUP (D)
NOGROUP
NONE--equivalent to NOGROUP
You can specify either ALL, NONE, or the [NO]GROUP keyword.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object. If you
specify /OCCLUDE=NOGROUP, CMS creates a group in every library in
the search list.
7.3.4 – Example
CMS> CREATE GROUP TIME_TST "files for time tests"
%CMS-S-CREATED, group DISKX:[PROJECT.CMSLIB]TIME_TST created
This command creates a group named TIME_TST. Once the group
name is established, elements can be placed in the group with
the INSERT ELEMENT command.
7.4 – LIBRARY
Creates one or more new CMS libraries in one or more existing
empty directories. You can have only one CMS library in each
directory.
Format:
CREATE LIBRARY directory-specification[,...] "remark"
7.4.1 – Restrictions
o You cannot specify both the /AFTER and the /BEFORE qualifiers
on the same command line.
7.4.2 – Command Parameters
directory-specification
Specifies one or more valid OpenVMS directories. Each directory must
not contain any files. A directory that is to be used as a CMS
library cannot be your current default directory. If you specify
more than one OpenVMS directory, you must separate the directory
specifications with commas. Wildcards are not allowed.
remark
Specifies a character string for the creation remark of the new
library to be logged in the history file with this command. The
remark is enclosed in quotation marks. If no remark was entered, a
null remark ("") is logged in the history file.
7.4.3 – Description
The CREATE LIBRARY command builds CMS control files in a
directory so that it can be used as a CMS library. After you have
established a library with the CREATE LIBRARY command, you can
issue CMS commands to manipulate the library. When you issue the
CREATE LIBRARY command, your current CMS library is automatically
set to the library or libraries specified. You can use CREATE
LIBRARY only once on a library.
You can create more than one library at a time by specifying the
CREATE LIBRARY command with more than one directory specification.
The directory specifications must be separated by commas.
When you execute this command, CMS defines a logical name that
begins with CMS$. These names are used by subsequent CMS commands.
You should not define logical names beginning with CMS$ because
this prefix is reserved for use by CMS.
7.4.4 – Qualifiers
7.4.4.1 /AFTER[=directory-specification]
Instructs CMS to insert new libraries into the existing library
search list immediately following the existing specified
directory. The specified directory must be in the existing
library search list. If you omit the directory specification,
CMS automatically adds the libraries (in the order you specify) to
the end of the list. You cannot specify both /AFTER and /BEFORE on
the same command line. If neither /AFTER or /BEFORE is specified,
the CREATE LIBRARY command's library list supersedes any existing
search list.
7.4.4.2 /BEFORE[=directory-specification]
Instructs CMS to insert new libraries into the existing library
search list immediately in front of the existing specified
directory. The specified directory must be in the existing
library search list. If you omit the directory specification, CMS
automatically adds the libraries (in the order you specify) to the
front of the list. You cannot specify both /AFTER and /BEFORE on
the same command line. If neither /AFTER nor /BEFORE is specified,
the CREATE LIBRARY command's library list supersedes any existing
search list.
7.4.4.3 /CONCURRENT (D)
Specifies whether elements in a library can have multiple
reservations by setting the concurrent attribute on the library.
Use /NOCONCURRENT to disallow multiple reservations.
Use MODIFY LIBRARY to change this attribute on an existing library.
7.4.4.4 /CREATE_DIRECTORY
Instructs CMS to create a directory to contain the library if the
directory does not already exist. /NOCREATE_DIRECTORY is the default.
7.4.4.5 /EXTENDED_FILENAMES
Used to create a CMS library that allows the use of extended file
names. This qualifier is only available on OpenVMS V7.2 and later.
Use /NOEXTENDED_FILENAMES to create a CMS library that does not allow
the use of extended file names. /NOEXTENDED_FILENAMES is the default.
Use MODIFY LIBRARY to change this attribute on an existing library.
7.4.4.6 /KEEP
Instructs CMS to not delete all versions of a file used to create
a new element or generation. /NOKEEP is the default.
Use MODIFY LIBRARY to change this attribute on an existing library.
7.4.4.7 /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.
Use MODIFY LIBRARY to change this attribute on an existing library.
7.4.4.8 /LONG_VARIANT_NAMES
Used to create a CMS library that allows the use of long variant names.
Use /NOLONG_VARIANT_NAMES to create a CMS library that does not allow
the use of long variant names. /NOLONG_VARIANT_NAMES is the default.
Use MODIFY LIBRARY to change this attribute on an existing library.
7.4.4.9 /REFERENCE_COPY=directory-specification
Specifies a valid OpenVMS directory to be used for reference copies
of library elements. The directory cannot be a CMS library, nor
should it be a subdirectory of a CMS library directory. If you use
the CREATE LIBRARY command to create a search list of more than
one library, you should specify a reference copy directory for
each library in the search list. If you specify only one reference
copy directory for more than one library, CMS creates one library
for the entire search list, not one library for each library in
the search list. Wildcards are not allowed.
/NOREFERENCE_COPY is the default.
Use MODIFY LIBRARY to change this attribute on an existing library.
7.4.4.10 /REVISION_TIME[=option]
Controls whether CMS uses the original file revision time or the
file storage time when a file is retrieved from the CMS library.
The options field can contain of the following keywords:
ORIGINAL (D)
STORAGE_TIME
Use the ORIGINAL keyword to indicate that the original revision
time of files placed in a CMS library should be restored unchanged
upon their retrieval. This is the default behavior.
Use the STORAGE-TIME keyword to indicate that the time when a file
was stored in a CMS library (through a CREATE ELEMENT or REPLACE
transaction) should be substituted for its original revision time
upon retrieval.
Use MODIFY LIBRARY to change this attribute on an existing library.
7.4.5 – Examples
(1) CMS> CREATE LIBRARY [RELEASE.CMSLIB] "follows development library"
%CMS-S-CREATED, CMS Library DISKX:[RELEASE.CMSLIB] created
This command creates a CMS library in the subdirectory
[RELEASE.CMSLIB]. The library does not contain any elements
yet. Subsequent CMS commands refer to the library contained
in [RELEASE.CMSLIB] until the user logs out or issues a SET
LIBRARY or another CREATE LIBRARY command.
(2) CMS> CREATE LIBRARY [DOC.PRE.CMSLIB],[DOC.TESTA.CMSLIB],
[DOC.FNL.CMSLIB] "creating doc lib"
This example creates three CMS libraries in the subdirectories
[DOC.PRE.CMSLIB], [DOC.TESTA.CMSLIB], and [DOC.FNL.CMSLIB], and
sets the library search list to the three libraries, in that
order.
8 – DELETE
8.1 – CLASS
Deletes one or more classes from a CMS library.
Format:
DELETE CLASS class-expression "remark"
8.1.1 – Restrictions
o You cannot delete a class that contains any element
generations unless you specify the /REMOVE_CONTENTS
qualifier.
o You cannot delete a class that has read-only access. (Use the
MODIFY CLASS/NOREAD_ONLY command to change the access to the
class.)
8.1.2 – Command Parameters
class-expression
Specifies the class or classes to be deleted from the CMS library.
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.
8.1.3 – Description
The DELETE CLASS command deletes one or more classes from a CMS
library. The class must exist and must not contain any element
generations unless the /REMOVE_CONTENTS qualifier is specified.
If the /REMOVE_CONTENTS qualifier is not specified and any
generations belong to the class, CMS issues an error message and
does not delete the class. If the /REMOVE_CONTENTS qualifier is
not specified, use the REMOVE GENERATION command to remove element
generations from a class before issuing the DELETE CLASS command.
Even though a class is deleted, records of transactions that
created and used the class are retained in the library history.
You can reuse the deleted class name to create a new class.
However, there is no distinction between the two classes in the
project history, except that their transactions are separated by
entries for DELETE CLASS and CREATE CLASS commands.
To determine which generations belong to a class, use the SHOW
CLASS command with the /CONTENTS qualifier.
8.1.4 – Qualifiers
8.1.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.
8.1.4.2 /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.
8.1.4.3 /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 CLASS
CLASS (D)
NOCLASS
NONE--equivalent to NOCLASS
You can specify either ALL, NONE, or the [NO]CLASS keyword.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object.
8.1.4.4 /REMOVE_CONTENTS
Controls whether CMS removes generations of elements from the
specified class prior to deleting the class. When /REMOVE_CONTENTS
is specified CMS displays an informational message for each element
generation that is removed from the class.
8.1.5 – Examples
(1) CMS> DELETE CLASS PRE_RELEASE "no longer necessary"
%CMS-S-DELETED, class DISKX:[PROJECT.CMSLIB]PRE_RELEASE deleted
This command deletes the class named PRE_RELEASE.
(2) CMS> REMOVE GENERATION *.* BETA*
_Remark: beta sites converted to released product
%CMS-I-GENREMOVED, generation 3 of element
DISKX:[PROJECT.CMSLIB]INI.FOR removed from class
DISKX:[PROJECT.CMSLIB]BETAFEB
%CMS-I-GENREMOVED, generation 4 of element
DISKX:[PROJECT.CMSLIB]SRC.FOR removed from class
DISKX:[PROJECT.CMSLIB]BETAFEB
%CMS-I-GENREMOVED, generation 3 of element
DISKX:[PROJECT.CMSLIB]INI.FOR removed from class
DISKX:[PROJECT.CMSLIB]BETAJAN
%CMS-I-GENREMOVED, generation 2 of element
DISKX:[PROJECT.CMSLIB]SRC.FOR removed from class
DISKX:[PROJECT.CMSLIB]BETAJAN
%CMS-S-REMOVALS, 4 removals completed
CMS> DELETE CLASS BETA* "beta sites converted to released product"
%CMS-I-DELETED, class DISKX:[PROJECT.CMSLIB]BETAFEB deleted
%CMS-I-DELETED, class DISKX:[PROJECT.CMSLIB]BETAJAN deleted
%CMS-S-DELETIONS, 2 classes deleted
This example removes all element generations from all classes
whose names begin with the string BETA, then deletes all of
the empty classes. CMS does not prompt for confirmation during
deletion unless you specify the /CONFIRM qualifier.
8.2 – ELEMENT
Deletes one or more elements from a CMS library.
Format:
DELETE ELEMENT element-expression "remark"
8.2.1 – Restrictions
o You cannot delete an element that belongs to a group or has a
generation in a class.
o You cannot delete an element that has a generation reserved.
o You cannot restore a deleted element.
o You cannot delete an element that has a generation under
review.
8.2.2 – Command Parameters
element-expression
Specifies one or more elements that are to be deleted from the
library. An element expression can be an element 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.
8.2.3 – Description
The DELETE ELEMENT command deletes an element from a CMS library.
If the element is set to /REFERENCE_COPY and there is a current
reference copy directory for the CMS library, CMS deletes the
corresponding file from the reference copy directory.
There cannot be any existing reservations for the element.
The element cannot be a member of a group, nor can one of its
generations belong to a class, or be under review. If one of
the element's generations is under review, use the CANCEL
REVIEW command to remove it from the review list. If an element
is reserved, you must unreserve or replace it before you can
delete the element. If the element belongs to any groups or
has generations in any classes, use the REMOVE ELEMENT or REMOVE
GENERATION command to remove it.
Even though an element is deleted, records of transactions that
created and used the element are retained in the library history.
You can reuse the deleted element name to create a new element.
However, there is no distinction between the two elements in the
library history, except that their transactions are separated by
entries for DELETE ELEMENT and CREATE ELEMENT commands.
8.2.4 – Qualifiers
8.2.4.1 /CONFIRM (D)
Controls whether CMS prompts you for confirmation before each
transaction.
When you 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 or QUIT or press RETURN, 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.
8.2.4.2 /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.
8.2.4.3 /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
ELEMENT (D)
NOELEMENT
NONE--equivalent to NOELEMENT
You can specify either ALL, NONE, or the [NO]ELEMENT keyword.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object.
8.2.5 – Example
CMS> DELETE ELEMENT INITX.FOR "x-version no longer required"
Delete element INITX.FOR? [Y/N] (N): Y
%CMS-I-DELETED, element DISKX:[PROJECT.CMSLIB]INITX.FOR deleted
%CMS-S-DELETIONS, 1 deletion completed
This example uses INITX.FOR as an experimental module; when it
is no longer needed, it can be deleted from the library.
8.3 – GENERATION
Deletes one or more generations of an element.
Format:
DELETE GENERATION element-expression "remark"
8.3.1 – Restrictions
o You cannot delete generation 1 of an element.
o You cannot delete a generation that has variants off it.
o You cannot delete a generation that has a review pending.
o You cannot delete a generation that is reserved.
o You cannot delete a generation that is in a class.
o All generations in the specified range of generations to be
deleted must be on the same line of descent.
o You cannot use /GENERATION in combination with /AFTER, /BEFORE,
/FROM, or /TO.
o You cannot specify /AFTER and /FROM on the same command line.
o You cannot specify /BEFORE and /TO on the same command line.
8.3.2 – Command Parameters
element-expression
Specifies one or more generations of an element. An element
expression can be an element name, 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.
8.3.3 – Description
The DELETE GENERATION command removes information about one or
more generations of an element. Once a generation is deleted, it
cannot be restored to its former place in the element in the CMS
library. You can, however, archive the contents of the generation
using the /ARCHIVE qualifier and later restore the contents of the
generation.
If the generation or range of generations to be deleted has a
direct descendant generation (that is, a descendant generation on
the same line of descent), then the changes associated with those
generations are combined, and then those changes are combined
with the changes in the descendant generation. If there is
no descendant generation, that is, the generation or range of
generations to be deleted is at the end of the line of descent,
then the changes associated with those generations are discarded.
You can specify a single generation with the /GENERATION
qualifier. /GENERATION=1+ is the default. You can also specify
a range of generations with either the /AFTER or /FROM qualifier
to delimit the beginning of a range, and either the /BEFORE or /TO
qualifier to delimit the end of a range. These sets of qualifiers
can be paired to specify ranges with inclusive or exclusive
endpoints (see the restriction section).
If you delete the latest generation on the main line of descent of
an element that has the reference copy attribute, CMS deletes the
generation's reference copy and creates a new reference copy that
corresponds to the generation that is now the latest generation on
the main line of descent.
8.3.4 – Qualifiers
8.3.4.1 /AFTER[=generation-expression]
Specifies the start of a range of generations that are to be
deleted, excluding the specified generation. You cannot specify
both /AFTER and /FROM or both /AFTER and /GENERATION. You must
specify the end of the range with either the /BEFORE or /TO
qualifier.
8.3.4.2 /ARCHIVE=[file-specification]
Specifies a file to which CMS writes archived generation
information. If the file specification is omitted, CMS creates
a file for each with the same name as the element and the .CMS_
ARCHIVE file type and places it in your default directory.
8.3.4.3 /BEFORE[=generation-expression]
Specifies the end of a range of generations that are to be
deleted, excluding the specified generation. You cannot specify
both /BEFORE and /TO or both /BEFORE and /GENERATION. You must
specify the start of the range with either the /AFTER or /FROM
qualifier.
8.3.4.4 /CONFIRM (D)
Controls whether CMS prompts you for confirmation before each
transaction.
When you 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 or QUIT or press RETURN, 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.
8.3.4.5 /FROM[=generation-expression]
Specifies the start of a range of generations that are to be
deleted, including the specified generation. You cannot specify
both /FROM and /AFTER or both /FROM and /GENERATION. You must
specify the end of the range with either the /BEFORE or /TO
qualifier.
8.3.4.6 /GENERATION[=generation-expression]
Specifies a particular generation of the element to be deleted. By
default, the most recent generation on the main line of descent is
deleted. You cannot combine /GENERATION with any of the following
qualifiers: /FROM, /TO, /AFTER, and /BEFORE.
8.3.4.7 /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.
8.3.4.8 /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
ELEMENT (D)
NOELEMENT
NONE--equivalent to NOELEMENT
You can specify either ALL, NONE, or the [NO]ELEMENT keyword.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object.
8.3.4.9 /TO[=generation-expression]
Specifies the end of a range of generations that are to be
deleted, including the specified generation. You cannot specify
both /TO and /BEFORE or both /TO and /GENERATION. You must specify
the start of the range with either the /AFTER or /FROM qualifier.
8.3.5 – Examples
(1) CMS> DELETE GENERATION/NOCONFIRM SAMPLE.PAS/GENERATION=5B1
_Remark: Delete variant line
%CMS-S-GENDELETED, 1 generation of element
DISKX:[PROJECT.CMSLIB]SAMPLE.PAS deleted
This command deletes generation 5B1 of the element SAMPLE.PAS.
The /NOCONFIRM qualifier directs CMS to suppress the prompt
confirming the operation.
(2) CMS> DELETE GENERATION SAMPLE.*/AFTER=V1/BEFORE=V2
_Remark: delete generations between released versions
Delete 5 generations after V1(1) before V2(7) of element SAMPLE.PAS?
[Y/N] (N): Y
%CMS-S-GENDELETED, 5 generations of element
DISKX:[PROJECT.CMSLIB]SAMPLE.PAS deleted
This command deletes all generations of the element after the
generation in class V1 and before the generation in class V2,
excluding the two generations in classes V1 and V2.
(3) CMS> DELETE GENERATION SAMPLE.PAS/AFTER=1/BEFORE=V1
_Remark: delete a range
%CMS-E-NOGENDELETED, no generations of
DISKX:[PROJECT.CMSLIB]SAMPLE.PAS deleted
-CMS-E-VARINRANGE, range has variants
CMS> DELETE GENERATION/ARCHIVE/FROM=2A1/TO=2A1+/NOCONFIRM SAMPLE.PAS
_Remark: delete the variant range and archive the deleted generations
%CMS-S-GENDELETED, 3 generations of element
DISKX:[PROJECT.CMSLIB]SAMPLE.PAS deleted
The first command specifies that all generations be deleted
between generation 1 and the generation in class V1. CMS could
not delete the generations, however, because it found variants
for the indicated generations.
The second command specifies a range of generations to be
deleted from and including the variant generation 2A1 to
and including the latest variant generation of the element
SAMPLE.PAS. In this case, CMS deleted 3 generations of the
element. The /ARCHIVE qualifier directs CMS to save the deleted
generations in an archive file in your default directory.
To display the descendants of a generation and the
classes containing the generations, use the SHOW
GENERATION/DESCENDANTS/MEMBER command.
8.4 – GROUP
Deletes one or more groups from a CMS library.
Format:
DELETE GROUP group-expression "remark"
8.4.1 – Restrictions
o You cannot delete a group that contains any elements or groups
unless you specify the /REMOVE_CONTENTS qualifier.
o You cannot delete a group that belongs to another group.
o You cannot delete a group that has read-only access. (Use the
MODIFY GROUP/NOREAD_ONLY command to change the access to the
group.)
8.4.2 – Command Parameters
group-expression
Specifies the group or groups to be deleted. A group expression
can be one or more group names, 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.
8.4.3 – Description
The DELETE GROUP command deletes a group from a CMS library. If
the group is not empty and the /REMOVE_CONTENTS qualifier is
not specified, or if the group belongs to another group, CMS
returns an error and does not delete the group.
Even though a group is deleted, records of transactions that
created and used the group are retained in the library history.
You can reuse the deleted group name to create a new group.
However, there is no distinction between the two groups in the
library history, except that their transactions are separated by
entries for DELETE GROUP and CREATE GROUP commands.
To determine which elements and groups belong to a group, use the
SHOW GROUP command with the /CONTENTS qualifier.
8.4.4 – Qualifiers
8.4.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.
8.4.4.2 /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.
8.4.4.3 /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 GROUP
GROUP (D)
NOGROUP
NONE--equivalent to NOGROUP
You can specify either ALL, NONE, or the [NO]GROUP keyword.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object.
8.4.4.4 /REMOVE_CONTENTS
Controls whether CMS removes elements and groups from the specified
group prior to deleting the group. When /REMOVE_CONTENTS is
specified CMS displays an informational message for each element or
group that is removed from the group.
8.4.5 – Example
CMS> DELETE GROUP TIME_TST "superseded by comparison tests"
%CMS-S-DELETED, group DISKX:[PROJECT.CMSLIB]TIME_TST deleted
This command deletes the group named TIME_TST.
8.5 – HISTORY
Deletes all or part of the library history.
Format:
DELETE HISTORY "remark"
8.5.1 – Command Parameters
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.
8.5.2 – Description
The DELETE HISTORY command deletes all or part of the library
history. By default, CMS writes the deleted history records to
a file named HISTORY.DMP in your current default directory. CMS
cannot access this file as a history file.
The DELETE HISTORY command does not delete the library creation
history record.
Whenever you delete some of the library history, CMS records two
transactions. As with other commands that modify the contents of
the library, CMS records the deletion transaction. In addition,
CMS logs a REMARK transaction at the point that corresponds to
the /BEFORE value. If you do not specify the /BEFORE qualifier,
the default is /BEFORE=current-time. The REMARK transaction
record includes the following remark: "PREVIOUS HISTORY DELETED".
Both the REMARK and the DELETE HISTORY transactions are unusual
transactions. When you use the SHOW HISTORY command, CMS
identifies unusual transactions by displaying an asterisk (*)
in the first column of the transaction record.
8.5.3 – Qualifiers
8.5.3.1 /BEFORE=date-time
Deletes all of the history information before a specified time. A
single entry is made in the history file specifying that a section
of the history data has been removed. This entry is made at the
location in the history file where the lines were deleted.
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.
8.5.3.2 /CONFIRM (D)
Controls whether CMS prompts you for confirmation before each
transaction.
When you 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 or QUIT or press RETURN, 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.
8.5.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.
8.5.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 OTHER
OTHER (D)
NOOTHER
NONE--equivalent to NOOTHER
You can specify either ALL, NONE, or the [NO]OTHER keyword.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object.
8.5.3.5 /OBJECT=object-expression
Specifies an object about which history information is to be
deleted. The object expression can be one or more class names,
element names, group names, a wildcard expression, or a list of
any of these, separated by commas. If you do not specify an object
expression, CMS deletes all classes, elements, and group
transaction records in the library subject to the constraints
imposed by other qualifiers.
8.5.3.6 /OUTPUT[=file-specification]
Directs CMS to write output to the specified file. If you omit the
/OUTPUT qualifier (or if you specify /OUTPUT but do not provide a
file specification), CMS creates a file named HISTORY.DMP in your
current default directory.
8.5.3.7 /TRANSACTIONS=(keyword,...)
8.5.3.8 /NOTRANSACTIONS=(keyword,...)
Deletes all transaction records generated by a specific command.
You can specify the following keywords with this qualifier:
ACCEPT FETCH REMOVE
ALL INSERT REPLACE
CANCEL MARK RESERVE
COPY MODIFY REVIEW
CREATE REJECT SET
DELETE REMARK UNRESERVE
VERIFY
If you specify more than one keyword, you must enclose the keyword
list in parentheses. The /TRANSACTIONS qualifier directs CMS
to delete transaction records for only the listed keywords. The
/NOTRANSACTIONS qualifier directs CMS to delete transaction records
for all keywords except the listed keywords. If you omit the
/TRANSACTIONS qualifier (or if you specify /TRANSACTIONS but do
not provide any keywords), CMS deletes transaction records for all
transaction types.
8.5.3.9 /USER=username
Deletes all transaction records created by the specified user.
8.5.4 – Example
CMS> DELETE HISTORY/BEFORE=TODAY "old history in HISTORY.DMP"
Confirm DELETE HISTORY/BEFORE=10-MAY-1988 [Y/N] (N): y
%CMS-S-HISTDEL, 89 history records deleted
This example deletes all of the library history prior to
the current day. The following shows the first few records
contained in the HISTORY.DMP file:
Deleted dump for CMS Library DISKX:[PROJECT.CMSLIB]
6-MAR-1988 17:07:50 SNAKE CREATE ELEMENT OUTPUT.FOR
"ASCII format"
6-MAR-1988 17:26:10 MARTIN CREATE ELEMENT INIT.FOR
"init routines"
8-MAR-1988 12:33:09 LISA RESERVE INIT.FOR(1) "change
header offset"
9-MAR-1988 17:34:04 LISA REPLACE INIT.FOR(2) "header
offset and additional free space added"
.
.
.
The CREATE LIBRARY transaction is not deleted from the library
history.
9 – DIFFERENCES
The DIFFERENCES command performs the following functions:
o Compares two files, two generations of elements, or a file and
a generation of an element (see File).
o Compares the contents of two classes (see /CLASS).
9.1 – file
Compares two files, two generations of elements, or a file and
a generation of an element. If the entities are different, CMS
creates a file that contains the lines that differ between them.
If they are the same, CMS issues a message to that effect and does
not create a differences file (unless the /FULL qualifier is in
effect).
Format:
DIFFERENCES file1 [file2]
9.1.1 – Command Parameters
file1
Specifies the first file that is to be compared. If you specify
/GENERATION for this parameter, file1 must be an element name;
otherwise, an OpenVMS file specification is assumed.
file2
Specifies the second file that is to be compared. If you specify
/GENERATION for this parameter, file2 must be an element name;
otherwise, an OpenVMS file specification is assumed.
CMS follows these rules when you do not provide a second file
specification:
o If you direct CMS to take file1 from a location that is not a
CMS library, CMS uses the next lower file version in the same
directory as file1.
o If you direct CMS to take file1 from a CMS library (by
specifying /GENERATION), CMS uses the latest default directory
version of file1 as the second input file.
9.1.2 – Description
The DIFFERENCES command compares the contents of two files. If
CMS finds differences, it creates a file named first-file-name.DIF
in your current default directory (unless /OUTPUT is in effect.)
If the files are the same, it issues a message to that effect
and does not create a differences file. By default, CMS compares
two files that are not located in a CMS library. However, you can
direct CMS to use element generations from the current library by
specifying the /GENERATION qualifier on one or both of the file
name parameters.
Note: If both file1 and file2 are element generations, both
generations must reside in the same library of the search list
or an error will occur.
A difference is defined as one of the following:
o A line or lines that are in one file and not in the other.
o A replacement of n lines by m lines (n may or may not be equal
to m).
Only the lines that differ are displayed in the differences file
(unless you specify /FULL).
A heading at the beginning of the differences file includes the
name of the user that issued the command, the date and time the
command was issued, and the file specifications of the two files
being compared. If you direct CMS to use element generations and
you have specified the /FORMAT option generation-differences,
the differences listing contains a section labeled "Generation
Differences" that contains the replacement history for the
element. Each generation used in the comparison is identified by
an asterisk (*) in the first column of the transaction record.
The differences between the files are contained in a section
labeled "Text Differences." By default, each difference is
formatted with the line or lines from the first file followed by
the differing line or lines from the second file. If a difference
consists of a line or lines in one file but not the other,
only the lines from the file containing the additional text are
displayed.
If you specify the /SKIP, /SENTINEL, and /IGNORE qualifiers on the
same command line, they are processed in the following order:
(1) /IGNORE=HISTORY
(2) /IGNORE=NOTES
(3) /SKIP
(4) /SENTINEL
(5) /IGNORE options other than HISTORY or NOTES
For example, if you specify /SKIP=5 and /SENTINEL=("sushi","bar"),
DIFFERENCES disregards the first 5 lines in each of the compared
files, and then searches the remainder of each file for the
sentinel character strings "sushi" and "bar".
9.1.3 – Qualifiers
9.1.3.1 /APPEND
Controls whether CMS appends the command output to an existing
file, or creates a new file. If you specify /APPEND and the output
file does not exist, CMS creates a new file. If you do not provide
an output file specification (see the description for /OUTPUT),
CMS searches your current default directory for a file with the
file name specified in the file1 parameter and the file type .DIF.
9.1.3.2 /FORMAT=(data-format, data-partition, [no]generation-differences)
Controls whether the output file is formatted, specifies the
type of formatting, and controls whether a list of generation
differences is included in the DIFFERENCES output. You can specify
the parameters in any order.
data-format
Specifies the type of format. Possible values for data formats
include: ASCII (Default), DECIMAL, HEXADECIMAL, and OCTAL.
data-partition
Specifies the type of data partition. Possible values for data
partitions include: BYTE, LONGWORD, RECORDS (Default), and WORD.
generation-differences
Specifies whether or not a list of generation differences is to
be included in the DIFFERENCES output. This option is applicable
only if two element generations are compared by the DIFFERENCES
command. In any other case, this option is ignored. Possible
values for generation-differences include: GENERATION_DIFFERENCES
and NOGENERATION_DIFFERENCES (Default).
9.1.3.3 /FULL
Directs CMS to include a complete listing in the output file,
including identical text and differences between file1 and file2.
9.1.3.4 /GENERATION[=generation-expression]
Directs CMS to search for an element generation in the current
CMS library. The /GENERATION qualifier must immediately follow
the element name to which it applies. If you specify /GENERATION
but do not provide a generation expression, CMS uses the latest
generation on the main line of descent.
9.1.3.5 /IGNORE=(keyword[,...])
Specifies one or more of the following keywords. Each keyword
indicates a type of special character to be ignored during the
comparison.
Keyword Ignored Characters
CASE Directs CMS to ignore any differences between the
case of alphabetic characters (A-Z, a-z).
FORM_FEEDS Directs CMS to remove formfeed characters as it
compares records from the two files.
HISTORY Directs CMS to ignore element generation history
as it compares a file with a generation. At least
one of the files must be an element generation
with the history attribute enabled.
LEADING_BLANKS Directs CMS to remove leading blanks and tabs as
it compares records from the two files.
NOTES Directs CMS to ignore notes as it compares a file
with a generation. At least one of the files must
be an element generation with the notes attribute
enabled.
SPACING Directs CMS to compress multiple blanks and tabs
into a single space as it compares records from
the two files.
TRAILING_BLANKS Directs CMS to remove trailing blanks and tabs as
it compares records from the two files.
If the HISTORY or NOTES keyword is specified, the history or notes
text is not used for the comparison, and is also removed from
the output generated by DIFFERENCES. For all other options, the
output generated by DIFFERENCES contains the original records used
for the comparison, instead of the modified form of the records
designated by the /IGNORE qualifier.
9.1.3.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.
9.1.3.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, CLASS)
ELEMENT (D)
NOELEMENT
CLASS (D)
NOCLASS
NONE--equivalent to (NOELEMENT, NOCLASS)
You can specify either ALL or NONE, or any combination of the
[NO]ELEMENT and [NO]CLASS keywords.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object.
9.1.3.8 /OUTPUT[=file-specification]
Directs CMS to write output to the specified file. CMS creates a
new file if you do not specify /APPEND. If you omit the /OUTPUT
qualifier (or if you specify /OUTPUT but do not provide a file
specification), CMS creates a file with the file name specified in
the file1 parameter and the file type .DIF. If you specify a file
name but omit the file type component, CMS writes the output to a
file with the specified file name and a file type of .DIF.
9.1.3.9 /NOOUTPUT
Directs CMS to execute a comparison without creating an output
file. This form of the comparison may be significantly faster
because CMS stops the transaction when it encounters the first
difference.
9.1.3.10 /PAGE_BREAK
Controls whether CMS allows page breaks in the output file. By
default, page breaks are converted to the string "<PAGE>" in the
output file. Use /PAGE_BREAK to request the inclusion of page
breaks in the output file.
9.1.3.11 /PARALLEL
Controls whether the differing lines from the two files are
formatted side by side. If you specify /PARALLEL, the differences
from the first file are displayed on the left and the differences
from the second file are displayed on the right. The heading of
the differences report displays the file specification of the
first file on the left and the file specification of the second
file on the right.
By default, the width of the listing is 132. Use the /WIDTH
qualifier to control the width. Vertical lines separate the text
on the left side of the report from the text on the right side.
The text from each of the files is allotted equal space (half the
width of the full report).
If a line from one of the files being compared is longer than half
the width of the full report, the line is truncated on the right.
An asterisk (*) is printed at the end of the line to indicate
that the line has been truncated.
9.1.3.12 /SENTINEL=("begin-delimiter", "end-delimiter")
Specifies a pair of strings used to delimit a section of text to
be ignored during the comparison of both files. The delimiters
can be up to 256 characters per line, and must be unique. Any text
between and including the delimiters is treated as if it did not
exist. If you do not enclose the sentinel strings in quotation
marks, they are converted to uppercase before the comparison of
the files. Sentinel strings may contain any characters, but if you
include spaces or tabs, they must be enclosed in quotation marks.
Sentinel strings can appear anywhere in a file. If text delimited
by a sentinel pair crosses record boundaries, the text after the
delimited region appears in its own record in the output file; it
is not appended to the contents of the record in which the begin
delimiter was found.
9.1.3.13 /SKIP=number-of-lines
Indicates the number of lines at the beginning of each file (or
generation) that are to be ignored during the comparison of both
files. You must specify a nonnegative integer value indicating the
number of lines to be ignored.
9.1.3.14 /WIDTH=n
Specifies the limit for the width of the differences report. The
value n is required and must be an integer in the range 48 to 511.
If n is less than 48, 48 is used. If n is more than 511, 511 is
used. The default width is the same as the width of the output
device.
The width of the report is rounded down to the nearest multiple
of 8 minus 1. CMS rounds down so that if you have specified the
/PARALLEL qualifier, CMS correctly interprets the horizontal tabs
in the file on the right. Thus, for example, if you specify a
value of 100 on the /WIDTH qualifier, the actual width is 95.
9.2 /CLASS
Compares the contents of two classes. If the particular generation
of any element, that is a member of the class, differs between the
classes, CMS creates a file that contains a listing of the class
members that differ between them. If the contents of the classes
are the same, CMS issues a message to that effect and does not create
a differences file (unless the /FULL qualifier is in effect). The
/CLASS qualifier must be specified prior to any other qualifiers.
Format:
DIFFERENCES/CLASS class1 class2
9.2.1 – Command Parameters
class1
Specifies the first class that is to be compared.
class2
Specifies the second class that is to be compared.
9.2.2 – Description
The DIFFERENCES/CLASS command compares the contents of two
classes. If CMS finds differences, it creates a file named
first-class-name.DIF in your current default directory (unless
/OUTPUT is in effect.) If the contents of the classes are the
same, it issues a message to that effect and does not create a
differences file.
Note: Both classes must reside in the same library of the search
list or an error will occur.
A difference is defined as one of the following:
o A particular generation of an element is a member of one
class but no generation of the element is a member of the
other class.
o One particular generation of an element is a member of one
class and a different generation of the same element is a
member of the other class.
Only the generations that differ are displayed in the differences
file (unless you specify /FULL).
A heading at the beginning of the differences file includes the
name of the user that issued the command, the date and time the
command was issued, and the class names of the two classes being
compared.
9.2.3 – Qualifiers
9.2.3.1 /APPEND
Controls whether CMS appends the command output to an existing
file, or creates a new file. If you specify /APPEND and the output
file does not exist, CMS creates a new file. If you do not provide
an output file specification (see the description for /OUTPUT),
CMS searches your current default directory for a file with the
file name specified in the file1 parameter and the file type .DIF.
9.2.3.2 /FULL
Directs CMS to include a complete listing in the output file,
including both identical and different generations between
class1 and class2.
9.2.3.3 /IGNORE=(keyword[,...])
Specifies one or more of the following keywords. Each keyword
indicates a type of difference to be ignored during the
comparison.
Keyword Ignored Difference
FIRST_VARIANT Directs CMS to ignore any differences where the
generation in one class is the first variant of
the generation in the other class. For example
generation 2C1 is a first variant of generation
2 and generation 4B6D1 is a first variant of
generation 4B6.
9.2.3.4 /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.
9.2.3.5 /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, CLASS)
ELEMENT (D)
NOELEMENT
CLASS (D)
NOCLASS
NONE--equivalent to (NOELEMENT, NOCLASS)
You can specify either ALL or NONE, or any combination of the
[NO]ELEMENT and [NO]CLASS keywords.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object.
9.2.3.6 /OUTPUT[=file-specification]
Directs CMS to write output to the specified file. CMS creates a
new file if you do not specify /APPEND. If you omit the /OUTPUT
qualifier (or if you specify /OUTPUT but do not provide a file
specification), CMS creates a file with the file name specified in
the class1 parameter and the file type .DIF. If you specify a file
name but omit the file type component, CMS writes the output to a
file with the specified file name and a file type of .DIF.
9.2.3.7 /NOOUTPUT
Directs CMS to execute a comparison without creating an output
file. This form of the comparison may be significantly faster
because CMS stops the transaction when it encounters the first
difference.
9.2.3.8 /PARALLEL
Controls whether the differing member generations from the two
classes are formatted side by side. If you specify /PARALLEL,
the differences from the first class are displayed on the left
and the differences from the second class are displayed on the
right. The heading of the differences report displays the class
name of the first class on the left and the class name of the
second class on the right.
By default, the width of the listing is 132. Use the /WIDTH
qualifier to control the width. Vertical lines separate the text
on the left side of the report from the text on the right side.
The text from each of the classes is allotted equal space (half
the width of the full report).
If a line from one of the classes being compared is longer than
half the width of the full report, the line is truncated on the
right. A plus sign (+) is printed at the end of the line to
indicate that the line has been truncated.
9.2.3.9 /SHOW=(keyword[,...])
Specifies one or more of the following keywords. Each keyword
indicates a type of class difference to show.
Keyword Difference Type
GENERATION_DIFFERENCES Directs CMS to show the difference if the
generation in one class differs from the
generation in the other class but one
generation isn't a variant of the other
generation.
VARIANT_DIFFERENCES Directs CMS to show the difference if the
generation in one class differs from the
generation in the other class and one
generation is a variant of the other. One
generation will be a variant of the other
if at some point in the path between one
generation and the other a generation is
reserved and replaced /VARIANT.
If the /SHOW qualifier is not specified, both generation differences
and variant differences are shown. If a generation of an element is
in one class but no generation of the element is in the other class
then the difference is always shown regardless of whether the /SHOW
qualifier is specified or not.
9.2.3.10 /WIDTH=n
Specifies the limit for the width of the differences report. The
value n is required and must be an integer in the range 48 to 511.
If n is less than 48, 48 is used. If n is more than 511, 511 is
used. The default width is the same as the width of the output
device.
The width of the report is rounded down to the nearest multiple
of 8 minus 1. CMS rounds down so that if you have specified the
/PARALLEL qualifier, CMS correctly interprets the horizontal tabs
in the generation comment on the right. Thus, for example, if you
specify a value of 100 on the /WIDTH qualifier, the actual width
is 95.
10 – FETCH
Retrieves a copy of a generation of one or more elements from a
CMS library.
Format:
FETCH element-expression "remark"
10.1 – Command Parameters
element-expression
Specifies one or more generations of an element to be retrieved
from the library. 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 fetched.
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.
10.2 – Description
The FETCH command delivers a copy of the specified element
generation to your current default directory. The element is not
reserved, and CMS does not allow you to replace a fetched element.
CMS allows you to fetch an element that is reserved, and notifies
you of any current reservations for the element.
The presence or absence of a remark determines whether the FETCH
transaction is recorded in the library history. If you enter a
remark, CMS records the transaction in the history file. If you
enter a null remark, CMS does not record the transaction in the
history file.
If a version of a file with the same name as the element already
exists in your current default directory when you execute the
fetch transaction, CMS notifies you. A new version is then created
with the next higher version number.
When you fetch a generation of an element from a CMS library, CMS
restores the file creation time, revision time, revision number,
and record format and attributes. The file that is placed in your
directory has the same creation and revision times as the file
that was used to create the generation that you are fetching.
10.3 – Qualifiers
10.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.
10.3.2 /GENERATION[=generation-expression]
Specifies a particular generation of the element that is to be
retrieved. If you omit /GENERATION, CMS fetches the most recent
generation on the main line of descent.
10.3.3 /HISTORY="string"
Specifies that history is to be included in the retrieved file.
The quoted string specifies the format of the history. The quoted
string must contain the characters #H or #B (lowercase is allowed)
and can contain other printing characters. To include a quotation
mark in the output history string, type it twice (""). To include
a number sign (#) in the output history string, type it twice
(##).
10.3.4 /NOHISTORY
Prevents CMS from appending the element history to the file. If
you omit /NOHISTORY, and the retrieved element has the history
attribute, the element history is included in the file when it is
delivered to your current default directory. An element has the
history attribute if you specified the /HISTORY qualifier on the
CREATE ELEMENT or MODIFY ELEMENT command.
10.3.5 /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.
10.3.6 /MERGE=generation-expression
Controls whether another generation of the element (called the
merge generation) is to be merged with the generation that is
being fetched (called the retrieved generation).
When you specify the /MERGE qualifier, CMS merges the lines of
the two generations and delivers a single copy to your default
directory. The file that is placed in your directory has the
current creation and revision times. The merge generation cannot
be on the same line of descent as the retrieved generation. When
there is a conflict between blocks of one or more lines, CMS
includes the conflicting lines and flags the conflict.
10.3.7 /NOTES="string"
Temporarily establishes the notes attribute for the element,
regardless of whether the element previously had the notes
attribute enabled. If neither the /NOTES or /NONOTES qualifier is
specified for an element, but the element has the notes attribute
enabled, notes are appended to the lines of the file when it is
retrieved by the FETCH or RESERVE command.
The quoted string specifies the format of the note. The quoted
string can contain text or the characters #G (or #g), or both.
If you specify /NOTES for an element that does not have the notes
attribute enabled, then you must also specify /POSITION.
10.3.8 /NONOTES
Specifies that notes are not to be embedded in the output file.
If you omit /NONOTES, and the retrieved element has the notes
attribute, CMS embeds notes in the output file. An element has
the notes attribute if you specified the /NOTES qualifier on the
CREATE ELEMENT or MODIFY ELEMENT command.
10.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.
10.3.10 /OUTPUT[=file-specification]
Directs CMS to write output to the specified file. If you omit the
/OUTPUT qualifier (or if you specify /OUTPUT but do not provide a
file specification), CMS creates a file with the same name as the
element.
If you fetch more than one element (by specifying wildcards or a
group name for the element expression parameter), and you do not
specify wildcards in the output file specification, CMS creates
successive versions of the file indicated by /OUTPUT.
10.3.11 /NOOUTPUT
Specifies that the fetch operation is to be performed along with
any history processing and error checking, but that no output file
is to be created. By default, an output file with the same name as
the element is created.
10.3.12 /POSITION=column-number
Specifies the column in which the note is to be placed. The column
number is required and must be an integer in the range 1 to 511.
The notes attribute or the /NOTES qualifier is required with the
/POSITION qualifier.
If the length of the line is less than the specified column
number, the note appears at the column number. If the length of
the line is greater than or equal to the column number, the note
is placed at the next tab stop after the end of the line. (Tab
stops are at position 9 and every 8 characters thereafter.)
10.4 – Example
CMS> FETCH INIT.FOR "check for correct spelling"
Element INIT.FOR currently reserved by:
(1) SMITH 2 30-APR-1988 15:48:35.65 "to add new routine"
%CMS-S-FETCHED, generation 2 of element DISKX:[PROJECT.CMSLIB]INIT.FOR
fetched
This command fetches the latest generation on the main line of
descent of element INIT.FOR. CMS indicates that the element is
reserved, then continues with the fetch transaction.
11 – HELP
Provides online CMS information.
11.1 – Command Parameters
topic
Specifies a subject that is related to CMS. For example, help
on the topic OVERVIEW consists of general information on CMS and
pointers to other topics that would be of interest to new users.
Help on CLASSES defines the concept of a class and points to help
on commands that manipulate classes.
command
Gives information about CMS either at DCL level or at CMS
subsystem level. At DCL level, the DCL command HELP CMS provides
online help on CMS commands, qualifiers, and other topics. For
example:
$ HELP CMS
To get help on a specific CMS command, such as the CREATE ELEMENT
command, type the command after HELP CMS. For example:
$ HELP CMS CREATE ELEMENT
You can get help at the CMS subsystem level by typing either HELP,
or HELP and the specific command. For example:
CMS> HELP CREATE ELEMENT
command /qualifier
Specifies a CMS command with an appropriate qualifier. For
example:
$ HELP CMS DIFFERENCES/PARALLEL
This command gives you help at DCL level on the PARALLEL qualifier
on the DIFFERENCES command.
command option
Specifies a CMS command with an appropriate option. For example:
$ HELP CMS SHOW ELEMENT
$ HELP CMS CREATE CLASS
These commands give you help at DCL level on the SHOW ELEMENT and
CREATE CLASS commands.
command option/qualifier
Specifies a CMS command with an option and a qualifier. For
example:
$ HELP CMS CREATE ELEMENT/RESERVE
This command gives you help at DCL level on the /RESERVE qualifier
on the CREATE ELEMENT command.
11.2 – Description
Online help for CMS is available at both the DCL and the CMS
subsystem command level. At DCL level, you can type HELP CMS or
CMS HELP to get information. At CMS subsystem level, you can type
HELP to get information. If you omit a parameter after HELP CMS,
you get an overview of the CMS HELP facility. In this overview,
the general syntax of a CMS command is displayed, and all the
keywords for which you can obtain more information are listed.
The command HELP CMS HELP gives a short explanation of how the
HELP topics are organized.
12 – INSERT
12.1 – ELEMENT
Places one or more elements or groups in the specified group or
groups.
Format:
INSERT ELEMENT element-expression group-expression "remark"
12.1.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).
12.1.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.
12.1.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.
12.1.4 – Qualifiers
12.1.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.
12.1.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.
12.1.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.
12.1.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.
12.1.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.
12.2 – GENERATION
Places one or more element generations in the specified class or
classes.
Format:
INSERT GENERATION element-expression class-expression "remark"
12.2.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).
12.2.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.
12.2.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.)
12.2.4 – Qualifiers
12.2.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.
12.2.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.
12.2.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.
12.2.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.
12.2.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.
12.2.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.
12.2.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.
12.2.4.8 /SUPERSEDE
12.2.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.
12.2.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.
12.3 – GROUP
Places one or more groups into the specified group or groups.
Format:
INSERT GROUP subgroup-expression group-expression "remark"
12.3.1 – Restrictions
o You cannot insert a group into another group that has read-only
access.
o You can insert a group into another group only once.
o You cannot create recursive groups; that is, a group cannot
directly or indirectly be a member of itself.
o You cannot insert a group from one library into a group in
another library (both groups must be in the same library).
12.3.2 – Command Parameters
subgroup-expression
Specifies one or more groups to be inserted into a second group
(indicated by group-expression). A subgroup expression can be a
group name, a wildcard expression, or a list of these separated by
commas.
group-expression
Specifies the group into which subgroup-expression 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.
12.3.3 – Description
The INSERT GROUP command inserts one or more groups into one
or more other groups. Both groups must exist. When you use the
INSERT GROUP command to insert group A into group B, the elements
accessible through group B change as the contents of group A
change. A group cannot be a member of itself; that is, it cannot
be a subgroup of itself. For example, you cannot insert group A
into group B if group A already contains group B.
12.3.4 – Qualifiers
12.3.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.
12.3.4.2 /IF_ABSENT
Directs CMS to insert subgroup-expression into group-expression
only if group-expression does not already contain it. If subgroup-
expression already belongs to group-expression, CMS takes no
action and does not return an error.
12.3.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.
12.3.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 GROUP
GROUP (D)
NOGROUP
NONE--equivalent to NOGROUP
You can specify either ALL, NONE, or the [NO]GROUP keyword.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object.
12.3.5 – Example
CMS> INSERT GROUP USER_MANUAL CODE_AND_DOCS "user documentation"
%CMS-S-INSERTED, group DISKX:[PROJECT.CMSLIB]USER_MANUAL inserted
into group DISKX:[PROJECT.CMSLIB]CODE_AND_DOCS
This command inserts the group named USER_MANUAL into the group
named CODE_AND_DOCS. As long as group USER_MANUAL belongs to
group CODE_AND_DOCS, any changes to the contents of USER_MANUAL
are reflected in the contents of CODE_AND_DOCS. Any element
accessible through USER_MANUAL is also accessible through CODE_
AND_DOCS.
13 – MARK
13.1 – GENERATION
Marks each specified element generation for review and adds it to
the review pending list.
Format:
MARK GENERATION element-expression "remark"
13.1.1 – Restrictions
o This command can be used only on element generations that do
not already have reviews pending.
13.1.2 – Command Parameters
element-expression
Specifies one or more elements or groups of elements whose
generations are to be marked with pending review status. An
element expression can be an element name, 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.
13.1.3 – Description
The MARK GENERATION command changes the review status of the
specified element generation from "none" to "pending" and inserts
it into the review pending list. You can then review the element
generation by using the REVIEW GENERATION command. Use one of the
following commands to change the review status of the element
generation: ACCEPT GENERATION, REJECT GENERATION, or CANCEL
REVIEW.
13.1.4 – Qualifiers
13.1.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.
13.1.4.2 /GENERATION[=generation-expression]
Specifies which generation of the element is to be marked as
having review pending status. If you omit /GENERATION, CMS marks
the most recent generation on the main line of descent.
13.1.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.
13.1.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, 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.
13.1.5 – Example
$ CMS MARK GENERATION/GENERATION=1X1 SPEC.COM
_Remark: check this gen out before reinserting into class
%CMS-S-MARKED, generation 1X1 of element
DISKX:[PROJECT.CMSLIB]EXAMPLE.SDML marked for review
This command marks a specific generation for review. CMS adds
the generation to the review pending list.
14 – MODIFY
14.1 – CLASS
Changes the characteristics of a specified class or classes.
Format:
MODIFY CLASS class-expression /qualifier "remark"
14.1.1 – Restrictions
o You cannot modify a class that has read-only access. If a
class has read-only access, you must change it to NOREAD_
ONLY access to change the contents of the class or any other
characteristics.
o You must specify one or more of the following qualifiers:
/NAME, /[NO]READ_ONLY, /REMARK.
14.1.2 – Command Parameters
class-expression
Specifies the class being modified. 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. Note that this parameter
and the string on the /REMARK qualifier are unrelated.
14.1.3 – Description
The MODIFY CLASS command changes the characteristics of one or
more classes. You can alter the following characteristics:
o The name of the class.
o The access to the class (READ_ONLY or NOREAD_ONLY). You cannot
change the contents, the name, or the remark of a class that
has been set to READ_ONLY.
o The creation remark that is associated with the class.
Use the SHOW CLASS command to display class characteristics.
14.1.4 – Qualifiers
14.1.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.
14.1.4.2 /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.
14.1.4.3 /NAME=class-name
Specifies the new name for the class. The new class name cannot
be the same as an existing class or group name. If a previously
used class or group name has been removed with the DELETE CLASS or
DELETE GROUP command, you can reuse that name. Wildcards and comma
lists are not allowed.
If you specify the /NAME qualifier, you cannot use wildcards or a
comma list in the class-name parameter, nor can you use a wildcard
for the /NAME qualifier. You cannot change the name of a class
that has read-only access.
14.1.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 CLASS
CLASS (D)
NOCLASS
NONE--equivalent to NOCLASS
You can specify either ALL, NONE, or the [NO]CLASS keyword.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object.
14.1.4.5 /READ_ONLY
14.1.4.6 /NOREAD_ONLY
Establishes or alters the read-only attribute of a class. To
change the characteristics of a read-only class, you must set
the class to NOREAD_ONLY. NOREAD_ONLY is the default attribute of
a class when it is created with the CREATE CLASS command.
14.1.4.7 /REMARK="string"
Specifies a new remark to be substituted for the creation remark
that is associated with the class. You cannot change the remark of
a class that has been set to READ_ONLY.
14.1.5 – Examples
(1) CMS> MODIFY CLASS PRE_RELEASE/READ_ONLY "freeze internal version"
%CMS-S-MODIFIED, class DISKX:[PROJECT.CMSLIB]PRE_RELEASE modified
This command sets the class named PRE_RELEASE to READ_ONLY.
(2) CMS> MODIFY CLASS PRE_RELEASE/NOREAD_ONLY/NAME=PRE_RELEASE_V3
_Remark: include additional functions
%CMS-S-MODIFIED, class DISKX:[PROJECT.CMSLIB]PRE_RELEASE modified
This example renames class PRE_RELEASE to PRE_RELEASE_V3.
Because PRE_RELEASE had been set to READ_ONLY, it is necessary
to use the /NOREAD_ONLY qualifier to modify the class.
14.2 – ELEMENT
Changes the characteristics of a specified element or elements.
Format:
MODIFY ELEMENT element-expression /qualifier "remark"
14.2.1 – Restrictions
o You cannot modify an element if it is set to read-only access.
o You can modify only the reference copy, remark, and review
attributes of an element that has a generation reserved.
o If you specify /NOTES, you must also specify /POSITION on the
same command line.
o You must specify one or more of the following qualifiers:
/[NO]CONCURRENT
/[NO]HISTORY
/NAME
/[NO]NOTES
/POSITION
/[NO]REFERENCE_COPY
/REMARK
/[NO]REVIEW
14.2.2 – Command Parameters
element-expression
Specifies one or more elements to be modified. An element
expression can be an element name, 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. Note that this parameter
and the string on the /REMARK qualifier are unrelated.
14.2.3 – Description
The MODIFY ELEMENT command changes the characteristics of one or
more elements. You can alter the following characteristics:
o The concurrent attribute of the element
o The history string that is inserted in the element history when
the element is reserved or fetched
o The element name
o The notes string and related position attribute
o The reference copy attribute of the element
o The creation remark that is associated with the element
o The review attribute
Use the SHOW ELEMENT command to display element characteristics.
If the history, notes, or position attribute is modified on an
element that has the reference copy attribute, CMS creates an
updated reference copy for the element.
14.2.4 – Qualifiers
14.2.4.1 /CONCURRENT
14.2.4.2 /NOCONCURRENT
Specifies whether this element can have multiple reservations. If
you do not specify this qualifier, the existing concurrent access
is not changed.
14.2.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.
14.2.4.4 /HISTORY="string"
Establishes the history attribute for the element. If an element
has a history attribute, its history (which is similar to that
produced by the ANNOTATE command) is included in the file when you
retrieve it with the FETCH or RESERVE command.
The quoted string specifies the format of the history. The quoted
string must contain the characters #H or #B (lowercase is allowed)
and can contain other printing characters. To include a quotation
mark in the output history string, type it twice (""). To include
a number sign (#) in the output history string, type it twice
(##).
14.2.4.5 /NOHISTORY
Deletes any existing history attribute. If both /HISTORY and
/NOHISTORY are omitted, any existing history attribute remains
unchanged.
14.2.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.
14.2.4.7 /NAME=element-name
Specifies the new name for the element. The new element name
cannot be the same as an existing element name. Do not use the
file name 00CMS because this name is reserved for CMS. If you
specify the /NAME qualifier, you cannot use wildcards or a comma
list in the element-name parameter, nor can you use a wildcard for
the /NAME qualifier.
If an element is set to /REFERENCE_COPY, CMS creates a new
reference copy of the element in the reference copy directory.
14.2.4.8 /NOTES="string"
Establishes the notes attribute for the element. If an element
has a notes attribute, notes are appended to the lines of the file
when it is retrieved by the FETCH or RESERVE command.
The quoted string specifies the format of the note. The quoted
string can contain text or the characters #G (or #g), or both.
14.2.4.9 /NONOTES
Cancels any current notes attribute and the corresponding position
attribute.
If both /NOTES and /NONOTES are omitted, any existing notes
attribute remains unchanged.
14.2.4.10 /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.
14.2.4.11 /POSITION=n
Establishes the position attribute; that is, the character
position at which the note generated by the /NOTES qualifier is to
begin on the line. A file that has a position attribute must have
a notes attribute. Thus, the /POSITION qualifier can be used only
if the element already has an established notes attribute, or the
/NOTES qualifier is used on the same MODIFY ELEMENT command.
The value n is required and must be an integer in the range 1 to
511. If the length of the line is less than n, the note appears
at position n. If the length of the line is greater than or equal
to n, the note is placed at the next tab stop after the end of
the line. (Tab stops are at position 9 and every 8 characters
thereafter.)
If you omit /POSITION, any current position attribute remains
unchanged.
14.2.4.12 /REFERENCE_COPY
14.2.4.13 /NOREFERENCE_COPY
Controls whether a new reference copy of an element is created or
deleted. If you specify /REFERENCE_COPY, CMS creates a new
reference copy of the element in the reference copy directory and
updates the current reference copy directory whenever you create a
new main line generation of the element. If you specify
/NOREFERENCE_COPY, CMS deletes the existing reference copy of the
element. The reference copy directory must be established before
you issue the MODIFY ELEMENT/REFERENCE_COPY command. Use the MODIFY
LIBRARY/REFERENCE_COPY command to establish the reference copy
directory.
Controls whether CMS creates a new reference copy of an element
whenever you create a new main line generation of the element. If
you specify /NOREFERENCE_COPY, CMS deletes the existing reference
copy.
To establish the reference copy directory, use the MODIFY
LIBRARY/REFERENCE_COPY command.
14.2.4.14 /REMARK="string"
Specifies a new remark to be substituted for the creation remark
that is associated with the element.
14.2.4.15 /REVIEW
14.2.4.16 /NOREVIEW
Controls whether new generations of the element are marked for
review. If you specify /REVIEW, new generations of the element are
marked for review. If you specify /NOREVIEW, new generations are
marked only if the reserved generation is either rejected or has a
review pending. If you do not specify this qualifier, the existing
review attribute is not changed.
To determine whether an element has the review attribute enabled,
use the SHOW ELEMENT/FULL command.
14.2.5 – Examples
(1) CMS> MODIFY ELEMENT INIT.FOR/NOCONCURRENT
_Remark: no more changes, other than those already discussed
%CMS-S-MODIFIED, element DISKX:[PROJECT.CMSLIB]INIT.FOR modified
This example sets the element INIT.FOR to NOCONCURRENT access.
This means that only one person can reserve the element at a
time.
(2) CMS> MODIFY ELEMENT/REVIEW EXAMPLE.SDML
_Remark: team should review all changes before performing build
%CMS-S-MODIFIED, element DISKX:[PROJECT.CMSLIB]EXAMPLE.SDML modified
This example marks the latest generation of the element
EXAMPLE.SDML for review, and adds it to the review pending
list. To display what generations are pending review, use the
SHOW REVIEWS_PENDING command.
14.3 – GENERATION
Changes the characteristics of a specified generation or
generations.
Format:
MODIFY GENERATION element-expression /qualifier "remark"
14.3.1 – Restrictions
o You must specify one of the following qualifiers: /GENERATION
or /REMARK.
14.3.2 – Command Parameters
element-expression
Specifies one or more elements whose generations are to be
modified. An element expression can be an element name, 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. Note that this parameter
and the string on the /REMARK qualifier are unrelated.
14.3.3 – Description
The MODIFY GENERATION command changes the remark that is
associated with a particular generation of one or more
elements. Use the SHOW GENERATION command to display generation
characteristics.
This command does not change a generation's review status. See
the ACCEPT GENERATION, CANCEL GENERATION, MARK GENERATION, REJECT
GENERATION, and REVIEW GENERATION commands for more information.
14.3.4 – Qualifiers
14.3.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.
14.3.4.2 /GENERATION[=generation-expression]
Specifies which generation of the element is to be modified. If
you omit /GENERATION, CMS modifies the most recent generation on
the main line of descent.
14.3.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.
14.3.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, 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.
14.3.4.5 /REMARK="string"
Specifies a new remark to be substituted for the creation
(replacement) remark that is associated with the generation. This
qualifier is required.
14.3.5 – Example
CMS> MODIFY GENERATION/GENERATION=5/REMARK="Obsolete"
_Element expression: SPEC.TXT
_Remark: Marked obsolete
%CMS-S-MODIFIED, generation 5 modified
This command specifies a new remark to be substituted for the
creation remark of generation 5 of element SPEC.TXT. You must
also specify the element expression, and its associated remark,
which is logged in the history file.
14.4 – GROUP
Changes the characteristics of the specified group or groups.
Format:
MODIFY GROUP group-expression /qualifier "remark"
14.4.1 – Restrictions
o You cannot change the attributes of a group that has been set
to READ_ONLY. If a group has read-only access, you must change
it to NOREAD_ONLY to change any other characteristics.
o You must specify one or more of the following qualifiers:
/NAME, /[NO]READ_ONLY, or /REMARK.
14.4.2 – Command Parameters
group-expression
Specifies the group to be modified. 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. Note that this parameter
and the string on the /REMARK qualifier are unrelated.
14.4.3 – Description
The MODIFY GROUP command changes the characteristics of one or
more groups. You can alter the following characteristics:
o The name of the group.
o The access to the group (READ_ONLY or NOREAD_ONLY). You cannot
change the contents of a group that has been set READ_ONLY.
o The creation remark that is associated with the group.
Use the SHOW GROUP command to display group characteristics.
14.4.4 – Qualifiers
14.4.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.
14.4.4.2 /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.
14.4.4.3 /NAME=group-name
Specifies the new name for the group. You cannot change the
name of a group that has been set to READ_ONLY. The new group
name cannot be the same as an existing group or class name.
Wildcards and comma lists are not allowed. If you specify the
/NAME qualifier, you cannot use wildcards or a comma list in the
group name parameter, nor can you use a wildcard for the /NAME
qualifier.
14.4.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 GROUP
GROUP (D)
NOGROUP
NONE--equivalent to NOGROUP
You can specify either ALL, NONE, or the [NO]GROUP keyword.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object.
14.4.4.5 /READ_ONLY
14.4.4.6 /NOREAD_ONLY
Establishes or alters the read-only attribute of a group. To
change the characteristics of a READ_ONLY group, you must set
the class to NOREAD_ONLY. NOREAD_ONLY is the default attribute of
a group when it is created with the CREATE GROUP command.
14.4.4.7 /REMARK="string"
Specifies a new remark to be substituted for the creation remark
that is associated with the group.
14.4.5 – Example
CMS> MODIFY GROUP TESTS/READ_ONLY "coordinate before changing
contents"
%CMS-S-MODIFIED, group DISKX:[PROJECT.CMSLIB]TESTS modified
This command sets the group TESTS to READ_ONLY. Once the group
is set to READ_ONLY, the contents cannot be changed.
14.5 – LIBRARY
Establishes or removes the connection between the current CMS
library and a reference copy directory.
Format:
MODIFY LIBRARY /qualifier "remark"
14.5.1 – Command Parameters
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.
14.5.2 – Description
The MODIFY LIBRARY command establishes or removes the connection
between the current CMS library and a reference copy directory.
The reference copy directory cannot be a CMS library. This command
does not add files to or delete any files from a reference
copy directory. Once you establish a reference copy directory
for a library, subsequent transactions that create new element
generations on the main line of descent also update the reference
copy directory (provided the element is set to /REFERENCE_COPY).
You must use the MODIFY ELEMENT/NOREFERENCE_COPY command on
the elements in the library before you can use the MODIFY
LIBRARY/NOREFERENCE_COPY command.
If you specify MODIFY LIBRARY/REFERENCE_COPY and the reference
copy directory is already set, CMS first verifies all the files
found in that directory. The contents of the directory must
exactly correspond with the elements that have /REFERENCE_COPY
set in the CMS library. If elements are set with /NOREFERENCE_
COPY and there are existing reference copies for those elements,
CMS advises you to use VERIFY/REPAIR. No further operations are
allowed until the reference copies have been repaired.
Use the SHOW LIBRARY command to display library characteristics.
14.5.3 – Qualifiers
14.5.3.1 /CONCURRENT (D)
Specifies whether elements in a library can have multiple
reservations by setting the concurrent attribute on the library.
Use /NOCONCURRENT to disallow multiple reservations. If this
qualifier is not specified the status of this attribute remains
unchanged.
14.5.3.2 /EXTENDED_FILENAMES
Change the attribute of a CMS library to allow the use of extended
file names. This qualifier is only available on OpenVMS V7.2 and
later. Use /NOEXTENDED_FILENAMES to change the attribute to disallow
the use of extended file names. If this qualifier is not specified
the status of this attribute remains unchanged.
14.5.3.3 /KEEP
Instructs CMS to not delete all versions of a file used to create
a new element or generation. If this qualifier is not specified
the status of this attribute remains unchanged.
14.5.3.4 /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.
14.5.3.5 /LONG_VARIANT_NAMES
Change the attribute of a CMS library to allow the use of long
variant names. Use /NOLONG_VARIANT_NAMES to change the attribute
to disallow the use of long variant names. If this qualifier is
not specified the status of this attribute remains unchanged.
14.5.3.6 /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 OTHER
OTHER (D)
NOOTHER
NONE--equivalent to NOOTHER
You can specify either ALL, NONE, or the [NO]OTHER keyword.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object.
14.5.3.7 /REFERENCE_COPY=directory-specification
Specifies a valid OpenVMS directory to be used for reference copies
of library elements. The directory cannot be a CMS library, nor
can it be a subdirectory of a CMS library directory. If you use
the MODIFY LIBRARY command on a search list consisting of more
than one library, you should specify a reference copy directory
for each library in the search list. If you specify only one
reference copy directory for more than one library, CMS uses one
reference copy directory for the entire search list, not one
reference copy directory for each library in the search list.
Use the /NOREFERENCE_COPY qualifier to remove the connection
between the current CMS library and the current reference copy
directory. Wildcards are not allowed.
14.5.3.8 /REVISION_TIME[=option]
Controls whether CMS uses the original file revision time or the
file storage time when a file is retrieved from the CMS library.
The options field can contain of the following keywords:
ORIGINAL (D)
STORAGE_TIME
Use the keyword ORIGINAL to indicate that the original revision
time of files placed in a CMS library should be restored unchanged
upon their retrieval. This is the default behavior.
Use the keyword STORAGE_TIME to indicate that the time when a file
was stored in a CMS library (through a CREATE ELEMENT or REPLACE
transaction) should be substituted for its original revision time
upon retrieval.
14.5.4 – Example
CMS> MODIFY LIBRARY/REFERENCE_COPY=[WORK.REFCOPY] "current
test area"
%CMS-S-MODIFIED, library [WORK.CODELIB] modified
This command establishes the reference copy directory
[WORK.REFCOPY] for the current CMS library. In addition, to
update the reference copy directory, an element must be set to
/REFERENCE_COPY. Thus, if these two conditions are met, each
transaction that creates a new main line element generation
also updates the reference copy directory.
14.6 – RESERVATION
Changes the characteristics of a specified reservation.
Format:
MODIFY RESERVATION element-expression /qualifier "remark"
14.6.1 – Restrictions
o You must specify the following qualifier: /REMARK.
14.6.2 – Command Parameters
element-expression
Specifies one or more elements whose reservation reservations are
to be modified. An element expression can be an element name, 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. Note that this parameter
and the string on the /REMARK qualifier are unrelated.
14.6.3 – Description
The MODIFY RESERVATION command changes the remark that is
associated with a particular reservation of one or more
elements. Use the SHOW RESERVATIIONS command to display
reservation characteristics.
14.6.4 – Qualifiers
14.6.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.
14.6.4.2 /GENERATION[=generation-expression]
Specifies which reserved generation of the element is to be
modified. If you have more than one reservation of the same
element generation, you must use the /IDENTIFICATION_NUMBER
qualifier to identify the reservation.
14.6.4.3 /IDENTIFICATION_NUMBER=n
Specifies which reservation is to be modified. This qualifier
is required when you have multiple reservations of the same
generation of an element. /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
before the user name.
14.6.4.4 /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.
14.6.4.5 /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.
14.6.4.6 /REMARK="string"
Specifies a new remark to be substituted for the remark that is
associated with the reservation. This qualifier is required.
14.6.5 – Example
CMS> MODIFY RESERVATION/GENERATION=5/REMARK="Add new feature"
_Element expression: SPEC.TXT
_Remark: Modify the reservation remark
%CMS-S-MODIFIED, reservation SPEC.TXT modified
This command specifies a new remark to be substituted for the
reservation remark that was specified when generation 5 of
element SPEC.TXT was reserved. You must also specify the element
expression, and its associated remark, which is logged in the
history file.
15 – REJECT
15.1 – GENERATION
Changes the review status of each specified element generation
from "pending" to "rejected" and removes it from the review
pending list.
Format:
REJECT GENERATION element-expression "remark"
15.1.1 – Command Parameters
element-expression
Specifies one or more elements whose generations are to be
rejected. An element expression can be an element name, a group
name, a wildcard expression, or a list of these separated by
commas.
remark
Specifies a character string to be associated with the element
generation specified, to be logged in the history file with this
command. The remark is enclosed in quotation marks. If no remark
was entered, a null remark ("") is logged.
15.1.2 – Description
The REJECT GENERATION command changes the review status of
each specified element generation from "pending" to "rejected"
and removes it from the review pending list. You can use this
command only on element generations that have reviews pending
(see the description of the REVIEW GENERATION command for more
information).
If you attempt to reserve a generation that has been rejected,
CMS issues a message stating that the generation was rejected,
and then prompts you for confirmation. Additionally, further
generations created from a rejected generation are marked for
review, regardless of the element's review attribute.
15.1.3 – Qualifiers
15.1.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.
15.1.3.2 /GENERATION[=generation-expression]
Specifies a particular generation of the element to be rejected.
If you omit /GENERATION, CMS rejects the most recently created
generation with a review pending. You specify this qualifier only
if more than one generation of an element is under review.
15.1.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.
15.1.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, 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.
15.1.4 – Example
$ CMS REJECT GENERATION EXAMPLE.SDML "don't change this until
it is fixed"
%CMS-S-REJECTED, generation 1X1 of element
DISKX:[PROJECT.CMSLIB]EXAMPLE.SDML rejected
This command rejects the latest generation of EXAMPLE.SDML,
which was on the review pending list. This generation of
EXAMPLE.SDML remains rejected unless you specify a MARK
GENERATION command.
16 – REMARK
Places a remark in the library history.
Format:
REMARK "remark"
16.1 – Description
The REMARK command adds a remark to the library history. When you
let CMS prompt you for the remark, the length of the remark cannot
exceed 254 characters. When you issue the remark on the command
line, the length of the remark cannot exceed 256 characters. The
remark is recorded in the library history in the following format:
date time username REMARK "remark"
16.2 – Qualifiers
16.2.1 /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.
16.2.2 /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 OTHER
OTHER (D)
NOOTHER
NONE--equivalent to NOOTHER
You can specify either ALL, NONE, or the [NO]OTHER keyword.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object.
16.2.3 /UNUSUAL
Specifies that the remark string placed in the history file be
marked as an unusual occurrence, so that it appears marked with an
asterisk in the output from SHOW HISTORY and is included in the
output from a SHOW HISTORY/UNUSUAL command.
16.3 – Example
CMS> REMARK "all transactions from this point use modules for
new system"
%CMS-S-REMARK, remark added to history file
This command adds the remark enclosed in quotation marks to the
library history.
17 – REMOVE
17.1 – ELEMENT
Removes one or more elements from one or more groups.
Format:
REMOVE ELEMENT element-expression group-expression "remark"
17.1.1 – Restrictions
o You cannot remove elements from a group that has read-only
access (see the description of the MODIFY GROUP command).
17.1.2 – Command Parameters
element-expression
Specifies one or more elements to be removed from one or more
groups. An element expression can be an element name, a group
name, a wildcard expression, or a list of these separated
by commas. When you use wildcard characters in the element
expression, /IF_PRESENT is the default. (CMS does not return an
error message if the group does not contain the element being
removed.)
group-expression
Specifies the group from which one or more elements are to be
removed. 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.
17.1.3 – Description
The REMOVE ELEMENT command removes one or more elements from one
or more groups. The command does not delete the elements from
the library, but there is no longer any association between the
elements and the groups.
17.1.4 – Qualifiers
17.1.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.
17.1.4.2 /IF_PRESENT
Directs CMS to remove the element from the group if it belongs to
the group. If the element does not belong to the group, CMS takes
no action and does not return an error. When you use wildcard
characters in the element expression, /IF_PRESENT is the default.
17.1.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.
17.1.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.
17.1.5 – Example
CMS> REMOVE ELEMENT *.* A2 "remove all elements from group"
%CMS-S-REMOVED, element DISKX:[PROJECT.CMSLIB]SEARCH.FOR
removed from group DISKX:[PROJECT.CMSLIB]A2
%CMS-S-REMOVED, element DISKX:[PROJECT.CMSLIB]ARGCHK.FOR
removed from group DISKX:[PROJECT.CMSLIB]A2
.
.
.
This command removes all the elements from the group A2.
17.2 – GENERATION
Removes one or more element generations from one or more classes.
Format:
REMOVE GENERATION element-expression class-expression "remark"
17.2.1 – Restrictions
o You cannot remove a generation from a class with read-only
access (see the description of the MODIFY CLASS command).
17.2.2 – Command Parameters
element-expression
Specifies one or more generations of elements to be removed from
one or more classes. An element expression can be an element
name, a group name, a wildcard expression, or a list of these
separated by commas. When you use wildcard characters in the
element expression, /IF_PRESENT is the default. (CMS does not
return an error message if the class does not contain a generation
of the element.)
class-expression
Specifies the class from which the element generation is to
be removed. The class must not have read-only access. 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.
17.2.3 – Description
The REMOVE GENERATION command removes an element generation from a
class. The command does not delete the element generation from the
library, but the element generation is no longer associated with
the class.
To remove one element generation from a class and replace it with
another generation of the same element, use the INSERT GENERATION
command with the /SUPERSEDE qualifier.
17.2.4 – Qualifiers
17.2.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.
17.2.4.2 /GENERATION[=generation-expression]
Directs CMS to remove a particular generation of an element
from one or more classes in the library. The generation must
be currently existing in the class. If you use a wildcard or a
list of class names for the class expression, CMS deletes the
particular generation from each specified class.
17.2.4.3 /IF_PRESENT
Directs CMS to remove any generation of the element that exists
in the class. If the class does not contain a generation from the
element, CMS takes no action and does not return an error. When
you use wildcard characters in the element expression, /IF_PRESENT
is the default.
17.2.4.4 /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.
17.2.4.5 /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.
17.2.5 – Example
CMS> REMOVE GENERATION USER.DOC PRE_RELEASE_V3
_Remark: internal documentation is online
%CMS-S-GENREMOVED, generation 2 of element
DISKX:[PROJECT.CMSLIB]USER.DOC removed from class
DISKX:[PROJECT.CMSLIB]PRE_RELEASE_V3
This example removes generation 2 of USER.DOC from class PRE_
RELEASE_V3.
17.3 – GROUP
Removes one or more groups from another group or groups.
Format:
REMOVE GROUP group-expression1 group-expression2 "remark"
17.3.1 – Restrictions
o You cannot remove a group from a group with read-only access
(see the description of the MODIFY GROUP command).
17.3.2 – Command Parameters
group-expression1
Specifies one or more groups to be removed. Wildcards and a comma
list are allowed. When you use wildcard characters or a comma
list in the group name, /IF_PRESENT is the default. (CMS does
not return an error message if group-expression2 does not contain
group-expression1.)
group-expression2
Specifies one or more groups from which the groups in group-
expression1 are to be removed. Wildcards and a comma list are
allowed.
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.
17.3.3 – Description
The REMOVE GROUP command removes a group from another group. The
command does not delete the group from the library, but there is
no longer any association between the two groups. Removing group
A from group B means that the contents of group A are no longer
accessible through group B.
17.3.4 – Qualifiers
17.3.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.
17.3.4.2 /IF_PRESENT
Directs CMS to remove group-expression1 only if it belongs to
group-expression2. If group-expression1 does not belong to group-
expression2, CMS takes no action and does not return an error.
When you use wildcard characters or a comma list in the group
name, /IF_PRESENT is the default.
17.3.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.
17.3.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 GROUP
GROUP (D)
NOGROUP
NONE--equivalent to NOGROUP
You can specify either ALL, NONE, or the [NO]GROUP keyword.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object.
17.3.5 – Example
CMS> REMOVE GROUP A1 A2 "remove group from group"
%CMS-S-REMOVED, group DISKX:[PROJECT.CMSLIB]A1 removed from group
DISKX:[PROJECT.CMSLIB]A2
This command removes group A1 from group A2.
18 – REPLACE
Returns each specified element reservation to the library and
creates a new generation of the element.
Format:
REPLACE element-expression "remark"
18.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.
18.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.
18.3 – Qualifiers
18.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.
18.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.
18.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.
18.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.
18.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.
18.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.
18.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.
18.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.
18.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.
18.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.
18.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.
18.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.
19 – RESERVE
Retrieves a copy of each specified element generation from a CMS
library and marks it as reserved.
Format:
RESERVE element-expression "remark"
19.1 – Command Parameters
element-expression
Specifies the element or elements from which a generation is
to be reserved. An element expression can be an element name,
a group name, a wildcard expression, or a list of these separated
by commas. By default, CMS reserves the most recent generation
on the main line of descent of each element designated by the
element-expression.
remark
Specifies a character string to be associated with the reservation
and logged in the history file with this command. The remark is
enclosed in quotation marks. If no remark was entered, a null
remark ("") is logged.
19.2 – Description
The RESERVE command sends a copy of the specified generation of
each specified element to your current default directory (or to
another location if you specified the /OUTPUT qualifier). Each
element is marked as reserved. Usually, after you have modified
the file, you return your changes to the library with the REPLACE
command. Alternatively, you can cancel the reservation with the
UNRESERVE command.
You can reserve more than one generation of the same element if
concurrent reservations are allowed. If a generation of an
element is reserved by you or another user, or a
generation of the element is under review or has been rejected,
CMS displays the current reservations and review comments, and
prompts whether you want to proceed with the command. If you
type YES, you are added to the list of current reservers. The
transaction is recorded as an unusual occurrence.
If you type NO or press RETURN, no action is taken.
If a version of the output file exists in your default directory
when you issue the RESERVE command, CMS notifies you. A new
version is then created with the next higher version number.
When you retrieve a generation of an element from a CMS library,
CMS restores the file creation and revision times. The file that
is placed in your directory has the same creation and revision
times as the file that was used to create the generation that
you are reserving. If you specify /MERGE, the file placed in your
default directory has the current creation and revision times.
19.3 – Qualifiers
19.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.
You cannot use /NOCONFIRM to override the prompt generated when
you attempt to reserve a generation of an element that is already
reserved by you or by another user.
19.3.2 /GENERATION[=generation-expression]
Specifies a particular generation of the element that is to be
reserved. If you omit /GENERATION, CMS reserves the most recent
generation on the main line of descent.
19.3.3 /HISTORY="string"
Specifies that history is to be included in the retrieved file.
The quoted string specifies the format of the history. The quoted
string must contain the characters #H or #B (lowercase is allowed)
and can contain other printing characters. To include a quotation
mark in the output history string, type it twice (""). To include
a number sign (#) in the output history string, type it twice
(##).
19.3.4 /NOHISTORY
Prevents CMS from including the element history in the file. If
you omit /NOHISTORY, and the retrieved element has the history
attribute, CMS includes the element history in the output file. An
element has the history attribute if the /HISTORY qualifier was
specified on the CREATE ELEMENT or MODIFY ELEMENT command.
19.3.5 /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.
19.3.6 /MERGE=generation-expression
Controls whether another generation of the element (called the
merge generation) is to be merged with the generation that is
being reserved (called the retrieved generation).
If you specify the /MERGE qualifier, CMS merges the lines of the
two generations and delivers a single copy of the file to your
default directory. The file that is placed in your directory has
the current creation and revision times. The merge generation
cannot be on the same line of descent as the retrieved generation.
When there is a conflict between blocks of one or more lines, CMS
includes the conflicting lines and flags the conflict.
19.3.7 /NOCONCURRENT
Specifies that the element cannot be reserved by another user
while you have it reserved. You must replace or unreserve the
element before others can reserve it. By default, CMS allows
concurrent reservations if the element has the concurrent
attribute set.
19.3.8 /NOTES="string"
Specifies that notes are to be appended to the lines of the
file as it is retrieved by the RESERVE operation. This qualifier
overrides the element's nonotes attribute, if one was established.
The quoted string specifies the format of the note. The quoted
string can contain text or the characters #G (or #g), or both.
If you specify /NOTES for an element that does not have the notes
attribute enabled, then you must also specify /POSITION.
19.3.9 /NONOTES
Specifies that notes are not to be embedded in the output file.
If you omit /NONOTES, and the retrieved element has the notes
attribute, CMS embeds notes in the output file. An element has
the notes attribute if the /NOTES qualifier was specified on the
CREATE ELEMENT or MODIFY ELEMENT command.
19.3.10 /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.
19.3.11 /OUTPUT[=file-specification]
Directs CMS to write output to the specified file. If you omit the
/OUTPUT qualifier (or if you specify /OUTPUT but do not provide a
file specification), CMS creates a file with the same name as the
element in your default directory.
If you reserve more than one element (by specifying wildcards or a
group name for the element expression parameter), and you do not
specify wildcards in the output file specification, CMS creates
successive versions of the file indicated by /OUTPUT.
19.3.12 /NOOUTPUT
Specifies that the generation is to be reserved, but that no
output file is to be created.
19.3.13 /POSITION=column-number
Specifies the column in which the note is to be placed. The column
number is required and must be an integer in the range 1 to 511.
The notes attribute or the /NOTES qualifier is required with the
/POSITION qualifier.
If the length of the line is less than the specified column
number, the note appears at the column number. If the length of
the line is greater than or equal to the column number, the note
is placed at the next tab stop after the end of the line. (Tab
stops are at positions 9 and every 8 characters thereafter.)
19.4 – Examples
(1) CMS> RESERVE FILEIO.BLI
_Remark: fix temporary descriptor bug
%CMS-S-RESERVED, generation 13 of element
DISKX:[PROJECT.CMSLIB]FILEIO.BLI reserved
This command reserves generation 13 of the element FILEIO.BLI.
When the element is replaced, a successor generation is
created.
(2) CMS> RESERVE SYNTAX.PAS
_Remark: add syntax for RECORD declaration
Element SYNTAX.PAS currently reserved by:
(1) JERRYH 1 24-JUL-1988 16:17:45 "implement FOR
loop syntax"
Proceed? [Y/N] (N): YES
%CMS-S-RESERVED, generation 1 of element
DISKX:[PROJECT.CMSLIB]SYNTAX.PAS reserved
This example creates a concurrent reservation for the element
SYNTAX.PAS. Because you type YES in response to the Proceed
prompt, generation 1 of the element is reserved.
(3) CMS> RESERVE COPY.BLI/GENERATION=12/MERGE=11A1
_Remark:merging new I/O routines with library self checking
%CMS-W-MERGECONFLICT, 31 changes successfully merged
with 3 conflicts
%CMS-S-RESERVED, generation 12 of element
DISKX:[PROJECT.CMSLIB]COPY.BLI reserved and merged with
generation 11A1
This command merges generation 11A1 into generation 12 of the
element COPY.BLI and reserves generation 12. The version that
is delivered to the user directory contains the changes from
both generations. Thirty-one changes were successfully merged.
There were three conflicts between the two generations. These
conflicts must be resolved by editing the file.
20 – RETRIEVE
20.1 – ARCHIVE
Retrieves one or more generations from one or more archive files.
Format:
RETRIEVE ARCHIVE file-expression
20.1.1 – Command Parameters
file-expression
Specifies the name of the archive file. The file expression can be
a file-name.type specification, a wildcard expression, or a list
of these separated by commas.
20.1.2 – Description
The RETRIEVE ARCHIVE command retrieves one or more generations of
an element from one or more archive files. By default, CMS
retrieves the highest numbered generation from the archive file
and places a copy of the generation in your default directory
with the same file name and type as the element whose generation
was originally deleted (unless you specify another name or location
with the /OUTPUT qualifier). You can indicate a specific generation
to be retrieved with the /GENERATION qualifier. CMS creates one
file for each retrieved generation. You do not need to have a
library currently set to use this command, because the RETRIEVE
ARCHIVE command does not interact with the CMS library.
20.1.3 – Qualifiers
20.1.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.
20.1.3.2 /GENERATION[=generation-expression]
Specifies a particular generation to be retrieved from the archive
file. If you omit /GENERATION, CMS retrieves the highest numbered
generation in the archive file.
20.1.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.
20.1.3.4 /OUTPUT[=file-specification]
Directs CMS to write output to the specified file. If you omit the
/OUTPUT qualifier (or if you specify /OUTPUT but do not provide a
file specification), CMS creates a file with the same name as the
archived element and the file type .CMS_ARCHIVE.
If you retrieve generations from more than one archive file and
you do not specify wildcards in the output file specification, CMS
creates successive versions of the file indicated by /OUTPUT.
20.1.4 – Example
CMS> RETRIEVE ARCHIVE/GENERATION=2A3 SAMPLE.CMS_ARCHIVE
%CMS-S-RETRIEVED, generation 2A3 of element
DISKX:[PROJECT.CMSLIB]SAMPLE.PAS retrieved from
DISKX:[WORK]SAMPLE.CMS_ARCHIVE;1
This command retrieves generation 2A3 from the file SAMPLE.CMS_
ARCHIVE in your default directory. CMS names generation 2A3
to its original element name SAMPLE.PAS and places it in your
default directory.
21 – REVIEW
21.1 – GENERATION
Associates a review comment with one or more specified element
generations.
Format:
REVIEW GENERATION element-expression "remark"
21.1.1 – Restrictions
o This command can be used only on element generations that have
reviews pending.
21.1.2 – Command Parameters
element-expression
Specifies one or more elements. An element expression can be an
element name, 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.
21.1.3 – Description
The REVIEW GENERATION command associates a review remark with the
specified element generation. The review status of the generation
must be "pending." You can display the remarks associated with the
generation by issuing the SHOW REVIEWS_PENDING command.
21.1.4 – Qualifiers
21.1.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.
21.1.4.2 /GENERATION[=generation-expression]
Specifies the generation of the element with which to associate
the review remark. If you omit /GENERATION, CMS uses the most
recently created generation with a review pending. You specify
this qualifier only if more than one generation of an element is
under review.
21.1.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.
21.1.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, 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.
21.1.5 – Example
$ CMS REVIEW GENERATION EXAMPLE.SDML "looks ok to me--JEFF"
%CMS-S-REVIEWED, generation 3 of element
DISKX:[PROJECT.CMSLIB]EXAMPLE.SDML reviewed
In this example, the latest generation of the element
EXAMPLE.SDML is pending review; the REVIEW GENERATION command
allows users to associate review comments with that generation.
The generation can then be accepted, canceled, or rejected.
Use the SHOW REVIEWS_PENDING command to display all generations
under review in the library.
22 – SET
22.1 – ACL
Manipulates the access control list (ACL) on various objects in
the CMS library.
Format:
SET ACL object-expression /OBJECT_TYPE=type "remark"
22.1.1 – Command Parameters
object-expression
Specifies one or more objects whose ACL is to be modified.
Wildcards and a comma list are allowed.
The object name depends on the object type (see the /OBJECT_TYPE
qualifier). For example, if the object type is CLASS, the object
name is the name of a class in the CMS library. The same principle
applies to elements and groups. If the object type is LIBRARY, the
object expression must be a list of one or more of the following
keywords:
ELEMENT_LIST
CLASS_LIST
GROUP_LIST
HISTORY
LIBRARY_ATTRIBUTES
These keywords are referred to as object subtypes. You can
abbreviate object subtypes. Wildcards are not allowed.
The object name can also be the name of a CMS command. If /OBJECT_
TYPE is specified as COMMAND, SET ACL modifies the ACL on the
given command. Commands that contain two words must be specified
with an underscore, for example, INSERT_ELEMENT.
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.
22.1.2 – Description
The SET ACL command is used to manipulate ACLs on various objects
in the CMS library. ACLs can be put on elements, groups, and
classes, as well as on the lists containing these entities. (An
ACL on a list can be thought of as a directory ACL.) An ACL can be
put on the entire library, and on the library history. ACLs can
also be used to control access to individual CMS commands.
22.1.3 – Qualifiers
22.1.3.1 /ACL[=(ace[,...])]
Specifies one or more access control entries (ACEs) to be
modified. When no ACE is specified, the entire access control
list (ACL) is affected. Separate multiple ACEs with commas and
enclose the list in parentheses. The specified ACEs are inserted
at the beginning of the ACL unless the /AFTER qualifier is used.
22.1.3.2 /AFTER=ace
Indicates that all access control entries (ACEs) specified with
the /ACL qualifier are added after the ACE specified with the
/AFTER qualifier. By default, any ACEs added to the access control
list (ACL) are always placed at the top of the list.
22.1.3.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.
22.1.3.4 /DEFAULT
Creates an ACL for one or more specified objects as if the object
were newly created. The /DEFAULT qualifier propagates the DEFAULT
option ACEs in the ACL of the entity list to the ACL of the
specified object. This qualifier can be used only with an object
that is a library entity, that is, either an element, class, or
group.
22.1.3.5 /DELETE
Indicates that the access control entries (ACEs) specified with
the /ACL qualifier are to be deleted. If no ACEs are specified
with the /ACL qualifier, the entire ACL is deleted. If the /ACL
qualifier specifies an ACE that does not exist in the ACL of the
specified object, you are notified that the ACE does not exist,
and the delete operation continues on to the next ACE on the ACL,
if any exists.
22.1.3.6 /LIKE=object-specification
Indicates that the ACL of the specified object is to replace the
ACL of the object or objects specified with SET ACL. Any existing
ACEs are deleted before the ACL specified by /LIKE is copied.
The type of the source and destination objects must be the same.
No wildcard characters are allowed in the /LIKE parameter.
22.1.3.7 /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.
22.1.3.8 /NEW
Indicates that any existing ACEs in the ACL of the object
specified with SET ACL are to be deleted. To use the /NEW
qualifier, you must specify a new ACL or ACE with the /ACL
qualifier.
22.1.3.9 /OBJECT_TYPE=type
Specifies the type of the object whose ACL is being modified.
There is no default object type; therefore, this qualifier is
required. The type must be one of the following keywords:
CLASS
ELEMENT
GROUP
LIBRARY
COMMAND
22.1.3.10 /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, OTHER)
ELEMENT (D)
NOELEMENT
GROUP (D)
NOGROUP
CLASS (D)
NOCLASS
OTHER (D)
NOOTHER
NONE--equivalent to (NOELEMENT, NOGROUP, NOCLASS, NOOTHER)
You can specify either ALL or NONE, or any combination of the
[NO]ELEMENT, [NO]GROUP, [NO]CLASS, and [NO]OTHER keywords.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object.
22.1.3.11 /REPLACE=(ace[,...])
Deletes the access control entries (ACEs) specified with the /ACL
qualifier and replaces them with those specified with /REPLACE.
Any ACEs specified with the /ACL qualifier must exist and must be
specified in the order in which they appear in the current ACL.
22.1.4 – Examples
(1) CMS> SET ACL/OBJECT=ELEMENT SAMPLE.PAS/ACL=(IDENTIFIER=WALLEN, -)
_CMS> ACCESS=RESERVE+CONTROL "setting up acl on element"
%CMS-S-MODACL, modified access control list for element
DISKX:[PROJECT.CMSLIB]SAMPLE.PAS
This command assigns an ACL on the element SAMPLE.PAS,
specifying that the user holding the identifier WALLEN has
reserve and control access on the element.
(2) CMS> SET ACL/OBJECT=LIBRARY ELEMENT_LIST/ACL=((IDENTIFIER=WALLEN, -)
_CMS> OPTIONS=DEFAULT,ACCESS=FETCH,(IDENTIFIER=WALLEN, -)
_CMS> ACCESS=CREATE+CONTROL))
_Remark: assign ACEs to newly created elements
%CMS-S-MODACL, modified access control list for subtype
DISKX:[PROJECT.CMSLIB]ELEMENT_LIST
This example shows how to assign two separate ACEs on the
element list. The first ACE specifies a default ACE to be
inherited by newly created elements in the library. The second
ACE allows the user holding the identifier WALLEN to create
elements in the library.
(3) CMS> SET ACL/OBJECT=ELEMENT/DEFAULT SAMPLE.PAS
_Remark: inherit default ACEs from element list
%CMS-S-MODACL, modified access control list for element
DISKX:[PROJECT.CMSLIB]SAMPLE.PAS
CMS> SHOW ACL/OBJECT=ELEMENT SAMPLE.PAS
ACLs in CMS Library DISKX:[PROJECT.CMSLIB]
SAMPLE.PAS
(IDENTIFIER=[PROJECT,WALLEN],ACCESS=FETCH)
The SET ACL command causes the default ACE from the element
list (see example 2) to be placed on the element SAMPLE.PAS.
The SHOW ACL command displays the ACE on element SAMPLE.PAS
(which is now assigned the default ACE from the element list in
example 2).
(4) CMS> SET ACL/OBJECT=CLASS BL1/ACL=(IDENTIFIER=[DEV,*]+LIBRARIAN, -)
_CMS> ACCESS=INSERT+REMOVE
_Remark: allow access to class for library employees
%CMS-S-MODACL, modified access control list for class
DISKX:[PROJECT.CMSLIB]BL1
This command assigns an ACL allowing insert and remove access
to class BL1 for users in group DEV holding the LIBRARIAN
identifier.
(5) CMS> SET ACL/OBJECT=CLASS/LIKE=BL1 BL2
_Remark: put ACL from class BL1 on class BL2
%CMS-S-MODACL, modified access control list for class
DISKX:[PROJECT.CMSLIB]BL2
CMS> SHOW ACL/OBJECT=CLASS
ACLs in CMS Library DISKX:[PROJECT.CMSLIB]
BL1
(IDENTIFIER=[DEV,*]+LIBRARIAN,ACCESS=INSERT+REMOVE)
BL2
(IDENTIFIER=[DEV,*]+LIBRARIAN,ACCESS=INSERT+REMOVE)
In this example, the /LIKE qualifier causes the ACL from the
class BL1 (see example 4) to be placed on the class BL2. The
SHOW ACL command displays the ACL on both classes BL1 and BL2.
22.2 – LIBRARY
Enables access to an existing CMS library or libraries. Subsequent
CMS commands automatically refer to the libraries identified by
this command.
Format:
SET LIBRARY directory-specification[,...]
22.2.1 – Command Parameters
directory-specification
Specifies one or more existing CMS libraries. The directory
that is used as the CMS library cannot be your current default
directory. The directory specification must conform to OpenVMS
conventions; it can also be a logical name. If you specify
more than one OpenVMS directory, you must separate the directory
specifications with commas. Wildcards are not allowed.
22.2.2 – Description
The SET LIBRARY command enables access to an existing CMS library
or list of libraries. Subsequent CMS commands automatically refer
to the library or libraries identified in the SET LIBRARY command.
The SET LIBRARY command defines logical names beginning with CMS$
that allow CMS commands to refer implicitly to the library. You
should not define logical names beginning with CMS$ because this
prefix is reserved for CMS.
The SET LIBRARY command performs some consistency checks on the
directory to verify that it is a valid CMS library (unless you
specify the /NOVERIFY qualifier). If the library is not valid, you
receive an error message.
The library must have been created with the CREATE LIBRARY
command. During each session in which you want to use your CMS
library, you must use the SET LIBRARY command before you access
a library. The command is not required, however, if you have
just created a library (see the description of the CREATE LIBRARY
command) because the CREATE LIBRARY command performs an implicit
SET LIBRARY.
You create a search list by specifying multiple libraries on
the SET LIBRARY command. This enables you to manipulate several
libraries with one command. You must include commas between the
directory specifications.
22.2.3 – Qualifiers
22.2.3.1 /AFTER[=directory-specification]
Instructs CMS to insert new libraries into the existing library
search list (that you previously specified by using a comma list
with the CREATE LIBRARY or SET LIBRARY command) immediately
following the existing specified directory. If you omit the
directory specification, CMS adds the libraries to the end of
the list. You cannot specify both /AFTER and /BEFORE on the same
command line. By default, the SET LIBRARY command's library list
supersedes any existing search list.
22.2.3.2 /BEFORE[=directory-specification]
Instructs CMS to insert new libraries into the existing library
search list (that you previously specified by using a comma list
with the CREATE LIBRARY or SET LIBRARY command) immediately
in front of the existing specified directory. If you omit the
directory specification, CMS adds the libraries to the front of
the list. You cannot specify both /AFTER and /BEFORE on the same
command line. By default, the SET LIBRARY command's library list
supersedes any existing search list.
22.2.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.
22.2.3.4 /VERIFY (D)
Allows you to set a library without performing the locking and
verification process CMS normally performs. This speeds up the SET
LIBRARY operation and allows a CMS library to be set even if the
library is locked by another user. However, if the library needs
recovery, the condition is not detected until another transaction
is attempted.
22.2.4 – Examples
(1) CMS> SET LIBRARY [WORK.CMSLIB]
%CMS-S-LIBIS, CMS library is DISKX:[WORK.CMSLIB]
This command sets the CMS library to the existing library
[WORK.CMSLIB].
(2) CMS> SET LIBRARY [WORK.CMSLIB],[TEST.CMSLIB]
%CMS-I-LIBIS, library is DISK$:[WORK.CMSLIB]
%CMS-I-LIBINSLIS, library DISK$:[TEST.CMSLIB] inserted at
end of library list
%CMS-S-LIBSET, library set
-CMS-I-SUPERSEDE, library list superseded
This command sets (or resets, if there was an existing library
or libraries) the current library to contain two libraries.
(3) CMS> SET LIBRARY [PROJECT.CMSLIB]/AFTER=[WORK.CMSLIB]
%CMS-I-LIBINSLIS, library DISK$:[PROJECT.CMSLIB] inserted after
DISKX:[WORK.CMSLIB]
%CMS-S-LIBSET, library set
Assuming you set your library as in example 2, this command
directs CMS to insert the library [PROJECT.CMSLIB] after the
library [WORK.CMSLIB]. The library list now contains the three
libraries [WORK.CMSLIB], [PROJECT.CMSLIB], and [TEST.CMSLIB],
in that order. Use the SHOW LIBRARY command to display the
library search list.
22.3 – NOLIBRARY
Removes one or more libraries from the current library search
list.
Format:
SET NOLIBRARY directory-specification[,...]
22.3.1 – Command Parameters
directory-specification
Specifies one or more existing CMS libraries in the current
library search list. The directory specification must conform
to OpenVMS conventions; it can also be a logical name which translates
to a search list. If you specify more than one OpenVMS directory, you
must separate the directory specifications with commas. Wildcards
are not allowed. If you do not supply a directory specification,
CMS removes all libraries from the current library search list.
22.3.2 – Description
The SET NOLIBRARY command removes one or more libraries from
the current library search list. None of the directories in the
library search list can be your current default directory. If all
libraries are removed from the list, the logical name CMS$LIB is
deassigned.
22.3.3 – Qualifiers
22.3.3.1 /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.
22.3.4 – Example
CMS> SET NOLIBRARY
%CMS-W-UNDEFLIB, library is undefined
This example removes all existing libraries from the current
library search list.
23 – SHOW
23.1 – ACL
Displays the access control list (ACL) associated with the
specified object or objects.
Format:
SHOW ACL object-expression /OBJECT_TYPE=type
23.1.1 – Command Parameters
object-expression
Specifies the CMS library object whose ACL is to be displayed.
Wildcards and a comma list are allowed.
The object name depends on the object type (see the /OBJECT_TYPE
qualifier). For example, if the object type is CLASS, the object
name is the name of a class in the CMS library. The same principle
applies to elements and groups. If the object type is LIBRARY, the
object expression must be a list of one or more of the following
keywords:
ELEMENT_LIST
CLASS_LIST
GROUP_LIST
HISTORY
LIBRARY_ATTRIBUTES
These keywords are called object subtypes. You can abbreviate
object subtypes. Wildcards are not allowed.
The object name can also be the name of a CMS command. If /OBJECT_
TYPE is specified as COMMAND, SHOW ACL displays the ACL for the
given command.
23.1.2 – Description
The SHOW ACL command displays the ACL associated with the
specified object or objects.
23.1.3 – Qualifiers
23.1.3.1 /APPEND
Controls whether CMS appends the command output to an existing
file, or creates a new file. If you specify /APPEND and the output
file does not exist, CMS creates a new file. If you do not provide
a file specification (see the description for /OUTPUT), the output
is appended to SYS$OUTPUT.
23.1.3.2 /OBJECT_TYPE=type
Specifies the type of the object whose ACL is to be displayed.
There is no default object type; therefore, this qualifier is
required. The object type can be one of the following keywords:
ELEMENT
CLASS
GROUP
LIBRARY
COMMAND
23.1.3.3 /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, OTHER)
ELEMENT (D)
NOELEMENT
GROUP (D)
NOGROUP
CLASS (D)
NOCLASS
OTHER (D)
NOOTHER
NONE--equivalent to (NOELEMENT, NOGROUP, NOCLASS, NOOTHER)
You can specify either ALL or NONE, or any combination of the
[NO]ELEMENT, [NO]GROUP, [NO]CLASS, and [NO]OTHER keywords.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object.
23.1.3.4 /OUTPUT[=file-specification]
Directs CMS to write output to the specified file, except for any
warning and error messages, which are written to SYS$OUTPUT and
SYS$ERROR. CMS creates a new file if you do not specify /APPEND.
If you omit the /OUTPUT qualifier (or if you specify /OUTPUT
but do not provide a file specification), CMS directs output to
the default output device (SYS$OUTPUT). If you omit either the
file name or the file type component, CMS supplies the missing
component from the default specification.
23.1.4 – Example
CMS> SHOW ACL/OBJECT=ELEMENT SAMPLE.PAS
ACLs in CMS Library DISKX:[PROJECT.CMSLIB]
SAMPLE.PAS
(IDENTIFIER=[PROJECT,WALLEN],ACCESS=FETCH)
This command displays the ACE on element SAMPLE.PAS.
23.2 – ARCHIVE
Displays information about one or more archive files.
Format:
SHOW ARCHIVE file-expression
23.2.1 – Command Parameters
file-expression
Specifies the name of the archive file. The file expression can be
a file-name.type specification, a wildcard expression, or a list
of these separated by commas.
23.2.2 – Description
The SHOW ARCHIVE command displays information about the contents
of one or more specified archive files.
23.2.3 – Qualifiers
23.2.3.1 /APPEND
Controls whether CMS appends the command output to an existing
file, or creates a new file. If you specify /APPEND and the output
file does not exist, CMS creates a new file. If you do not provide
an output file specification (see the description for /OUTPUT),
the output is appended to SYS$OUTPUT.
23.2.3.2 /BRIEF
The /BRIEF qualifier displays the name of the element, the
generations archived into this file, the name of the person
who archived the file, the date and time, the remark entered on
the DELETE GENERATION command, and the name of the library in
which the original element resided.
23.2.3.3 /FULL
The /FULL qualifier displays complete generation file information
for each archived generation.
23.2.3.4 /INTERMEDIATE
The /INTERMEDIATE qualifier displays the generation history for
the archived generations.
23.2.3.5 /OUTPUT[=file-specification]
Directs CMS to write output to the specified file, except for any
warning and error messages, which are written to SYS$OUTPUT and
SYS$ERROR. CMS creates a new file if you do not specify /APPEND.
If you omit the /OUTPUT qualifier (or if you specify /OUTPUT
but do not provide a file specification), CMS directs output to
the default output device (SYS$OUTPUT). If you omit either the
file name or the file type component, CMS supplies the missing
component from the default specification.
23.2.4 – Examples
(1) CMS> SHOW ARCHIVE/BRIEF SAMPLE.CMS_ARCHIVE
25-JAN-1988 17:08:47 JONES DISKX:[WORK.CMSLIB]
SAMPLE.PAS(2A1--2A3) "delete the variant range and archive
the deleted generations"
This command displays information about the archive file,
consisting of the date and time entered with the DELETE
GENERATION command, the name of the person who archived the
file, the library in which the original element resided, the
generations that were archived into the file, and the remark
entered on the DELETE GENERATION command.
(2) CMS> SHOW ARCHIVE/FULL SAMPLE.CMS_ARCHIVE
25-JAN-1988 17:08:47 JONES DISKX:[WORK.CMSLIB] SAMPLE.PAS(2A1--2A3)
"delete the variant range and archive the deleted generations"
2A1 22-JAN-1988 14:27:41 JONES "reserved concurrently
to add routines"
File creation: 22-JAN-1988 14:27
File revision: 24-JAN-1988 17:12 (1)
Record format: Variable length
Record attributes: Carriage return carriage control
Review status: None
2A2 22-JAN-1988 14:36:56 JONES "another routine added"
File creation: 22-JAN-1988 14:36
File revision: 22-JAN-1988 18:01 (1)
Record format: Variable length
Record attributes: Carriage return carriage control
Review status: None
2A3 22-JAN-1988 14:45:12 JONES "last one I promise"
File creation: 22-JAN-1988 14:45
File revision: 27-JAN-1988 08:30 (1)
Record format: Variable length
Record attributes: Carriage return carriage control
Review status: None
This command displays complete generation file information for
each archived generation in the archive file.
23.3 – CLASS
Displays information about one or more classes in a CMS library.
Format:
SHOW CLASS [class-expression]
23.3.1 – Command Parameters
class-expression
Specifies one or more classes to be listed. If you do not specify
a class name, CMS lists all classes in the library. A class
expression can be a class name, a wildcard expression, or a list
of these separated by commas.
23.3.2 – Description
The SHOW CLASS command lists the names of all established classes
in alphabetical order, along with the associated creation remarks.
23.3.3 – Qualifiers
23.3.3.1 /APPEND
Controls whether CMS appends the command output to an existing
file, or creates a new file. If you specify /APPEND and the output
file does not exist, CMS creates a new file. If you do not provide
an output file specification (see the description for /OUTPUT),
the output is appended to SYS$OUTPUT.
23.3.3.2 /BRIEF
The /BRIEF qualifier displays only class names.
23.3.3.3 /CONTENTS
Controls whether CMS identifies the element generations that
belong to each class. If you specify /CONTENTS, CMS displays the
class name and the creation remark, along with the element name
and generation number for each generation in the class.
23.3.3.4 /FULL
The /FULL qualifier displays the name, creation remark, and
read-only attribute (if established) for each class.
23.3.3.5 /INTERMEDIATE
The /INTERMEDIATE qualifier displays the name and creation remark
for each class.
23.3.3.6 /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 CLASS
CLASS (D)
NOCLASS
NONE--equivalent to NOCLASS
You can specify either ALL, NONE, or the [NO]CLASS keyword.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object.
23.3.3.7 /OUTPUT[=file-specification]
Directs CMS to write output to the specified file, except for any
warning and error messages, which are written to SYS$OUTPUT and
SYS$ERROR. CMS creates a new file if you do not specify /APPEND.
If you omit the /OUTPUT qualifier (or if you specify /OUTPUT
but do not provide a file specification), CMS directs output to
the default output device (SYS$OUTPUT). If you omit either the
file name or the file type component, CMS supplies the missing
component from the default specification.
23.3.4 – Examples
(1) CMS> SHOW CLASS
Classes in CMS Library DISKX:[RELEASE.CMSLIB]
INTERNAL_RELEASE "for internal use only"
MESSAGETEST "filter evolution checks"
PASCAL_CLASS "PASCAL tests"
This command displays the class name and the creation remark
for each class in the library.
(2) CMS> SHOW CLASS/BRIEF
Classes in CMS Library DISKX:[RELEASE.CMSLIB]
INTERNAL_RELEASE MESSAGETEST PASCAL_CLASS
This command limits the output to class names only.
23.4 – ELEMENT
Displays information about one or more elements in a CMS library.
Format:
SHOW ELEMENT [element-expression]
23.4.1 – Command Parameters
element-expression
Specifies one or more elements to be listed. If you do not supply
an element expression, CMS lists all the elements in the library.
An element expression can be an element name, a group name, a
wildcard expression, or a list of these separated by commas.
23.4.2 – Description
The SHOW ELEMENT command lists the name of each specified element
in alphabetical order, along with the remark logged at the
time the element was created or modified. You can also specify
qualifiers that provide information about element attributes,
concurrent access, and the groups to which the element belongs.
23.4.3 – Qualifiers
23.4.3.1 /APPEND
Controls whether CMS appends the command output to an existing
file, or creates a new file. If you specify /APPEND and the output
file does not exist, CMS creates a new file. If you do not provide
an output file specification (see the description for /OUTPUT),
the output is appended to SYS$OUTPUT.
23.4.3.2 /BRIEF
The /BRIEF qualifier displays only element names.
23.4.3.3 /FORMAT="string"
Controls whether the output of the SHOW ELEMENT command is
formatted. You can use the /FORMAT qualifier in combination
with the /OUTPUT qualifier to set up a command file. With this
command file, you can execute a CMS command or a DCL command on a
specified set of elements (such as all elements in a group).
The format string can contain printing characters; within the
format string, CMS recognizes #E (and #e) as the element format
parameter. For each line of output (one line per element), CMS
displays the format string and replaces each occurrence of #E (or
#e) with the element name. To include a number sign in the output
line, type it twice (##). When you specify /FORMAT, CMS does
not generate the heading normally produced by the SHOW ELEMENT
command.
To set up a command file, you specify a format string consisting
of a command, including the dollar sign ($) prompt and the
element format parameter (for example, /FORMAT="$ CMS FETCH #E").
Use the /OUTPUT qualifier to direct the output to a command file.
When you execute the SHOW ELEMENT command with these qualifiers,
CMS creates a command file containing a list of FETCH commands
that use each element in the denoted set as parameters.
23.4.3.4 /FULL
The /FULL qualifier displays the name, creation remark, and the
attributes in effect for the specified elements.
23.4.3.5 /INTERMEDIATE
The /INTERMEDIATE qualifier displays the name and creation remark
associated with the element.
23.4.3.6 /MEMBER
Lists the element name, creation remark, and the names of any
groups to which the element belongs.
23.4.3.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)
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.
23.4.3.8 /OUTPUT[=file-specification]
Directs CMS to write output to the specified file, except for any
warning and error messages, which are written to SYS$OUTPUT and
SYS$ERROR. CMS creates a new file if you do not specify /APPEND.
If you omit the /OUTPUT qualifier (or if you specify /OUTPUT
but do not provide a file specification), CMS directs output to
the default output device (SYS$OUTPUT). If you omit either the
file name or the file type component, CMS supplies the missing
component from the default specification.
23.4.4 – Examples
(1) CMS> SHOW ELEMENT/BRIEF
Elements in CMS Library DISKX:[PROJECT.CMSLIB]
CCM.FOR CCM1.FOR COPYTEST.FOR
This command limits the output to element names only.
(2) CMS> SHOW ELEMENT/FORMAT="$ CMS FETCH #E"/OUTPUT=FETCH.COM
This command produces a file named FETCH.COM that contains a
fetch command for each element in the library. The contents of
a file produced by this command might look like the following:
$ CMS FETCH INIT.FOR
$ CMS FETCH INITX.FOR
$ CMS FETCH MSGDOC.FOR
$ CMS FETCH OUTPUT.FOR
$ CMS FETCH SEARCH.FOR
23.5 – GENERATION
Displays information about one or more element generations in a
CMS library.
Format:
SHOW GENERATION [element-expression]
23.5.1 – Restrictions
o You cannot specify the /ANCESTORS and /DESCENDANTS qualifiers
on the same command line.
o You cannot specify the /DESCENDANTS and /FROM qualifiers on the
same command line.
o If you specify the /FROM qualifier, you must also specify the
/ANCESTORS qualifier on the same command line.
23.5.2 – Command Parameters
element-expression
Specifies one or more elements. For each element, CMS lists the
transaction record of the most recent generation on the main line
of descent. If you do not supply an element expression, CMS lists
a transaction record for each element in the library. An element
expression can be an element name, a group name, a wildcard
expression, or a list of these separated by commas.
23.5.3 – Description
The SHOW GENERATION command lists information about a specific
generation of an element or a group of elements. By default, this
command displays the transaction record of the latest generation
on the main line of descent. You can also use SHOW GENERATION
to display the element name and generation number of all element
generations belonging to a specified group or class.
23.5.4 – Qualifiers
23.5.4.1 /ANCESTORS
Displays the transaction records of the specified element
generation and all of its ancestors. The transaction records are
listed in reverse chronological order. If you do not specify a
particular generation, the list begins with the latest generation
on the main line of descent.
The ancestors of a main line generation are all the preceding
generations back to the first generation of an element. The
ancestors of a variant-line generation are all preceding
generations on the variant line of descent, and any generations
back to the first generation on the main line.
23.5.4.2 /APPEND
Controls whether CMS appends the command output to an existing
file, or creates a new file. If you specify /APPEND and the output
file does not exist, CMS creates a new file. If you do not provide
an output file specification (see the description for /OUTPUT),
the output is appended to SYS$OUTPUT.
23.5.4.3 /BEFORE=date-time
Displays all of the generation information before a specified time.
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.
23.5.4.4 /BRIEF
The /BRIEF qualifier displays only element names and
generation numbers for each specified generation.
23.5.4.5 /DESCENDANTS
Displays the transaction records of the specified element
generation and of all its descendants. The transaction records
are listed in reverse chronological order. If you do not specify a
particular generation, the list begins with generation 1.
The descendants of a generation consist of all the successor
generations, including those that on variant lines of descent.
Thus, you can use this command to determine whether any variant
lines of descent exist for a particular element.
23.5.4.6 /FORMAT="string"
Controls whether the output of the SHOW GENERATION command is
formatted. You can use the /FORMAT qualifier in combination
with the /OUTPUT qualifier to set up a command file. With this
command file, you can execute a CMS command or a DCL command on a
specified set of elements (such as all elements in a class).
The format string can contain printing characters; within the
format string, CMS recognizes #E (and #e) as the element format
parameter, and #G (and #g) as the generation number format
parameter. For each line of output (one line per generation),
CMS displays the format string and replaces each occurrence of #E
or #G with the element name or generation number, respectively.
To include a number sign in the output line, type it twice (##).
When you specify the /FORMAT qualifier, CMS does not generate the
heading normally produced by the SHOW GENERATION command.
To set up a command file, you specify a format string consisting
of a command, including the dollar sign ($) prompt and a
format parameter (#E or #G) (for example, /FORMAT="$ CMS FETCH
#E/GENERATION=#G"). Use the /OUTPUT qualifier to direct the output
to a command file. When you execute the SHOW GENERATION command
with these qualifiers, CMS creates a command file containing a
list of FETCH commands that use each element in the denoted set as
parameters.
23.5.4.7 /FROM=generation-expression
Specifies the generation that begins the list of ancestors. You
must specify the /ANCESTORS and /FROM qualifiers on the same
command.
23.5.4.8 /FULL
The /FULL qualifier displays standard CMS transaction information
(the element name, generation number, date, time, user, and remark),
and also produces information about the file creation and revision
date and time, the file revision number, and the record format and
attributes.
23.5.4.9 /GENERATION[=generation-expression]
Specifies the generation about which you want information. When
you use the /GENERATION qualifier with the element-name parameter,
the transaction record of the indicated generation is displayed.
23.5.4.10 /INTERMEDIATE
The /INTERMEDIATE qualifier displays the element name, generation
number, date, time, user, and remark associated with the transaction
that created the generation.
23.5.4.11 /MEMBER
Lists the element name, generation number, and the names of any
classes to which the element generation belongs.
23.5.4.12 /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.
23.5.4.13 /OUTPUT[=file-specification]
Directs CMS to write output to the specified file, except for any
warning and error messages, which are written to SYS$OUTPUT and
SYS$ERROR. CMS creates a new file if you do not specify /APPEND.
If you omit the /OUTPUT qualifier (or if you specify /OUTPUT
but do not provide a file specification), CMS directs output to
the default output device (SYS$OUTPUT). If you omit either the
file name or the file type component, CMS supplies the missing
component from the default specification.
23.5.4.14 /SINCE=date-time
Displays all of the generation information since a specified time.
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.
23.5.5 – Examples
(1) CMS> SHOW GENERATION/BRIEF
Element generations in CMS Library DISKX:[TAYLOR.CMSLIB]
CCM.FOR/2 CCM1.FOR/1 COPYTEST.FOR/2
This command directs CMS to display only the element name
and the number of the latest main line generation for each
element. Because no element is specified in the command line,
CMS displays information about all elements in the library.
(2) CMS> SHOW GENERATION CCM.FOR
Element generations in CMS Library DISKX:[TAYLOR.CMSLIB]
CCM.FOR 2 7-DEC-1988 14:15:51 SMITH "header changed"
This command displays the element name, generation number,
date, time, and remark associated with the latest main line
generation for element CCM.FOR.
(3) CMS> SHOW GENERATION/FULL CCM.FOR
Element generations in CMS Library DISKX:[TAYLOR.CMSLIB]
CCM.FOR 2 6-MAR-1988 17:34:04 SMITH "header changed"
File creation: 6-MAR-1988 17:24
File revision: 6-MAR-1988 17:24 (1)
Record format: Variable length
Record attributes: Carriage return carriage control
This command produces information about the file creation
and revision date and time, the file revision number, and
the record format and attributes, in addition to the standard
CMS transaction information (element name, generation number,
date, time, user, and remark). This additional information
describes the file that was used to create the particular
element generation, in this case generation 2 of CCM.FOR.
(4) CMS> SHOW GENERATION/GENERATION=RELEASE5 -
_CMS> /FORMAT="$ CMS FETCH #E/GENERATION=#G" -)
_CMS> /OUTPUT=FETCH_CLASS.COM
This example produces a file named FETCH_CLASS.COM that
contains a fetch command for each element that belongs to
the class named RELEASE5. The FETCH command retrieves the
element of the correct generation from the RELEASE5 class. The
contents of a file produced by this command might look like the
following:
$ CMS FETCH INIT.FOR/GENERATION=6
$ CMS FETCH OUTPUT.FOR/GENERATION=7
$ CMS FETCH SEARCH.FOR/GENERATION=3
23.6 – GROUP
Displays information about one or more groups in a CMS library.
Format:
SHOW GROUP [group-expression]
23.6.1 – Command Parameters
group-expression
Specifies the group to be listed. If you do not supply a
group expression, CMS lists all groups in the library. A group
expression can be a group name, a wildcard expression, or a list
of these separated by commas.
23.6.2 – Description
The SHOW GROUP command lists the names of all established groups
in alphabetical order, along with the remark logged at the time
each group was created or modified.
23.6.3 – Qualifiers
23.6.3.1 /APPEND
Controls whether CMS appends the command output to an existing
file, or creates a new file. If you specify /APPEND and the output
file does not exist, CMS creates a new file. If you do not provide
an output file specification (see the description for /OUTPUT),
the output is appended to SYS$OUTPUT.
23.6.3.2 /BRIEF
The /BRIEF qualifier displays only group names.
23.6.3.3 /CONTENTS[=n]
Lists the group name and creation remark, along with the names of
any elements or groups contained within the specified group.
You can specify an integer value (n) that directs CMS to display
nested groups up or down to and including the level indicated by
n. When you specify /CONTENTS without a value, CMS displays one
level of contents. You can also specify /CONTENTS=ALL to display
all levels of contained groups.
23.6.3.4 /FULL
The /FULL qualifier displays the group name, creation remark, and
read-only attribute (if established) for each group.
23.6.3.5 /INTERMEDIATE
The /INTERMEDIATE qualifier displays the name and creation remark
associated with each group.
23.6.3.6 /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 GROUP
GROUP (D)
NOGROUP
NONE--equivalent to NOGROUP
You can specify either ALL, NONE, or the [NO]GROUP keyword.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object.
23.6.3.7 /OUTPUT[=file-specification]
Directs CMS to write output to the specified file, except for any
warning and error messages, which are written to SYS$OUTPUT and
SYS$ERROR. CMS creates a new file if you do not specify /APPEND.
If you omit the /OUTPUT qualifier (or if you specify /OUTPUT
but do not provide a file specification), CMS directs output to
the default output device (SYS$OUTPUT). If you omit either the
file name or the file type component, CMS supplies the missing
component from the default specification.
23.6.4 – Examples
(1) CMS> SHOW GROUP
Groups in CMS Library DISKX:[PROJECT.CMSLIB]
ARTWORK "graph display"
OUT_DEFS "output definition files"
TEST_ART "tests for graphs"
This command displays the group name and the creation remark
associated with the group, by default. Because no group name
is specified on the command line, CMS lists all groups in the
library.
(2) CMS> SHOW GROUP ARTWORK/CONTENTS
Groups in CMS Library DISKX:[WORK.CMSV3.CALL.TEST.CMSLIB]
ARTWORK "graph display"
5666.ARTWRK
CHAP_ART.TXT
FIG3.FIG
MODPARAM5.SDML
TEST_ART
This command produces a list of elements and groups that are
members of group ARTWORK. The group TEST_ART was inserted into
ARTWORK with the INSERT GROUP command; thus, as the contents of
TEST_ART change, the elements accessible in the group ARTWORK
change.
23.7 – HISTORY
Displays a chronological list of transactions performed on a
CMS library. You can limit the number of transactions that are
displayed by specifying different parameters and qualifiers on the
command.
Format:
SHOW HISTORY [object-expression]
23.7.1 – Command Parameters
object-expression
Specifies an object about which history information is to be
displayed. The object expression can be one or more class names,
element names, group names, a wildcard expression, or a list of
any of these, separated by commas. If you do not specify an object
expression, CMS lists all classes, elements, and groups in the
library.
23.7.2 – Description
The SHOW HISTORY command lists information about CMS library
transactions. CMS records all transactions that update the
library. The following transactions are not logged in the library
history:
ANNOTATE SET LIBRARY
DIFFERENCES SHOW commands
FETCH (no remark) VERIFY (no qualifiers)
RETRIEVE ARCHIVE
The SHOW HISTORY command displays a chronological list of
transactions. The transaction records are displayed in the
following format:
date time username command remark
A space separates each item in the transaction record. Each item
is explained below.
date
Displays the date the command was issued, in the following
format:
[d]d-mmm-yyyy
For example:
9-JUN-1988
time
Displays the time the command was issued, in the following
format:
hh:mm:ss
For example:
17:12:12
09:02:33
username
Displays the user name of the person who issued the command.
command
Identifies the command that was issued. The string "CMS" does
not appear as part of the command. The command name, option
name (if any), and any parameters are displayed. If the command
operates on a particular generation of an element, the element
name is followed by the generation number enclosed in parentheses;
for example, SEMANTICS.PAS(3). Qualifiers that indicate some
modification of the library are logged; for example, the /NAME
qualifier with a MODIFY command.
remark
Specifies a character string that was 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 displayed.
The following is an example of one transaction record:
11-AUG-1988 11:54:15 TAYLOR REPLACE SYNTAX.PAS(3) "RECORD and FOR
loop syntax compatible"
This record shows that on August 11, 1988, at 11:54, user TAYLOR
issued the REPLACE command on SYNTAX.PAS, which created generation
3.
For any command that caused an unusual occurrence, CMS displays an
asterisk in the first column.
Note that because transaction records for elements, groups, or
classes deleted from a library are retained (see DELETE ELEMENT,
DELETE GROUP, and DELETE CLASS), SHOW HISTORY can display records
for elements and classes that do not currently exist. If a deleted
name is reused, SHOW HISTORY does not distinguish between the old
and the new histories.
23.7.3 – Qualifiers
23.7.3.1 /APPEND
Controls whether CMS appends the command output to an existing
file, or creates a new file. If you specify /APPEND and the output
file does not exist, CMS creates a new file. If you do not provide
an output file specification (see the description for /OUTPUT),
the output is appended to SYS$OUTPUT.
23.7.3.2 /BEFORE=date-time
Lists all history information prior to a specified date. By
default, the time is the current date and time. The time value
can be an absolute, delta, or combination time value, or one of
the following keywords: TODAY, TOMORROW, or YESTERDAY.
23.7.3.3 /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 OTHER
OTHER (D)
NOOTHER
NONE--equivalent to NOOTHER
You can specify either ALL, NONE, or the [NO]OTHER keyword.
By default, CMS performs occlusion for all objects; that is, CMS
selects only the first occurrence of a specified object.
23.7.3.4 /OUTPUT[=file-specification]
Directs CMS to write output to the specified file, except for any
warning and error messages, which are written to SYS$OUTPUT and
SYS$ERROR. CMS creates a new file if you do not specify /APPEND.
If you omit the /OUTPUT qualifier (or if you specify /OUTPUT
but do not provide a file specification), CMS directs output to
the default output device (SYS$OUTPUT). If you omit either the
file name or the file type component, CMS supplies the missing
component from the default specification.
23.7.3.5 /SINCE=date-time
Specifies that only those history entries dated on or after the
given time are to be displayed. The time value can be an absolute,
delta, or combination time value, or one of the following
keywords: TODAY, TOMORROW, or YESTERDAY. When the /SINCE qualifier
is omitted, all transactions that occurred since the library was
created are displayed. If you specify the /SINCE qualifier but do
not specify a value, CMS defaults to /SINCE=TODAY.
23.7.3.6 /TRANSACTIONS=(keyword,...)
23.7.3.7 /NOTRANSACTIONS=(keyword,...)
Displays all transaction records generated by a specific command.
You can specify the following keywords with this qualifier:
ACCEPT FETCH REMOVE
ALL INSERT REPLACE
CANCEL MARK RESERVE
COPY MODIFY REVIEW
CREATE REJECT SET
DELETE REMARK UNRESERVE
VERIFY
If you specify more than one keyword, you must enclose the keyword
list in parentheses. The /TRANSACTIONS qualifier directs CMS
to list transaction records for only the listed keywords. The
/NOTRANSACTIONS qualifier directs CMS to list transaction records
for all keywords except the listed keywords.
23.7.3.8 /UNUSUAL
Controls whether transactions recorded as unusual occurrences
are displayed. If you specify /UNUSUAL, only unusual transactions
are displayed. By default, /NOUNUSUAL displays all transactions,
including unusual occurrences. The following CMS transactions are
defined as unusual occurrences:
o A RESERVE command specifying an element that is already
reserved
o A concurrent replacement
o A VERIFY/RECOVER command
o A VERIFY/REPAIR command
o A CONVERT LIBRARY command
o A REMARK/UNUSUAL command
23.7.3.9 /USER=username
Lists the transactions executed by the specified user.
23.7.4 – Example
CMS> SHOW HISTORY
History of CMS Library DISKX:[PROJECTLIB]
15-JAN-1988 08:45:15 SNOW CREATE LIBRARY [PROJECTLIB] "code library"
25-JAN-1988 10:23:42 SNOW CREATE ELEMENT STRING.LIB(1) "string defs"
25-JAN-1988 13:37:57 SCHULTZ CREATE ELEMENT SIGNAL.LIB(1) "signaling
defs"
25-JAN-1988 14:09:37 PADDOCK CREATE ELEMENT CONVRT.BLI(1) "gen
conversion util"
26-JAN-1988 13:59:16 PADDOCK DELETE ELEMENT CONVRT.BLI "wrong format"
27-JAN-1988 10:51:05 PADDOCK CREATE ELEMENT CNVNUM.BLI(1) "conversion
routines"
10-FEB-1988 10:51:48 SNOW CREATE ELEMENT SYSUTL.BLI(1) "general
utilities"
21-FEB-1988 11:11:55 SNOW RESERVE STRING.LIB(1) "change definitions"
23-FEB-1988 11:22:31 SNOW REPLACE STRING.LIB(2) "added characters"
23-FEB-1988 11:23:41 PADDOCK RESERVE CNVNUM.BLI(1) "change constant
values"
23-FEB-1988 12:15:21 SNOW FETCH STRING.LIB(1) "check differences"
23-FEB-1988 12:20:42 PADDOCK REPLACE CNVNUM.BLI(2) "constant values
changed"
.
.
.
This command shows part of the early history of a library.
23.8 – LIBRARY
Displays the directory specification of the current CMS library.
SHOW LIBRARY also checks whether the directory is a valid CMS
library (unless you specify the /BRIEF qualifier).
Format:
SHOW LIBRARY
23.8.1 – Description
The SHOW LIBRARY command identifies the current CMS library. If
you have not designated a CMS library for the current session
(with SET LIBRARY or CREATE LIBRARY), this command issues an error
message.
23.8.2 – Qualifiers
23.8.2.1 /APPEND
Controls whether CMS appends the command output to an existing
file, or creates a new file. If you specify /APPEND and the output
file does not exist, CMS creates a new file. If you do not provide
an output file specification (see the description for /OUTPUT),
the output is appended to SYS$OUTPUT.
23.8.2.2 /BRIEF
The /BRIEF qualifier displays the directory specification (and
does not lock the library) even if the default library is locked
by another user. However, if the library needs recovery, it is
not detected until another operation is performed.
23.8.2.3 /FULL
The /FULL qualifier displays the current library directory
specification, the number of elements, groups, classes,
reservations, concurrent replacements, reviews pending, and
the current reference copy directory specification, if any.
23.8.2.4 /INTERMEDIATE
The /INTERMEDIATE qualifier displays the directory specification
of the current CMS library.
23.8.2.5 /OUTPUT[=file-specification]
Directs CMS to write output to the specified file, except for any
warning and error messages, which are written to SYS$OUTPUT and
SYS$ERROR. CMS creates a new file if you do not specify /APPEND.
If you omit the /OUTPUT qualifier (or if you specify /OUTPUT
but do not provide a file specification), CMS directs output to
the default output device (SYS$OUTPUT). If you omit either the
file name or the file type component, CMS supplies the missing
component from the default specification.
23.8.3 – Examples
(1) CMS> SHOW LIBRARY
Your CMS library list consists of:
DISKX:[PROJECT.CMSLIB]
This command displays the device and directory where the
current CMS library is located.
(2) CMS> SHOW LIBRARY/FULL
Your CMS library list consists of:
DISKX:[CODE.CMSLIB]
and contains
224 elements
4 groups
7 classes
6 reservations
0 concurrent replacements
5 reviews pending
REFERENCE_COPY directory is DISKX:[CODE.REQUIRE]
This command directs CMS to display additional information
about the contents of the library.
23.9 – RESERVATIONS
Displays all current reservations and concurrent replacements in
effect at the time the command is issued.
Format:
SHOW RESERVATIONS [element-expression]
23.9.1 – Command Parameters
element-expression
Specifies one or more elements for which CMS displays current
reservation and concurrent replacement information. If you do
not specify an element expression, information is displayed for
all elements. An element expression can be an element name, a
group name, a wildcard expression, or a list of these separated by
commas.
23.9.2 – Description
The SHOW RESERVATIONS command provides information about current
reservations and concurrent replacements. For each element that
has one or more generations reserved, the output consists of the
element name and the following:
o For each reservation--identification number, user, reserved
generation number, date, time, and remark
o For each concurrent replacement--user, replaced generation
number, date, time, and remark
The elements are listed in alphabetical order.
23.9.3 – Qualifiers
23.9.3.1 /APPEND
Controls whether CMS appends the command output to an existing
file, or creates a new file. If you specify /APPEND and the output
file does not exist, CMS creates a new file. If you do not provide
an output file specification (see the description for /OUTPUT),
the output is appended to SYS$OUTPUT.
23.9.3.2 /BEFORE=date-time
Lists current reservations that were executed prior to the
specified time. The date value can be an absolute, delta, or
combination time value, or one of the following keywords: TODAY,
TOMORROW, or YESTERDAY. By default, CMS displays all existing
reservations.
23.9.3.3 /CONCURRENT
Lists only concurrent reservations and concurrent replacements.
23.9.3.4 /GENERATION[=generation-expression]
Lists reservations for a specific generation or set of generations
in a class.
23.9.3.5 /NOREPLACEMENTS
Indicates that concurrent replacements are not to be displayed.
23.9.3.6 /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.
23.9.3.7 /OUTPUT[=file-specification]
Directs CMS to write output to the specified file, except for any
warning and error messages, which are written to SYS$OUTPUT and
SYS$ERROR. CMS creates a new file if you do not specify /APPEND.
If you omit the /OUTPUT qualifier (or if you specify /OUTPUT
but do not provide a file specification), CMS directs output to
the default output device (SYS$OUTPUT). If you omit either the
file name or the file type component, CMS supplies the missing
component from the default specification.
23.9.3.8 /SINCE=date-time
Lists current reservations that were executed after the specified
time. The time value can be an absolute, delta, or combination
time value, or one of the following keywords: TODAY, TOMORROW, or
YESTERDAY.
23.9.3.9 /USER=username
Lists current reservations that were executed by the specified
user. If you do not specify this qualifier, CMS lists reservations
held by all users.
23.9.4 – Example
CMS> SHOW RESERVATIONS
Reservations in CMS Library DISKX:[PROJECT.CMSLIB]
AUDIT.FOR
(2) STEVEW 8 25-APR-1988 09:46:38 "add checks for
file attributes"
Concurrent replacements
STEVEM 9 16-MAY-1988 16:01:30 "change %ascid
& non-picrefs to pic"
GETCMD.FOR
(1) STEVEM 15 17-MAY-1988 21:28:34 "fix access
violation"
INIT.FOR
(1) SMITH 13 15-MAY-1988 15:09:33 "context
reference--add_field"
LSTUTL.FOR
(1) STEVEM 5 17-MAY-1988 21:43:10 "bug fixes"
This command lists the element name, the identification
number of the reservation, the user who has it reserved, the
generation number, and the date, time, and remark associated
with the reservation for each element. In addition, CMS reports
that the element AUDIT.FOR has been concurrently replaced,
creating generation 9. As a result, user STEVEW must create a
variant when he replaces the element.
23.10 – REVIEWS_PENDING
Displays a list of element generations that currently have review
pending status.
Format:
SHOW REVIEWS_PENDING [element-expression]
23.10.1 – Command Parameters
element-expression
Specifies one or more elements which are to be searched for
generations with pending reviews. By default, all elements are
searched. An element expression can be an element name, a group
name, a wildcard expression, or a list of these separated by
commas.
23.10.2 – Description
The SHOW REVIEWS_PENDING command provides information about
element generations currently marked for review. For each element
with generations under review, the output consists of the element
name, user, generation number, date, time, replacement remark,
and any associated review comments that were established with the
REVIEW GENERATION command. The elements are listed in alphabetical
order.
23.10.3 – Qualifiers
23.10.3.1 /APPEND
Controls whether CMS appends the command output to an existing
file, or creates a new file. If you specify /APPEND and the output
file does not exist, CMS creates a new file. If you do not provide
an output file specification (see the description for /OUTPUT),
the output is appended to SYS$OUTPUT.
23.10.3.2 /BEFORE=date-time
Specifies that only generations placed under review before the
indicated date and time are to be displayed. By default, all
generations with reviews pending are displayed. The date value
can be an absolute, delta, or combination time value, or one of
the following keywords: TODAY, TOMORROW, or YESTERDAY.
23.10.3.3 /GENERATION[=generation-expression]
Specifies that only reviews pending for generations matching
the generation expression are to be displayed. By default, all
generations with reviews pending are displayed.
23.10.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, 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.
23.10.3.5 /OUTPUT[=file-specification]
Directs CMS to write output to the specified file, except for any
warning and error messages, which are written to SYS$OUTPUT and
SYS$ERROR. CMS creates a new file if you do not specify /APPEND.
If you omit the /OUTPUT qualifier (or if you specify /OUTPUT
but do not provide a file specification), CMS directs output to
the default output device (SYS$OUTPUT). If you omit either the
file name or the file type component, CMS supplies the missing
component from the default specification.
23.10.3.6 /SINCE=date-time
Specifies that only generations placed under review after the
indicated date and time are to be displayed. By default, all
generations with reviews pending are displayed. The date value
can be an absolute, delta, or combination time value, or one of
the following keywords: TODAY, TOMORROW, or YESTERDAY.
23.10.3.7 /USER=username
Specifies that only reviews pending for generations created by the
indicated user are to be displayed. By default, all generations
with reviews pending are displayed.
23.10.4 – Example
$ CMS SHOW REVIEWS_PENDING
Reviews pending in CMS Library DISKX:[WORK.CMSLIB]
EXAMPLE.SDML
DAVIS 3 22-JAN-1988 10:40:26 "example is now complete"
Review comments
EVEDITOR 23-JAN-1988 14:41:54 "this looks wonderful!"
JONES 25-JAN-1988 11:30:02 "agreed...let's submit it"
4777TIM_TST.BAS
KENW 6 04-FEB-1988 09:22:36 "we need to verify this
program"
This command shows all generations of elements in the library
that are currently on the review pending list.
23.11 – VERSION
Displays the version number of the CMS system currently in use.
Format:
SHOW VERSION
23.11.1 – Description
The SHOW VERSION command shows the version number of the current
CMS system.
23.11.2 – Qualifiers
23.11.2.1 /APPEND
Controls whether CMS appends the command output to an existing
file, or creates a new file. If you specify /APPEND and the output
file does not exist, CMS creates a new file. If you do not provide
an output file specification (see the description for /OUTPUT),
the output is appended to SYS$OUTPUT.
23.11.2.2 /OUTPUT[=file-specification]
Directs CMS to write output to the specified file, except for any
warning and error messages, which are written to SYS$OUTPUT and
SYS$ERROR. CMS creates a new file if you do not specify /APPEND.
If you omit the /OUTPUT qualifier (or if you specify /OUTPUT
but do not provide a file specification), CMS directs output to
the default output device (SYS$OUTPUT). If you omit either the
file name or the file type component, CMS supplies the missing
component from the default specification.
23.11.3 – Example
CMS> SHOW VERSION
CMS Version V3.0
This command shows the current version of CMS.
24 – UNRESERVE
Cancels one or more reservations of a generation of an element.
Format:
UNRESERVE element-expression "remark"
24.1 – Command Parameters
element-expression
Specifies one or more elements whose reservations are to be
canceled. An element expression can be an element name, 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.
24.2 – Description
The UNRESERVE command cancels an existing reservation of a
generation of an element. You cannot unreserve a generation held
by another user unless you hold BYPASS privilege or unless you are
granted BYPASS access to the element by an access control entry.
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 canceled. 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 canceled. 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.
24.3 – Qualifiers
24.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 unreserve a concurrent reservation or when you
cancel another user's reservation.
24.3.2 /DELETE[=file-specification]
Controls whether all versions of the unreserved file are deleted.
If you omit /DELETE, the files are not deleted. If you specify
/DELETE without a file specification, all versions of the
unreserved files are deleted from your current directory. The
file specification allows you to specify a different location and
the name of the file to be deleted.
24.3.3 /GENERATION=generation-expression
Specifies which reserved generation of the element is to be
unreserved. If you have more than one reservation of the same
element generation, you must use the /IDENTIFICATION_NUMBER
qualifier to unreserve the reservation.
24.3.4 /IDENTIFICATION_NUMBER=n
Specifies which reservation is to be unreserved. 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.
24.3.5 /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.
24.3.6 /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.
24.4 – Examples
(1) CMS> UNRESERVE FILEIO.BLI
_Remark: problem elsewhere
%CMS-S-UNRESERVED, element DISKX:[PROJECT.CMSLIB]FILEIO.BLI
unreserved
This command cancels the existing reservation of the element
FILEIO.BLI.
(2) $ SET PROCESS/PRIVILEGE=BYPASS
$ CMS UNRESERVE SAMPLE.TXT "unreserving on behalf of SMITH"
Element A.TXT currently reserved by:
(1) SMITH 1 17-FEB-1988 13:43:52 "sample module
for program"
Unreserve (1) SAMPLE.TXT generation 1, held by SMITH? [Y/N] (N): Y
%CMS-S-UNRESERVED, element DISKX:[SMITH.WORK.CMSLIB]SAMPLE.TXT
unreserved
This example shows the cancellation of another user's existing
reservation (through the use of BYPASS privilege) of the latest
generation of the element SAMPLE.TXT. If concurrent reservations
of element SAMPLE.TXT existed, you would need to specify the exact
reservation to be canceled by using either the /GENERATION or
/IDENTIFICATION qualifier.
25 – VERIFY
Performs a series of checks on your CMS library to confirm that
the library structure and library files are in a valid form.
Format:
VERIFY [element-expression]
25.1 – Restrictions
o You cannot specify the /RECOVER and /REPAIR qualifiers on the
same command line.
o You cannot specify an element expression parameter when you use
the /RECOVER qualifier.
o The /FILE_ATTRIBUTES and /WARN_ON_REPAIR qualifiers are only valid
with the /REPAIR qualifier.
25.2 – Command Parameters
element-expression
Specifies one or more elements to be verified. If you do not
supply an element expression, CMS verifies every file in the
library. You cannot specify an element expression parameter if
you use the /RECOVER qualifier. An element expression can be an
element name, a group name, a wildcard expression, or a list of
these separated by commas.
25.3 – Description
The VERIFY command performs a series of consistency checks on
your library. If you issue VERIFY under normal conditions, the
command executes successfully, indicating that the information
in your library is correct. However, if the data in the library
is invalid, the command returns an error message indicating that
there is an error in the verification of the library. You can
use the /RECOVER and /REPAIR qualifiers on the VERIFY command to
correct some of the errors discovered by VERIFY.
Recovery and repair transactions are marked as unusual occurrences
in the library history.
25.4 – Qualifiers
25.4.1 /CONFIRM (D)
Controls whether CMS prompts you for confirmation prior to
deleting any invalid reference copies during a VERIFY/REPAIR
operation. In some cases, however, if CMS finds invalid reference
copies (for example, if there is one valid reference copy and the
remaining reference copies are invalid), it automatically deletes
the invalid copies without prompting for confirmation.
If you type YES, ALL, TRUE, or 1, CMS executes the transaction. If
you type NO or QUIT or press RETURN, 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.
25.4.2 /FILE_ATTRIBUTES
Specifies that, for element data files and reference copies, only
problems with file attributes are to be repaired. By default all
problems are repaired.
This qualifier is particularly useful when files are reported as
not closed by CMS, for example because file protection has been
changed in OpenVMS, but there may also be more significant
problems, such as duplicate or incorrect files. By using this
qualifier, the less significant problems can be fixed, enabling
any other problems to be more easily identified.
25.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.
25.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, OTHER)
ELEMENT (D)
NOELEMENT
GROUP (D)
NOGROUP
OTHER (D)
NOOTHER
NONE--equivalent to (NOELEMENT, NOGROUP, NOOTHER)
You can specify either ALL or NONE, or any combination of the
[NO]ELEMENT, [NO]GROUP, and [NO]OTHER keywords.
If you do not specify an element expression on the VERIFY command,
the default is /OCCLUDE=NONE. If you do specify an element
expression, the default is /OCCLUDE=ALL.
25.4.5 /OUTPUT=file-specification
Directs CMS to write to the specified file. If an incomplete file
specification is given, unspecified parts are provided from the
default filename VERIFY.LOG in the default directory.
25.4.6 /RECOVER
Controls whether the VERIFY command cancels an incomplete
transaction. You use the /RECOVER qualifier when a transaction
with the library is incomplete and the rollback mechanism does not
automatically cancel the command. For example, you must use
the /RECOVER qualifier if the OpenVMS system fails while a
CMS command is updating the library.
If a CMS command is terminated and the library is left in an
inconsistent state, CMS recognizes that the last transaction
was incomplete and automatically initiates command rollback
to return the library to a valid format.
If you have set up a restrictive protection scheme and a system
failure occurs during a CMS transaction and leaves your library
in an inconsistent state, the VERIFY/RECOVER command should be
executed by the same person who was using CMS at the time of the
system failure or by a person with sufficient privileges.
25.4.7 /REPAIR
Controls whether or not the VERIFY command repairs the CMS
library and files in the CMS library. You should use the /REPAIR
qualifier if VERIFY issues a message concerning one of the
following conditions:
o The CMS library has inconsistencies that CMS indicates are
repairable.
o Element data files in the library were not closed by CMS.
o The checksum of elements in the library is invalid.
o Generations in the library have invalid maximum record size.
o A data block was not found on pass 1.
o The reference copy for an element is missing.
o A reference copy is found for an element with the /NOREFERENCE_
COPY qualifier.
o There are duplicate reference copies for an element.
o The reference copy of an element is invalid.
If reference copies need repairing, VERIFY/REPAIR creates or
deletes files as necessary to correct the information in the
reference copy directory.
If a file was not closed by CMS, VERIFY/REPAIR repairs the OpenVMS
RMS file header so that the file can be successfully verified. If
the checksum of a file does not correspond to the contents of the
file, VERIFY/REPAIR recalculates the checksum so that the library
can be verified.
If any of these conditions exist, data may have been changed in
the library by methods other than the normal updating of the
library with CMS commands. For example, a file may have been
opened and modified with a text editor. You may want to find out
why the files could not be verified.
25.4.8 /WARN_ON_REPAIR
Specifies that messages indicating that problems have been repaired
should be output as warnings. By default, these messages are
informational messages. When used with the /NOLOG qualifier, only
messages indicating successful repairs and errors will be displayed.
25.5 – Example
CMS> VERIFY
%CMS-I-VERCLS, class list verified
%CMS-I-VERCMD, command list verified
%CMS-I-VERELE, element list verified
%CMS-I-VERGRP, group list verified
%CMS-I-VERRES, reservation list verified
%CMS-I-VERFRE, internal free space list verified
%CMS-I-VERFRE, internal free space list verified
%CMS-I-VERFRE, internal free space list verified
%CMS-I-VERFRE, internal free space list verified
%CMS-I-VERFRE, internal free space list verified
%CMS-I-VERFRE, internal free space list verified
%CMS-I-VERFRE, internal free space list verified
%CMS-I-VERARC, archive control block verified
%CMS-I-VER2, internal contiguous space verified
%CMS-I-VERCON, control file verified
%CMS-I-VEREDF, element DISKX:[PROJECT.CMSLIB]INIT.FOR verified
%CMS-I-VEREDF, element DISKX:[PROJECT.CMSLIB]MSGDOC.FOR verified
%CMS-I-VEREDF, element DISKX:[PROJECT.CMSLIB]OUTPUT.FOR verified
%CMS-I-VEREDFS, element data files verified
%CMS-I-VERIFIED, library DISKX:[PROJECT.CMSLIB] verified
This example indicates that the library is in a consistent
format. If VERIFY reports errors, see the description of the
error message in Appendix A.
26 – Classes
A class is a set of specific element generations. It can be used
to define a system version (such as a base level) consisting of
different generations of several elements. An element generation
can belong to zero, one, or several classes, but a class may contain
no more than one generation of a given element.
A class name is any string of 39 or fewer characters, consisting of
letters, digits, underlines, hyphens, dollar signs, and periods.
(1) HELP CMS CREATE CLASS tells how to establish one or
more new classes.
(2) HELP CMS DELETE CLASS tells how to delete one or more
classes.
(3) HELP CMS INSERT GENERATION tells how to insert one or
more element generations into one or more classes.
(4) HELP CMS MODIFY CLASS tells how to change the
attributes of one more classes.
(5) HELP CMS REMOVE GENERATION tells how to remove one or
more generations from one or more classes.
(6) HELP CMS SHOW CLASS tells how to display information
about one or more classes.
27 – Elements
An element is the basic structural unit in a library. An element
consists of a file and all its versions, called generations.
An element name is the file name and type specified with the CMS
CREATE ELEMENT command. When you retrieve an element from the
library, CMS places a copy of the element in your default directory.
Each time you replace an element in the library, CMS creates a new
generation of that file.
CMS can store any type of file except a directory file.
(1) HELP CMS CREATE ELEMENT tells how to create new files
in a CMS library.
(2) HELP CMS DELETE ELEMENT tells how to delete one or more
elements.
(3) HELP CMS INSERT ELEMENT tells how to insert one or more
elements into one or more groups.
(4) HELP CMS MODIFY ELEMENT tells how to change the attributes
of one more elements.
(5) HELP CMS REMOVE ELEMENT tells how to remove one or more
elements from one or more groups.
(6) HELP CMS SHOW ELEMENT tells how to display information
about one or more elements.
28 – Groups
A group is a collection of elements. You establish a group to
manipulate related elements as a single unit. For instance, you
could establish a group that contains all the chapters in a book.
Groups can contain elements or other groups.
A group name is a string of 39 or fewer characters, consisting of
letters, digits, underlines, hyphens, or dollar signs.
(1) HELP CMS CREATE GROUP tells how to establish one or
more new groups.
(2) HELP CMS DELETE GROUP tells how to delete one or more
classes.
(3) HELP CMS INSERT ELEMENT tells how to insert an element
into a group.
(4) HELP CMS INSERT GROUP tells how to insert one group
into another group.
(5) HELP CMS MODIFY GROUP tells how to change the attributes
of one more groups.
(6) HELP CMS REMOVE ELEMENT tells how to remove one or more
elements from one or more groups.
(7) HELP CMS REMOVE GROUP tells how to take a group out of
another group.
(8) HELP CMS SHOW GROUP tells how to display information
about one or more groups.
29 – Libraries
A CMS library is an OpenVMS directory containing specially formatted
files which CMS uses to operate. You create a library by first creating
an OpenVMS directory (with the $ CREATE/DIRECTORY command) and then
creating a CMS library in that directory (with the CMS CREATE LIBRARY
command). Once you have created a library, it must be reserved
exclusively for use by CMS.
(1) HELP CMS CREATE LIBRARY tells how to create a new library.
(2) HELP CMS CONVERT LIBRARY tells how to convert your V2.n
library to V3.0 format.
(3) HELP CMS MODIFY LIBRARY tells how to change the attributes
of one more libraries.
(4) HELP CMS SET LIBRARY identifies one or more existing
libraries as your current library list.
(5) HELP CMS SET NOLIBRARY removes one or more libraries from
the currently set library list.
(6) HELP CMS SHOW LIBRARY displays the directory specification
of your currently set CMS library or libraries.
30 – New User
Welcome to CMS. You can invoke CMS in one of two ways:
(1) You can enter the command "CMS", then press RETURN. This
invokes the CMS subsystem (shown by the prompt CMS>). Once
in subsystem mode, you can execute commands by entering
subcommands, keywords, parameters, and qualifiers. To return
to DCL, type "EXIT" or press CTRL/Z.
(2) You can also enter commands one at a time from DCL level.
After each command is completed, CMS returns control to DCL.
If your project already has a library, you can set default to it by
typing the following:
$ CMS SET LIBRARY DISKX:[OURPROJECT.OURLIB]
(1) HELP CMS gives a list of topics for which help is available.
(2) HELP CMS CREATE LIBRARY tells how to set up a project
library.
(3) HELP CMS OVERVIEW explains what CMS is and how it is used.
For more information and help on getting started, see Chapter 1 of
the "Guide to DIGITAL Code Management System for OpenVMS Systems".
31 – Overview
During development, team members continually make changes to project
files. CMS stores, keeps track of, and monitors these files (called
elements). CMS also lets you manipulate combinations of files within
a library (called groups and classes).
CMS stores project files in a central library where they are available
to all project members. Some of the functions you can perform using
CMS include the following:
(1) Store elements in a library for safekeeping
(2) Retrieve elements, and modify and test them in your own
directory
(3) Control concurrent modifications to the same element
(4) Merge concurrent modifications to a file
(5) Create successive versions, or generations, of files
(6) Compare two versions of an element within a library
(7) Organize related library elements into groups
(8) Define a set of various element generations (called a class)
to make up a baselevel or release version of a project
(9) Track which users are working on which files from the library
(10) Maintain a historical account of element and library
transactions
A CMS library can store any type of file except for a directory file.
(1) HELP CMS New_User explains how to invoke CMS.
(2) HELP CMS CREATE LIBRARY tells how to establish a new project
library.
(3) HELP CMS gives a list of topics on which help is available.
32 – Release Notes
You can find the release notes for this release and previous versions of CMS in SYS$HELP:CMSvvu.RELEASE_NOTES, where vv is the major version number, and u is the update number. To list all the CMS release notes available, type: $ DIRECTORY SYS$HELP:CMS*.RELEASE_NOTES.