CMS stores all the information it needs in a library. A CMS library is an OpenVMS directory containing specially formatted files. It serves as a container or repository for various CMS entities (called objects).

An element is the basic structural unit in a CMS library; it consists of one file and all its versions. An element generation represents a specific version of that element. When you create an element and place it in a CMS library for the first time, CMS creates generation 1 of that element. Each time you reserve and then replace a generation of an element in the library, CMS creates a new generation of that element.

For information on libraries, see Chapter 3, Libraries. For information on elements and generations, see Chapter 4, Elements and Generations.

A group is a set of elements (or other groups) that you can combine and manipulate as a unit. For example, you might create a group containing all the elements that process error messages.

A class is a set of particular generations of elements. You typically combine generations of elements into classes to represent progressive stages, or base levels, in the development of an entire system.

For information on groups and classes, see Chapter 5, Groups and Classes.

As changes are made to a file in the OpenVMS file system, new versions of that file are created. Similarly, as an element is developed in CMS, new generations of that element are created. In addition to storing the element and its generations, CMS manages the development process by using reservations and replacements.

A reservation exists in the CMS library when you retrieve an element generation with the intent to modify it. The reservation ends and a replacement occurs when you return the modified contents to the library.

For information on reservations and replacements, see Chapter 4, Elements and Generations.

You can mark an element generation for review to indicate that its contents should be reviewed by other users. After the review process is complete, the element generation can be marked as having been accepted or rejected.

For information on marking an element generation for review and the review process, see Section 4.5.4, “The Review Attribute”.

All CMS commands that modify a library or its contents are recorded in the library history. You can display any part of the history by using the SHOW HISTORY command. All commands that are recorded allow you to enter a remark, which is recorded in the history along with the command. Remarks are useful in explaining library and element modifications.

For information on library history, see Chapter 4, Elements and Generations. For information on remarks, see Section 10.2.3, “Remarks”.

For easy reference, you can direct CMS to automatically store copies of the latest main-line generation of selected library elements in a separately designated directory, called a reference copy directory.

For information on reference copies, see Sections 3.1.4 and 4.5.3.

The first generation of a newly created element is generation 1. Every time you reserve and replace a generation of that element, CMS numbers a new generation by adding 1 to the number of the reserved generation. This new generation is a descendant of the generation from which it was created. The main line of descent consists of generation 1 and its direct descendants.

A generation can have only one direct ancestor and one direct descendant, but it can also have a number of variant descendants. Those generations that are not on the direct line of descent of a generation are called variant generations. You specify variant generations by adding a letter, called the variant letter, and the number 1 to the parent generation. For example, generation 2E1 is a variant descendant of generation 2.

A variant generation and its direct descendants (for example, generations 2E1, 2E2, 2E3) form a variant line of descent. A variant generation can have variant descendants; for instance, generation 2E1W1 is a variant descendant of generation 2E1.

For information on lines of descent and variant generations, see Chapter 6, Variants and Merging.

You can create variant generations at any time, but default usage creates successive generations along the same line of descent. You must create a variant generation when the direct successor of a reserved generation already exists and you replace a concurrent reservation.

A concurrent reservation exists when an element generation has been reserved more than once by one or more users. In this case, only one of these reservations can be replaced on the direct line of descent; the rest of the reservations must be replaced as variant generations.

For information on concurrency, see Section 4.3, “Concurrency”.

You can use variant generations to maintain separate but related development of an element, or you might have generations that have undergone concurrent development.

If concurrent changes have been made to a generation, you can merge the changes from one line of descent and some variant line of descent into a single generation.

CMS resolves changes from two generations by comparing them to their common ancestor generation. If both generations change a region of their common ancestor in different ways, this region is known as a conflict. Where the changes do not conflict, CMS includes the appropriate change; where the changes conflict, CMS includes the changes from both generations and flags the conflicting region. In either case, you should verify the resulting merged output for correctness; for example, program source code should be compiled and executed to ensure that it is syntactically and logically correct. After verifying and making any necessary modifications, you can replace the merged reservation.

For information on merging and conflicts, see Chapter 6, Variants and Merging.

The OpenVMS operating system provides a security mechanism based on user identification codes (UIC) and access control lists (ACLs) to control access to files within the file system. Similarly, you can use CMS ACLs for controlling access to CMS objects through CMS operations. For you to successfully access an object in the CMS library, both the file system and the CMS internal security mechanism must allow you to do so.

For information on the OpenVMS and CMS security mechanisms, see Chapter 7, Security Features.

You can use CMS ACLs to specify that a CMS object being accessed constitutes an event, and that some action should be taken when an event occurs. You can specify lists of people to be notified when certain events occur on objects in the CMS library. The default action performed is notification through the OpenVMS Mail Utility (MAIL) to one or more users. CMS provides a default notification event handler; in addition, you can write event handlers of your own for CMS to use.

For information on events and notification, see Chapter 8, Event Handling and Notification.

When you choose one of these menu items, a dialog box is displayed, enabling you to view and specify options for that operation.

When you choose one of these menu items, a dialog box is displayed, enabling you to view and specify options for that operation.

You obtain help in the DECwindows Motif environment by pulling down the Help menu. Help provides brief information about screen objects, concepts, and tasks that you can perform in CMS.

A Help window opens to display information about the object.

CMS displays an additional window with the view you choose.

You can display any number of views that you want; each view is independent of other views. By using CMS views, you can choose objects on which you want to perform functions.

A dialog box is displayed, enabling you to specify the user name for which CMS should display reservations.

You can also obtain information about CMS objects by expanding them. See Section 2.3.4, “Expanding and Collapsing CMS Objects” for more information.

The following sections describe these methods.

2.3.4.1. Double Clicking

Figure 2.1, “Expanding a Group” shows the group DOC_TEST expanded to show its children.

To expand this group using double clicking, do the following:

1. Pull down the View menu.

2. Choose the Group menu item.

3. Double click on the desired group (in this example, group DOC_TEST), or choose the Expand item from the View menu.

Group DOC_TEST expands into its components, including elements and any other groups contained in group DOC_TEST. Double clicking on the element BASCOM.REQ expands it into its generations.

Note

If an item is expanded fully, double clicking collapses the information into the previous level of information.

You can also expand an object by choosing a function. For example, to expand the group DOC_TEST, do the following:

1. Click on the desired object (in this example, group DOC_TEST).

2. Pull down the View menu.

3. Choose the Expand menu item; the Expand submenu is displayed.

4. Choose the Children submenu item.

Section 2.3.4.2, “Choosing a Function” contains more information about choosing a function.

2.3.4.3. Using the Pop-Up Menu

CMS provides a pop-up menu enabling you to quickly access some of the most commonly used CMS functions. You can use the pop-up menu with any CMS object that can be used in those functions.

To get the pop-up menu, press and hold MB3. Or, to first choose an object for the operation, click on the object, then press and hold MB3 to get the pop-up menu.

Figure 2.2, “CMS Pop-Up Menu” shows the pop-up menu.

LSE> CMS SHOW LIBRARY

Your CMS library list consists of:   DISK11:[EXCERPTS.CMS.VMS]

LSE> CMS SET LIBRARY DISK11:[SUMMARIES.CMS.VMS]

All other CMS operations are available via the LSE command-line interface.

You create a directory to contain your CMS library by using the DCL command CREATE/DIRECTORY. The format of the command is as follows: CREATE/DIRECTORY directory-specification

$ CREATE/DIRECTORY [PROJECT.CMSLIB] 

The name PROJECT identifies the first-level directory. This command creates the empty subdirectory [.CMSLIB] within the directory [PROJECT]. For more information on the CREATE/DIRECTORY command, see the VSI OpenVMS DCL Dictionary.

If you want to place access control lists (ACLs) on the library directory, you should do so before you create the library, so files created during library creation are assigned the correct protection. See Chapter 7, Security Features for more information on ACLs.

You create a CMS library with the CREATE LIBRARY command. The CREATE LIBRARY command creates CMS control files in the specified directory. The directory must exist and must be empty. Once you create a library in a directory, CMS uses that directory to locate and store files. Note that your default directory cannot be a CMS library. After you create a library with the CREATE LIBRARY command, all subsequent CMS commands refer to this library until the end of the terminal session, until you specify a different library with the SET LIBRARY command, or until you deassign the library list with the SET NOLIBRARY command.

$ CMS CREATE LIBRARY [PROJECT.CMSLIB]
_Remark: test procedure library
%CMS-S-CREATED, CMS library DISKX:[PROJECT.CMSLIB] created
%CMS-I-LIBIS, Library is DISKX:[PROJECT.CMSLIB]
%CMS-S-LIBSET, CMS library set

You can create more than one library with the CREATE LIBRARY command by specifying a list of directory specifications separated by commas. For more information, see Section 3.2, “Using Libraries”.

The CREATE LIBRARY command also allows you to optionally specify a directory to be used for maintaining reference copies of library elements. For information about using reference copy directories, see Section 3.1.4, “Creating a Reference Copy Directory”.

You store a file in a CMS library with the CREATE ELEMENT command. CREATE ELEMENT uses the input file you provide to create the first version of an element. This first version represents generation 1 of the element. An element represents all the versions of a particular file as it is developed. Every element in the CMS library must have a unique name.

$ CMS CREATE ELEMENT OUTPUT.FOR "ascii output format routines"
%CMS-S-CREATED, element [PROJECT.CMSLIB]OUTPUT.FOR created

This command creates the element named OUTPUT.FOR. Generation 1 of element OUTPUT.FOR now exists in the library.

The file specified in the CREATE ELEMENT command must be present in your current, default directory (unless you specify a different location by using the /INPUT qualifier). CMS deletes all copies of that file from the default or specified directory after creating the new element. You can override this default by specifying the /KEEP or /RESERVE qualifier on the CREATE ELEMENT or MODIFY ELEMENT command, or library-wide by specifying the /KEEP qualifier on the CREATE LIBRARY or MODIFY LIBRARY command. The contents of the file used to create the element become generation 1 of that element.

CMS can store and operate on nontext files; however, CMS cannot store directory files.

There is no explicit limit on the number of elements (or groups or classes) that can exist in a library. However, there might be limits imposed by your system configuration, including system, process, disk space, and virtual memory limitations.

To create an element in the library, you must have read access to the file from which you are creating the element.

Figure 3.1, “Building a CMS Library” shows the process of establishing a library and creating elements in it. See Chapter 4, Elements and Generations for more information about elements.

A reference copy directory is a directory in which CMS maintains a copy of the latest generation on the main line of descent of each element.

The reference copy directory cannot be a CMS library, nor can it be a subdirectory of a CMS library directory. Although CMS allows different libraries to be assigned the same reference copy directory, it is strongly recommended that you assign each CMS library its own unique reference copy directory.

$ CREATE/DIRECTORY [PROJECT.CMSLIB]
$ CREATE/DIRECTORY [PROJECT.REFCOPY]
$ CMS CREATE LIBRARY [PROJECT.CMSLIB]/REFERENCE_COPY=[PROJECT.REFCOPY]
_Remark: Master library with reference copies
%CMS-S-CREATED, library DISKX:[PROJECT.CMSLIB] created

In this example, the first CREATE/DIRECTORY command creates the CMS library directory [PROJECT.CMSLIB]; the second CREATE/DIRECTORY command creates the reference copy directory [PROJECT.REFCOPY]. The CREATE LIBRARY command initializes a CMS library in the [PROJECT.CMSLIB] directory and creates a permanent association between the CMS library and the [PROJECT.REFCOPY] directory.

