Code Management System

The Code Management System (CMS) is a library system for software development and maintenance, part of DECset. Its features include:

• storing code and other related files in libraries
• controlling versions of code (generations)
• manipulating groups of objects as a unit
• manipulating versions of the entire system (classes)
• managing code reviews
• keeping track of history and storing comments
• merging changes made to different generations of the software
• additional security mechanisms
• providing notifications when an event occurs

CMS routines can also be called from VDE, the OpenVMS Development Environment. VDE allows you to build libraries of libraries and manage classes across different libraries.

Concepts

• A CMS library is a repository for CMS objects. It resides in a directory that has been initialized for use solely by CMS; your default directory cannot be a CMS library. The CREATE LIBRARY command creates CMS control files in the specified directory. A working library is chosen with the SET LIBRARY command; CMS$LIBRARY logical is defined to point to your current library. Once the library is created, it should only be accessed through CMS commands.
• A CMS element represents all versions of a particular file in a CMS library. An element cannot be a directory file.
• A CMS generation represents a specific version of an element. When an element is first created, CMS creates generation 1 of that element. When the element is later modified (reserved and replaced), CMS creates a new generation of that element.
• A CMS group is a set of elements that can be manipulated as a unit.
• A CMS class is a set of particular generations of elements. Typically generations of elements are combined into classes to represent progressive stages, or base levels, in the development of an entire system.
• A reservation is when an element is taken out for modification and then replaced with a new version.
• A reference copy directory is a directory that stores the copies of the latest main-line generation of selected library elements.

Working with Libraries

A CMS library is a bit like a Git repository: it is a directory where the code files are stored and where CMS stores its files. All CMS work happens within a library. To start working with CMS, you need to create a library first.

If there is already a CMS library in a directory, you can just do a CMS SET LIBRARY followed by that directory:

$ CMS SET LIBRARY [JDOE.TEST]

Files that are already in the directory can be added to the library with the following command:

$ CMS CREATE ELEMENT/KEEP full-path-to-file "Commit message"

To create a CMS library, make sure your default directory is NOT the directory that you want your CMS library to be in. Then execute CMS CREATE LIBRARY directory-specification "Commit message":

$ CMS CREATE LIBRARY [.TEST] "First library"

To display elements in the library, issue the CMS SHOW ELEMENT command:

$ CMS SHOW ELEMENT

Working with Elements

Elements in a library are files that you want to track, e.g. code files. Add them to the library with the CREATE ELEMENT command; if the file already exists, use the /KEEP qualifier:

CMS CREATE ELEMENT/KEEP TEST.C "First version"

To change an element:

• RESERVE it
• edit it
• REPLACE it

For example, here is how to change TEST.C:

First, set the library where the file is:

CMS> set library [.test]
 %CMS-I-LIBIS, library is WORK7:[JDOE.TEST]
 %CMS-S-LIBSET, library set
 -CMS-I-SUPERSEDE, library list superseded

View the latest generation for TEST.C:

CMS> show generation test.c

Element generations in CMS Library WORK7:[JDOE.TEST]

TEST.C        3      16-DEC-2022 07:26:30 JDOE"Changed the message"

Reserve the file. By default, the latest generation is reserved; you can specify the generation using /GENERATION:

CMS> reserve test.c
_Remark: "Add another message"
%CMS-S-RESERVED, generation 3 of element WORK7:[JDOE.TEST]TEST.C reserved

Exit CMS and edit the file using EVE:

CMS> exit
$ edit test.c
#include<stdio.h>
void main()
{
printf("Hello Everyone!");
printf("Goodbye!");
getch ();
}
[End of file]
Buffer: TEST.C
7 lines written to file WORK7:[JDOE]TEST.C;2

Enter CMS and see that the file is still reserved:

$ cms
CMS> sh reservation

Reservations in CMS Library WORK7:[JDOE.TEST]

TEST.C
   (1)   JDOE   3      16-DEC-2022 08:56:18 "Add another message"

Replace the file:

CMS> replace test.c "Added a message"
%CMS-S-GENCREATED, generation 4 of element WORK7:[JDOE.TEST]TEST.C created

See that the new generation has been added:

CMS> sh generation

