Digital PDFs

AA-L371B-TE

December 1984

64 pages

Original

2.5MB

Document:	User’s Introduction to VAX DEC/CMS
Order Number:	AA-L371B-TE
Revision:
Pages:	64
Original Filename:	http://bitsavers.org/pdf/dec/vax/vms/layered_product/AA-L371B-TE_Users_Introduction_to_VAX_DEC_CMS_2.0_198411.pdf

OCR Text

User's Introduction to

VAX DEC/CMS
Order No. AA-L371B-TE

November 1984

REVISION/UPDATE INFORMATION:

This document supersedes the
User's Introduction to DEC/CMS.
(Order No. AA-L371 A-TE).

OPERATING SYSTEM AND VERSION: VAX/VMS Version 4.0
SOFTWARE VERSION:

VAX DEC/CMS Version 2.0

digital equipment corporation • maynard, massachusetts

First Printing, May 1982
Revised, November 19P 1
The information in this document is subject to change without notice and should not
be construed as a commitment by Digital Equipment Corporation. Digital Equipment
Corporation assumes no responsibility for any errors that may appear in this document.
The software described in this document is furnished under a license and may be used
or copied only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment that is
not supplied by Digital Equipment Corporation or its affiliated companies.
Copyright © 1982, 1984 by Digital Equipment Corporation.
All Rights Reserved.
Printed in U.S.A.
The postpaid READER'S COMMENTS form on the last page of this document
requests the user's critical evaluation to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
DEC
DEC/CMS
DEC/MMS
DECnet
DECsystem-10
DECSYSTEM-20
DECUS
DECwriter

DIBOL
EduSystem
IAS
MAS SBUS
MicroPDP-11
Micro/RSX
Micro VMS
PDP

PDT
RSTS
RSX
TOPS-20
UNIBUS
VAX
VMS
VT

~omoomo
ZK2334

HOW TO ORDER ADDITIONAL DOCUMENTATION
In Continental USA and Puerto Rico call

800-258-1710

In New Hampshire. Alaska, and Hawaii call

603-884-6660

In Canada call 613-234-7726 (Ottawa-Hull)
800-267-6146 (all other Canadian)

DIRECT MAIL ORDERS (USA & PUERTO RICO)*
Digital Equipment Corporation
P.O. Box CS2008
Nashua. New Hampshire 03061

DIRECT MAIL ORDERS (CANADA)
Digital Equipment of Canada Ltd.
940 Belfast Road
Ottawa, Ontario K1G 4C2
Attn: P&SG Business Manager

DIRECT MAIL ORDERS (INTERNATIONAL)
Digital Equipment Corporation
. P&SG Business Manager
clo Digltal's local subsidiary or
approved distributor

•Any prepaid order from Puerto Rico must be placed
with the local Digital subsidiary (809-754-7575)
Internal orders should be placed through the Software Distribution Center (SOC), Digital Equipment
Corporation, Northboro, Massachusetts 01532

Contents
Page

Preface

Chapter 1 CMS Concepts
1.1 Overview of DEC/CMS .

. 1-1

1.1.1 Library Elements . . . . . . . . . . .
1.1.2 Making Changes to a Library Element.
1.1.3 Reserving and Replacing an Element

1.2 Interactive Help . . . . . . . . . . . . . .
1.3 Project Planning and Development . . . . .

. 1-2
. 1-2
. 1-3
. 1-4
. 1-4

1.3.1 Using Groups for Structural Organization . .
1.3.2 Using Classes for Organization by Milestone .

. 1-4
. 1-4

1.4 A Typical CMS Application. . . . . . . . . . . .

. 1-5

Chapter 2 Building a CMS Library
2.1
2.2
2.3
2.4

Creating a Library Directory . .
Protecting a CMS Library. . . .
Creating a CMS Library . . . .
Placing Project Files in the CMS Library

. 2-1
. 2-1
. 2-2
. 2-2

Chapter 3 Accessing Files In a CMS Library
3.1
3.2
3.3
3.4
3.5

Getting Started - CMS SET LIBRARY . . .
Reserving a Library Element - CMS RESERVE . . .
Canceling a CMS Reservation - CMS UNRESERVE .
Replacing a Modified Element in the Library
Getting a Read-only Copy. . . . . . . . . . . . . .

. 3-1
. 3-2
. 3-3
. 3-3
. 3-5

Chapter 4 CMS SHOW Commands
4.1
4.2
4.3
4.4
4.5
4.6

What Files Are in The Library? - CMS SHOW ELEMENT . . . . .
What Files are Being Worked On? - CMS SHOW RESERVATIONS .
What Transactions Have Occurred? - CMS SHOW HISTORY . . . .
What Is Generation n of Element X? - CMS SHOW GENERATION . . . .
How Did Element X Evolve? - CMS SHOW GENERATION /ANCESTORS . . .
What Evolved from Program X? - CMS SHOW GENERATION /DESCENDANTS

iii

. 4-1
. 4-2
. 4-2
. 4-3
. 4-3
. 4-4

Chapter 5 The Evolving CMS library
5.1 Alternate Development Paths . . . . .
5.2 Merging Alternate Development Paths .

. 5-1
. 5-4

5.2.1 Replacing a Merged Copy. . . .
5.2.2 Resolving Merge Conflicts. . . .
5.3 Working Simultaneously on the Same Element.
5.3.1 Reserving an Element That Is Already Reserved . . . . .
5.3.2 Replacing an Element That Has Already Been Replaced .

Cllaptlr 8 Pro)8ct Organization With CMS
6.1 The Early CMS Library. . . . . .
6.2 Using CMS Groups . . . . . . . .

. 5-6
. 5-6

. 5-7
. 5-8

. 5-9

. 6-1
. 6-3

6.2.1 Building a CMS Group . . .
6.2.2 Using the Group Designation . .
6.2:3 Removing Elements from Groups . . . . . . . . .
6.2.4 Displaying the Group Structure of a CMS Library .
6.3 Using CMS Classes . . . . . . . .
6.3.1
6.3.2
6.3.3
6.3.4
6.3.5
6.3.6

Building a CMS Class . . . . . . . . . .
Using the Class Designation. . . . . . . .
Displaying the Class Structure of a Library
Assigning Elements to Multiple Classes
Removing an ~lement from a Class .
Defming a Release with CMS . . .
6.3.7 Supporting a Product Using CMS.

. 6-3
. 6-3
. 6-3
. 6-4
. 6-4

. 6-5
. 6-7
. 6-7
. 6-7
6-10
6-10
6-10

Chapter 7 Addmonal CMS Commands
7.1 Getting Line-by-Line Information . . .
7.2 Comparing Files . . . . . . . . . . .

. 7-1
. 7-2

Appendix A Notes on Using CMS Libraries

Gloulry
Index
Examples
1-1 Sample CMS Terminal Session .
5-1 'Merge Conflicts Flagged . . . .
7-1 Sample Annotated Listing . . .
7-2 Sample CMS DIFFERENCES Listing. .
A-1 The CMS Storage Method (Simplified) .

. 1-3
. 5-7
. 7-2
. 7-3
.A-1

Flgunl
2-1 Building a CMS Library
5-1 Main Line Evolution . .
5-2. Variant Line Evolution.
5-3 Merging Element Generations.
5-4 A Merged Element . . . . . .
6-1 An Early CMS Library . . . . . . . . .
6-2 A CMS Library Showing a Defined Class
6-3 Multiple CMS Classes . . . . . . . . .
. .
.
6-4 A CMS Class Containing a Superseded Element Generation
iv

. 2-4
. 5-3
. 5-3
. 5-5
. 5-6
. 6-2
. 6-6
. 6-9
6-12

PREFACE
OBJECTIVE
This manual explains how to use VAX DEC/CMS (Code Management System). It is an
introductory level book with examples that illustrate basic techniques.

INTENDED AUDIENCE
This manual is intended for software engineers, technical writers, and managers working
. on a wide range of software projects.
Version 2 of DEC/CMS runs only on the VAX/VMS operating system Version 4.0 or later.

STRUCTURE OF THIS DOCUMENT
The User's Introduction to VAX DEC/CMS is divided into seven chapters, one appendix,
and a glossary.
• Chapter 1, CMS Concepts, describes how CMS facilitates the software development
cycle and briefly explains how to use CMS.
• Chapter 2, Building a CMS Library, describes how to set up a CMS library and also
how to load files into the library.
• Chapter 3, Using a CMS Library, describes the basic commands that you use to
retrieve and replace library files.
• Chapter 4, CMS SHOW Commands, explains how you can use CMS commands to get
information about the contents and the history of a CMS library.
• Chapter 5, The Evolving CMS Library, describes how to use CMS to track concurrent
development.
• Chapter 6, Project Organization with CMS, describes how to use CMS to organize a
software project.
• Chapter 7, Additional CMS Commands, describes commands that provide additional
functions.
v

• Appendix A, Notes on Using CMS Libraries, contain:- general information that is useful in understanding how CMS works.
• The Glossary defines important terms.

ASSOCIATED DOCUMENTS
• The VAX DEC/CMS Reference Manual (Order No. AA-L372B-TE) provides detailed
information about CMS concepts and commands.
• The VAX DEC/CMS Callable Interface Manual (Order No. AA-Z340A-TE) contains
information about using the DEC/CMS callable routines.

•Installing VAX DEC/CMS (Order No. AA-Z338A-TE) supplies the instructions for
installing CMS on a VAXNMS system.
•The VAX DEC/CMS Pocket Guide (Order No. AV-L374A-TE) provides concise information about CMS commands and callable routines.

CONVENTIONS USED IN THIS DOCUMENT
Convention

Meaning

{]

Square brackets indicate that the enclosed item is optional.
A horizontal ellipsis indicates that the preceding item(s) can be
repeated one or more times.

s CMS SHOW 1.1rns 1 ON

Interactive examples show system output (prompt characters and
output lines) in black type. All lines that you enter are printed in
red type.

element

A term that appears in italics is defined in the Glossary.

Unless otherwise noted:
• All numeric values are represented in decimal notation.
• You terminate a command by pressing the RETURN key.

Chapter 1

CMS Concepts
DEC/CMS (Code Management System) is a program library system for software development and maintenance. DEC/CMS (also referred to as CMS) stores source files in a library,
keeps track of changes made to these files, and records user access to the files in the libraries In addition, CMS supplies two ways to organize files within a library; these formal
mechanisms for library organization provide a focus for system design.
This chapter describes the basic CMS functions. The commands that you use to build and
then use a CMS library are described in subsequent chapters. This chapter also describes a
hypothetical project that uses CMS. (Examples throughout this manual refer to this
project.)

1.1 Overview of DEC/CMS
CMS operates as an online librarian for a project. While you perform the normal functions
of program development, modification, and testing, CMS keeps track of your files. After
you place your programs in a CMS library, you can retrieve the programs to modify and
test them in your own directory. You then replace the modified programs in the library for
safekeeping. Also, you can look up the history of every program in the library, because
CMS maintains its own records.
CMS is available at the system command level; commands to CMS are similar to DCL commands (such as EDIT, COPY, and SET). You can also use CMS at the subsystem level; once
you invoke the CMS image, you can execute any number of CMS commands while remaining within the CMS subsystem.
CMS does its job without imposing unnecessary restrictions on project members. You can
do all program modification, editing, testing, and development in the familiar VAXNMS
environment. You use CMS to perform the following operations:
• Place a program in the library (Chapter 2).
• Copy a program from the library to your current default directory and mark the
library copy as reserved by you (Chapter 3).
• Return a modified program back to the library (Chapter 3).
• Retrieve a copy of a program from the library for read-only purposes ~Chapter 3).
1-1