Once a reference copy directory is established for a library, CMS maintains reference copy files in that directory. Every time you create a new main-line generation of an element (by using CREATE ELEMENT or REPLACE), CMS updates the reference copy of that element. Existing elements in the library will not have the reference copy attribute set. Use the /REFERENCE_COPY qualifier on the MODIFY ELEMENT command to enable the reference copy attribute on those elements for which reference copies are to be maintained. See Section 4.5.3, “The Reference Copy Attribute” for more information.

$ CREATE/DIRECTORY [PROJECT.REFCOPY]
$ CMS
CMS> SET LIBRARY [PROJECT.CMSLIB]
CMS> MODIFY LIBRARY/REFERENCE_COPY=[PROJECT.REFCOPY]
_Remark: Establish reference copy directory
CMS> MODIFY ELEMENT/REFERENCE_COPY *.* "enable reference copy"

The MODIFY LIBRARY command establishes the directory [PROJECT.REFCOPY] as the reference copy directory for the current CMS library [PROJECT.CMSLIB]. The MODIFY ELEMENT command changes the reference copy attribute for all currently existing elements and creates reference copies for them. Use the SHOW LIBRARY/FULL command to display the directory specification of a reference copy directory.

If you do not want some elements to have reference copies, modify those elements with the /NOREFERENCE_COPY qualifier on the MODIFY ELEMENT command. For more information, see the descriptions of the CREATE ELEMENT and MODIFY ELEMENT commands in the online help or the VSI DECset for OpenVMS Code Management System Reference Manual.

CMS does not create reference copies for any variant generations. CMS maintains a reference copy only of the latest generation on the main line of descent of each element.

You set one or more libraries by entering the SET LIBRARY command, or the CREATE LIBRARY command, which performs an implicit SET LIBRARY operation. The SET LIBRARY command defines a DCL logical name, CMS$LIB, which points to the library or libraries you have selected. After you have selected a library or libraries, all CMS commands you enter refer to the CMS$LIB library list. The library list exists until you enter another SET LIBRARY, SET NOLIBRARY, or CREATE LIBRARY command, or log out.

$ CMS SET LIBRARY [PROJECT.CMSLIB]
%CMS-I-LIBIS, library is DISKX:[PROJECT.CMSLIB]
%CMS-S-LIBSET, library set
%CMS-I-SUPERSEDE, library list superseded

This command sets (or resets) the library search list to contain only the library [PROJECT.CMSLIB].

CMS> SET LIBRARY [PROJECT1.CMSLIB],[PROJECT3.CMSLIB]
%CMS-I-LIBIS, library is DISKX:[PROJECT1.CMLSIB]
%CMS-I-LIBINSLIS, library DISKX:[PROJECT3.CMSLIB] inserted at end of library list
%CMS-S-LIBSET, library set

This command sets (or resets) the library search list to contain only the two libraries [PROJECT1.CMSLIB] and [PROJECT3.CMSLIB].

If you try to set your library to a directory that has not been initialized by CREATE LIBRARY, CMS$LIB becomes undefined and CMS issues a warning message.

To add libraries to an established library search list, use the /BEFORE and /AFTER qualifiers on the CREATE LIBRARY or SET LIBRARY command to control the placement of the new libraries in the existing library search list.

CMS> CREATE LIBRARY [PROJECT1.CMSLIB],[PROJECT3.CMSLIB]
CMS> SET LIBRARY [PROJECT2.CMSLIB]/BEFORE=[PROJECT3.CMSLIB]

In this example, the CREATE LIBRARY command establishes the library search list consisting of the two libraries [PROJECT1.CMSLIB] and [PROJECT3.CMSLIB]. The SET LIBRARY command inserts the library [PROJECT2.CMSLIB] in the library search list. The library search list now consists of three libraries: [PROJECT1.CMSLIB], [PROJECT2.CMSLIB], and [PROJECT3.CMSLIB], in that order.

If you specify either the /BEFORE or the /AFTER qualifier without a value, the new library (or libraries) are added to the existing search list either before or after the entire library list, respectively.

If you do not specify either qualifier, a new library search list is created, replacing the entire existing library search list.

To remove one or more libraries from the existing search list, use the SET NOLIBRARY command. The SET NOLIBRARY command accepts one or more library directory specifications, which are then removed from the list, leaving the rest of the list intact. If you do not specify a library directory, every library from the entire library search list is removed, and the library search list becomes undefined. For more information on the SET NOLIBRARY command, see the online help or the VSI DECset for OpenVMS Code Management System Reference Manual.

$ CMS FETCH CODE,BUILD.COM "fetch all code and the build procedure"

In this example, the group CODE represents all program source modules, and the element BUILD.COM is the build procedure to compile and link the program.

$ CMS INSERT ELEMENT MAIN.BAS CODE "insert main module into CODE group"

This command inserts the element MAIN.BAS into the group CODE.

When you specify multiple object types in a CMS command, CMS simultaneously performs occlusion on all applicable objects. Specifically, in the preceding example, CMS simultaneously performs occlusion on the elements and the groups, and ignores occlusion for other object types. A special case occurs when you use a group name as an element specification. In this case, the elements in the group occlude subsequent instances of those elements (if element occlusion is enabled). In such cases, CMS performs element occlusion even if the specification contained only group names.

CMS> FETCH SAMPLES
_Remark: fetch 1st instance of element generations from group SAMPLES
%CMS-I-FETCHED, generation 2 of element DISKX:[PROJECT.CMSLIB]SAMPLE.DAT fetched
%CMS-I-FETCHED, generation 2 of element DISKX:[PROJECT.CMSLIB]SAMPLE.PAS fetched
%CMS-I-FETCHES, 2 elements fetched

CMS> FETCH/OCCLUDE=NOELEMENT SAMPLES
_Remark: fetch all instances of element generations from group SAMPLES
%CMS-I-FETCHED, generation 2 of element DISKX:[PROJECT.CMSLIB]SAMPLE.DAT fetched
%CMS-I-FETCHED, generation 2 of element DISKX:[PROJECT.CMSLIB]SAMPLE.PAS fetched
%CMS-I-FETCHES, 2 elements fetched

CMS> FETCH SAMPLE.DAT,SAMPLE.PAS
_Remark: fetch first instance of sample elements
%CMS-I-FETCHED, generation 1 of element DISKX:[WORK.CMSLIB]SAMPLE.DAT fetched
%CMS-I-FETCHED, generation 1 of element DISKX:[WORK.CMSLIB]SAMPLE.PAS fetched
%CMS-I-FETCHES, 2 elements fetched\
CMS> FETCH/OCCLUDE=NOELEMENT SAMPLE.DAT,SAMPLE.PAS
_Remark: fetch all instances of sample elements
%CMS-I-FILEXISTS, file already exists, DISKX:[WORK]SAMPLE.DAT;2 created
%CMS-I-FETCHED, generation 1 of element DISKX:[WORK.CMSLIB]SAMPLE.DAT fetched
%CMS-I-FILEXISTS, file already exists, DISKX:[WORK]SAMPLE.DAT;2 created
%CMS-I-FETCHED, generation 1 of element DISKX:[WORK.CMSLIB]SAMPLE.PAS fetched
%CMS-I-FILEXISTS, file already exists, DISKX:[WORK]SAMPLE.DAT;3 created
%CMS-I-FETCHED, generation 1 of element DISKX:[PROJECT.CMSLIB]SAMPLE.DAT fetched
%CMS-I-FILEXISTS, file already exists, DISKX:[WORK]SAMPLE.PAS;3 created
%CMS-I-FETCHED, generation 1 of element DISKX:[PROJECT.CMSLIB]SAMPLE.PAS fetched
%CMS-I-FETCHES, 4 elements fetched

In the first command, CMS assumes /OCCLUDE=ALL, and fetches only the first instance of each of the elements SAMPLE.DAT and SAMPLE.PAS. In the second command, because the /OCCLUDE=NOELEMENT qualifier was specified, CMS fetches all occurrences of each element from both libraries.

Thus, an element specification consisting of a group containing a set of elements, and an element specification consisting of a list of the same set of elements, are not equivalent. In the first case, CMS locates the first instance of the group. Previous instances of the elements in the group might exist in an earlier library, but are not selected because they are not located in the library with the specified group. In the second case, the first instance of each of the specified elements is found, regardless of which library they might be in. In fact, they might be found in libraries in the list prior to the library in which the group is found.

The following examples show how to control occlusion on various CMS objects. For the following examples, assume the library is set to [WORK.CMSLIB],[PROJECT.CMSLIB]. The library [WORK.CMSLIB] contains the two elements SAMPLE.DAT and SAMPLE.PAS, with generation 1 of the element SAMPLE.PAS inserted into class V1. The library [PROJECT.CMSLIB] contains the two elements SAMPLE.DAT and SAMPLE.PAS. These two elements are inserted into the group SAMPLES. Generation 2 of element SAMPLE.PAS is inserted into class V2. Figure 3.2, “Library Occlusion” matches the following examples.

You create an element with the CREATE ELEMENT command. Each time you reserve and replace a generation of an element, you create a new generation of that element (see Section 4.2.4, “Replacing an Element Generation”).

In the CREATE ELEMENT command, you specify the name and type of the file that is to become the name of the element. Within a library, all element names must be unique. The file-name component cannot be 00CMS because that name is reserved for CMS. Specify the file with the following syntax: filename.type

$ CMS CREATE ELEMENT INIT.FOR "initialization routines"
%CMS-S-CREATED, element DISKX:[PROJECT.CMSLIB]INIT.FOR created

This command creates an element named INIT.FOR from the file INIT.FOR. CMS searches for the file named INIT.FOR in your default directory; use the /INPUT qualifier on the CREATE ELEMENT command to specify a different location, a different file name, or both.

$ CMS CREATE ELEMENT/keep/binary FILE1.C "Creating binary element"
%CMS-S-CREATED, element DISK1:[DIR.CMSDIR]FILE1.C created

This command creates an element named FILE1.C. /BINARY qualifier is used so that CMS creates the element as binary type and treats it as binary type for future transactions.

The FETCH command copies the contents of an element generation into a file. Unlike the RESERVE command, FETCH does not mark an element generation as reserved, and you cannot replace a fetched copy in the library. You can fetch a copy of a generation of an element regardless if the element is reserved.

$ CMS FETCH TIMTST.COM
_Remark: Testing storage blocks
%CMS-S-FETCHED, generation 2 of element DISKX:[PROJECT.CMSLIB]TIMTST.COM fetched

CMS retrieves the latest main-line generation of the element TIMTST.COM (generation 2). To retrieve an earlier generation (or variant generation; see Chapter 6, Variants and Merging), specify the /GENERATION qualifier on the FETCH command.

CMS creates a file with the same name as the fetched element, and places this file in your current, default directory. Use the /OUTPUT qualifier on the FETCH command to specify a different file name, a different location, or both.

After creating an element in a CMS library, use the RESERVE command to retrieve a copy of a generation of the element to make changes to it. When you reserve a generation, CMS retrieves a copy of the generation of the element and marks that generation as reserved in the CMS library. You can then edit, compile, test, and debug the file as necessary. Most of your work with the CMS library consists of reserving library element generations for work and replacing the modified files back into the library as new generations.

When you reserve a generation of an element, CMS creates a file with the same name as the element, and places this file in your current, default directory. Use the /OUTPUT qualifier on the RESERVE command to specify a different location, a different file name, or both.

