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:
$ 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.