UCM version v5_2

UVM: Version Management.

Contents:
Command Syntax: General syntax rules and conventions.
Command Index: A list of available commands.
GUVM: Graphical command interface.
UVMA: Access Commands.
UVMI: Informational Commands.
CHECKIN: Implementation specific preprocessing.
See the Table of Contents for more information.

RCS (Revision Control System) is a readily available UNIX product which is very similar to Digitil's CMS (Code Management System) product except that it operates on individual files rather than on libraries. UVM (UNIX Version Management) provides a more complete CMS like functionality by organizing RCS files into UVM libraries and providing commands to access them and collect information about them.

Unlike CMS, a UVM library directory can contain other UVM libraries so as to form directory tree. For most purposes the libraries in the tree are independent of each other, however, with some obvious exceptions, a UVM command applied to any UVM library will also be applied to any sub-libraries it may contain.

Command Syntax:

The UVM commands are internally organized into two sets which are invoked using two different Perl scripts: UVMA (UVM Access) commands are used to create and control accesses to the UVM libraries; and UVMI (UVM Inquire) commands return information about the libraries and their contents.

These two command sets can be invoked directly through uvma and uvmi or indirectly through the generic command, uvm. The uvm, uvma and uvmi commands all follow a consistant syntax with the following components:-

• The command set identifier: uvm, uvma or uvmi.
• A one or two word command name which is can be abbreviated to the smallest number of unambiguous number of characters and which is case insensitive.
  Note that "uvm S*how" commands are all interpreted as "uvmi" commands whereas all other "uvm" commands are interpreted as "uvma" commands.
• An argument consisting of a library or element specification of the form "library" or "library/file" which is usually optional and which can usually contain wild card specifications in either or both the library and file parts. When using wild cards the argument must be enclosed in quotes. For most commands "file" can either refer to UVM elements directly or be the name of a UVM group. The default value for "file" is "*". Generally the library specification refers to all UVM libraries found in the directory tree(s) pointed to by library. However, if the -F option is supplied then only UVM libraries directly pointed to by library are referenced. If omitted the library specification, "library" will default to the one last specified in a uvma or uvmi command. This is recorded in the file $HOME/UVM_DEFAULT.
• Zero or more options which consist of an option flag followed by the option value. The option flag consists of a "-" immediately followed by a single character, case sensitive, identifier. If the option value consists of more than one "word" it must be enclosed in quotes. Spaces between the flag and its value are optional.

Command Index:

uvm Default          	uvm Show Default
uvm Create Library   	uvm Show Description
uvm Describe Library 	uvm Show Groups
uvm Create Element   	uvm Show Activity
uvm Describe Element 	uvm Show Reservations
uvm Reserve          	uvm Show Changes
uvm Unreserve        	uvm Show Dependency
uvm Replace          	uvm Show List
uvm Fetch            	uvm Show Content
uvm Remove           	uvm Show History
uvm Insert           	uvm Show Difference
uvm Move             	uvm Show Tags
uvm Rename           	uvm Show Membership
uvm Tag
uvm Untag
uvm Group
uvm Ungroup

UCM version v5_2

GUVM: Graphical Command Interface

The currently selected UVM command is displayed in the command area of the screen. The various command components are put together by either typing directly into the input boxes or by choosing components from the menu lists or option buttons. Note that if the selected command does not expect some of arguments shown, then the corresponding input boxes will be disabled.

The radio buttons on the left of the screen are used to switch between three lists which can be used to:

1. Select UVM commands
2. Choose from one of the sublibraries referenced by the current default library specification
3. Choose an existing element from the library pointed to by the current default library specification.

Command options can be selected by clicking on the corresponding button. One exception is the -F option which is toggled on or off with the "Reference sublibraries" radio button. This option controls whether or not the library specification is interpreted as a "flat" directory specifier or as the the root of a directory tree. The other exception is the "-h" option which is automatically provided when the UVM libraries do not reside on a the local machine.