CMS prompts you to enter a remark when you reserve an element generation. You should use the remark to explain why you are reserving the generation; the remarks provide a permanent record of your work. If you need to revise the remark at a later time, you can use the MODIFY RESERVATION command to enter a new remark string.

$ CMS RESERVE SYNCHRON.BAS
_Remark: losing sample from one data line
%CMS-S-RESERVED, generation 2 of element DISKX:[PROJECT.CMSLIB]SYNCHRON.BAS reserved

CMS copies the element generation into a file that is created in your current default directory. CMS marks the generation with your reservation and records the transaction in the library transaction history.

$ CMS RESERVE SYNCHRON.BAS/GENERATION=1
_Remark: Commenting data line sampling code
%CMS-S-RESERVED, generation 1 of element DISX:[PROJECT.CMSLIB]SYNCHRON.BAS reserved

A copy of the first generation of the element is then placed in the current, default directory.

CMS allows you to concurrently reserve more than one generation of the same element, or the same generation more than once. If any generation of an element is already reserved (by you or another person) CMS issues a message about the reservation already in effect. You then have the option to proceed with your reservation or quit. If you choose to proceed with the reservation, the element is considered to have concurrent reservations. While you have an element generation reserved, any user who reserves or attempts to reserve a generation of the same element receives a CMS message indicating that you have reserved the element generation. See Section 4.3.2, “Concurrent Reservations” for more information on concurrent reservations.

$ CMS UNRESERVE SYNCHRON.BAS
_Remark: element not applicable–wrong file
%CMS-S-UNRESERVED, element DISKX:[PROJECT.CMSLIB]SYNCHRON.BAS unreserved

Normally, CMS allows you to unreserve only your own reservation. However, if you hold BYPASS privilege or if an access control entry (ACE) on the element grants you BYPASS access, you can cancel any reservation of that element held by another user. The cancellation of the reservation is then logged in the history file under your name. See Chapter 7, Security Features for more information.

$ CMS RESERVE SPEC.RNO
_Remark: Misspelling in Reliability section
%CMS-S-RESERVED, generation 3 of element DISKX:[PROJECT.CMSLIB]SPEC.RNO reserved
    .
    .
    .
$ CMS REPLACE SPEC.RNO
_Remark: Reliability section typo fixed
%CMS-S-GENCREATED, generation 4 of element DISKX:[PROJECT.CMSLIB]SPEC.RNO created

In this example, the current generation (generation 3) is reserved to correct a typographical error, and then replaced.

To avoid creating a new generation if the input file has no changes from the reserved generation, use the /IF_CHANGED qualifier on the REPLACE command. You can also use the /INSERT_INTO_CLASS qualifier to insert the generation into one or more classes automatically. For more information, see the description of the REPLACE command in the online help or the VSI DECset for OpenVMS Code Management System Reference Manual.

Normally, CMS allows you to replace only your own reservation. However, if you hold BYPASS privilege or if an ACE on the element grants you BYPASS access, you can replace any reservation of that element held by another user. This mechanism allows you to designate a single person who is responsible for reviewing and entering all changed reservations into the library, for example. See 7 and 8 for more information on ACEs.

CMS allows you to concurrently reserve more than one generation of the same element, or the same generation more than once. When you replace the generations that are concurrently reserved by you, you must specify the /GENERATION or /IDENTIFICATION_NUMBER qualifier on the REPLACE command. See Section 4.3.3, “Concurrent Replacements” for information on replacing concurrent reservations.

You can monitor changes made to elements by using the notification ACE or the review attribute.

The notification ACE enables you to specify a list of people to be notified when particular events occur in a CMS library. See Chapter 8, Event Handling and Notification for more information on CMS notification.

The review attribute enables you to specify that newly created element generations are to be placed on a review pending list. You can then associate review remarks with a generation under review. To assign the review attribute, use the /REVIEW qualifier on either the CREATE ELEMENT or the MODIFY ELEMENT command. The review attribute specifies that any new generations of that element are marked as pending review. You can also mark a specific generation for review by using the MARK GENERATION command. To determine which generations have reviews pending, use the SHOW REVIEWS_PENDING command.

$ CMS SHOW ELEMENT
Elements in CMS Library DISKX:[PROJECT.CMSLIB]
ADCONVERT.BAS "analog to digital conversion routines"
ERRMSG.TXT    "initial load"SAMPLE.BAS    "Sampling module"
SPEC.RNO      "ADS functional specification"
SYNCHRON.BAS  "Synchronization routines"
TIMTST.COM    "Command procedure for tests"

In this case, SHOW ELEMENT displays an alphabetical list of all the elements in the project library [PROJECT.CMSLIB], along with their remarks. You can also use the SHOW ELEMENT/MEMBER command to display the element name, creation remark, and the name of any groups to which the element belongs.

$ CMS SHOW GENERATION SYNCHRON.BAS/GENERATION=3
Element generations in CMS Library DISKX:[PROJECT.CMSLIB]
SYNCHRON.BAS    3    26-JUN-2005 09:44:12 KELLEY "a/d conversion integrated"

This command displays the characteristics of generation 3 of the element SYNCHRON.BAS.

$ CMS SHOW GENERATION/GENERATION=BASELEVEL1 SYNCHRON.BAS
Element generations in CMS Library DISKX:[PROJECT.CMSLIB]
   SYNCHRON.BAS    3    26-JUN-2005 09:44:12 KELLEY "a/d conversion integrated"

This command displays the generation of element SYNCHRON.BAS that is in class BASELEVEL1.

$ SHOW GENERATION/MEMBER/DESCENDANTS TEST.FOR
Element generations in CMS Library DISKX:[PROJECT.CMSLIB]
   TEST.FOR
     2     18-OCT-1994 15:04:54 SMITH "header changed"

     1     26-SEP-1994 13:38:04 SMITH ""
               Member list:        RELEASE1

This command displays the generation number, date, time, remark, and the name of any classes to which each generation belongs for all the generations of the element TEST.FOR.

$ CMS SHOW HISTORY
History of CMS Library DISKX:[PROJECT.CMSLIB]
2-MAY-2005 14:22:16 WHIPPLE CREATE LIBRARY DISKX:[PROJECT.CMSLIB] "a/d data
       sampling library"
2-MAY-2005 14:26:47 MARTIN CREATE ELEMENT SPEC.RNO "ADS functional
       specification"
8-JUN-2005 12:09:02 WHIPPLE CREATE ELEMENT ADCONVERT.BAS "analog to digital
       conversion routines"
8-JUN-2005 12:25:41 WHIPPLE CREATE ELEMENT SAMPLE.BAS "Sampling module"
8-JUN-2005 12:29:24 HENRY CREATE ELEMENT SYNCHRON.BAS "Synchronization
       routines"
8-JUN-2005 14:01:36 HENRY CREATE ELEMENT TIMTST.COM "Command procedure for
       tests"
9-JUN-2005 14:47:40 DAVIS RESERVE SYNCHRON.BAS(1) "losing sample from one
       data line"

CMS does not record transactions that do not alter the library. CMS logs FETCH transactions only if you supply a remark.

You can use the SHOW HISTORY command with the /UNUSUAL qualifier to report any abnormal library transactions that occurred, such as two reservations in effect for the same element at the same time.

$ CMS SHOW RESERVATIONS
Reservations in CMS Library DISKX:[PROJECT.CMSLIB]
SAMPLE.BAS  (1)  JIMK     1
      30-JUN-2005 11:19:29 "add code for more data lines"
SYNCHRON.BAS  (1)  KELLEY   3
      18-JUN-2005 09:42:03 "integrate a/d conversion"

$ CMS SHOW GROUP/CONTENTS TIME_TST
Groups in CMS Library DISKX:[PROJECT.CMSLIB]TIME_TST
           "comparison testing prototype group"
    SYNCHRON.BAS
    TIMTST.COM

This command lists the elements contained in group TIME_TST.

To delete one or more generations of an element from the library, use the DELETE GENERATION command. This command is useful if you replaced a wrong version of a file into the CMS library, or if you want to remove old generations of elements. This command permanently removes information about a generation from the corresponding element in the library. If the latest main-line generation is deleted, the next latest main-line generation is placed into the reference copy directory. Deleting a generation does not remove changes from subsequent generations that were originally made in the deleted generation and thus exist in subsequent generations.

Deleting unneeded generations allows operations that access generations (for example, FETCH, REPLACE, and RESERVE) to complete faster because the number of generations to be searched is reduced (see Section 9.3.2, “Deleting and Archiving Element Generations” for more information).

When you delete an element generation, you can optionally use the /ARCHIVE qualifier to direct CMS to create an archive file. When you specify /ARCHIVE, CMS creates a file containing all the information from the deleted generation, and places it in your default directory. For more information, see Section 9.3.2, “Deleting and Archiving Element Generations” and the description of DELETE GENERATION/ARCHIVE in the online help and the VSI DECset for OpenVMS Code Management System Reference Manual.

CMS allows you to control concurrent access to an element by using the concurrent attribute. You define the concurrent attribute by specifying the /[NO]CONCURRENT qualifier. The library-wide default is /CONCURRENT, which can be changed at the library or element level.

You can prohibit concurrent access by specifying the /NOCONCURRENT qualifier on the CREATE ELEMENT command for a new element, or by using the MODIFY ELEMENT command to change the attribute of an existing element. You cannot modify concurrent access to an element while a generation of the element is reserved. When you prohibit concurrent access to an element, only one reservation of the element is allowed at a time until you use the MODIFY ELEMENT/CONCURRENT command to allow concurrent access.

You can temporarily prohibit concurrent access for the duration of a reservation by specifying the /NOCONCURRENT qualifier on the RESERVE command. If you reserve a generation of an element in this way, you must replace it or cancel the reservation (with the UNRESERVE command) before you or anyone else can reserve any generation of the element.

$ CMS RESERVE BASTEST.GNC
_Remark: reserving for final production
Element BASTEST.GNC currently reserved by:
      (1)    DAVIS       3     28-JAN-2005  09:27:46  "for testing"
Proceed?  [Y/N] (N):

If you type NO or press Return, CMS does not execute the reserve transaction. If you type YES, CMS places a copy of the generation in your current, default directory, marks the element as concurrently reserved, and records the reservation transaction in the library history. CMS records the transaction as an unusual occurrence. For information about unusual occurrences, see Chapter 9, Library Maintenance.

CMS allows multiple reservations by a single user; that is, you can reserve more than one generation of the same element, and you can also reserve the same generation more than once. CMS assigns a unique identification number to each reserved generation. The identification number appears first on each line. Use the SHOW RESERVATIONS command to determine the identification number of each reservation. You must use the /IDENTIFICATION_NUMBER qualifier to replace a concurrent reservation (see Section 4.3.3, “Concurrent Replacements”).

$ CMS REPLACE BASTEST.GNC
_Remark: replacing after completing edits
Concurrent replacements
      (1)    DAVIS       2     28-JAN-2005  09:27:46  "for testing"
Proceed?  [Y/N] (N):

If you type NO or press Return after the Proceed? prompt, CMS does not execute the replacement transaction. If you type YES, CMS proceeds with the command and records the transaction as an unusual occurrence. For information about unusual occurrences, see Chapter 9, Library Maintenance.