Element generations in CMS Library WORK7:[JDOE.TEST]

TEST.C        4      16-DEC-2022 08:57:11 JDOE "Added a message"

Variant Generations

To create an alternative development path for an element (similar to a branch in Git, but for a particular file), you need to create a variant generation. When you replace the file, use /VARIANT to specify a letter that will be used to refer to that variant generation:

$ CMS RESERVE TEST.C
$ EDIT TEST.C                    !some edits happen here
$ CMS REPLACE TEST.C /VARIANT=C

Before, there were 4 generations of TEST.C: 1, 2, 3 and 4. After the REPLACE command is executed, generation 4C1 appears. If then CMS RESERVE TEST.C is executed without /GENERATION, generation 4 is reserved and when the file is replaced, generation 5 is created. To reserve generation 4C1, execute RESERVE TEST.C /GENERATION=4C1; when the file is replaced, generation 4C2 is created.

Merging

You can merge two variant generations into one with RESERVE/MERGE:

CMS> reserve test.c /merge=4c2
_Remark: Merging the Christmas version with master
 %CMS-W-MERGECONFLICT, 0 changes successfully merged with 1 conflict
 %CMS-W-RESERVED, generation 5 of element WORK7:[JDOE.TEST]TEST.C reserved and merged with 4C2
CMS> sh generation test.c

Element generations in CMS Library WORK7:[JDOE.TEST]

TEST.C        5      16-DEC-2022 08:57:11 JDOE "Added a message"
CMS> exit

Because the same lines were changed in versions 5 and 4C2, there was a merge conflict. When we EDIT the reserved file, it looks like this:

$ edit test.c
#include<stdio.h>
void main()
{
**************** Conflict 1     ************************************************
printf("Goodbye!");
printf("Hello Everyone!");
********************************************************************************
printf("Merry Christmas Everyone!");
printf("And happy New Year!");
************** End of Conflict 1     *******************************************
getch ();
}
[End of file]

When the conflict is resolved, generation 6 of TEST.C is created.

Reviewing

To ask for an element to be reviewed, issue MARK GENERATION element-name comment:

$ cms mark generation test.c "Review the last generation"
%CMS-S-MARKED, generation 5 of element WORK7:[JDOE.TEST]TEST.C marked for review

It will appear in the list of files to be reviewed that can be displayed by issuing CMS SHOW REVIEWS_PENDING:

$ cms show review

Reviews pending in CMS Library WORK7:[JDOE.TEST]

TEST.C
   JDOE 5      16-DEC-2022 09:48:56 "Resolved the merge conflict"

Then the file can be reviewed using a text editor.

To leave a remark, us REVIEW GENERATION filespec comment. To accept the file, issue ACCEPT GENERATION filespec comment:

CMS> accept generation test.c
_Remark: "You know what its FINE"
%CMS-S-ACCEPTED, generation 5 of element WORK7:[JDOE.TEST]TEST.C accepted

To reject the file, issue REJECT GENERATION.

Working with Groups

A group is a collection of elements that you will then be able to manage (reserve, replace, etc.) with one command. To create a group, execute CREATE GROUP:

CMS> CREATE GROUP C_FILES "A group for C files"

To add elements to your group, use INSERT ELEMENT:

CMS> INSERT ELEMENT TEST2.C C_FILES "Inserted the second C file into the group"

Then you can refer to them as a grop, for example:

CMS> RESERVE C_FILES "About to change both files"

When you then modify and replace the files, new generations will be created for both of them:

CMS> replace c_files
_Remark: Modified both of my C files
%CMS-I-GENCREATED, generation 6 of element WORK7:[ZELENINA.TEST]TEST.C created
-CMS-I-NOCHANGES, no changes
%CMS-I-GENCREATED, generation 2 of element WORK7:[ZELENINA.TEST]TEST2.C created
-CMS-I-NOCHANGES, no changes
%CMS-I-REPLACEMENTS, 2 elements replaced
CMS> sh generation c_files 

Element generations in CMS Library WORK7:[ZELENINA.TEST]

TEST.C        6      16-DEC-2022 11:16:03 ZELENINA "Modified both of my C files"
TEST2.C       2      16-DEC-2022 11:16:03 ZELENINA "Modified both of my C files"