The three buttons on the right of the screen are used to execute or obtain help on the selected command or to exit out of the interface program. If no command is selected then the Help button provides general help on using of the interface program.

The command interface also allows access to UVM libraries residing on a remote host as declared in the "Remote UVM Host" field. In this case the selected UVM command is executed on the remote host using the ssh protocol. The "Remote user" field can be used to specify a user name for the remote host if it is different to that on the local machine. Since some commands require access to the user's local file space the "-h" option is automatically added with the local user/host name as its argument. For this to work correctly a two-way proxy login needs to established between the remote and local hosts.

Output from UVM commands, the "cd-ls" button, and the help facility is dispayed in the scrollable text area at the bottom right corner of the screen.

The interface program also allows the user to change and view their current working directory using the "cd-ls" button in combination with its associated input field. The button causes consecutive cd and ls commands to be issued with the contents of the input field used as an argument to the cd command. This function is important when using UVM commands that cause files to be created in or deleted from the user's area.

UCM version v5_2

UVMA: Access Commands

uvm Def*ault library

Defines the default library specification to be used by subsequent uvm, uvma or uvmi commands. A list of the UVM libraries that will be referenced by these commands is displayed.

uvm C*reate L*ibrary library [-c "Comment"]

Creates a UVM library defined by the directory path name, "library". UVM library directories can contain other UVM library directories provided, of course, that they are not called UVM.
-c Option values:

• A single line of descriptive text enclosed in quotes
• The name of a text file containing the description.
• If omitted the user will be prompted for a description.

uvm Des*cribe L*ibrary library [-c "Comment"] [-F]

Changes the description of UVM library(s) defined by the directory path name(s), "library".
-c Option values:

• A single line of descriptive text enclosed in quotes
• The name of a text file containing the description.
• If omitted the user will be prompted for a description.

uvm C*reate E*lement [library/][file] [-c "Comment"] [-h Host]

Creates UVM library element(s) in the library defined by the directory path name, "library". An RCS file is created from each file in the user's local area which matches the file specification, "file". The user's local file is deleted after the UVM element has been successfully created. Before the RCS file is created an implementation specific Perl script, CHECKIN, is executed which can be used to preprocess the file.
-c Option values:

• A single line of descriptive text enclosed in quotes
• The name of a text file containing the description.
• If omitted the user will be prompted for a description.

-h Option value: Has the form [[user@]host:][path]

• This option causes UVM to look for the initial work file(s) in the directory specified by path on the host machine specified by host. Copies are done using scp.

Note: Wild card specifications are not permitted in the library specification and the file specification cannot correspond to an existing group name.

uvm Des*cribe E*lement [library/][file] [-c "Comment"] [-F]

Changes the description of the specified UVM library element(s).
-c Option values:

• A single line of descriptive text enclosed in quotes
• The name of a text file containing the description.
• If omitted the user will be prompted for a description.

Note: This command does not affect the modification date of the element.

uvm Res*erve [library/][file] [-h Host] [-F]

Extracts a working version of the latest revision of the specified UVM element(s) into the user's local area and locks the RCS file. The lock will prevent other users from attempting to modify the same element.
-h Option value: Has the form [[user@]host:][path]

• This option causes UVM to copy the work file(s) to the directory specified by path on the host machine specified by host. Copies are done using scp.

Note: This command does not affect the modification date of the element. If the user does not supply a file specification, they will be prompted to confirm that they really do want to reserve all elements in the library.

uvm Unr*eserve [library/][file] [-F]

Unreserves the specified UVM element(s) that have been reserved by other users. The user will be informed as to who currently has the element reserved and will be asked if they wish to proceed. If they choose to do so they will be prompted for a reason and this will be automatically mailed to the users who had made the original reservation.

uvm Rep*lace [library/][file] [-c "Comment"] [-h Host] [-F]