At least one reserver must replace a concurrent reservation as a variant generation. You replace the concurrent reservation as a variant generation by specifying the /VARIANT qualifier on the REPLACE command. This begins a variant line of descent. Either user can then merge the variant generation back into the original line so both sets of program modifications appear in one generation, or the variant line of descent can be continued (see Chapter 6, Variants and Merging for more information).

CMS allows you to concurrently reserve a specific generation more than once. When you replace the generations that are concurrently reserved by you, you must specify which reservation is to be replaced. You can do this with either the /GENERATION qualifier or the /IDENTIFICATION_NUMBER qualifier on the REPLACE command.

$ CMS REPLACE BASTEST.GNC/IDENTIFICATION_NUMBER=2
_Remark: replacing after completing edits
Element BASTEST.PAS currently reserved by:
      (1)    DAVIS       3     28-JAN-2005  09:27:46  "for testing"
Proceed?  [Y/N] (N):

In this example, the /IDENTIFICATION_NUMBER qualifier specifies that the second reserved generation be replaced into the CMS library. CMS reports other existing reservations you hold for that element (in this case, the first reserved generation), and then prompts you to proceed.

You must also use the /GENERATION or /IDENTIFICATION_NUMBER qualifier if you are replacing another user's reservation. For more information, see Section 7.3, “OpenVMS BYPASS Privilege and CMS BYPASS Access” and the description of the REPLACE command in the online help or the VSI DECset for OpenVMS Code Management System Reference Manual.

When the history attribute is defined for an element, CMS includes the element generation history in the output file when you retrieve a generation of an element from the library with the FETCH or RESERVE command. This history is a list of the transactions that created each generation of the element. Each transaction record consists of the generation number, user, date, time, and remark associated with the generation.

Use the /HISTORY qualifier to define the history attribute for an element. You can either establish the history attribute when the element is created with the CREATE ELEMENT command, or change the history attribute of an existing element with the MODIFY ELEMENT command. You can cancel the history attribute by using the /NOHISTORY qualifier on the MODIFY ELEMENT command. You can also specify the /[NO]HISTORY qualifier on the FETCH and RESERVE commands to temporarily override the element's history attribute.

The format of the /HISTORY qualifier is as follows: /HISTORY="string"/NOHISTORY

"string"

"!#H""
/*#b*/"

The exclamation point (!) and the slash-asterisk characters (/* */) indicate comments.

%CMS-I-NOHISTNOTES, history and notes will not be included in output file

CMS REPLACEMENT HISTORY, Element element-name

This line enables the REPLACE command to distinguish the history from the rest of the file when it is returned to the library. CMS does not consider history text to be part of the file. Instead, the history is added to the file when it is retrieved from the library and removed when the file is replaced into the library. The generation numbers of a retrieved generation and its ancestors are marked with an asterisk (*).

Do not insert or modify text in the history section while editing a file in your directory. CMS expects only history lines between the two header lines. The REPLACE command reports an error if it finds any other text where the history should be, and the command is not executed. You must then delete the extra text with an editor and reenter the REPLACE command.

$ CMS MODIFY ELEMENT SEMANTICS.PAS/HISTORY="{#H}" "est. history attribute"

{ CMS REPLACEMENT HISTORY, Element SEMANTICS.PAS }
{ *6    28-JUL-2005 10:00:54 EDGAR   "formal parameter list support added"}
{ *5    24-JUL-2005 16:10:14 DAVIS   "actual parameter list support added"}
{ *4    20-JUL-2005 12:22:07 MARTIN  "preliminary work on routine calls done"}
{ 3C1   17-JUL-2005 12:15:45 JEFF    "error checking on CASE statement works"}
{ *3    11-JUL-2005 11:57:18 MALER   "CASE statement support"}
{ *2     7-JUL-2005 11:56:05 HENRY   "FOR loop support done"}
{ *1     9-JUN-2005 18:11:25 BARRETT "semantic analysis module"}
{ CMS REPLACEMENT HISTORY, Element SEMANTICS.PAS }

See Section 4.5.5, “Examples of Using Element Attributes” for an example of using the history attribute.

You use the /NOTES qualifier to define the notes attribute, and the /POSITION qualifier to define the column in which the note should start. You can establish these attributes when the element is created with the CREATE ELEMENT command, or you can change the attributes of an existing element with the MODIFY ELEMENT command. Any element that has the notes attribute must have the position attribute and vice versa. Use the /NONOTES qualifier with the MODIFY ELEMENT command to cancel both attributes.

You can also specify the /[NO]NOTES and /POSITION qualifiers with the FETCH and RESERVE commands to temporarily override the element's notes and position attributes.

The format of the /NOTES qualifier is as follows:

/NOTES="string"
/NONOTES

"string"

"!#G"
"/*#g*/"

The exclamation point (!) and the slash-asterisk characters (/* */) indicate comments.

