|
|
The general flow of CMS is as follows:
Add files to CMS
When a file needs to be changed
Other commands that are used as needed
CMS is executed by entering DSI CMS at the DCL prompt. The program first checks for the symbol DSI_CMS_LIBRARY. If this symbol exists then it is used to locate the CMS library. This symbol is generally set up in the file DSI_CMS_LOGICALS.COM which is automatically executed upon setting default to an application work area using the command procedure DSILIB:SET_DEFAULT.COM.
If the above procedures cannot locate a library directory, then you must use the LIBRARY command to set up the library directory before using any other commands.
CMS Structure
The CMS library consists of a root directory, a library database and a series of subdirectories to provide control of source files. In general, each software application will have a separate CMS library. The CMS library is referenced by either a logical name that points to the root directory or the directory name itself. It is recommended that logical names be used to allow the CMS library to be easily moved.
In the main directory there are four files:
CMS_INDEX.DAT- This contains one record for each file in the source library. This record is added by the CREATE command and is used to link all the files together that are related to a source file.
HISTORY.DIR- This directory contains the history text files.
SOURCE.DIR- This directory contains the latest version of the files inserted into the library.
UPDATE.DIR- This directory contains the difference files used to produce an earlier version of the file in the source subdirectory.
Logical Name Setup
It is suggested that the three system logicals be set up for each library. The first logical should point to the main library directory. The second logical should point to the CMS source subdirectory and the third logical should point to the test or development account associated with the library. For example if the library directory for the source to an accounts receivable application is CMS_DISK:[AR] and the development account is AR_DISK:[AR.DEVEL] then the following definitions should be made:
$DEFINE/SYSTEM
AR_CMS CMS_DISK:[AR]
$DEFINE/SYSTEM
AR_SOURCE CMS_DISK:[AR.SOURCE]
$DEFINE/SYSTEM
AR_WORK AR_DISK[AR.DEVEL]
The logical AR_SOURCE is used for search commands to locate strings in the source files without having to reserve or copy all of the files. Note that all CMS libraries can then be shown with the command SHOW LOGICAL *CMS and all work areas can be show with the command SHOW LOGICAL *WORK.
Library Creation
The steps to create a CMS library are:
The following section is a description of each command in alphabetical order.
COPY file-name
The COPY command creates a copy of a file in your default directory. It does not reserve the file, nor does it check to see if the file has already been reserved.
CREATE file-name
The CREATE command is used to create a record in the CMS library database. This record contains the current information about the file and is the link between the source, history and difference files. A record must be created before any other commands can be given for a specific file. The file name used by CMS for the file will only be the given name and extension. Any node, device or directory information will be ignored. If the file already exists in the library, the message 'File already exists' will be displayed.
After the CMS record has been created, you will be reminded to LINK this file to its master file if it is a sub-program. See the LINK command.
DELETE file-name
The DELETE command is used to remove a file from a library. The control record is deleted from the library database and all associated history and difference files are deleted as well. This command can be used any time after a file has been created unless the file has been reserved by another user. After you enter this command the file status is displayed and you are prompted 'Sure delete file'. If anything other than a word beginning with Y is entered, the command is aborted and no action is taken.
DOCUMENT file-name date
The DOCUMENT command is used to update the documentation date of a file. If only the command and the filename are entered, the documentation date will default to the system date. A date may also be included if the default is not desired. Note: a LIST /DOC will produce a list of all files in the library that have been modified since the last documentation date.
EXIT
The EXIT command causes CMS to exit and return either to DCL or the procedure that it was called from.
HELP
The HELP command displays a summary of the commands available.
HISTORY file-name
The HISTORY command displays the current status of the selected file and then accesses the revision history file. History can only be accessed on entries in the library that have had a file inserted.
INSERT file-name
The INSERT command is used to add a file to the library. If the file cannot be opened, an error message will be displayed and no changes will be made.
If the record for the file has not been created (See section ), you will receive the message "Entry must be created before a file can be inserted." Use the CREATE command to add a file entry to the library database and then INSERT the file.
If the file has previously been inserted but is not currently reserved or is reserved to another username, then you cannot insert the file and an error message will be displayed. Note that if you then reserve the file, the current file in the library will be copied to your default directory causing a later version of the file to be created.
If the file purpose field is blank, you will be prompted for a one line description that will be used by the LIST command.
If this is the first time this file is being inserted, the file will be copied to the library and a history file will be initialized and brought into an editor. A longer description of the file can now be entered. When you exit the history file, the source file will be copied into the library and the original file will be deleted.
If the file was reserved to you, a difference file will be created and saved, the revision number of the file will be incremented, and the history file will be brought into an editor. Either a description of the changes made should now be entered or the request for change file can be included. When you exit the history file, the source file will be copied into the library and the original file will be deleted.
LIBRARY library-directory
The LIBRARY command is used to tell CMS which source library to use. The parameter library-directory must either be a logical name that points to a directory or a directory name that already exists. CMS then checks the structure of the directory and if the library has not been created and initialized, you will receive the following prompt:
Library not found, Create new library
If you answer Y, CMS will initialize the library structure. After the library has been set, all other library commands will work.
LINK sub-file master-file
The LINK command establishes a connection between a sub-file and a master file so that there is a single history file for all changes made to a master program and the files needed to build it. If, for example, a program A.EXE is built from the files A.BAS, SUB1.BAS and SUB2.BAS, then issuing the following commands tells CMS that the two sub-files SUB1.BAS and SUB2.BAS are linked to the master file A.BAS:
LINK SUB1.BAS A.BAS
LINK SUB2.BAS A.BAS
Once these commands have been issued, there will be only one history file for any change to any of the files.
Note that this command should usually be entered right after the CMS entry is created and before any file is inserted. Otherwise the history file for the sub-file will no longer be accessible from CMS.
LIST file-name
The LIST command produces a status list of all the files in the selected library. The file-name parameter is optional and may contain wild card characters. There are four switches that modify the behavior of the list command.
OVERRIDE reserved file
The OVERRIDE command is used to INSERT a file that is reserved to another username.
After this command is entered, a difference file will be created and saved, the revision number of the file will be incremented, and the history file will be brought into an editor. Either a description of the changes made should now be entered or the request for change file can be included. When you exit the history file, the source file will be copied into the library and the original file will be deleted.
Please note, once an OVERRIDE has been entered, the file will no longer be reserved.
RECALL file-name version
The RECALL command is used to get a copy of an earlier version of a file. The version number must be between 0, for the first version inserted, and one less than the current version stored. CMS applies the difference files to the current version to back out the changes and leaves the requested version of the file in you current default directory. Note that the CMS version is unrelated to the VMS file version. This command does not reserve the file as inserting the file produced by this command would effectively erase the later changes.
RESERVE file-name
The RESERVE command is used to obtain a copy of a file from the library and to reserve the file to your username. This prevents another user from making changes to a copy of the file and then moving it back into the library, thereby overriding your changes.
In order to reserve a file, it must have been previously inserted into the library and not reserved to any user. When you reserve a file a copy is placed in your default directory. Changes can then be made to this copy and tested. Upon completion of testing the file can then be inserted back into the library.
When a file is reserved, an optional comment can be entered to clarify the purpose of reserving the file. This comment will be displayed on a full listing and is cleared automatically when the updated file is inserted back into the library or the file is unreserved.
UNLINK sub-file
The UNLINK command deletes the link between the given sub-file and its previously linked master file. After this command, the sub-file will have its own history file created the next time a change is inserted into the library.
Note that this command does not change the old master history file and any information in it is not transferred to the new history file.
UNRESERVE file-name
The UNRESERVE command releases a previously reserved file without updating the library. This can only be done by the user that originally reserved the file. It is used when you decide not to make any changes to a file that you had previously checked out and you want to allow other users to make changes to the file.