Creates a new revision of the specified UVM element(s) from working file(s) in the user's local area. The revision will only be created if the UVM library element was originally "reserved" by the same user. The RCS file is unlocked after the revision has been created. Before the RCS file is replaced an implementation specific Perl script, CHECKIN, is executed which can be used to preprocess the file. This is the same script that was executed when the element was created.
-c Option values:

• A single line of descriptive text enclosed in quotes
• The name of a text file containing the description.
• If omitted the user will be prompted for a description.

-h Option value: Has the form [[user@]host:][path]

• This option causes UVM to look for the work file(s) in the directory specified by path on the host machine specified by host. Copies are done using scp.

uvm F*etch [library/][file] [-r revision] [-h Host] [-F]

Creates a copy of the specified UVM element(s) in the user's local area. The revision of the element to be fetched is specified by revision.
-r Option values:

• A specific revision number (e.g. 1.1).
• A symbolic tag name.
• A free format date/time specification specifies the most recent revision that existed at that time. ( In general a date/time specification will need to be enclosed in quotes. See the RCS man pages for a discussion of acceptable date/time formats.)
• If omitted the latest revision will be fetched.

-h Option value: Has the form [[user@]host:][path]

• This option causes UVM to copy the output file(s) to the directory specified by path on the host machine specified by host. Copies are done using scp.

Note: The files created are given read-only access.

uvm Rem*ove [library/][file] [-h Host] [-F]

Removes UVM element(s) from a library. The corresponding RCS files are moved into the user's current working directory. The element(s) will also be removed from any groups they may have belonged to. Since this operation can have implications on objects built from the library, it should be used with caution.
-h Option value: Has the form [[user@]host:][path]

• This option causes UVM to copy the removed file(s) to the directory specified by path on the host machine specified by host. Copies are done using scp.

Note: As a safety precaution the user will be prompted for a confirmation of each removal.

uvm I*nsert [library/][file] [-h Host]

Creates a UVM element(s) from existing RCS file(s) in the user's current working directory. The revision history and any tags in the existing RCS file are preserved. The CHECKIN procedure will be called for each new element. This operation can be used to undo a prior remove command.
-h Option value: Has the form [[user@]host:][path]

• This option causes UVM to look for the RCS file(s) in the directory specified by path on the host machine specified by host. Copies are done using scp.

Note: Wild card specifications are not permitted in the library specification and the file specification cannot correspond to an existing group name.

uvm M*ove [library/][file] -l destination [-F]

Moves UVM element(s) from their current library, "library", into the one specified by the required -l option. The element(s) will also be removed from any groups they may have belonged to. Since this operation can have implications on objects built from the old library, it should be used with caution.
-l Option values:

• A directory specification for an existing UVM library.

Note: As a safety precaution the user will be prompted for a confirmation for each move.

uvm Ren*ame [library/][file] -f new_file [-F]

Changes the name of UVM element(s) from "file" to "new_file". Group membership is preserved and all references to the element(s) in the library's HISTORY file are modified to use the new name(s). Since this operation can have implications on objects built from the old library, it should be used with caution.
-f Option values:

• A file name specification describing the new element name(s).
• If "file" contains a wild card specifiers ( * ), then the part of each element name which is matched by the *'s will replace the corresponding *'s in "new_file"

Note: As a safety precaution the user will be prompted for a confirmation for each rename.

uvm T*ag [library/][file] -n tag_name[:revision] [-F]

Assigns a symbolic tag name, "tag_name", to the specified revision of the UVM element(s). Tag names must contain alphanumeric characters only.
-n Option values:

• If "revision" is omitted then the latest revision of the element(s) will be tagged.
• If "revision" is a symbolic tag name then only elements containing a revision tagged with that name will be tagged with "tag_name".
• If "revision" is a free format date/time specification then the most recent revision (if any) that existed at that time will be tagged. (In general, a date/time specification will need to be enclosed in quotes. See the RCS man pages for a discussion of acceptable date/time formats.)
• If "tag_name" has already been assigned to a revision of the element it will moved to the one specified by "revision".