To include a number sign (#) in the string, type it twice (##). To include a quotation mark in the string, type it twice (""). If the file contains source code, you must include comment indicators applicable to your source code in the string so the program can be compiled or assembled. The notes are then treated as comments. See Section 4.5.5, “Examples of Using Element Attributes” for an example.

%CMS-I-NOHISTNOTES, history and notes will not be included in output file

A note for a line appears at the position specified by the /POSITION qualifier. The /POSITION qualifier is required when /NOTES is specified.

/POSITION=n

n

Specifies the character position at which the notes are to appear on the line. The position value must be an integer in the range 1 to 511.

The note is placed to the right of the text of the line. If the length of the line is less than n, the note begins at position n. If the length of the line is greater than or equal to n, the note begins at the next tab stop after the end of the text of the line. (Tab stops are at position 9 and at every 8 characters thereafter.)

CMS does not consider notes to be part of the element generation. Instead, notes are added to the file when it is retrieved from the library and removed when the file is replaced into the library. If, while editing the file, you add text after the note or within the note, CMS does not recognize it as a note; and therefore, replaces it as part of the generation. If you add text that looks like a note, CMS interprets it as a note and removes it before replacing the file.

See Section 4.5.5, “Examples of Using Element Attributes” for an example of using the notes and position attributes.

An element reference copy is a copy of the latest main-line generation of an element. CMS maintains reference copies of the latest generations of selected library elements in a non-library directory.

If you have established a reference copy directory for a library, each newly created element is automatically set with the /REFERENCE_COPY qualifier. New elements inherit the reference copy attribute from the library setting.

When the reference copy attribute is enabled for an element, CMS creates a reference copy by fetching a copy of the latest main-line generation into the reference copy directory. If, for any reason, the reference copy directory cannot be updated, CMS does not create the new generation.

You can use the /REFERENCE_COPY qualifier to define the reference copy attribute for a single element. Either establish the reference copy attribute when the element is created with the CREATE ELEMENT command, or change the reference copy attribute of an existing element with the MODIFY ELEMENT command. You can prevent CMS from creating a reference copy by specifying the /NOREFERENCE_COPY qualifier with the CREATE ELEMENT or MODIFY ELEMENT command.

/REFERENCE_COPY
/NOREFERENCE_COPY

For more information on reference copies, See Section 3.1.4, “Creating a Reference Copy Directory” and the /[NO]REFERENCE_COPY qualifier in the online help or the VSI DECset for OpenVMS Code Management System Reference Manual.

When the review attribute is enabled for an element, CMS places any newly created generations of that element on the review pending list, and marks them for review. You can associate review remarks with a generation under review by using the REVIEW GENERATION command (see the online help or the VSI DECset for OpenVMS Code Management System Reference Manual).

You use the /REVIEW qualifier to define the review attribute for an element. You can establish the review attribute when the element is created with the CREATE ELEMENT command, or you can change the attribute of an existing element with the MODIFY ELEMENT command. You can cancel the review attribute by using the /NOREVIEW qualifier on the MODIFY ELEMENT command.

The format of the /[NO]REVIEW qualifier is as follows:

/REVIEW
/NOREVIEW

To determine what generations are under review, use the SHOW REVIEWS_PENDING command, which also shows any review comments. Once a generation is under review, a user trying to retrieve that generation with a FETCH command is informed that a review is pending. If you retrieve the generation with the RESERVE command, you are informed that a review is pending and are prompted for confirmation to continue. The messages are issued until the generation's review status is resolved. A generation with a review pending cannot be deleted.

You can resolve a generation's review status in one of three ways: accept the generation with the ACCEPT GENERATION command, cancel the review with the CANCEL REVIEW command, or reject the generation with the REJECT GENERATION command. If you accept the generation or cancel the review, CMS halts review-related messages and confirmations on subsequent reservation attempts. If you reject the generation, CMS issues a message indicating that the generation was reviewed and rejected. The generation is still accessible so the problems in it that caused the rejection can be corrected.

A generation created from a generation that currently has a review pending or that was previously rejected is automatically marked for review, regardless of the setting of the element's review attribute.

You can also use the MARK GENERATION and REVIEW GENERATION commands to mark a generation for review and to review the generation. For more information, see the descriptions of these commands in the online help or the VSI DECset for OpenVMS Code Management System Reference Manual.

See Section 4.5.5, “Examples of Using Element Attributes” for an example of using the review attribute.

$ CMS CREATE ELEMENT DOC.C/HISTORY="!#H"/NOTES="!#G"/POSITION=80
_Remark: Require file for multiple reservations
%CMS-S-CREATED, element DISKX:[PROJECT.CMSLIB]DOC.C created

This command creates an element called DOC.C. The element contains data structures written in the C programming language. The /HISTORY qualifier specifies that history is to be appended to the file when it is retrieved from the library. Each line of the history is preceded by a slash and asterisk (/*), which indicates a comment in the C language. The /NOTES and /POSITION qualifiers specify that generation numbers are to be embedded in the lines of the file at position 80. The generation numbers are preceded by an exclamation point (!).

The history and notes are embedded in the file DOC.C when it is retrieved with the RESERVE or FETCH command. Alternatively, you can specify /NONOTES or /NOHISTORY with the FETCH or RESERVE command to direct CMS to omit the notes or history in the file.

$ CMS FETCH DOC.C
_Remark: take a look at history and notes specifications
%CMS-S-FETCHED, generation 3 of element DISKX:[PROJECT.CMSLIB]DOC.C fetched

/* Tests of CMS$CREATE_LIBRARY return status values */ 
#include <stdio.h>                  /* Input/output utilities */ 
#include "[]easy.h"  /* Descriptor utilities   */ 

globalvalue cms$_created;
globalvalue cms$_nocreate;

main()
{

   /* Dynamic descriptor allocation */ 

       DYNDESC(d_libspec);
       DYNDESC(d_cmsdir);                                           !2 

   /* Local variables */ 
     int lib_db[50];
     int status;
     char *libspec = "testlib:";
     char *cmsdir = "[.cmsdir]";                                    !2 

     DYNDESC_A(d_libspec, libspec);
     DYNDESC_A(d_cmsdir, cmsdir);

/* The actual tests */
     status = cms$create_library(&lib_db,&d_cmsdir);                !2 
     if (status == cms$_nocreate)
         printf("\nReturn status = CMS$_NOCREATE\n");
     else
         printf("\n*** Unrecognized return status ***\n");
     printf("\n\nCorrect operation\n");
     status = cms$create_library(&lib_db,&d_libspec);
     if (status == cms$_created)
         printf("\nReturn status = CMS$_CREATED\n");
     else
         printf("\n*** Return status is unsuccessful ***\n");       !3 
}
! CMS REPLACEMENT HISTORY, Element DOC.C  
! *3    23-AUG-2005 12:19:50 DOC$SMITH "" 
! *2    10-AUG-2005 12:17:44 DOC$JONES "" 
! *1     4-AUG-2005 12:14:16 DOC$SMITH "" 
! CMS REPLACEMENT HISTORY, Element DOC.C  

! CMS REPLACEMENT HISTORY, Element DOC.C.

The history shows the transactions that created each generation of the element.

CMS> MARK GENERATION BASCHAP*.SDML
_Remark: need to review chapters for BASIC manual
%CMS-I-MARKED, generation 1 of element DISKX:[PROJECT.CMSLIB]BASCHAP1.SDML marked for review
%CMS-I-MARKED, generation 1 of element DISKX:[PROJECT.CMSLIB]BASCHAP2.SDML marked for review
%CMS-I-MARKED, generation 1 of element DISKX:[PROJECT.CMSLIB]BASCHAP3.SDML marked for review
%CMS-I-MODIFICATIONS, 3 modifications completed
CMS> SHOW REVIEWS_PENDING
Reviews pending in CMS Library DISKX:[PROJECT.CMSLIB]
BASCHAP1.SDML    DAVIS      1      28-JAN-2005 15:48:25 "creating Chapter 1 INTRO"
BASCHAP2.SDML    DAVIS      1      28-JAN-2005 15:48:29 "creating Chapter 2 SYNTAX"
BASCHAP3.SDML    DAVIS      1      28-JAN-2005 15:48:32 "creating Chapter 3 NEW FEATURES"
CMS> FETCH BASCHAP3.SDML
_Remark: new features still applicable?
Generation 1 of element BASCHAP3.SDML has a review pending
%CMS-S-FETCHED, generation 1 of element DISKX:[PROJECT.CMSLIB]
BASCHAP3.SDML fetched
    .
    .
    .
CMS> REJECT GENERATION BASCHAP3.SDML "new features made into separate section, not an entire chapter"
%CMS-S-REJECTED, generation 1 of element DISKX:[PROJECT.CMSLIB]BASCHAP3.SDML rejected
CMS> RESERVE BASCHAP3.SDML "need to pull section"
Generation 1 of element BASCHAP3.SDML has been rejected
Proceed?  [Y/N] (N): YES
%CMS-S-RESERVED, generation 1 of element DISKX:[PROJECT.CMSLIB]BASCHAP3.SDML reserved

A group is a collection of elements or other groups, or a combination of both. You combine one or more elements into a group that you can then manipulate as a single unit. For example, you might create a group that contains all the files that process error messages, a group that contains all the chapters and appendixes in a book, or a group that contains the modules needed to build a part of a database.

Even if an element is in a group, you can still manipulate the element as an object that is separate from the group. A group can also belong to one or more other groups. The only restriction is that a group cannot be a member of itself; that is, it cannot directly or indirectly be a subgroup of itself.

A class is a set of specific generations of elements that can be manipulated as a unit. A class can hold only one generation of any element.

You use classes to represent the state of development of a system or set of elements at a particular time or stage. You can think of a class as a picture taken of a library at a particular time. For example, you might create a class named FIRST_DRAFT that contains only those generations of elements that were used in producing the first draft of a manual.

Typically, you create a class to contain generations of all the components of a software system for a release version of a product. You can establish classes for different stages or milestones. For example, you could establish one class for implementation, a second for testing, and a third for generations that have completed the first two stages. As each module progresses through each stage, you assign each generation to an appropriate class; thus, you can easily determine your progress by displaying the contents of the different classes, and you can later reconstruct any stage of development.

Once you insert an element generation into a class, further changes made to the element are not reflected in the contents of that class.

When you use groups, you manipulate elements. A group is an entity that enables you to give a name to a set of elements in the library and manipulate the set of elements with that name. You typically use groups to associate elements together. For example, you could create a group containing all the art figures in a manual, or a group containing all source modules that contain callable entry points.

When you use classes, you manipulate specific generations of elements. A class is an entity that enables you to give a name to a set of specific generations of elements in the library and manipulate the set with that name. In contrast to groups, classes contain only one generation from an element. You typically use classes to take a “timed snapshot” of a set of generations; that is, the generations that are meaningful to a project at a particular time. For example, you could create a class containing the specific generations that are included in a code freeze or field-test kit, or a class containing the specific generations that make up the state of the project on some other significant date. Figure 5.1, “Groups and Classes” shows the relationship between a group and a class.

The circles in the figure represent four elements and their generations. The number in each circle represents the generation number of the element generation. These four elements and their respective generations are contained in group BUILDBASE, a group containing the modules needed to build part of a database.

The dashed line that connects element generations represents class BASELEVEL4. Class BASELEVEL4 contains the element generations that comprise the state of the library on March 12, the date the project moved to base level 4.

$ CMS CREATE GROUP USER_MANUAL "user documentation"
%CMS-S-CREATED, group DISKX:[PROJECT.CMSLIB]USER_MANUAL created

This command creates an empty group named USER_MANUAL.

After you establish a group, you place one or more elements in the group with the INSERT ELEMENT command.

$ CMS INSERT ELEMENT COPYRIGHT.DOC,BOOTSTRAP.DOC USER_MANUAL
_Remark: copyright page
%CMS-I-INSERTED, element DISKX:[PROJECT.CMSLIB]COPYRIGHT.DOC inserted into group DISKX:[PROJECT.CMSLIB]USER_MANUAL
%CMS-I-INSERTED, element DISKX:[PROJECT.CMSLIB]BOOTSTRAP.DOC inserted into group DISKX:[PROJECT.CMSLIB]USER_MANUAL
%CMS-S-INSERTIONS, 2 insertions completed

Figure 5.2, “Generations in a Group” shows the group USER_MANUAL, which contains two elements, BOOTSTRAP.DOC and COPYRIGHT.DOC.

This figure shows that all generations of the two elements are associated with the group. Therefore, you can access any generation of the elements in a group.

The element expression specified on the INSERT ELEMENT command can be one or more element names, group names, or a wildcard expression (for information about element expressions, see Section 10.2.5, “Element Expressions”). If you specify a group name with the INSERT ELEMENT command, CMS enters the names of all of the elements in that group into the destination group. For instance, if you use INSERT ELEMENT to insert the contents of group A into group B, the contents of group B are not affected by any subsequent changes of the contents of group A.

$ CMS INSERT GROUP USER_MANUAL CODE_AND_DOCS
%CMS-S-INSERTED, group DISKX:[PROJECT.CMSLIB]USER_MANUAL inserted into
DISKX:[PROJECT.CMSLIB]group CODE_AND_DOCS

This command inserts the group USER_MANUAL into the group CODE_AND_DOCS. The INSERT GROUP command enters the group name USER_MANUAL into the list of entries for the group CODE_AND_DOCS. If the contents for the group USER_MANUAL change, the elements accessible through CODE_AND_DOCS also change.

$ CMS FETCH USER_MANUAL "copy for internal sites"
%CMS-I-FETCHED, generation 4 of element DISKX:[PROJECT.CMSLIB]
BOOTSTRAP.DOC fetched%CMS-I-FETCHED, generation 1 of element DISKX:[PROJECT.CMSLIB]
COPYRIGHT.DOC fetched%CMS-S-FETCHES, 2 elements fetched

When you enter the FETCH command, CMS places a copy of the latest generation on the main line of descent of each element belonging to the group named USER_MANUAL into your current, default directory.

By default, when you retrieve a group of elements, you get the latest generation on the main line of descent of each element in the group. By using the /GENERATION qualifier, you can gain access to a specific generation. Note that when you use the /GENERATION qualifier with groups, the generation expression is applied across the group. Thus, if you were to fetch a group of elements and you specified /GENERATION=2, CMS would retrieve the second generation of each element in the group.

$ CMS REMOVE ELEMENT SPEC.RNO DOCUMENTATION
_Remark: User's manual ready for first review
%CMS-S-REMOVED, element DISKX:[PROJECT.CMSLIB]
SPEC.RNO removed from group DISKX:[PROJECT.CMSLIB]
DOCUMENTATION

This command removes the element SPEC.RNO from the group DOCUMENTATION.

$ CMS REMOVE GROUP USER_MANUAL CODE_AND_DOCS "removing group"
%CMS-S-REMOVED, group DISKX:[PROJECT.CMSLIB]
USER_MANUAL removed from group DISKX:[PROJECT.CMSLIB]
CODE_AND_DOCS

This command removes the group USER_MANUAL from the group CODE_AND_DOCS. However, CMS does not delete or alter the groups being removed.

CMS> DELETE GROUP TIME_TST "superseded by comparison tests"
%CMS-S-DELETED, group DISKX:[PROJECT.CMSLIB]TIME_TST deleted

This command deletes the group named TIME_TST.

If the group is not empty, or if it belongs to another group, CMS returns an error and does not delete the group. Use the REMOVE ELEMENT or REMOVE GROUP command to remove elements or groups from the group before entering the DELETE GROUP command.

$ CMS CREATE CLASS INTERNAL_RELEASE "for use in-house only"
%CMS-S-CREATED, class DISK:[PROJECT.CMSLIB]
INTERNAL_RELEASE created

This command creates a class called INTERNAL_RELEASE. The class does not yet contain any element generations.

You place an element generation into a class with the INSERT GENERATION command.

CMS> INSERT GENERATION INIT.FOR INTERNAL_RELEASE
_Remark: Initialization routine for demo
%CMS-S-GENINSERTED, generation 2 of element DISKX:[PROJECT.CMSLIB]
INIT.FOR inserted in class DISKX:[PROJECT.CMSLIB]INTERNAL_RELEASE
CMS> INSERT GENERATION ARGCHK.FOR/GENERATION=3 INTERNAL_RELEASE
_Remark: Demo semantic analyzer
%CMS-S-GENINSERTED, generation 3 of element DISKX:[PROJECT.CMSLIB]
ARGCHK.FOR inserted in class DISKX:[PROJECT.CMSLIB]INTERNAL_RELEASE

The INSERT GENERATION command uses the latest generation on the main line of descent, unless you specify the /GENERATION qualifier. A class can contain no more than one generation of an element. A generation can belong to zero, one, or more classes.

Figure 5.3, “The Relationship Between Groups and Elements” shows the relationship of elements, generations, and the class INTERNAL_RELEASE.

The class INTERNAL_RELEASE contains generation 2 of INIT.FOR, generation 2 of SEARCH.FOR, generation 3 of OUTPUT.FOR, and generation 3 of ARGCHK.FOR.

You can also insert a generation into one or more classes using the /INSERT_INTO_CLASS qualifier to the REPLACE command. See the VSI DECset for OpenVMS Code Management System Reference Manual for information on using this qualifier.

$ CMS RESERVE SEARCH.FOR/GENERATION=INTERNAL_RELEASE
_Remark: add support for alternate two-character graphics
%CMS-S-RESERVED, generation 2 of element DISKX:[PROJECT.CMSLIB]SEARCH.FOR reserved

This command reserves generation 2 of SEARCH.FOR, because that generation belongs to the class INTERNAL_RELEASE.

If a class is established to contain each version or base level of a system, you can accurately reconstruct any previous version of the system. For example, if the users of your system use version 1, the element generations that constitute version 1 could belong to the class VER1. If the software has changed because you are in the process of developing version 2 and a bug is reported in version 1, you can retrieve the generation of the element in which the bug appeared because you know that it belongs to class VER1.

$ CMS REMOVE GENERATION DISPLAY.BAS BASELEVEL1 "no longer needed"

In this example, a generation of the element DISPLAY.BAS is removed from class BASELEVEL1. CMS then revises information about BASELEVEL1 so no generation of DISPLAY.BAS is included in the class.

$ CMS SHOW CLASS/CONTENTS BASELEVEL1
Classes in CMS Library DISKX:[PROJECT.CMSLIB]
BASELEVEL1 "Specifying all generations for first base level"
    ADCONVERT.BAS       5
    DISPLAY.BAS         2
    SAMPLE.BAS          6
    SYNCHRON.BAS        4

This command displays all the elements and their generations in class BASELEVEL1.

$ CMS DELETE CLASS PRE_RELEASE "no longer necessary"
%CMS-S-DELETED, class DISKX:[PROJECT.CMSLIB]PRE_RELEASE deleted

This command deletes the class named PRE_RELEASE.

If any element generations belong to the class, CMS issues an error message and does not delete the class. Use the REMOVE GENERATION command to remove element generations from a class before entering the DELETE CLASS command.

To create a variant generation, use the /VARIANT= x qualifier on the REPLACE command. This creates a variant line of descent that CMS can distinguish from the main line of descent. The parameter x, called the variant letter, is any single alphabetic character (A through Z). If you enter the variant letter as a lowercase character, CMS converts it to uppercase. CMS copies the replaced file into the library and labels the variant generation by appending the variant letter and the number 1 to the generation number of the ancestor generation.

$ CMS REPLACE INIT.FOR/VARIANT=T
_Remark: Routine added for multi-user system
%CMS-S-GENCREATED, generation 7
T1 of element DISKX:[PROJECT.CMSLIB]INIT.FOR created

The variant letter (in this case, T) identifies the new line of descent. The variant letter has no meaning to CMS; you can use it for mnemonic purposes. For instance, you can choose a variant letter that indicates the purpose of the variant line, such as F for fixes, E for enhancements, and so forth.

The number after the variant letter identifies successive generations on that new line of descent. For example, if you reserve and replace generation 7T1 of INIT.FOR, generation 7T2 is created. Each variant can have variants of its own using the same method; for example, you could replace a variant to generation 7T1 with the REPLACE/VARIANT=E command to create generation 7T1E1.

You can create a variant line for any reason; however, there are two cases in which you must create a variant in order to replace an element.

First, when two or more reservations are in effect for the same generation of the same element at the same time, all but one of the reservations must be replaced as a variant. CMS manages concurrent changes by allowing only one replacement to become the next generation on the same line of descent. The other replacements must begin variant lines of descent; the changes can then be merged back into the original line of descent (see Section 6.2.1, “Merging Element Generations”).

Figure 6.1, “Creating a Variant Generation” shows one element at three different stages of development. In stage I, the element has six generations. At this point, two users reserve generation 6 of the element. The users replace their reservations, creating generation 7 (stage II) and variant generation 6X1 (stage III).

Second, when you reserve a generation other than the most recent one on a line of descent, you must always create a variant successor because the successor on the same line of descent already exists. For example, if you reserved an earlier generation to modify software that has already been released, you must create a variant to store the modification. The change can then be merged into the original line of descent (see Section 6.2, “Merging Two Generations of an Element”).

Figure 6.2, “Extending a Variant Generation from an Earlier Generation” shows one element at two stages of development. If you reserve generation 3 of the element, you must create a variant (shown here as generation 3T1) when you replace the generation with the REPLACE command, because generation 4 already exists.

$ CMS RESERVE SEMANTICS.PAS/GENERATION=3C1
_Remark: checks for multiple CASE labels
%CMS-S-RESERVED, generation 3C1 of element DISKX:[PROJECT.CMSLIB]SEMANTICS.PAS reserved
    .
    .
    .
(modify and test element file)
    .
    .
    .
$ CMS REPLACE SEMANTICS.PAS 
_Remark: error checking on multiple CASE labels done
%CMS-S-GENCREATED, generation 3C2 of element DISKX:[PROJECT.CMSLIB]SEMANTICS.PAS created

In this example, the /GENERATION qualifier on the RESERVE command specifies that generation 3C1 is to be reserved. The REPLACE command returns the element to the library and creates generation 3C2, which is on the same line of descent as its predecessor, 3C1.

The ancestors of a generation on the main line of descent are all the preceding generations back to the first generation of the element (generation 1). The ancestors of a variant generation are all the preceding generations on the variant line of descent, which includes all generations on the path back to the first generation of the element. Figure 6.3, “Ancestors on a Tree of Descent” shows the path to the ancestors of generation 2B2.

The descendants of a generation consist of all successive generations (on the same line of descent) and all their variant generations. Figure 6.4, “Descendants on a Tree of Descent” shows the paths that connect the descendants of generation 2.

To display the ancestors or descendants of a generation, use the SHOW GENERATION command with the /ANCESTORS or /DESCENDANTS qualifier, respectively.

When you merge generations, CMS identifies the generation you specify with the /MERGE qualifier, the generation being fetched or reserved, and all edits on the lines of descent for the two generations. (The two generations used in the merge transaction cannot be on the same line of descent.)

CMS then compares the changes that have been made in both generations being merged against the lines of descent. CMS looks for identical regions of text between each of the generations being merged and the lines of descent. These identical regions provide “anchor” points. The location of changes is determined relative to these anchor points—not relative to any particular line number. For example, CMS could consider line 200 in one generation being merged to be at the same location as line 500 in the other generation.

CMS-E-SIZEMISMAT, cannot merge generations with different size records
CMS-E-GENRECSIZE, generation ## has ##-byte records, ## has ##-byte records

The /MERGE qualifier identifies the element generation that CMS merges into the generation being retrieved with the FETCH or RESERVE command.

$ CMS FETCH DATACHAP.TXT/GENERATION=7B3/MERGE=3A1

Figure 6.5, “The Relationship Between a Generation and an Element” shows the contents of three generations of the element CITY.TXT (generations 1, 2, and 1S1) and the relationship between the element generations.

$ CMS RESERVE CITY.TXT/MERGE=1S1
_Remark: merge generations 2 and 1S1
%CMS-I-MERGECOUNT, 2 changes successfully merged with no conflicts
%CMS-S-RESERVED, generation 2 of element DISKX:[PROJECT.CMSLIB]CITY.TXT reserved and merged with generation 1S1

This command merges generation 1S1 into generation 2 of CITY.TXT. The output file (named CITY.TXT) contains the text common to both generations and the changes made to both generations. (The file is placed in your current default directory, or, if you use the /OUTPUT qualifier, another location.) CMS marks generation 2 of the element CITY.TXT as reserved. The generation indicated by the /MERGE qualifier (in this example, generation 1S1) is not reserved.

BOSTON
DETROIT
NEW YORK
SAN FRANCISCO

The line DETROIT is the only difference between generation 1 and generation 2. This change occurs after the line BOSTON in the line of descent. The line SAN FRANCISCO is the only difference between generation 1 and generation 1S1. This change occurs after the line NEW YORK in the line of descent. Because the changes in generations 1S1 and 2 occur at different places in the lines of descent, both changes can be applied without conflict.

$ CMS REPLACE CITY.TXT "completed new format"
%CMS-S-GENCREATED, generation 3 of element DISKX:[PROJECT.CMSLIB]CITY.TXT created

The generation created by the replacement is a successor only to the generation that was reserved. Because generation 2 was specified as the retrieved generation when it was reserved, the REPLACE command creates generation 3.

Figure 6.6, “A Generation After Replacement in the Library” shows the relationship of the generations of CITY.TXT after the replacement transaction. Note that no ancestor or line of descent relationship exists between generation 1S1 and generation 3.

If you do not want to create a new generation but want to produce a merged file, use the FETCH/MERGE command to merge two lines of descent. You can also use the ANNOTATE/MERGE command to create a single file that contains the text common to both generations and the changes made to both generations. For more information, see the ANNOTATE command in the online help or the VSI DECset for OpenVMS Code Management System Reference Manual.

For information on verifying the merge transaction, see Section 6.2.3, “Verifying Merged Changes”.

If CMS detects conflicting changes in the merged generations, it notifies you by including the changes from both generations in the resulting file and surrounding them with asterisks.

BOSTON
DETROIT
NEW YORK
PORTLAND

$ CMS RESERVE CITY.TXT/MERGE=1S1
_Remark: merge two generations
%CMS-W-MERGECONFLICT, 1 change successfully merged with 1 conflict
%CMS-S-RESERVED, generation 2 of element DISKX:[PROJECT.CMSLIB]
CITY.TXT reserved and merged with generation 1S1

BOSTON
DETROIT
NEW YORK
*************** Conflict 1     *************************************************
PORTLAND
********************************************************************************
SAN FRANCISCO
******** End of Conflict 1     *************************************************

When the two generations are merged, one change is successfully merged and one conflict exists. The line DETROIT from generation 2 is applied to the lines of descent without conflict. That is, there is no change from generation 1S1 in the same location. However, the line PORTLAND from generation 2 and the line SAN FRANCISCO from generation 1S1 both occur at the same location. Each conflict is flagged with the word “Conflict” and a sequential conflict number in a line of asterisks. (For files with short fixed-length records, CMS attempts to fit the “Conflict” label; if the Conflict label does not fit, CMS outputs only asterisks.) Following the asterisks, CMS displays the conflicting segments of text.

The merging process is based solely on the text in the files being merged and is performed with no understanding of the meaning of that text. Thus, the resulting file from a “successful” merge might not have the desired form. For example, consider a document where both changes include the same paragraph, but at different places in the file. The successfully merged copy will contain a redundant paragraph. Or consider simultaneous changes made to a code module where one change deleted an unused routine whereas the other called that routine. The merged version would contain the call but no routine to be called, yet the merge would be considered successful by CMS.

You should always verify that the merge transaction had the intended results. You can use the ANNOTATE/MERGE command to produce an annotated listing that shows all changes made to a file, or you can use the DIFFERENCES/FULL command to compare the contents of the files. If you use the DIFFERENCES command, perform the differences transaction three times: once against the new file and each of the merged generations (to ensure that their contents were preserved) and once against the new file and the lines of descent.

In addition, because CMS does not understand the meaning of the text in the files being merged, where applicable you should always compile and link the file as a precautionary measure.

For more information on the ANNOTATE and DIFFERENCES commands, see the online help or the VSI DECset for OpenVMS Code Management System Reference Manual.

UIC-based protection controls access to directories and files as well as other OpenVMS objects. On OpenVMS systems, each user has an associated UIC. Typically, UICs are presented in numeric or alphanumeric format, for example, [221,253], or [PROJECT,JONES].

$ SET PROTECTION=(S:RWE,O:RWE,G:RWE,W) [PROJECT]CMSLIB.DIR

$ SET PROTECTION=(S:RWD,O:RWD,G:RWD,W) [PROJECT.CMSLIB]01CMS.CMS

An ACL consists of access control entries (ACEs) that grant or deny access to a directory or file (or other OpenVMS object) to specific users. You use ACLs with a library directory to define access to an entire library. You use ACLs with library files to establish greater control over access to library contents. Generally, OpenVMS ACLs are used in conjunction with the standard UIC-based protection as a way to fine-tune protection.

See the VSI OpenVMS DCL Dictionary for more information on these commands. For information on ACLs and ACEs, see the VSI OpenVMS Guide to System Security.

$ SET FILE/ACL=(IDENTIFIER=CMSMGR,ACCESS=READ+WRITE+DELETE),-
_$ (IDENTIFIER=[JONES],ACCESS=READ+WRITE+DELETE), -
_$ (IDENTIFIER=[507,*],ACCESS=READ) [PROJECT.CMSLIB.CMS$000]EXAMPLE.PAS

An ACL consists of ACEs that grant or deny access to a command or other object to specific users.

The following sections describe the format of an ACE and an ACL.

IDENTIFIER=PROJ_LEADER + [PROJ,*]

IDENTIFIER=PROJ_LEADER, ACCESS=MODIFY+DELETE

SET ACL /OBJECT_TYPE=type object-expression "remark"

Specifying a CMS ACL on a command enables you to restrict one or more users from accessing that command. This provides a broad protective mechanism that allows greater control over the CMS library than using OpenVMS ACLs and UICs.

You use CMS ACLs on commands and other objects; in most cases, using CMS ACLs on commands is the most effective method to suit most user's needs.

You can display this list of commands by entering the SHOW ACL /OBJECT_TYPE=COMMAND * command. Note that commands containing two words must include an underscore.

To access a command, you must have EXECUTE access to that command.

The following sections describe these objects in detail.

$ CMS SET ACL/OBJECT_TYPE=LIBRARY GROUP_LIST -
_$ /ACL=(IDENTIFIER=PROJ_TEAM,ACCESS=CREATE) ""

$ CMS SET ACL/OBJECT_TYPE=LIBRARY ELEMENT_LIST/ACL=(IDENTIFIER=PROJ_TEAM, -
_$ OPTIONS=DEFAULT, ACCESS=FETCH) ""

This example shows a possible protection scheme using both OpenVMS and CMS security mechanisms.

Suppose a project team consists of the members Smith, Brown, Jones, Anderson, and Nelson. Smith is the project leader, Brown and Jones are senior developers, and Anderson and Nelson are junior developers. All project team members except Nelson hold the PROJECT identifier.

CMS ACLs support two types of ACEs: identifier ACEs and action ACEs. You use identifier ACEs to control which users can perform which CMS operations on a specified object (see Section 7.2.1, “Creating CMS ACLs”). You use action ACEs to define CMS events. An action ACE enables you to specify a particular action to be taken when a CMS object is accessed in a certain way.

An action ACE has the following format:

(ACTION[=image], PARAMETER=string [,IDENTIFIER=identifier] [,OPTIONS=options] [,ACCESS=access])

The ACTION clause identifies the ACE as an action ACE; you can optionally use it to specify a shareable image containing your own event-handler routine, CMS$EVENT_ACTION (see Section 8.1.3, “Using Your Own Event Handler”). Do not include the .EXE file extension in the event-handler name. If you do not specify a user-written, event-handler routine on the ACTION clause, CMS uses the default event handler SYS$SHARE:CMS$EVENT_ACTION image.

If you use the default image, the string specified on the PARAMETER clause must be a valid MAIL recipient specification, such as MYNODE::JONES or @DISTLIST, or a list of specifications separated with commas. You might need to enclose the string in quotation marks if the string contains a list, period, comma, or other non-alphanumeric characters. You should also enclose the string in quotation marks when differentiating between uppercase and lowercase, or CMS will convert the string to uppercase.

NOTIFY=@LIST
(ACTION, PARAMETER=@LIST)

You cannot use the NOTIFY clause, however, if you specify a user-written handler.

The IDENTIFIER clause is optional in action ACEs. If it is not specified, CMS assumes the IDENTIFIER=* clause by default. The IDENTIFIER, OPTIONS and ACCESS clauses are described in detail in Section 7.2.1, “Creating CMS ACLs”.

See Section 8.3, “Examples” for examples of action ACEs.

A CMS event occurs only when the user has been granted the right to perform the operation and the operation has been successfully performed. Therefore, you cannot use an event handler to prevent a command from performing its operation, nor does the command fail if the event handler cannot be invoked.

Multiple events can occur as a result of a single CMS command being executed. For example, if action ACEs have been assigned to the elements A.TXT and B.TXT and to the command RESERVE, three independent events can be triggered by the command RESERVE A.TXT,B.TXT, one for each of the three objects.

$ CMS INSERT ELEMENT A.TXT,B.TXT TEST_BAS ""

This command could trigger an event associated with the group TEST_BAS, but not with the elements A.TXT and B.TXT.

When CMS detects that a specified event has occurred, it invokes the event handler routine CMS$EVENT_ACTION in the SYS$SHARE:CMS$EVENT_ACTION image, or, if you have written your own shareable image, in your user-provided image.

ACTION=image_name

See Section 8.1.1, “Specifying Action ACEs” for more information.

You must include a routine named CMS$EVENT_ACTION in your image. CMS dynamically activates the CMS$EVENT_ACTION routine's image, if necessary, by calling LIB$FIND_IMAGE_SYMBOL, then calls the CMS$EVENT_ACTION routine.

CMS$EVENT_ACTION (library_data_block,
                 user_param,
                 library_specification_id,
                 ace_parameter_id,
                 history_record_id)

library_data_block

Specifies the library data block (LDB) for the current library.

Specifies the user_arg value passed in a call to a callable CMS routine whose action caused the event. If no user argument was specified in the user call, or if the event did not occur as a result of a user call to a callable CMS routine, the call-frame entry for user_param points to a location containing the value zero. In this case, user_param is allocated as read-only storage.

library_specification_id

Specifies a string identifier for the current CMS library directory specification.

ace_parameter_id

Specifies a string identifier for the string found in the PARAMETER clause of the current ACE (the ACE that defines the current event).

history_record_id

Specifies a string identifier for the string containing the history record written as a result of the current CMS operation (the operation that caused the current event).

The library_data_block argument should be used only by the default CMS$EVENT_ACTION routine; any user-written CMS$EVENT_ACTION routine should ignore it. The user_param argument is provided so a user-written CMS$EVENT_ACTION routine can interpret it; the default CMS$EVENT_ACTION routine ignores it. If you use the default CMS$EVENT_ACTION routine, CMS expects the ace_parameter_id argument to point to a string containing a list of valid MAIL recipient specifications.

When the default CMS$EVENT_ACTION routine encounters errors, it signals error conditions. If the severity code of the condition is an informational or a warning status code, CMS handles it without interrupting the execution of the CMS$EVENT_ACTION routine. On completion, the CMS$EVENT_ACTION routine returns a completion status code; this status code is signaled by CMS if it does not indicate success.

A user-provided CMS$EVENT_ACTION routine should not issue calls to callable CMS routines other than CMS$GET_STRING or CMS$PUT_STRING. Otherwise, a call issued by CMS$EVENT_ACTION might cause a new CMS event to occur, and possibly trigger an infinite chain of events. A user-provided CMS$EVENT_ACTION routine, however, can call the default CMS$EVENT_ACTION routine as part of its event-handling action.

Most CMS commands update several files in the library. If a command is terminated while it is updating the library, the library can be left in a state in which some files have been modified and others have not. Usually, if a command is terminated prematurely, the rollback mechanism cancels and rolls back the transaction (see Section 9.1, “Command Rollback”). If CMS cannot roll back the library, you must use the VERIFY/RECOVER command to restore the library to a consistent state.

If you terminate a command at a time when the files in the library might have been left in an inconsistent state, CMS recognizes that the command execution was incomplete. When any user tries to enter a subsequent CMS command to the same library, CMS attempts automatic recovery. If automatic recovery fails, CMS advises the user to enter VERIFY/RECOVER. In this case, users cannot access the CMS library until VERIFY/RECOVER has been executed.

The VERIFY/RECOVER and VERIFY/REPAIR commands use earlier versions of files in the library to restore the library. You should not delete or purge any files from the library, because CMS performs its own cleanup functions.

%CMS-E-USEREPAIR, use VERIFY/REPAIR

The VERIFY/RECOVER command affects only the currently set CMS library or libraries, not your default directory. An incomplete transaction might mean that the process of moving files into your directory or deleting files from your directory is incomplete. You must recognize these conditions yourself and, if necessary, remedy them with CMS or DCL commands.

For example, the REPLACE command generally uses a file from your current, default directory to update the element file. If the system fails during a replacement transaction, the process of updating the library file might be incomplete. CMS never deletes any files from your directory until a transaction is complete. In this case, you would need to enter the VERIFY/RECOVER command to cancel the transaction. The file that was being copied would still be in your current, default directory. Another REPLACE command creates a new generation as you originally intended.

If you have set up a restrictive file protection scheme and there is a system failure during a CMS transaction that leaves your library in an inconsistent state, a user with sufficient access to the library and its files should execute the VERIFY/RECOVER command. You can also recover the library if you have BYPASS privilege, or read, write, and execute access to all the library files. For more information, see Chapter 7, Security Features.

CMS uses information in the file header of a library file to confirm that the file was closed by CMS. If the file was not closed by CMS (for example, if it was opened and closed with a text editor), VERIFY/REPAIR repairs the file header so it can be successfully verified.

For each element, CMS maintains a number known as a checksum. A checksum is a count that varies with the number of characters and the value of the characters in a file. Every time CMS writes a file in the library, the checksum is recalculated. The VERIFY command calculates the checksum for every element in the library. If this checksum does not equal the stored value, data has probably been lost from, added to, or changed in the file.

The VERIFY/REPAIR command corrects a bad checksum by recalculating the value based on the current contents of the file and then storing this value. The contents of the file are not altered. If you know that data has been lost from or added to the element, you must correct it manually. See Section 9.2.3, “Correcting Errors” for more information.

The VERIFY/REPAIR command adjusts element generations that were created from files with fixed-length records by earlier versions of CMS and have a stored maximum record size of zero. VERIFY/REPAIR examines the element data file, determines what the correct size should be, and stores this value with the generation.

The VERIFY/RECOVER and VERIFY/REPAIR commands use earlier versions of files in the library to restore the library. You should not delete or purge any files from the library, because CMS performs its own cleanup functions.

%CMS-E-VEREDFERR, element DISKX:[PROJECT.CMSLIB]TEST.SDML verified with errors
-CMS-E-NOTBYCMS, data file DISKX:[PROJECT.CMSLIB]TEST.SDML;1 not closed by CMS

Other programs (such as a text editor) can also cause this error.

%CMS-E-BADCRC, bad checksum in element 

This error is usually accompanied by the CMS-E-NOTBYCMS error. A bad checksum indicates that the contents of the element data file are different from what CMS expects. This usually means that data in the file has been corrupted. Corruption can occur if something has changed the contents of the element data file; this can happen if you alter the element data file, or if a previous version of the element data file was restored from backup. Corruption can also occur if the library directory contains a revision of the CMS database (01CMS.CMS) that does not correspond to the element data file. This typically occurs if the 01CMS.CMS file was restored from backup, but the rest of the library contains more recent versions of element files and was not restored.

You can use the VERIFY/REPAIR command to correct BADCRC errors. If CMS finds more than one version of the element file, it keeps the version containing the correct checksum, and deletes the other files. If no file exists with the correct checksum, VERIFY/REPAIR records the checksum from the most recent file, and deletes any other copies. CMS can then use that value for future checks. CMS does not attempt to alter the contents of the file.

You should use VERIFY/REPAIR to correct BADCRC errors only if you understand the source of these errors and the potential impact of repairing them.

If a library has a reference copy directory, the VERIFY/REPAIR command performs a comparison between the reference copy and the latest generation on the main line of descent for each element in the library.

If CMS finds a reference copy for an element that does not have the reference copy attribute, it prompts you for confirmation, then deletes the reference copy file.

CMS maintains a history file in which all operations that modify the library are recorded. Each operation causes a single record (or one record for each item, when wildcards have been used) to be written into the 01CMS.HIS control file. As libraries get older, history files typically become quite large, taking up disk space and causing SHOW HISTORY performance to degrade. Because very old history is generally no longer useful, you can use the DELETE HISTORY command to reduce the size of the file.

Element generation information (for example, as displayed with the commands SHOW GENERATION, FETCH/HISTORY, and ANNOTATE) is part of each generation and is not stored in the history file; therefore, it is not affected by the deletion of the library history.

When you enter a FETCH, RESERVE, or REPLACE command, CMS searches all the generations of a specified element for the generation you are trying to access. As libraries get older, the number of generations usually increases, and CMS commands that operate on element generations respond more slowly.

You can alleviate this problem by deleting the generations of an element that you no longer need. For example, if you have an element with 100 generations, and generation 5 was released in version 1 of your product, generation 30 was released in version 2, generation 43 was released in version 3, and you are currently developing version 4, you probably do not need to reproduce generations prior to 43, with the exception of those specific generations that went into the released versions. You can use the DELETE GENERATION command to remove the unneeded generations (for more information, see the online help or the VSI DECset for OpenVMS Code Management System Reference Manual).

When you delete a generation, the definition of the generation is permanently removed from the corresponding element in the CMS library. Deleting a generation does not remove changes from subsequent generations that were originally made in the deleted generation. If you delete a generation from the end of a line of descent, all the changes representing that generation are removed from the delta file (see Section 4.4, “Delta Files” and Appendix B, CMS Library Storage Method). If you remove a generation from the middle of a line of descent, changes made in that generation are propagated into the surviving descendant and combined or eliminated from the delta file if possible, because later generations still depend on those changes. You should not rely on generation deletion to reduce the size of a delta file.

If you want to delete an element generation from the CMS library but might still want to access the contents of that generation, you can use the /ARCHIVE qualifier on the DELETE GENERATION command. This qualifier directs CMS to create an archive file containing all the information from the deleted generation.

The archive file is self-contained; you do not need a CMS library to restore the contents of the file. The archive file exists outside of the CMS library and can be backed up onto tape and deleted. You can use the SHOW ARCHIVE command to display the contents of an archive file. Use the RETRIEVE ARCHIVE command to retrieve a copy of any of the generations in an archive file. You cannot restore a generation from the archive directly into the CMS library. To restore the generation, you must retrieve the generation into a file, use the RESERVE command to reserve a generation of the element in the library, then use the REPLACE command to replace the reservation, using the retrieved file as input.

Although the VERIFY command does not operate on archive files, the files store a checksum of the information in the file. The RETRIEVE ARCHIVE command issues a warning message if it finds that the checksum of the data in the file does not match the stored checksum. An incorrect checksum does not prevent you from accessing the data in the file, but it might indicate that the file is corrupt. In this case, you should restore another copy from backup.

You use a directory specification to refer to a directory that contains (or will contain) a CMS library or reference copy directory. A directory specification is used as a parameter to the CREATE LIBRARY, SET LIBRARY, and SET NOLIBRARY commands, and as a qualifier value to the COPY ELEMENT command. In addition, it is a parameter to the DCL command CREATE/DIRECTORY, which is used to create a directory that will contain a CMS library (see Chapter 3, Libraries) or reference copy directory.

disk:[directory]

disk

Specifies one or more disks where the directory that contains your CMS library is located. If you omit the disk name, your current default disk is assumed.

directory

Specifies a directory that contains your CMS library. Directory names must be enclosed in square brackets ([]). Wildcards are not allowed.

For more information on how to specify disk and directory names, see the VSI OpenVMS User's Manual.

$ CMS SET LIBRARY [SWIFT.CMSLIB]

This example specifies the subdirectory CMSLIB under the top-level directory [SWIFT] on the current default disk.

CMS> REPLACE DATAFIG3.SDML "updated figure to show new merge routine"

For the purpose of command-line interpretation, remarks are defined as parameters; thus, you can enter qualifiers after the remark. However, the remark must be the last parameter entered on the command line. Because remarks are defined as parameters, CMS attempts to translate the remark if other parameters are missing or incorrectly placed. If, for example, you omit an element name from the syntax of a command, but you enter a remark, CMS assumes that the remark is intended as the name of an element.

Quotation marks ("") are required to enclose the remark if you enter it on the same line as the command and the remark contains any spaces. For example, a one-word remark entered on the command line does not require enclosing quotation marks. The text can consist of any printing characters, spaces, and tabs. If you press Ctrl/Z as part of a remark, it terminates the command input at that point, and CMS executes the command. If you press Ctrl/C as part of a remark, CMS cancels the command. To insert a quotation mark (") within a remark, type it twice (""). If a remark consists only of two consecutive quotation marks (""), the remark text is null.

CMS> REPLACE DATAFIG3.SDML
_Remark: updated figure to show new merge routine

Type the text of the remark immediately following the prompt. In this case, you need not enter quotation marks unless you want them to be included in the text of the remark. If you press Return in response to the prompt, you are not prompted again, and the remark text is entered as null.

When you start the remark on the same line as the CMS command, the total length of the remark (including quotation marks), added to the character count for the rest of the command, cannot exceed 256 characters. When you enter the remark in response to the prompt, the length of the remark cannot exceed 254 characters.

You cannot use the hyphen continuation character (-) to continue a remark. If you type a hyphen within a remark and then press Return, the hyphen becomes the last character in the logged remark. The closing quotation marks are assumed. To continue a remark, type the remark until the text wraps to the next line.

Examples

You name an element by specifying it as the parameter to the CREATE ELEMENT command.

filename.type

filename

Specifies the file-name component of an OpenVMS file specification. The filename can be 0 to 39 characters, and must begin with an alphanumeric character. For a list of the characters that you can use in a file name, see the VSI OpenVMS User's Manual. Note that systems running versions of OpenVMS that support extended file names no longer have these and other filename restrictions on ODS-5 volumes. See your system manager for details on the /EXTENDED_FILENAMES qualifier if this applies to your environment.

type

Specifies the file-type component of an OpenVMS file specification. The file type can be 0 to 39 characters. For a list of the characters you can use in a file type, see the VSI OpenVMS User's Manual.

TEST.BAS
     SAMPLE.SDML
     ARGCHK.COM
     MOD5.S

SAMPLE^ ORIGIN.TXT

Any file listing requests for this library would display the previous file name as SAMPLE^_ORIGIN.TXT (RMS automatically replaces the space with an underscore). Other characters must also be preceded by the circumflex character, but the space is the only character replaced like this.

An element expression lets you name multiple instances of an element in a single parameter field.

CMS> SET LIBRARY [JONES.CMSLIB]
CMS> CREATE ELEMENT ELE.SDML,*.LIS,DATASAM.PAS "element list"

This command sets the current CMS library to [JONES.CMSLIB] and creates the element ELE.SDML, all elements with a file type of .LIS, and the element DATASAM.PAS. These elements are created from files in your default disk and directory.

You must include a period (.) in the element expression to select one or more elements from the complete list of elements in the library. If you do not include a period, CMS interprets the parameter as a group name and selects elements based on the list of groups established in the library.

An element generation is a specific version of an element. Each time you reserve and replace a version of an element in the library, CMS creates a new generation of that element. The first generation of an element is generation 1. Each element generation is assigned a unique generation number; by default, subsequent generations are numbered sequentially by adding 1 to the predecessor generation number.

You can create a variant generation number from an existing generation number by appending a variant letter to the existing generation number and starting a new level number sequence beginning at 1. For example, the generation 7A1 could be a variant generation of generation 7.

level-number [variant-letter level-number]...

In this syntax, the level-number is a positive integer, and leading zeros are not allowed. The variant-letter is a single alphabetic character (a through z, A through Z).

An element generation expression enables you to specify a particular generation of an element. You can specify a generation indirectly by using a class name, the plus operator, the semicolon, or relative generation offsets. These methods can be combined or used separately.

The format of a generation expression is as follows:

generation-number

Specifies a unique element generation.

class-name

Specifies a CMS class name according to the syntax rules in Section 10.2.9, “Class Names”. If a class name value is given, the generation specification refers to the generation in the specified class.

+

Indicates the plus operator. CMS locates the latest generation on the same line of descent as the generation specified by the generation number or class name.

;

Required to separate the relative generation offset from the generation specification. The semicolon is not allowed in cases where a generation number or class name has been omitted and CMS supplies a default value.

relative-generation-offset

Specifies an integer that directs CMS to locate an ancestor or direct descendant of the specified generation. If the relative generation number is negative, CMS locates an ancestor generation. If the relative generation number is positive, CMS locates a direct descendant. The absolute value of the relative generation number indicates how many steps should be taken to the next existing ancestor or descendant generation. A relative generation offset of zero has no effect.

If generations have been deleted, CMS selects the third existing generation prior to the generation you specified. For example, assume the current generation of SAMPLE.PAS in class VERSION1 is generation 7, and generations 5 and 6 have been deleted on the main line of descent for SAMPLE.PAS (thus, the line of descent appears as 1, 2, 3, 4, 7).

Examples

Assume the element SEMANTICS.PAS has six generations on the main line of descent. In addition, a variant line consists of generations 3C1 and 3C2. Generation 5 belongs to the class VERSION1. The following examples show valid forms of the /GENERATION qualifier for the element SEMANTICS.PAS.

Various CMS command qualifiers require quoted strings, file specifications, directory specifications, numeric values, alphabetic values, times, or generation expressions as qualifier values.

/OUTPUT = TESTFE.COM
/OUTPUT: TESTFE.COM

The following sections describe file specifications and the format for entering dates.

Each command description in the online help or the VSI DECset for OpenVMS Code Management System Reference Manual contains a list of qualifiers and qualifier defaults. The default indicates the action taken when you omit the qualifier.

/[NO]APPEND
/NOAPPEND

On the left, the qualifier is listed with brackets ([]) around the optional part of the qualifier (NO). On the right, the default is listed.

/MERGE=generation-exp      /NOMERGE
/NOMERGE

If you use the positive form, the generation expression is required. If you use the negative form, which is the default, the generation expression is not allowed.

The defaults (if any) for qualifier values are explained in the qualifier descriptions and are also indicated by the letter D next to the qualifier name.

The percent sign (%) is the single-character wildcard indicator. When you use the percent sign in a command parameter, CMS selects elements, groups, or classes by substituting any single, allowable character for the percent sign.

DATA1.FOR
DATA2.FOR

The asterisk (*) is the partial- and full-field wildcard indicator. When you use an asterisk in a command parameter, CMS selects objects whose names contain the character patterns given in the wildcard expression. CMS replaces the asterisk with any number of allowable characters (within the range of zero to the maximum size of the field).

DATA.FOR
DATA1.FOR
DATA2.FOR
DATA_IN.FOR
DATA_OUT.FOR

To cancel a wildcard transaction before it has completed, press Ctrl/C. If you press Ctrl/C during a wildcard transaction that updates the library, CMS finishes the immediate transaction, but does not continue. For example, if you are replacing several elements and you press Ctrl/C during there placement of the first element, CMS finishes that replacement transaction but does not continue with the others.

When you enter a wildcard command from DCL command level and then press Ctrl/C during execution of the command, CMS returns control to DCL. If you enter the command from the CMS subsystem prompt level, control is returned to CMS.