• Display a list oflibrary programs (Chapter 4).
• List all versions of a library program (Chapter 4).
• Display the library status or history (Chapter 4).
• Control concurrent modifications to the same program (Chapter 5).
• Create specific sets of programs within a library (Chapter 6).
• Compare two ASCII files in your default directory (Chapter 7).
• Compare two versions of a program within a library (Chapter 7).
A CMS library can store an ASCII file that was created by a text editor such as EDT or
SOS. However, the files you store in the library should be ASCII files that are unlikely to
change completely in each iteration. (See Appendix A for a discussion oflibrary storage.)
Usually, text and source files are the project elements that require tracking.
NOTE
Use only CMS commands to access CMS libraries. You are responsible for the
types of files in the library; a file must be sequential and cannot have the same
characteristics as a binary file. You are also responsible for the method of putting files in the library and the method of manipulating them in the library;
. files that have been put in the library using non-CMS commands may eventually be deleted by CMS. In general, the integrity of a library is not assured if it
has been changed using means other than CMS.

1.1.1 library Elements
An el.ement is the basic structural unit in a CMS library. An element consists of one ASCII
file. You create and name an element when you transfer a file from your current default
directory to a CMS library.

1.1.2 Making Changes to a library Element
After you have created an element in a CMS library, you reserve the element in order to
make changes to it. When you reserve an element, CMS places a copy of the element file in
your current default directory. You can then edit, compile, test, and debug as usual. When
you are ready, you replace the element in the library, and CMS stores the changes that
have been made.
When you create an element and place it in a CMS library for the first time, CMS creates
generation 1 of that element. An element generation represents a phase in the development
of that element. Each time you reserve and replace an element in the library, CMS creates
a new generation. You can recreate any phase in the development of an element by retrieving the appropriate generation.

1-2

CMS Concepts

CMS numbers the new generations in succession. A CMS generatwn number is not to bt.·
confused with the version number that VAXNl\lS assigns to directory files; file versio11
numbers have no significance to CMS. CMS ignores the number of work sess10ns done
outside the library, and assigns a new generation number only when the element is
returned to the Ii brary.

1.1.3 Reserving and Replacing an Element
Example 1-1 shows how you can use CMS in the course of program development.
$CMS RESERVE TESTl.FOR
_Remark: check for non-Printing chars
ZCMS-S-RESERVEDt generation 1 of element TESTl.FOR reserved
$EDIT TESTl .FOR

$ FORTRAN TESTl/DEBUG
$ LINK/DEBUG TESTl
$ RUN TEST 1