Note: This command does not affect the modification date of the element.

uvm Unt*ag [library/][file] -n tag_name [-F]

Removes the symbolic tag name indicated by the -t option from the specified UVM element(s).
Note: This command does not affect the modification date of the element.

uvm G*roup [library/][file] -g group [-F]

Adds the specified UVM element(s) to the group(s) indicated by the -g option. If the group does not currently exist, it will be created.
-g Option values:

• "group" cannot be the name of an existing UVM element.
• If wild cards are used in the group specification the element(s) will be added to all matching groups.

Note: This command does not affect the modification date of the element.

uvm Ung*roup [library/][file] -g group [-F]

Removes the specified UVM element(s) from the group(s) indicated by the -g option. If this operation empties a group, it will be automatically deleted. Wild cards can be used in the group specification provided it is enclosed in quotes.
Note: This command does not affect the modification date of the element.

UCM version v5_2

UVMI: Informational Commands

uvm S*how Def*ault [-F]

Displays the current setting for the default library specification which will be used by subsequent uvm, uvma or uvmi commands. A list of the UVM libraries referenced by this specification will also be displayed.

uvm S*how Des*cription [library] [-F]

Displays the description of a UVM library(s). This description is supplied when the elements are created and can be changed with the uvm describe library command.

uvm S*how G*roups [library] [-F]

Displays lists of all the groups existing in the specified library(s).

uvm S*how A*ctivity [library] [-d days] [-F]

Shows the activity in the specified UVM library(s). Library activity consists of a list of all UVM commands which can modify the library contents: create element, reserve, replace, remove, insert, move, rename, tag, and untag. Each entry in the activity list contains a date (GMT), user name, command name, and element name. The tag and untag entries also include the option values but produce only one entry per command issued whereas the other commands produce an entry for each affected element.
-d Option values:

• A decimal number indicating the number of days of activity to be included in the list. Only activity occurring in the past "days" days will be included in the list.
• If omitted all library activity will be displayed.

uvm S*how R*eservations [library] [-u [user]] [-F]

Lists any elements that are currently reserved in the specified UVM library(s).
-u Option values:

• A specified user name limits the list to those elements reserved by that user.
• If the -u option flag is given without a corresponding value, the list will be limited to elements reserved by the user issuing the command.
• If both flag and value are omitted, all reserved elements will be displayed.

uvm S*how Ch*anges [library] [-n [rev_1][:rev_2]] [-F]
uvm S*how Ch*anges [library] [-d [days]] [-F]

Lists the UVM elements in the specified library(s) which have different revision numbers associated with the two revisions specified by the -n option or which have changed during the time specified by the -d option. If both options are omitted then the default -d option is used.
-n Option values:

• Symbolic tag names specify the corresponding tagged revisions.
• The value "Original" specifies the original version.
• The value "NOW" or "Latest" specifies the latest revision of each element.
• A free format date/time specification specifies the most recent revision, if any, that existed at that time. ( In general a date/time specification will need to be enclosed in quotes. The may additionally need to be enclosed in parentheses (..) in order to resolve ambiguities resulting from the : used in a time specification. See the RCS man pages for a discussion of acceptable date/time formats.)
• If omitted "rev_1" defaults to the original revisions of the library elements. In this case elements which do not satisfy "rev_2" will not be listed.
• If omitted "rev_2" defaults to the latest revisions of the library elements. In this case elements which do not satisfy "rev_1" will not be listed.

-d Option values:

• A number of days specified as a decimal fraction.
• If omitted then the number of days since "Jan 1, 1970" is assumed.

uvm S*how Dep*endency [library] -f file [-F]

Lists the elements in "library" which contain a KPP include reference to the file "file". This command assumes that the default version of CHECKIN has been used to create dependency lists in the UVM subdirectory of the specified libraries. This command is useful for determining which elements will be affected by changes to a KPP include file.

uvm S*how L*ist [library/][file] [-r revision] [-F]

Creates a multi-column list of the elements in the specified library(s) which match the "file" specification and have a revision number matching the revision specified by the -r option. The matching revision number is included in the list.
-r Option values:

• Symbolic tag names specify the tagged revisions.
• A free format date/time specification specifies the most recent revision that existed at that time. ( In general a date/time specification will need to be enclosed in quotes. See the RCS man pages for a discussion of acceptable date/time formats.)
• If omitted the latest revisions of the elements are listed.

uvm S*how Co*ntent [library/][file] [-r revision] [-F]

Displays the contents of the requested revision of the specified library element(s).
-r Option values:

• Symbolic tag names specify the tagged revisions.
• A free format date/time specification specifies the most recent revision that existed at that time. ( In general a date/time specification will need to be enclosed in quotes. See the RCS man pages for a discussion of acceptable date/time formats.)
• If omitted the latest revisions of the elements are displayed.

uvm S*how H*istory [library/][file] [-n [rev_1][:rev_2] [-F]
uvm S*how H*istory [library/][file] [-d [days]] [-F]

Displays detailed information about the specified library element(s). The information includes the element description as defined by the comment supplied at the time it was created and a summary of revisions as specified by the options. This summary includes the comments supplied when it was replaced, the date and time it was replaced, the user name of the person who made the replacement, and the number of lines changed. If the -d option is used the element descriptions of all specified elements will be displayed along with revision summaries, if any, for those revisions made during the last "days" days. If the -n option is used then a summary is printed only for those elements which have two different revisions satisfying the revision expressions "rev_1" and "rev_1". A revision summary is included for all revisions between and including the two specified. If both options are omitted then the default -d option is used.
-n Option values:

• Symbolic tag names specify the corresponding tagged revisions.
• The value "Original" specifies the original version.
• The value "NOW" or "Latest" specifies the latest revision of each element.
• A free format date/time specification specifies the most recent revision, if any, that existed at that time. ( In general a date/time specification will need to be enclosed in quotes. The may additionally need to be enclosed in parentheses (..) in order to resolve ambiguities resulting from the : used in a time specification. See the RCS man pages for a discussion of acceptable date/time formats.)
• If omitted "rev_1" defaults to the original revisions of the library elements.
• If omitted "rev_2" defaults to the latest revisions of the library elements.

-d Option values:

• A number of days specified as a decimal fraction.
• If omitted then the number of days since "Jan 1, 1970" is assumed.

uvm S*how Di*fference [library/][file] [-n [rev1][:rev2] [-F]

Lists the differences between two revisions of the specified element(s), but only if the revisions exist and are different.
-n Option values:

• Symbolic tag names specify the corresponding tagged revisions.
• The value "Original" specifies the original version.
• The value "NOW" or "Latest" specifies the latest revision of each element.
• A free format date/time specification specifies the most recent revision, if any, that existed at that time. ( In general a date/time specification will need to be enclosed in quotes. The may additionally need to be enclosed in parentheses (..) in order to resolve ambiguities resulting from the : used in a time specification. See the RCS man pages for a discussion of acceptable date/time formats.)
• If omitted "rev1" defaults to the original revisions of the library elements.
• If omitted "rev2" defaults to the latest revisions of the library elements.

uvm S*how T*ags [library/][file] [-F]

Lists the revision numbers associated with any symbolic tags applied to the element(s). The latest revision number is also displayed.

uvm S*how M*embership [library/][file] [-F]

Lists the groups (if any) that the specified library element(s) belong to.

UCM version v5_2

CHECKIN: Implementation specific preprocessing

system( CHECKIN $library $name );

$library is a variable containing the UVM library specification and $name is the name of the input file for the create or replace operation.

This call provides a hook which can be used to perform various checks or operations on UVM elements before they are inserted into the library. The default version of the CHECKIN command is a Perl script which scans the input file for KPP include references and creates a list of the included files in the UVM subdirectory. The file containing this dependency list is given the same name as the input file.