$CMS REPLACE TESTl,FOR
_Remark:
ZCMS-S-GENCREATEOt generation 2 of element TEST1.FOR created
$CMS SHOW HISTORY TESTl.FOR
History of DEC/CMS Library _ORA3:[PROGRAMS.LIBRARYJ

28-MAY-19Ba 15:0a:37 SHAW CREATE ELEMENT TESTl.FOR "parameter list test"
29-MAY-19Ba 12:2a:52 SHAW RESERVE TESTl.FOR<ll "check for non-Printing chars"
30-MAY-19Ba 1B:OS:a2 SHAW REPLACE TEST1.FORC2l "check for non-Printing chars"

Example 1-1: Sample CMS Terminal Session
The first command to CMS (CMS RESERVE TESTl.FOR) directs CMS to retrieve the element TESTl.FOR from the library. CMS responds with the prompt "_Remark:". This
allows you to label the transaction with an appropriate remark. After the remark is
entered, CMS executes the command and places a copy of the file associated with the element TESTl.FOR in your current default directory.
The series of commands that follow the first library transaction represent commands a
programmer might use to modify and test the file TESTl.FOR. The next command to CMS
(CMS REPLACE TESTl.FOR) also allows the programmer to enter a remark for the
transaction. In this case, no remark is entered. CMS returns the file to the library. The last
command to CMS (CMS SHOW HISTORY TESTl.FOR) displays information about the
CMS Concepts

1-3

element TESTl.FOR on the terminal. Since no remark was entered for the replacement
transaction, the remark entered for the CMS RESERVE transaction is also logged for the
CMS REPLACE transaction.

1.2 Interactive Help
Information about CMS is available at the terminal. The HELP CMS command provides
online documentation in summary form for setting up a CMS library and for using specific
CMS commands. For example, the following command displays information about the
CMS RESERVE command:
$

HELP CMS RESERVE

You can also get help at the subsystem level:
CMS>HELP RESERVE

Since VAXNMS allows abbreviations you need type only enough of a CMS command to
distinguish it from any other CMS command.

1.3 Project Planning and Development
CMS provides two mechanisms for organizing library elements-groups and classes; by
using groups and classes, you can plan and use your CMS libraries more effectively. Each
mechanism imposes its own kind of structure on the library, yet they can be used in the
same library without conflict. The following sections summarize these methods of project
organization. See Chapter 6 for more information.

1.3.1 Using Groups for Structural Organization
Individual modules of code or text exist in a CMS library as elements. CMS allows you to
combine related elements into a group that you can then manipulate as a unit. For example, you might create a group that contains all modules that process error messages.

1.3.2 Using Classes for Organization by Milestone
The second method of organization is to create classes. You use classes to organize your
library by milestones.
One approach is to integrate the modules into working versions or "base levels" that
represent progressive stages in the development of the entire system. A different approach
might be to establish classes for more localized stages-one class for each stage of coding,
testing, and integration to be performed for each generation of the element. The way in
which you use classes is dependent on the structure of your library and the methodology
that you use for software development.

1-4

CMS Concepts

1.4 A Typical CMS Application
The following story summarizes how the programmers on one project used CMS. Exmnplt'"
throughout this manual refer to the experiences that these programmers had using CMS.
The three-programmer team was developing an analog data sampling program. The team
members agreed to use CMS, rather than keeping track of project files manually. During
the design phase, the project members planned the structure of the product and determined the basic CMS mechanisms they would use to reflect that structure. The lead
programmer, Rick Sanchez, created a library directory for CMS access. As they wrote the
design documentation, the project members put the files for these documents in the CMS
library.
When the design phase was finished, Rick put some project files from his current default
directory into the project library. Then Rick told Glenn Lewis and Sue Kelley the project
library directory name, and Glenn and Sue added their own working programs to the project library. Now the project files (SYNCHRON.BAS, SAMPLE.BAS, SPEC.RNO, and several others) resided in the library as elements.
To organize the library elements, the project members created groups to contain selected
elements. CMS maintained the list of elements contained in each group. After establish. ing the groups, project members were able to manipulate each group of elements as a single unit.
Once the project library was set up, it was used as a repository for the project programs.
Each developer had access to all of the library elements, and any work done on a program
would be recorded and tracked automatically by CMS. When progress on a program
branched out to an alternate development path, CMS tracked both the original development path and the alternate path. CMS maintained a complete program history of all modifications to the original set of programs.
Rick and Glenn worked on the same program from time to time. When Glenn requested
SAMPLE.BAS while Rick was working on it, CMS notified him that Rick had it reserved.
Occasionally Glenn had to ignore the warning and use the same program. When Rick
replaced the program, CMS reported that Glenn had worked on the program while he was
updating it. CMS stored these concurrent changes to the program. Any one of the team
members could use CMS to merge their changes and flag any conflicting modifications
(changes that affected the same line of the code).
Although all three programmers used the command file, TIMTST.COM, to test modifications to their own programs, TIMTST.COM itselfrarely changed. CMS allowed the project
members to get copies of the command file while protecting the command file from inadvertent modification.

CMS Concepts

1-5

When the team was ready to build its first prerelease version of the data sampler, CMS
aided in specifying the programs in that version (or "base level"). Rick established a CMS
class to combine specific versions of these programs together and named the class
BASELEVELl. By this time, some programs had been modified more than 20 times. Rick
inserted specific generations (program versions) of each project program in that class so
there would be no confusion over which generation of a program belonged in the base level.
Throughout the project the programmers found that CMS helped to define project development and direction more clearly. Each project member could review all library transactions and associated remarks. In addition, the programmers could selectively review the
transactions related to a specific aspect of project development. They also discovered that
CMS functions simplified their work. For example, when Sue was on vacation, Glenn made
some changes to an element that Sue usually worked on. Later, Sue was able to get line-byline information on the element, indicating which of her planned modifications had
already been done. Rick found that the CMS history and its remarks could be used as
reminders of project accomplishments when he wrote his status reports.
Later Mike Cohen joined the team. His first assignment was to evaluate problem reports
from field test sites. He found that the CMS annotated listings of the program modifications helped him locate recently changed code more easily. When he wanted to know the
reasons for the changes, Mike referred to the programmer's remarks that CMS recorded
when each modification was performed.
Now the original developers have moved on to new projects. Mike, however, has chosen to
stay with the data sampling project, and he has a new programmer to help him with project
support and enhancements. They still use the project's CMS library, which now contains
every line of code written for the data sampler, along with a complete historical record of
the project.

1-6

CMS Concepts

Chapter 2

Building a CMS Library
This chapter describes the procedures and CMS commands that you use to set up a CMS
library. When you establish a CMS library, you create a directory that is to be used only as
a CMS library. You then define the protection that will allow the appropriate people to
access the library. Once the directory is established, you can direct CMS to initialize the
library and then place project files in the library. If you do not have to create a library or
create elements in a library, you can skip this chapter and go to Chapter 3.
You set up the library in four steps:
l.

Create a directory to contain the CMS library.

Establish the protection scheme for the library.

3. Initialize the directory as a CMS library.
4. Store files in the library as elements.
::>nee you have created the library, you should use only CMS to access it.

~.1

Creating a Library Directory

Jse the DCL command CREATE/DIRECTORY to establish a directory to contain a CMS
ibrary. For example, at the beginning of the data sampler project, Rick set up a CMS
ibrary subdirectory with the command:
; CREATE/DIRECTORY [PROJECT.AOSLIBJ

rhis command created the subdirectory [PROJECT.ADSLIB] for use as the project library
lirectory on Rick's default disk.

~.2 Protecting a CMS Library
;Ms does not define any protection scheme for a library directory or any of the files conained within the library. Thus, you must explicitly define a -VIC-based or ACL-based proection .scheme for your libraries.

2-1

Hick >vanted Glenn and Sue, who also are in his user identification code (lJlCl group, to
have access to the library files at will. After he created the subdirectory [PROJECT.ADSLIB] for use as the CMS libtary, he used the following commands to set the
required protection:
$SET PROTECTION=<S:RWEtO:RWEtG:RWE) [PROJECTJAOSLIB.DIR
$SET FILE/ACL=<DEFAULT_PROTECTION15:RWD.O:RWD1G:RWDI EPROJECTJADSLIB.DIR

The DCL command SET PROTECTION specifies that system, owner, and group members
have the standard read, write, and execute access to the [PROJECT.ADSLIB] directory.
The DCL command SET FILE/ACL specifies that system, owner, and group members are
allowed read, write, and delete access to all new files created in the library directory.
See the VAX DEC/CMS Reference Manual for more information about protecting CMS
libraries.

2.3 Creating a CMS Library
The CMS CREATE LIBRARY command creates CMS control files in a directory. Once. you
initialize a directory with CMS data structures, CMS uses that directory to locate and
store project files. All commands to the CMS system automatically refer to this directory
until the end of the terminal session, or until you specify a different library with the CMS
SET LIBRARY command (see Section 3.1).
For example, Rick initialized the subdirectory, ADSLIB, with the following command:
CMS CREATE LIBRARY [PROJECT.ADSLIBJ
_Remark: a/d data sampling library
!CMS-S-CREATEDt DEC/CMS library DRA3:[PROJECT.ADSLIBJ created
$

Then, with the library created, protected, and initialized, he was ready to use CMS and
place project files in the library.

2.4 Placing Project Files in the CMS Library
The CMS CREATE ELEMENT command instructs CMS to move a file from your current
default directory into the library. (When CMS places a file in the library, all copies of that
file are deleted from your current default directory. You can use the /INPUT qualifier to
direct CMS to use a file from a directory other than your current default, in which case
CMS deletes the file from the specified area.) An element name is the file name and type of
the file specified in the CMS CREATE ELEMENT command. Every element in the CMS
library must have a unique name.
On the data sampler project, Rick moved five files into the library. He gave CMS the following CMS CREATE ELEMENT commands:

2-2

Building a CMS Library

CMS CREATE ELEMENT SPEC.RNO
_Remarl\: ad samPlin9 functional sPecific&'t.Jcr.
ZCMS-S-CREATED1 element SPEC.RNO created
$ CMS CREATE ELEMENT ADCONVERT.BAS
_Remarl\: analog to di9ital conversion routines
ZCMS-S-CREATED, element ADCONVERT,BAS created
$ CMS CREATE ELEMENT SAMPLE.BAS
_Remarl\: SamPling module
ZCMS-S-CREATED, element SAMPLE.BAS created
$ CMS CREATE ELEMENT SYNCHRON,BAS
_ReMark: Synchronization routines
ZCMS-S-CREATED1 element SYNCHRON.BAS created
$ CMS CREATE ELEMENT TIMTST.COM
_ReMarl\: ComMand Procedure for tests
ZCMS-S-CREATED1 element TIMTST.COM created
$

Figure 2-1 shows the effects of each action in the building procedure. When Sue and Glenn
put their files into the library, they used the CMS CREATE ELEMENT command with
their own file names.

Building a CMS Library

2-3

DRA3:

DRA3

-----Project-----.

-----Project----.,.
---ADSLIB---

(Before CMS Directory Setup)

1. CMS Directory Established

DRA3:

-----Project-----.

.------Project----.,.

- - - ADSLIB - - -

. - - - - ADSLIB----.

1CMS Data Structures

lcMS Data Structures!

ADCONVERT. BAS
SAMPLE.BAS
SPEC.ANO
SYNCHRON.BAS
TIMETST.COM

2. CMS Library Initialized

3. Library Elements Loaded
ZK-369-81

Figure 2-1: Building a CMS Library

2-4

Building a CMS Library

When determining which files should be in a library, remember that CMS elements must
be ASCII files. The ASCII files must have been created or modified by a text editor such as
EDT. If you are in doubt about a file's suitability as a CMS library element, check the file
characteristics in your own directory with the following command.
$DIRECTORY /FULL f1lename.t•F

A file must be sequential and cannot have the characteristics of a binary file. If these conditions are not met, CMS cannot handle the file. See the VAX DEC/CMS Reference Manual
for more information about file characteristics.
Once you create elements in a library, you can impose a structure on your library by creating groups of elements. A group consists of one or more elements that CMS manipulates as
a unit. See Chapter 6 for more information about groups.

Building a CMS Library

2-5

Chapter 3

Accessing Files in a CMS Library
This chapter describes the CMS commands that you use to access files in a CMS library.
These commands perform the following functions:
• The CMS SET LIBRARY command gives you access to a particular library.
• The CMS RESERVE command copies a generation of an element file to your current
default directory. You perform all program modifications and testing in your own
directory with an editor, compiler, and utility. CMS records the reservation transaction and marks the element as reserved.
· • The CMS UNRESERVE command cancels your reservation and leaves the element
copy in your directory. CMS marks the library element as available for other reservations and records the transaction. Since there are no mQ_diiicatio_nsio theJibrary element, CMS-does-iiotui)aate the library element.
• The CMS REPLACE command copies the latest version of the element file from your
current default directory to the CMS library, creating a new generation of the element. CMS deletes the element file from your directory, allows you to enter a remark
to document the changes, records the transaction, and concludes your reservation.
• The CMS FETCH command copies an element into your current default directory.
The copy is treated as a read-only version for information, not for modification. An
element is not reserved when it is fetched, therefore fetched copies cannot be returned
to the library with the CMS REPLACE command.
'he sections that follow illustrate how each command can be used in various project
ituations.

',.1 Getting Started - CMS SET LIBRARY
.efore you can use CMS commands on an existing CMS library, you must use the CMS
ET LIBRARY command to establish access to that library. To set your library, type CMS
ET LIBRARY followed by the CMS library directory name. Each user must supply the
ame of the library directory when using the command:
CMS SET LIBRARY directory

fter Rick built the CMS library, he told Glenn and Sue the library directory name,
3-1

[PROJECT.ADSLIBJ. Glenn included the SET LIBRAHY command in 'his LOGIN.C0;\1
file so that each time he logged on to the system, he automatically had aocess to the library
elements. He entered the follo~ing command in his LOGIN.COM file:
$CMS SET LIBRARY [PROJECT.ADSLIBJ

Rick put the same command in his own LOGIN .COM file, but Sue decided to issue the CMS
SET LIBRARY command each time she wanted to work on the data sampler.
After you have established access to a library, you can display the name of your CMS
library directory by using the CMS SHOW LIBRARY command:
$ CMS SHOW LIBRARY

When you have access to an existing CMS library, CMS responds with the name of your
CMS library directory. If you do not have access to a library, CMS returns the following
message:
ICMS-E-NOREF1 error referencin! CMSSLIB:

3.2 Reserving a Library Element - CMS RESERVE
Most of your dealings with the CMS library for your project consist of reserving library
elements for work and replacing modified elements back into the library. If you have established access to a library (see Section 3.1) you can select an element and reserve it.
Use the CMS RESERVE command to reserve a library element. CMS always expects you
to enter a remark when you reserve an element. The remark that you enter should explain
why you are reserving the element. CMS then accepts your CMS RESERVE command and
copies the element into your current default directory. CMS marks the element with your
reservation and records the transaction in the library transaction history. While you have
an element reserved, anyone reserving any generation of the same element receives a
CMS message informing them that you have the element reserved.
At one point during the data sampling project, Sue Kelley reserved the element
SYNCHRON.BAS to debug a problem about lost data from one of the input channels. The
reservation transaction follows:
$ CMS RESERVE SYNCHRON.BAS
_Remark: losing saMPle froM one data line
ICMS-S-RESERVEDt generation 2 of eleMent SYNCHRON.BAS reserved

CMS places a copy of the element in Sue's current default directory and displays a message, indicating that generation 2 of element SYNCHRON .BAS is reserved.
By default, CMS retrieved the most recent generation of the element SYNCHRON.BAS
(generation 2). If Sue wanted to reserve an earlier generation to see if the same problem
existed, she could have specified the earlier generation with the /GENERATION qualifier.
That reservation transaction would have been as follows:

3-2

Accessing Files in a CMS Library

CMS RESERVE SYNCHRON,BA5 /GENERATION=l
_RemarK: Checf;1ng data li1,e sampling
ZCMS-S-RESERVEO, generation 1 of element SYNCHRON.BAS reserued

Sue would have received a copy of the first generation of the element in her current default
directory.
A remark can be entered in quotation marks in the same line with any CMS command. Sue
could have typed:
$CMS RESERVE SYNCHRON.BAS "losing sample from one data line"

If any generation of an element is already reserved by another person, CMS responds to
your request by issuing a message about the reservation already in effect. You then have
the option to proceed with your reservation or to quit. Usually two people choose not to
work on the same element concurrently. However, should the need arise, CMS provides the
mechanism to handle concurrent development. See Chapter 5 for information about concurrent reservations.

3.3 Canceling a CMS Reservation - CMS UNRESERVE
When you reserve a library element with the CMS RESERVE command and then decide
. not to modify that element, you can cancel your reservation with the CMS UNRESERVE
command. CMS accepts your UNRESERVE command and the remark you enter with it,
marks the element as available, and records the cancellation in the library history. CMS
does not update the element generation number when you cancel a: reservation.
The CMS UNRESERVE command is useful when you accidentally reserve the wrong element, or when you want to make an unmodified element available for another user, or
when you do not want your modifications to become part of an element. When you use the
CMS UNRESERVE command, the element in the library is not modified; it remains the
same as it was when you reserved it.
For instance, Glenn Lewis reserved a project element to diagnose a problem. A quick view
of the file showed him that he had selected an element that was not related to the problem.
He used the CMS UNRESERVE command to cancel his reservation for that element.
$ CMS UNRESERVE SYNCHRON.BAS
_Remark: Pr a not aPPlicable - wrong file
ZCMS-S-UNRESERVED• element SYNCHRON.BAS unreserved

CMS canceled Glenn's reservation, leaving SYNCHRON.BAS available for other users.
CMS left the copies in Glenn's directory and recorded the transaction.

3.4 Replacing a Modified Element in the Library
After modifying a reserved element, you put the modified element back in the project
library with the CMS REPLACE command. This command brings the library up to date on
element modifications and documents them.
Accessing Files in a CMS Library

3-3

L:se the CMS REPLACE command when you complete work on an element. The CMS
REPLACE command copies the latest version of the element file from your current default
directory into the project library. CMS then deletes all copies of that element from your
directory, assigns a new CMS generation number to the stored element generation, and
ends your reservation of that elem~nt. CMS also records the transaction.

For example, Rick reserved the current generation (generation 3) of the data sampler's
functional specification to correct a typographical error. When he finished correcting that
element, he replaced it.
$ CMS RESERVE SPEC.RNO
_ReMark: MissPellinf in Reliability section
ZCMS-S-RESERVEDo feneration 3 of eleMent SPEC,RNO reserved

CMS REPLACE SPEC.RNO
_Remark: ReliabilftY section tYPO fixed
ZCMS-S-GENCREATED, seneration a of eleMent SPEC.RNO created

CMS ended Rick's reservation of SPEC.RNO, deleted all copies from Rick's current default
directory, and recorded the transaction.
You can use the CMS REPLACE command with its /RESERVE qualifier when you wish to
update the library while retaining the element for additional modifications. This form of
the command wntinues your reservation of the element. The /RESERVE qualifier also
prevents CMS from deleting any copies of the element from your directory. CMS assigns a
new generation number to the stored element generation and records the transaction
along with your remark.
In the sample project, Glenn had three separate problem reports to check against a single
element. As he solved each problem, he used the CMS REPLACE command with the
/RESERVE qualifier to document his modifications. The first two transactions follow:
CMS REPLACE SAMPLE.BAS /RESERVE
_ReMark: Pr a - doc. error fixed - doins 5 next
ZCMS-I-GENCREATEDo feneration 2 of element SAMPLE.BAS created
-CMS-S-RESERVEDo feneration 2 of ,eleMent SAMPLE.BAS reserved

$ CMS REPLACE SAMPLE.BAS /RESERVE
_ReMark: Pr 5 - double Precision added
ZCMS-S-GENCREATEQ, feneration_ 3 of eleMen~ SAMPLE.BAS created and reserved

CMS updated the library with two new generations of the element, but Glenn still had his
copy for the next modification, and the element was still reserved for him. Each of the generations was documented with Glenn's comments in the library history.

3-4

Accessing Files in a CMS Library

You should replace a modified element whenever you reach <! :0gical stopping point in
development. This gives you a record of the specific reason for the element modification.
For example, when you modify a reserved element by adding a single routine and have no
further work to do on that element, use the CMS REPLACE command to document that
addition and return the element to the library. When you want to make several different
modifications to a reserved element, use the CMS REPLACE /RESERVE command after
all but the last modification. This allows you to document each modification but retain the
element for further work.

If you replace an element that was concurrently reserved and then replaced by another
user, you must create an alternate development path. (Refer to Chapter 5 for information
on alternate development paths.)

3.5 Getting a Read-only Copy
The CMS FETCH command copies an element file into your current default directory.
Unlike the CMS RESERVE command, CMS FETCH does not mark an element reserved,
and CMS does not allow you to replace a fetched copy in the library. You can fetch a copy of
an element whether the element is reserved or not. Use the /GENERATION qualifier to
fetch an earlier generation of the element.
· Whenever Rick needed to check his modifications to the data sampling software he used
the CMS FETCH command to retrieve a copy of the testing command file, TIMTST.COM.
For example:
CMS FETCH TIMTST,COM
_Remark: Testing storage blocks
%CMS-S-FETCHED• Element TIMTST.CDM• generation 2 fetched

CMS delivered a copy of the file to Rick's directory, and he used it to test his modifications.
When he finished testing his modifications, he simply deleted TIMTST.COM from his
directory. This transaction did not affect the library copy of the file.
A situation may arise in which you need to fetch an element that you have previously
reserved. If, for example, you wish to abandon a series of edits and start over, fetch the
element generation that you have previously reserved. If your current default directory
already contains a copy of the file you are fetching, CMS notifies you and continues the
transaction. In this case, CMS assigns the next higher file version number to the new file
and displays the following messages:
%CMS-I-FILEXISTS, file already exists• DRA1:[TESTSJTEST.FOR;2 created
%CMS-S-FETCHED1 generation 3 of element TEST.FOR fetched

When you issue the CMS REPLACE command, CMS always moves the highest-numbered
version of an element file from your current default directory to the library. Thus, if you
most recently worked on the fetched version, the changes that correspond to the fetched
version will be stored in the library.

Accessing Files in a CMS Library

3-5

Chapter 4

CMS Show Commands
As you begin to work with an existing CMS library, you might need additional information
about it. The CMS SHOW commands provide information about the library structure, history, and current status. This chapter contains information about several of the CMS
SHOW commands. The following list indicates the kind of information that you can get by
using each of these commands.
• What files are in the library?-CMS SHOW ELEMENT (Section 4.1)
• What files are being worked on? - CMS SHOW RESERVATIONS (Section 4.2)
• What transactions have occurred?- CMS SHOW HISTORY (Section 4.3)
• What is generation n of element X? - CMS SHOW GENERATION (Section 4.4)
• HowdidelementXevolve?-CMSSHOWGENERATION/ANCESTORS(Section4.5)
• What evolved from element X? - CMS SHOW GENERATION/DESCENDANTS
(Section 4.6)

4.1 What Files Are in The Library? - CMS SHOW ELEMENT
fhe CMS SHOW ELEMENT command displays an alphabetical list of the elements that
:ire in your library. For instance, in the sample project Rick used the CMS SHOW
~LEMENT command to see which elements were in the project library. CMS reported six
~lements in the library.
CMS SHOW ELEMENT
in DEC/CMS Library DRA3:[PRDJECT,ADSLI8]
~DCDNVERT.BAS "analo~ to di~ital conversion routines"
~RRMSG.TXT
"initial load"
3AMPLE.8AS
"SaMPlin~ Module"
3PEC.RNO
"ADS functional sPecification"
3YNCHRON,8AS "Synchronization routines"
rIMTST.COM
"COMMand Procedure for tests"

~leMents

4-1

4.2 What Files are Being Worked On? - CMS SHOW RESERVATIONS
The CMS SHOW RESERVATIONS command lists those reservations currently in effect.
In the sample project, Rick used this command to see which elements were being worked
on:
$

CMS SHOW RESERVATIONS

CMS reported which elements were reserved, who reserved the element, the generation
that was reserved, when, and why. Rick used this command to determine whether or not
any files from his default directory should be returned to the library.
Reservations in DEC/CMS Library DRA3:[PROJECT,ADSLIBl
SAMPLE.BAS
LEWIS
SYNCHRON.BAS
KELLEY
3

30-JUN-1984 11:19:29 "add code for more data lines"
18-JUN-1984 09:a2:03 "intefrate aid conversion"

4.3 What Transactions Have Occurred? - CMS SHOW HISTORY
Whenever you create, retrieve, or replace a library element, CMS stores information about
the transaction in its chronological history file. Various CMS SHOW commands display
historical information about the library. For example, the CMS SHOW HISTORY command allows you to review a chronological list of all library transactions. Early in the sample project, Sue used this command to request a record of library transactions:
$

CMS SHOW HISTORY

CMS reported the following:
History of DEC/CMS Library ORA3:[PROJECT.ADSLIBJ
1-MAY-1984 14:22:16 SANCHEZ CREATE LIBRARY DRA3:[PROJECT.ADSLIBJ "aid data
sa111Plin!' library"
1-MAY-1984 14:26:47 SANCHEZ CREATE ELEMENT SPEC.RNO "ADS functional
specification•
1-JUN-1984 12:09:02 SANCHEZ CREATE ELEMENT ADCONVERT.BAS "anal of to difital
conversion routines"
1-JUN-1984 12:25:41 SANCHEZ CREATE ELEMENT SAMPLE.BAS "Sa111Plin!' module"
1-JUN-1984 12:29:24 SANCHEZ CREATE ELEMENT SYNCHRON.BAS "Srnchronization
routines"
1-JUN-1984 14:01:36 SANCHEZ CREATE ELEMENT TIMTST,COM "Co111111and Procedure for
tests"
5-JUN-1984 14:47:40 KELLEY RESERVE SYNCHRQN,BASC1l "losinf sa111Ple from one
data line"

Note that CMS does not record transactions that do not alter the library. (These commands
include CMS ANNOTATE, CMS DIFFERENCES, CMS SET LIBRARY, and CMS SHOW
commands. CMS logs fetch transactions only if you supply a remark.)

4-2

CMS Show Commands

Once your librar~· has a large number of transactions, you can limit the CMS SHOW
HISTORY display with the /SINCE= date qualifier. If Sue had used CMS SHOW
HISTORY /SINCE= 15-MAY-1984, CMS would have reported only the transactions since
that date.
The CMS SHOW HISTORY command can be used with the qualifier /UNUSUAL to report
any abnormal library transactions that occurred, for exampie, two reservations in effect
for the same element at the same time.

4.4 What Is Generation n of Element X? - CMS SHOW GENERATION
When you need information about a specific generation of an element, use the CMS SHOW
GENERATION command to list the transaction that created the generation. When you
include a generation number, it must be specified with the /GENERATION qualifier. If you
omit a generation number, CMS assumes the most recent generation.
Rick investigated the creation of generation 3 with the following command:
S

CMS SHOW GENERATION SYNCHRON.BAS /GENERATION=3

CMS replied:
. SYNCHRON, BAS

2G-JUN-19Sa 09:aa:12 KELLEY "aid conversion integrated"

4.5 How Did Element X Evolve?- CMS SHOW GENERATION /ANCESTORS
The CMS SHOW GENERATION /ANCESTORS command lists the transactions that created each prior generation of the element. CMS produces a list in reverse chronological
order with one line about each generation. Each line includes the element name, generation number, user name, date, time, and remark of the transaction that created the
generation.
You can limit the listing by using the /GENERATION qualifier to specify a generation
number; in this case, the generation listing begins with the specified generation. If you
omit a generation number, CMS provides a complete ancestor list from the most recent
library version back to generation 1.
During the data sampler project, Glenn Lewis began modifications to the element
SYNCHRON.BAS sometime after Rick and Sue had both worked on it. To review the history of the element, he used the CMS SHOW GENERATION /ANCESTORS command as
follows:
$

CMS SHOW GENERATION /ANCESTORS SYNCHRON.BAS

CMS listed the following transactions:
SYNCHRON.BAS
3
2G-JUN-198a 09:aa:12 KELLEY a/d conversion integrated''
2
10-JUN-lSSa 13:10:12 KELLEY "last data line included"
1-JUN-19Sa 12.2s.2a SANCHEZ ''Synchronization routines''
11

CMS Show Commands

4-3

CMS ShOW GENERATION /ANCESTORS reported that the current version of
SYNCHRON .BAS is generation 3, which was replaced by Sue Kelley at 9:44 A.M. on June
26 after she integrated the conversion code. The previous generation (also created by Sue)
involved modifications to correct errors. Rick Sanchez placed the original element in the
library on June 1.

4.6 What Evolved from Program X? - CMS SHOW GENERATION
/DESCENDANTS
To get a report of all subsequent generations of an element, use the CMS SHOW
GENERATION /DESCENDANTS command. It allows you to specify a generation number
with the /GENERATION qualifier; generation 1 is the default generation. As in the display of ancestors, CMS SHOW GENERATION /DESCENDANTS lists the generations in
reverse chronological order.
For example, Rick knew that generation 2 had been debugged, so he requested only its
descendants:
$

CMS SHOW GENERATION /DESCENDANTS SYNCHRON,BAS /GENERATION=Z

CMS would list the following transactions:
SYNCHRON.BAS
3
26-JUN-1984 09:44:12 KELLEY "a/d conversion integrated"
2
10-JUN-1984 13:10:12 KELLEY "last data line included"

The CMS SHOW GENERATION /DESCENDANTS command reported that the problem
was resolved in generation 2 and that generation 3 includes new conversion code. This
command is also useful if you do not know if any variant lines of descent have been created
(see Chapter 5).

4-4

CMS Show Commands

Chapter 5

The Evolving CMS Library
Chapters 1, 2, and 3 describe how to use CMS commands to store and update a file in a CMS
library. The examples in these chapters show how to use CMS to build the main development path of an element, called the main line of descent.
Some circumstances require alternate development paths for project programs: for example, a change in scope of an existing program, trial development of a slightly different
internal program structure, or the discovery of an error in an earlier generation of an
~xisting program. To handle these circumstances, CMS allows you to establish a path that
is a variant of the main line of development- a branching in the evolution of the element.
'.::MS maintains a complete history in support of alternate development paths.
rhis chapter describes the use of the NARIANT qualifier on the CMS REPLACE comnand for creating alternate development paths. It describes the /MERGE qualifier for the
=:MS RESERVE and CMS FETCH commands. The /MERGE qualifier allows you to com>ine two paths of development. This chapter also describes concurrent reservations. Pro,-am evolution is illustrated in diagrams that show successive states of a library.

;.1 Alternate Development Paths
\n alternate development path in CMS is known as a variant line of descent. You establish
L variant line by using the N ARIANT = x qualifier on the CMS REPLACE command. This
reates a variant generation that CMS can distinguish from the main line of descent. The
1arameter x, called the variant letter, is any single alphabetic character. The format of the
ommand is as follows:
CMS REPLACE element-name /VARIANT=x
~MS copies the element from your default directory into the library and labels the variant
:eneration by appending the variant letter and the numeral 1 to the generation number.
'or example, if you had reserved generation 7 of an element named TEST! .FOR, you could
reate a variant as follows:

CMS REPLACE TEST1.FOR /VARIANT=A
Remark: Routine added for multi-user sYstem
CMS-S-GENCREATEDt 9eneration 7A1 of element TESTt.FDR created

5-1

The number after the letter A identifies successive generations on that variant branch. If
you reserve and replace generation 7 Al of TESTl.FOR, generation 7A2 will be created.
For added meaning, you can choose a variant letter that indicates the purpose of the variant line - "A" for alternate, "B" for bug fixes, "E" to indicate enhancements, and so forth.
Each variant can have variants of its own using the same N ARIANT method; for example,
a variant to 7Al could be replaced with NARIANT=E to become 7A1El.
During the data sampler project, Glenn knew that the program SAMPLE.BAS would have
to be tested in two separate environments, and that some differences would exist in the
code for each environment. He decided to establish a variant to the current main line for
the second system. Glenn reserved the most recent main line element and then replaced it
as a variant, starting a variant line of development. Figure 5-1 shows the main line development for SAMPLE.BAS prior to the variant path. Figure 5-2 shows the parallel line of
development after the program was replaced as a variant. Glenn's procedures to establish
the variant line of descent were as follows:
S CMS RESERVE SAMPLE.BAS
_Remark: handle different inPut for second system
lCMS-S-RESERVEDt element SAMPLE.BAS, feneration 3 reserved

<modification and

tes~l

S CMS REPLACE SAMPLE.BAS /VARIANT=A
_Remark: Modified for second sYstem
lCHS-S-GENCREATEDt feneration 3A1 of element SAMPLE.BAS created

Now Glenn could test the variant in a different environment, keeping the main line generation for his first target system.

5-2

The Evolving CMS Library

CMS LIBRARY
SAMPLE.BAS

ZK-360-81

Figure 5-1: Main Line Evolution
CMS LIBRARY
SAMPLE.BAS

......

ZK-361-81

Figure 5-2: Variant Line Evolution

The Evolving CMS Library

5-3

5.2 Merging Alternate Development Paths .
At some point in development, you may want to merge the changes made to an element in
a variant line back into the main line of descent. When you reserve an element from the
library, you can merge any two generations of the element that are not on the same line of
descent. Use the /MERGE= y qualifier on the CMS RESERVE command; y is the generation that is merged into the reserved generation.
Ifyou are merging a generation on the main line into a variant generation, you reserve the

variant, and specify the main line generation number as the value for the /MERGE qualifier. (The /MERGE= y qualifier can also be used with the FETCH command if you wish to
only see merge results, without updating the library.)
The /MERGE qualifier directs CMS to identify the common ancestor, the most recent generation that is common to both lines of descent. Internally, the subsequent changes in both
lines of descent are integrated with the common ancestor.
When you merge two generations of an element, CMS creates a file in your current default
directory. This file contains the results of the merge transaction. Because merging is only a
mechanical process, you must always check to be sure that the result is what you intend. If
there are conflicting modifications, CMS flags these lines in the file. As you are checking
the program for accuracy, you must resolve these conflicts.
To continue with the earlier example, Glenn decided after producing two generations of
SAMPLE.BAS on each development path, that the two paths should be combined. The
combined generation of SAMPLE.BAS would have code from each development path.
Glenn used the CMS RESERVE command with its /MERGE qualifier to combine the two
generations and produce a single main line generation. Figure 5-3 illustrates the combining of the two generations into a merged copy in his default directory. Glenn used the following CMS command to merge the two generations:
CMS RESERVE SAMPLE.BAS /MERGE=3A2
_Remark: Combining sYs2 version into dual-support version
ICMS-I-MERGECOUNTo 4 chan!es successfully mer!ed with no conflicts
ICMS-S-RESERVEOt !eneration 5 of element SAMPLE.BAS reserved and mer!ed
with feneration 3A2

5-4

The Evolving CMS Library

CMS LIBRARY
SAMPLE.BAS

USERS DIRECTORY
ZK-362-81

Figure 5-3: Merging Element Generations

rhe CMS RESERVE command with the /MERGE qualifier did the clerical work of combinng the changes from the two lines of development. CMS reported that four areas of
:hanges in generations 5 and 3A2 did not conflict and were incorporated successfully into
he default directory copy. After compiling and testing the program, Glenn used the CMS
mPLACE command to create generation 6 on the main line.

The Evolving CMS Library

5-5

5.2.1 Replacing a Merged Copy
Glenn used the following command to return the merged default directory copy of
SAMPLE.BAS to the library as generation 6 on the main line:
CMS REPLACE SAMPLE.BAS
_ReMarK: 3A2 and 5 Mer!ed for dual-suPPort
ZCMS-S-GENCREATEO, !eneration 6 of eleMent SAMPLE.BAS created
$

Figure 5-4 shows the library after the merged version of the element was replaced.
CMS LIBRARY
SAMPLE.BAS

ZK-363-81

Figure 5-4: A Merged Element

5.2.2 Resolving Merge Conflicts
When you merge two generations with either the CMS RESERVE command or the CMS
FETCH command, CMS checks for conflicting changes at the same line of the code. CMS
notifies you of any conflicts and flags the conflicting lines so that you can resolve the problem. Example 5-1 shows a flagged conflict in a source file.

5-6

The Evolving CMS Library

15
:0

OPTION TYPE = E;'PLICIT
DECLARE STRING DELTA_TIME

***************Conflict 1

******************************************~··*·~

DECLARE STRING ASC_TIME
******~******************************************************************~····~

MAP ISTRING_LENI STRING ASC_TIME

******** End of Conflict 1
SO

= 80

*******************************************~*•••

DECLARE LONG RETCODE
DIM LONG BINARY_DELTAlll
DIM LONG NOWlll
DIM LONG BINARY_CVT_TIMElll

Example 5-1: Merge Conflicts Flagged
Each conflict is flagged with the word "Conflict" and a sequential conflict number in a line
of asterisks. Following the asterisks, CMS displays the conflicting segments of text.
When you resolve the conflicts, use a text editor (for example, EDT) to delete the unwanted
lines and the asterisks from the file, and return the copy to the library with the CMS
REPLACE command.

5.3 Working Simultaneously on the Same Element
Situations can arise in which two people must work on the same element at the same time.
For example, one person has already reserved an element when a second person enters a
CMS RESERVE command for the same element. CMS informs the second person that the
element is reserved. At this point, the transaction can be terminated, or, the second
reserver can disregard the CMS message, reserve the element, and modify one of its generations. When the first reserver replaces the element, CMS reports that a concurrent reservation was made and tells who the second reserver was. Even if the second reserver has
already replaced the element, CMS reports the replacement transaction to the first person.
For example, if you reserve element TEST.BAS for modification after another person has
reserved it, you cause a concurrent reservation for element TEST.BAS. CMS always notifies you if an element is already reserved.
If you cannot avoid a concurrent reservation, be aware that some additional effort is
involved when replacing concurrently-reserved elements. The following sections show the
procedures for reserving an already-reserved element and for replacing such an element
into the library.

The Evolving CMS Library

5-7

5.3.1 Reserving an Element That Is Already Reserved
If the library element you wish to modify is already reserved by another person, CMS

accepts your CMS RESERVE command and the remark you enter with it. Then CMS
reports that the element is currently reserved and by whom. You may not reserve an element you have already reserved. If you use the CMS RESERVE command on an element
you have already reserved, CMS reminds you with the following message.
ZCMS-E-NORESERVATION1 error reseruins element TESTl.FOR
-CMS-E-RESERVEDBYYQU, element TESTl.FOR is already reserved by

YOU

Once CMS tells you about a previous reservation, it still gives you the option to reserve the
element at that time. If you choose to proceed, CMS delivers a copy of the element to your
default directory, marks the element as concurrently reserved by you, and notes the reservation transaction in the library history. Because concurrent reservations are not normal
for the library, CMS notes the concurrent reservation as an unusual condition. Unusual
conditions are displayed with the CMS SHOW HISTORY /UNUSUAL command.
In the sample project, when Glenn Lewis reserved the element SAMPLE.BAS, CMS
reported that Sue was updating the element by adding a new search routine. Glenn chose
not to work on the element at the same time. That reservation interaction was as follows:
CMS RESERVE SAMPLE.B~S
_Remark: Chanse con~ersion inPut
%CMS-I-RESBY1 Currently Reserved by
KELLEY Generation 7 31-SEP-1984 08:15:47 "extendin5 conversion"
Proceed? CY/NJ
<Nl: no
S

Glenn decided not to reserve SAMPLE.BAS at the same time Sue was updating it. He
waited until she replaced the modified element into the project library before making his
modifications.
Another time Glenn had no choice but to reserve an element concurrently. Rick had
reserved the element SYNCHRON.BAS for modifications, and he was out of the office
when Glenn needed to change the element to diagnose a problem at a test site. Glenn
reserved the element as follows:
S CMS RESERVE SYNCHRON.BAS

_Remark: Remote site down - 7th Phone call!
ZCMS-I-RESBY1 Currently Reserved bY
Sanchez Generation 4 10-SEP-1982 10:36:24 "Chansins FLDEXP"
Proceed? CY/NJ
<N>: Yes
%CMS-S-RESERVED; Element SYNCHRON.BASt seneration 4 reserved

Once he had reserved SYNCHRON.BAS, Glenn made the modifications to solve the test
site's problem. He then replaced SYNCHRON.BAS, creating generation 5.

5-8

The Evolving CMS Library

5.3.2 Replacing an Element That Has Already Been Replaced
When two users modify the same element at the same time, the first user can replace the
modified generation with the normal CMS REPLACE command to produce the next generation. However, the second user must replace the modifications as a variant generation.
One or the other can then choose to merge that variant back into the main line so that both
sets of program modifications appear in one generation.
When Rick returned, he used the CMS SHOW RESERVATIONS command to see what was
out of the library at the moment. CMS listed his reservation of SYNCHRON.BAS and
showed that Glenn had reserved and replaced the element while Rick was away.
$

CMS SHOW RESERVATIONS

SYNCHRON,BAS
10-SEP-1982 10:36:24 "changing FLDEXP"
SANCHEZ
Concurrent Replacements
LEWIS
5
14-SEP-1982 15:04:52 "Added switch test"

·Now Rick had to resolve the differences between generation 4 of the element, which was
reserved and in his directory, and generation 5, which Glenn had replaced in the library.
His choices were:
.
.
• To cancel his reservation with the CMS UNRESERVE command. This would be the
simplest solution ifhe had not done any work on the element. Rick would then reserve
the generation Glenn had replaced.
• To replace the modified element in the library as a variant generation of the element
using the CMS REPLACE NARIANT command, and then make another reservation
with the /MERGE qualifier. CMS would combine the changes, identifying any conflicts between the two generations. Rick and Glenn could resolve any conflicts and
replace the merged element as generation 6.
Since Rick had already modified the program, he chose the second option as the most effecti ve, and entered the following CMS commands:

The Evolving CMS Library

5-9

$
CMS REPLACE SYNCHRUN.BM~
.ARIANT=A.
_ ReJTI a r f; : F i x e .j b •.It '·' / o c h c ,. g e f o r re 11~6' t e s i t e
ZCMS-S-GENCREATED1 generatibn 4A1 of eleMent SYNCHRON,BAS created
$ CMS RESERVE SYNCHRON.lAS
/MERGE=QAl
_ReMarK: Merging 5 1 reMote f 1 • ) and QA (table fix)
ZCMS-5-MERGECDUNT, 3 chan!es successfully Merged with no conflicts
ZCMS-5-RESERVED• 9enerat1on 5 of eleMent SYNCHRON.BAS reserued and Mer!ed
with !eneration 4Al

(read and test I

$ CMS REPLACE SYNCHRON.BAS
_ReMarK: RePlacin9 Merged eleMent - no chan!es needed
ZCMS-5-GENCREATEDt 9eneration 6 of eleMent SYNCHRON.BAS created

There were no conflicting lines in the merged generations. Had any of the modificatiom
been made to the same line in the program, CMS would have noted these as conflicts.

5-10

The Evolving CMS Library

Chapter&

Project Organization with CMS
Earlier chapters in this manual describe how CMS can be used for storing project files and
for tracking the changes to these files during development. The commands that perform
these functions can be used by any one library user without a great deal of interaction with
other team members. Yet CMS is a project tool, and a project usually involves a number of
people. This chapter describes CMS as an organization and communication tool for any
number of people on a project. The commands described are basic commands; full command capabilities are described in the VAX DEC/CMS Reference Manual .

.6.1 The Early CMS Library
Figure 6-1 shows the early data sampler project library. Although the various elements
have been worked on by more than one project member, each element has evolved independently. After the first generation of each element was placed in the library, the programmers modified and tested the elements, thereby creating new generations each time they
returned the elements to the library.

6-1

CMS LIBRARY
S.11,MPLE BAS

SYNCHRON BAS

ADCONVERT.BAS

DISPLAY BAS

TIMETST COM

SPEC.ANO

ZK-1755-24

Figure 6-1: An Early CMS Library

For example, note that the element SAMPLE.BAS had evolved to its seventh generation
when this "snapshot" of the library was taken; yet by the same date the functional specification, SPEC.RNO, had been modified only once. The rest of this chapter builds on this
basic diagram to demonstrate how CMS aids interaction among project members. For clarity, only six of the project library elements are shown in the diagrams.

6-2

Project Organization with CMS

6.2 Using CMS Groups
CMS uses the element as the basic structural unit in a library. However, you can combine
one or more elements into a group that you can manipulate as a unit. Also, you can use
groups to reflect the general structure of the software project. The following sections
describe how to build and manipulate CMS groups.

6.2.1 Building a CMS Group
To build a group, you create an empty group with the CMS CREATE GROUP command.
Then you use CMS INSERT ELEMENT commands to associate elements with that group
name.
The project team established a group to contain elements that handled data. They created
the group and then inserted elements into that group with the following commands:
CMS CREATE GROUP DATA-ROUTINES
_ReMarK: routines for input & conversion
!CMS-S-CREATEQ, !rouP DATA-ROUTINES created
$ CMS INSERT ELEMENT SAMPLE.BAS DATA_ROUTINES
_ReMarK: inPut saMPlin! routines
!CMS-S-INSERTEQ, eleMent SAMPLE.BAS inserted into !rouP DATA-ROUTINES
.$ CMS INSERT ELEMENT ADCDNVERT.BAS DATA_ROUTINES
_ReMark: analo!-to-digital conversion
!CMS-S-INSERTEQ, eleMent ADCDNVERT,BAS inserted iRto !rouP DATA_RQUTINES
$

By using the CMS INSERT ELEMENT command, you can insert individual elements into
a group. You can also use the CMS INSERT GROUP command to associate a group of elements with another group. Because this is a bookkeeping function, the insertion of elements (or groups) into a specific group is only a logical connection. No physical merging of
elements occurs, so you can access individual elements as usual. See the VAX DEC/CMS
Reference Manual for more information about using these commands.

6.2.2 Using the Group Designation
Once you define a group, CMS allows you to access all the elements in the group by specifying the group name. For example, Rick wanted to check the latest generations of each of
the modules that process the input data. He used the following command to fetch all of the
. appropriate elements:
$

CMS FETCH DATA_ROUTINES "chacKin! si!nal

sto~a!e"

CMS retrieved the latest main line generation of each of the elements belonging to the
group DAT.A_ROUTINES.

6.2.3 Removing Elements from Groups
The CMS REMOVE ELEMENT command allows you to eliminate an element from a
group. This command only removes the association between an element and a group; it
does not alter or delete the element.
Project Organization with CMS

6-3

The proje..:t team had created a group named DOCUMENTATION; for some time, this
group contained only the element SPEC.RNO, the functional specification for the
software. As the project progressed, they hired a writer, Paul Abbott. Paul created several
elements in the library for the user's manual. When the documentation was ready for
review, he decided to use the group DOCUMENTATION. To keep the functional specification separate from the user documentation, he removed SPEC.RNO with the following
command:
$ CMS REMOVE ELEMENT SPEC.RNO DOCUMENTATION
_Remark: user's manual ready for first review
ZCMS-S-REMOVEDt element SPEC,RNO remoued from 9rouP DOCUMENTATION

6.2.4 Displaying the Group Structure of a CMS Library
To find out what groups are defined in your library, use the CMS SHOW GROUP command. CMS lists the group names in alphabetical order with the remark that was entered
when the group was created. To obtain a list of all elements in a specific group, use the CMS
SHOW GROUP command with the /CONTENTS qualifier. For example, Rick wanted to
check the contents of the group named DAT.A_BOUTINES:
CMS SHOW GROUP/CONTENTS DATA_ROUTINES
Groups in DEC/CMS Library DRA3:CPROJECT,ADSLIBl
$

DATA-ROUTINES "routines for inPut & conversion"
ADCONVERT.BAS
SAMPLE.BAS

6.3 Using CMS Classes
CMS allows you to define sets of element generations, called classes. CMS keeps track of
which element generations you assign to a specific class. You can use classes to represent
milestones for any or all phases of a project.
The purpose of a class is determined by the methodology used by project members. For
example, you can establish classes that represent different stages of development for each
element generation. Each generation represents a cycle that includes several steps:
reserving the element, adding or changing code, testing, and then replacing the element.
You can establish classes for different stages; one for implementation, another for testing,
and a third class for the generations that have completed the first two stages. As each.module progresses through each stage, you assign it to the appropriate class; thus, you can
easily determine your progress by displaying the contents of the different classes.
You can also use classes for system integration. When all the modules reach a working
stage in development, you integrate the modules into the first working version or "base
level" of the product for testing. Each module that is used in the base level corresponds to
an element generation in a CMS library. You can create a class that contains each element
generation used in the base level.

6-4

Project Organization with CMS

Different base levels represent milestones in the development of a project. For example.
test versions, internal release versions, and external release versions might bi: significant
milestones. A project can also evolve through additional releases with enhancements and
corrections. These stages vary from project to project, but the life of a project is essentially
the same for a payroll application program as it is for a compiler project - from design and
development to test and release, then to maintenance and enhancement. You can establish
one or more classes to reflect each of the different stages of a project.

6.3.1 Building a CMS Class
To build a class, you create an empty class with the CMS CREATE CLASS command. Then
you use CMS INSERT GENERATION commands to place specific element generations in
that class. (CMS allows only one generation of an element per class.) The /GENERATION
qualifier of the CMS INSERT GENERATION command specifies the generation to be
inserted. When you omit the qualifier, CMS places the most recent main line generation in
the class.
On the data sampler project, the team created a class called BASELEVELI and assigned
specific generations of the library elements to that class. Rick did this with the following
commands:
CMS CREATE CLASS BASELEVEL1
_Remark: SPecifYins all sens for first base level
ICMS-S-CREATED, class BASELEVEL1 created
$ CMS INSERT SAMPLE.BAS /GENERATION=S BASELEVEL1
_Remark: Checked and OKd bY SK
ICMS-S-GENINSERTED• seneration 6 ~f element SAMPLE.BAS inserted into class .
BASELEVEL1
$ CMS INSERT SYNCHRON.BAS /GENERATION=4 BASELEVEL1
_Remark: Checked and OKd by RS
ICMS-S-GENINSERTED, seneration 4 of element SYNCHRON.BAS inserted into class
BASELE~JEL 1
$ CMS INSERT ADCDNVERT,BAS BASELEVEL1
_Remark: Using latest• checked OK this am - GL
ICMS-S-GENINSERTEQ, seneration 5 of element ADCONVERT.BAS inserted into class
BASELEVEL1
$ CMS INSERT DISPLAY.BAS BASELEVEL1
_Remark: Terminal disPlaY of sampled data
ICMS-S-GENINSERTED, seneration 2 of element DISPLAY.BAS inserted into class
BASELEVEL1
$

Figure 6-2 indicates which element generations were inserted in the class BASELEVELl.
The class consists of only those element generations specified by the CMS INSERT
GENERATION commands. Because this is a bookkeeping function, the insertion of generations into a specific class is only a logical connection. No physical merging of elements
occurs, so you can access individual generations and elements as usual with other CMS
commands.

Project Organization with CMS

6-5

..
CMS LIBRARY
SAMPLE BAS

SYNCHRON BAS

ADCONVERT.BAS

DISPLAY BAS

TIMETST COM

BASELEVEL 1

Figure 6-2: A CMS Library Showing a Defined Class

6-6

Project Organization with CMS

SPEC.ANO

ZK-365-81

·6.3.2 Using the Class Designation
Once you define a class, CMS allows you to access any element generation in that class by
specifying the class name. You do not have to know the specific generation number of the
element. For example, when a problem in the base level was reported to the project team,
Rick had to test SAMPLE.BAS. To ensure that the proper generation of the element was
tested, he used the following command:
$

CMS RESERVE SAMPLE.BAS /GENERATION=BASELEVELI

CMS placed the proper element, generation 6, in the default directory, even though the
latest generation was 7.

6.3.3 Displaying the Class Structure of a library
To find out what classes are defined in your library, use the CMS SHOW CLASS command.
CMS lists the class names in alphabetical order with the remark that was entered when
the class was created. To obtain a list of all generations in a specific class, use the CMS
SHOW CLASS command with the /CONTENTS qualifier. For example, Rick wanted to
check the contents of the class the project was using for the first base level:
$

CMS SHOW CLASS/CONTENTS BASELEVELI

·CMS listed all of the elements and their generations inserted in BASELEVELl as follows:
Classes in DEC/CMS Library DRA3:CPROJECT.ADSLIBJ
BASELEVELI "Specifying all !ens for first base level"
ADCONVERT,BAS
5
DISPLAY.BAS
2
SAMPLE.BAS
6
SYNCHRON.BAS
a

6.3.4 Assigning Elements to Multiple Classes
In addition to keeping track of an established class, CMS allows you to designate some or
all of the element generations in one class as belonging to another class as well. This permits a base level or release to contain various options to the standard version.
On the sample project, Rick wanted an alternate version of the first base level for demonstration purposes. He needed to suppress some of the newer features that were not fully
implemented so the data sampler could work without errors when it was demonstrated. He
used the following procedure to accomplish this:
1.

He reserved the conversion element, ADCONVERT.BAS.

He modified it to ignore the new features.

He replaced the modified element as a variant of the standard element.

He established a new class called DEMOA to contain the modified synchronization
element and all of the other elements that made up the base level of the data
sampler.
Project Organization with CMS

6-7

He used the following CMS commands to create class DEMOA:
s' CMS CREATE CLASS DEMOA
_ReMarK: Runnable baseleuell uers1an - onlv for demos
lCMS-S-CREATEDr class DEMOA created

S CMS INSERT ADCONVERT.BAS /GENERATIDN=5D1 DEMDA
_ReMarK: Modified BLl version for demos
lCMS-S-GENINSERTED1 generation 501 of element ADCONVERT.BAS inserted into
class DEMDA
$ CMS INSERT SAMPLE.BAS /GENERATION=BASELEVELl DEMOA
_ReMarK: BLl version OK for demos
lCMS-S-GENINSERTEDr generation 6 of element SAMPLE.BAS inserted into class
DEMO A
$ CMS INSERT SYNCHRON.BAS /GENERATlON=BASELEVELl DEMOA
_ReMarK: BLl version DK for demos
lCMS-S-GENINSERTEDr generation a of element SYNCHRON,BAS inserted in class
DEM DA
$ CMS INSERT DISPLAY.BAS /GENERATIDN=BASELEVELI DEMOA
_ReMarK: BLl version OK for demos
lCMS-S-GENINSERTEDr generation 2 of eleMent DISPLAY.BAS inserted in class
DEMOA

Figure 6-3 shows the variant, 5Dl, branching from the main line of descent for element
ADCONVERT.BAS. The two different base levels are indicated. Note that BASELEVELl
and DEMOA are identical except for ADCONVERT.BAS, which has a different generation
in each class.

6-8

Project Organization with CMS

CMS LIBRAR'!
SAMPLE BAS

SYNCHRON BAS ADCONVERT.BAS

DISPLAY.BAS

TIMETST.COM

SPEC RNO

............. BASELEVEL1
+M+++- DEMOA

ZK-366-81

Figure 6-3: Multiple CMS Classes
Project Organization with CMS

6-9

6.3.5 Removing an Element from a Class
The CMS REMOVE GENERATION command allows you to eliminate an element generation from a class. For example, suppose that the first base level was going to be reduced in
scope, and DISPLAY.BAS dropped from the class BASELEVELl. The command to accomplish this task would be:
$

CMS REMOVE GENERATION DISPLAY.BAS BASELEVEL1

CMS would then revise its information about BASELEVELI so that DISPLAY.BAS would
not be included in the class. All future references to BASELEVELI would refer to the class
without DISPLAY.BAS.

6.3.6 Defining a Release with CMS
The process for establishing a release version of library elements is the same as it is for
defining a base level - you create a class and then insert appropriate element generations
into it. The class name could be the release version number (RELI or RELEASE2A, for
instance). CMS still maintains the audit trails back to the beginning of the project so that
the complete project history is available.

6.3. 7 Supporting a Product Using CMS
When an error is reported in either a base level or a release version of a product, careful
tracking is needed to ensure that the appropriate generation is corrected. It is also necessary to maintain the integrity of that version with proper historical information. CMS
helps merge the modification into the product code and preserves the integrity of the
library history.
The CMS INSERT GENERATION command, when used with the /ALWAYS qualifier, lets
you correct a class and replace the problem generation with a corrected generation. Any
existing generation of that element is removed from the class, and the generation specified
takes its place.
In the sample project, an error within an element used in the first release required correction. The corrected element was needed to replace the incorrect module in the release class.
Mike corrected the problem in the following way.
1.

He reserved the element generation containing the error.

He modified and tested the element until it was satisfactory.

He replaced the corrected element as a variant.

He inserted the generation in the class while superseding the previous generation
of the element.

These are the commands he used:

6-10

Project Organization with CMS

CMS RESERVE DISPLAY.E~S /GENERATIDN=RELEASEI
_ReMark: PR No. a - To fix uninitialized variable
ICMS-S-RESERVED1 eleMent DISPLAY.BAS, feneration 9 reserved

<debuf • Modification and test)

CMS REPLACE DISPLAY.BAS /VARIANT=B
_ReMark: Additional initialization done - R1-PR-G fixed
ICMS-S-GENCREATED1 feneration 9B1 of eleMent DISPLAY.BAS created
$ CMS INSERT GENERATION DISPLAY.BAS /GENERATION=SBI RELEASE! /ALWAYS
_ReMark: PR No, a - rePlaceMent for fen 9 buf in Rel 1
ICMS-S-GENINSERTED1 feneration 9B1 of eleMent DISPLAY.BAS inserted into
class RELEASEI

Part A of Figure 6-4 shows the portion of the library with the class RELEASE! in its original form. Part B of Figure 6-4 shows the project library after the error in element
DISPLAY.BAS had been corrected. The class name RELEASE! refers to the class containing the corrected element DISPLAY.BAS. The class that contained generation 9 of
DISPLAY.BAS is not maintained.

Project Organization with CMS

6-11

CMS LIBRARY
SAMPLE.BAS

SYNCHRON.BAS ADCONVERT.BAS

DISPLAY.BAS

TIMETST COM

SPEC.ANO

ZK-367-8

11111111111 RELEASE1

(original)

CMS LIBRARY
SAMPLE.BAS

SYNCHRON.BAS ADCONVERT.BAS

• • - • - RELEASE1 (superseded)

DISPLAY.BAS

TIMETST.COM

SPEC.ANO

ZK-368-81

Figure 6-4 : A CMS Class Containing a Superseded Element Generation
6-12

Project Organization with CMS

Chapter 7

Additional CMS Commands
This chapter describes the CMS ANNOTATE and CMS DIFFERENCES commands:
• The CMS ANNOTATE command provides the history and line-by-line information
about a library element. CMS lists the history of all changes ever made to the element
and then lists each line of the element, tagging each line with the number of the generation in which the line appears. CMS does not record an ANNOTATE operation in
the library history.
• The CMS DIFFERENCES command performs a line-by-line comparison of any two
ASCII files. CMS does not record a DIFFERENCES operation in the library history.

7.1 Getting Line-by-Line Information
CMS maintains information about changes to each element in the library. The CMS
ANNOTATE command produces a line-by-line listing of the changes made in any generation of a specified element. The annotated listing begins with a summary of changes to the
element (when it was modified, which generation was modified, and who did the modifying). Then, CMS lists the program and labels all lines that were not in the first generation.
Each line that has been added (or changed) is marked with the generation number to indicate when the line was added or when it was last modified. The annotation process writes
the listing in a file in your default directory. By default, CMS gives the file the same name
as the element, but with a file type ANN. To annotate an earlier generation of the element,
Lise the /GENERATION qualifier.
When Sue Kelley wanted to see what modifications Rick Sanchez made to the element
rIMECVT.BAS, she used the following command:
~ CMS ANNOTATE TIMECVT.BAS
tCMS-S-ANNOTATEDr Element TIMECVT.BASr generation 3 annotated

'.;MS delivered a file, TIMECVT.ANN, to Sue's current default directory. Example 7-1
;hows the printed annotated output. The historical information at the top of the listing
ndicates the user, date, time, and remark entered each time a new generation was cre1ted. The second entry of the history shows that Rick replaced a modified copy of
rIMECVT.BAS, creating generation 2. The line-by-line information indicates that Rick
nodified line 6.

7-1

Example 7-1 shows a sample of the information delivered by the CMS ANNOTATE
command.
Annotat•d list1nf for element TIMECVT.BAS in DEC/CMS Library ORA3:CLEWIS.BCCMSJ

•3
•2

•1

25-"AR-198a

15:~'-'::8

25-MAR-1984 15:49:01 ~ELLEY ''add check for invalid delta t1Me~
25-MAR-1984 15:39:58 SANCHEZ ''JP - f1~ed lenfth str1nf required''
25-MAR-1984 15:37:11 SANCHEZ ''time conversion Profram"

Annotated listinf for eleMent TIMECVT.BAS in DEC/CMS Library ORA3:lLEWIS.BCCMSJ

25-MAR-1984 15:50:29

rem Profram to compute an absolute time fiv•n the Present t1Me
fem and a delta time. The result is written to a file.

OPTION TYPE = EXPLICIT
DECLARE STRING DELTA_TIHE
MAP CSTRING_LENl STRING ASC_TIME
DECLARE LONG RETCODE
DIM LONG !llNARY-DELTACll
DIM LONG NOW( 1 l
DIM LONG BINARY_CVT_TIHE<ll

z
3
4

5
6

7
8
9
10

12
13
14
15
16
17
18
19
20
21
22

100

150

175

26
27

3
3
3

30
31

zoo

32
33
34

35
36
37
38

39
40

LONG CONSTANT SS$_NORMAL
LONG CONSTANT SSLIVTIHE
LONG FUNCTION LIB$AODX
LONG FUNCTION LIB$SUBX
LONG FUNCTION Ll!l$1NT _DVER
LONG FUNCTION SYS$BINTIH <STRING BY OESC, LONG BY REFl
LONG FUNCTION SYS$GETTIH <LONG BY REF>
LONG FUNCTION SYS$ASCTIH <LONG BY REFo STRING BY DESCo
LONG BY REF, LONG BY REFl
LET RETCDDE = LIB$INT_OVER<Ol

PRINT "InPut delta timeM

23
3
3
3
3

EXTERNAL
EXTERNAL
EXTERNAL
EXTERNAL
EXTERNAL
EXTERNAL
EXTERNAL
EXTERNAL

3Z767

INPUT DELTA-TIME
LET RETCDDE = SYS$BINTIH ( DELTA_TIHE, BINARY_DELTACOl l
IF <RETCODE = SS$_NDRHALl THEN GOTO ZOO
ELSE IF RETCODE = SS$_IVTIHE THEN
~
PRINT ,"INVALID TIME"
GOTO DONE
END IF
ENO IF
LET RETCDDE = SYS$GETTIM<NDW<Oll
IF <VAL< DELTA_TIME l > 0 l THEN
RETCODE=Ll~$AODXCNOW<Ol oBINARY-DELTA COl
oBINARY_CVL TIHE<Ol l
END IF
LET RETCDDE = SYS$ASCTIH< oASC_TIHEoBINARy_CVLTIME<Ol ol
OPEN "TIME.TMP" FOR OUTPUT AS FILE •1
PRINT •I oASC_TIHE
CLOSE •1
Done: END

Example 7-1: Sample Annotated Listing

7.2 Comparing Files
The CMS DIFFERENCES command allows you to do line-by-line comparisons of two
ASCII files. The files can exist in a CMS library or in a non-library directory. (If the files are
in a CMS library, they must be in the same library; you cannot use CMS to compare elements from different libraries.)
7-2

Additional CMS Commands

When CMS compares two files, it outputs a listing file to your d~fault directory. By default,
the listing file has the same name as the first file specified in the CMS DIFFERENCES
command, with a file type of DIF. The file lists the names of the two files that were compared, and then lists all differing lines of the two files in sequential order with line numbers and full line text. CMS DIFFERENCES does not generate an output file if the
comparison does not result in any differences.
On the data sampler project, Rick used the CMS DIFFERENCES command to check a bug
fix. He compared the element generation that contained the bug against the next generation by using the CMS DIFFERENCES command:
CMS DIFFERENCES TIMECVT.BAS /GENERATION=2 TIMECVT.BAS /GENERATION=!
%CMS-I-DIFFERENT, files are different

Rick used the /GENERATION qualifier to direct CMS to use generations 1 and 2 of
TIMECVT.BAS in the comparison. Example 7-2 shows the report from this comparison,
TIMECVT.DIF.
DEC/CMS File Comparison Utility
Files Compared BY SANCHEZ On 25-MAR-198a 15:51:58
!ll Element TIMECVT.BAS Generation 2
!2l Element TIMECVT.BAS Generation 1

**** Generation Differences ****
TIMECVT.BAS
3
25-MAR-198a 15:a9:01 KELLEY "add check for invalid delta time"
*2
25-MAR-198a 15:39:58 SANCHEZ "JP - fixed length string required"
*1
25-MAR-198a 15:37:11 SANCHEZ "time conversion Program"

**** Text Differences ****

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Element TIMECVT.BAS<2l Line 6
ll
MAP <STRING_LENl STRING ASC_TIME = 80
Element TIMECVT.BAS<ll Line 6
2l
DECLARE STRING ASC_TIME

**** End of Differences ****

Example 7-2: Sample CMS DIFFERENCES Listing
TIMECVT.DIF shows the element generations used in the comparison, the generation history for the element, and the differences between the two generations.

Additional CMS Commands

7-3

Appendix A

tJotes on Using CMS Libraries
This appendix contains information that may be useful to you as you build and use your
CMS library. In general, project planning will have the greatest impact on how you can
best use CMS. Each project has its own characteristics that determine how you should
organize it.
The Library Storage Method

CMS stores the entire text of the first generation of an element. Each time you replace an
element, CMS determines what has been changed in the element file(s). In order to save
storage space, only the new and changed lines of successive generations are stored. The
rule of thumb for estimating online mass storage for the library is to allow three times the
amount of space that you would normally allow for one copy of all project files.
A file in a CMS library can be portrayed as shown in Example A-1.

< 1 ,2 ,3)
APPLES
( 1 •2 ,3 > BANANAS
< 1 ,2 ,3 > CHERRIES
Cl>
POOCHES
(2)
PAUNCHES
<3>
PEACHES
< 112 ,3)
ELDERBERRIES

Example A-1: The CMS Storage Method (Simplified)

Example A-1 shows that each data item is numbered according to the element generations
in which the item appears. The line "POOCHES" (-occurring in the first generation) has
been changed to "PAUNCHES" in the second generation, and changed again to
"PEACHES" in the third generation.

A-I

CMS can provide a complete copy of any of the three generations whenever necessary. (It
can also produce an annotated copy showing all changes in each generation and identify
the person who made those changes.) However, in the library, the data require only seven
lines of storage space. Conventional storage methods would require 15 lines, five lines for
each of the three copies of the data.
Project members do not have to keep back-up copies of CMS library files in their own
account. Normal system backup procedures should be followed for the contents of a CMS
library, as for any valuable files. CMS itself keeps a certain amount of back-up information
to recover from an incomplete transaction after a system failure.
Elements are stored most efficiently when modifications leave the majority of the file lines
unchanged. CMS only stores one copy of an element; this copy includes all lines from the
first generation plus all modifications to successive generations. Thus the number of differences (relative to the number of original lines) affects system efficiency.
For example, the modifications to successive generations of a FORTRAN source program
might typically change 15 to 20 percent of the lines during the development of that program. Since the bulk of the program does not change, this kind of element is ideal for a
CMS library. On the other hand, the same program listing file would change drastically
with each modification due to the compiler's effect on line numbers, addresses, and so forth.
Each generation of the stored listing element would contain almost as many differences as
original lines.
·

A-2

Notes on Using CMS Libraries

Glossary
Class
A set of element generations with only one generation per element.
Concurrent replacement
A library transaction that replaces an element that has been marked as concurrently
reserved.
Concurrent reservation
Two or more reservations in effect for the same element at the same time.
Element
An ASCII file that is stored in a DEC/CMS library.
Fetch
Retrieves a copy of a library element that (in terms of library tracking) is for readonly purposes; the element is not reserved.
Generation
Representation of a phase in the development of an element: every time you retrieve
and then return an element to the library (see Reservation and Replacement) a new
generation is created. Any generation of an element can be retrieved; each generation reflects the changes that were made at that particular point in development.
Generation number
A number or a combination of numbers and letter(s) that identify an element
generation.
Group
A set of elements that can be manipulated as a unit.

History
The historical record of library access (generally includes all transactions except
those that display library information or that access library contents for read-only
purposes).

Library
The largest group of files that DEC/CMS recognizes as a unit.
Glossary-I

e of descent
A series of generations of an element, created by successive reservation and replacement transactions .
.n line of descent
The series of generations of an element that are identified by single generation
numbers.
·ging

Combining two generations of an element that do not lie on the same line of descent.
1lacement
A library transaction in which a user returns a reserved element to a library, thus
ending the reservation.
ervation
A library transaction in which a user retrieves a copy of an element file from the
library. DEC/CMS marks that library element as reserved by the user. For the duration of the reservation, if any user reserves that element, CMS indicates that it is
reserved.
iant generation
An element generation that does not lie on the same line of descent as its predecessor.
iantletter
A letter used in a generation number to identify a variant line of descent.
iant line of descent
A line of descent that is separate from the main line of descent: an alternate development path. Generation numbers of variant line generations consist of combinations
of numbers and variant letter(s).

Glossary-2

INDEX

A
Abbreviation, command, 1-4
Access to library, 3-2
Alternate development paths, 5-1
.ANN file type, 7-1
ANNOTATE, 7-1
Annotated listing, 7-1
sample, 7-2
· ASCII file comparison, 7-2

B
Back-up, library, A-1
Base level, 6-4

c
Cancellation
concurrent reservat'ion, 5-9
reservation, 3-3
Class, 1-4
creation, 6-5
display, 6-7
name, 6-5
placement of generations in, 6-5
reference by name, 6-7
removal of a generation, 6-10
replacement of generations, 6-10
CMS, 1-1
CMS capabilities, 1-1
Code Management System, 1-1

Combination of two generations, 5-4
Command
CREATE ELEMENT, 2-2
CREATE LIBRARY, 2-2
SET LIBRARY, 3-1
Command abbreviation, 1-4
Command, CMS
·;-;, (see also individual subcommand
names)
CMS ANNOTATE, 7-1
CMS CREATE CLASS, 6-5
CMS CREATE GROUP, 6-3
CMS DIFFERENCES, 7-2
CMS FETCH, 3-5
CMS INSERT ELEMENT, 6-3
CMS INSERT GENERATION, 6-5
CMS REMOVE ELEMENT, 6-3
CMS REMOVE GENERATION, 6-10
CMS REPLACE; 3-3
CMS RESERvE, 3-2
CMS SHOW, 4-1
CMS SHOW CLASS, 6-7
CMS SHOW ELEMENT, 4-1
CMS SHOW GENERATION, 4-3
CMS SHOW
GENERATION/ANCESTORS, 4-3
CMS SHOW
GENERATION/DESCENDANTS,
4-4

CMS SHOW GROUP, 6-4
CMS SHOW HISTORY, 4-2
CMS SHOW LIBRARY, 3-2
CMS SHOW RESERVATIONS, 4-2
CMS UNRESERVE, 3-3

Comparison of ASCII files, 7-2
Concurrent replacement, 5-9
Concurrent reservation, 5-7
cancellation, 5-9

record, 5-8
replacement, 5-9
warning, 5-7
Conflict
merge, 5-6
resolution, 5-7
/CONTENTS, 6-4, 6-7
CREATE (VMS command)
/DIRECTORY, 2-1
/PROTECTION, 2-1
CREATE CLASS, 6-5
CREATE ELEMENT, 2-2
CREATE GROUP, 6-3
CREATE LIBRARY, 2-2
Creating a VMS library, 2-1

Element (Cont.)
removal from a group, 6-3
replacement, 3-3
replacement with a fetched copy, 3-5
reservation, 3-2
VMS characteristics, 2-5

F
FETCH, 3-5
/MERGE, 5-4
File
characteristics, 1-2
comparison, 7-2
library, 1-2
File type
.ANN, 7-1
.DIF, 7-3
Files for the library, 2-5

DEC/CMS, 1-1
Definition of a release, 6-10
.DIF file type, 7-3
DIFFERENCES, 1~2
Display, terminal
(see Terminal display)

/GENERATION, 3-2
Generation
combining, 5-4
merging, 5-4
placement in a class, S-:5
reference by class name, 6- 7
removal from a class, 6-10
successive, 1-2
variant, 5-1
Group, 1-4
creation, 6-3
display, 6-4
name, 6-3
removal of an element, 6-3

E
Element
ancestor, 4--3
annotated listing, 7-1
cancellation of a reservation, 3-3
concurrent reservation, 5-7
creation, 2-2
definition, 2-2
descendant, 4-4
display list of, 4-1
generation of, 4--3
merging generations, 5-4
name, 2-2
read-only copy, 3-5

Index-2

H
HELP, 1-4
History
ANCESTORS, 4-3
DESCENDANTS, 4-4
generation, 4-3

N
Initializing a library, 2-2
INSERT ELEMENT, 6-3
INSERT GENERATION, 6-5
INSERT GENERATION /ALWAYS,
6-10

K
Keeping a reserved element, 3-4
Kinds of files, 1-2, 2-5

Name
class, 6-5
element, 2-2
group, 6-3

0
Online documentation, 1-4

p
L
Library
back-up, A-1
creation, 2-1
evolution, 5-1
history, 4-2
history display, 4-2
storage space, A-1
Library directory
Setting up
VMS, 2-1
Library information, terminal display,
4-1
Line of descent
main, 5-1, 5-3
merging changes, 5-4
variant, 5-1, 5-3
Listing, annotated, 7-1
LOGIN.COM, 3-2

Placing files in library, 2-2 ···
Project
development stages, 1-4
interaction, 6-1
organization, 1-4, 6-1
Protection
VMS library, 2-1

Q
Qualifier, CMS
/ALWAYS, 6-10
/CONTENTS, 6-4, 6-7
/GENERATION, 3-2
/MERGE, 5-4
/RESERVE, 3-4
/SINCE=date, 4-3
/UNUSUAL, 5-8
N ARIANT, 5-1

M
R
Main line of descent, 5-1, 5-3
/MERGE,5-4
Merging generations, 5-4
conflict, 5-6
replacing a merged generation, 5-6

Release
definition, 6-10
REMOVE ELEMENT, 6-3
REMOVE GENERATION, 6-10

Index-3

REPLACE, 3-3
/RESERVE, 3-4
N ARIANT=x, 5-1
Replacement
concurrent, 5-9
Replacement of a merged generation, 5-6
Reservation
cancellation, 3-3
cancellation of a concurrent, 5-9
concurrent, 5-7
·
of a reserved element, 5-8
Reservation of an element, 3-2
/RESERVE, 3-4
RESERVE, 3-2
/GENERATION, 3-2
/MERGE,5-4
Resolution of merge conflicts, 5-7

s
Sample terminal session, 1-3
SET LIBRARY commarld, 3-1
Setting up a library, 2-1
SHOW, 4-1
CLASS, 6-4, 6-7
ELEMENT, 4-1
GENERATION, 4-3
HISTORY, 4-2
HISTORY /SINCE=date, 4-3
HISTORY /UNUSUAL, 5-8
LIBRARY, 3-2
RESERVATIONS, 4-2
SHOW GENERATION
ANCESTORS, 4-3
DESCENDANTS, 4-4
Specification of a generation, 3-2
Stages of project development, 1-:4
Starting a CMS library, 2-1
Storage apace, A-1
Succesaive generation, 1-2

Index-4

T
Terminal display
class, 6-7
group, 6-4
history, 4-2
library elements, 4-1
library information, 4-1 ·
reservations, 4-2
Trace
·
ancestors, '4_3
descendants, 4-4
Tracking a project, 6-1
Typical CMS application, 1-5
.~i

UNRESERVE, 3-3
/UNUSUAL, 5-s·Updating the history, 3-:4

v
N ARIANT, 5-1
Variant
generation, 5-1
letter, 5-1
line of descent, 5-1, 5~3,
variant of a, 5-2

t~.

Warning
concurrent reservation, 5-7
merge conflict, 5-6

User's Introduction to
VAX DEC/CMS

AA-L371B-TE

Reader's Comments
Note: This form is for document comments only. DIGITAL

will

use comments
submitted on this form at the company's discretion. If you require a written reply and are eligible to receive one under Software Performance :
Report (SPR> service, submit your comments on an SPR form.

Did you find this manual understandable, usable, and well-organized? Please
make suggestions for i m p r o v e m e n t . - - - - - - - - - - - - - - - - - -

Did you find errors in this manual? If so, specify the error a!ld the page number.

Please indicate the type of user/reader that you most nearly represent.
D
D
D
D
D
D

·'

Assembly language programmer
Higher-level language programmer
Occasional programmer (experienced)
User with little programming experience
Student programmer
"t'
. I~
Other (please s p e c i f y ) · _ - - - - - - - - - - - - - - - - J.~

::t ..

Name---------------- Date-----------Organization--------------------------Street _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __
City _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ State ___ Zip0 ;-ode_ _ _ __
Country·

I
I
I

---Do Not Tear· Fold Here and Tape

------------------------------------.J

111111

No Postage
Necessary
if Mailed in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT N0.33 MAYNARD MASS
POSTAGE WILL BE PAID BY ADDRESSEE

SSG PUBLICATIONS ZK1-3/J35
DIGITAL EQUIPMENT CORPORATION
110 SPIT BROOK ROAD
NASHUA, NEW HAMPSHIRE 03062-2698

---Do Not Tear- Fold.Here and T a p e - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

I
I