Overview of the VCM Command-line Utility (VCMUtility)

The VCMUtility is a command-line utility that compares a StarTeam source view to a target view, and optionally merges the differences into the target view.

You can start a View Compare/Merge session from the command line and finish it in the StarTeam Cross-Platform Client in the View Compare/Merge UI. For example, you can use the VCMUtility to create a VCM session, perhaps using its DefaultAction option, but do not let it commit. It will automatically save the VCM session with any alternate name you choose if needed. You can then open that VCM session in the StarTeam Cross-Platform Client, review and make adjustments, then commit the changes to the repository.

Syntax

The syntax for the command-line uses the following conventions.

Curly braces { }	Encloses required syntax elements.
Square brackets[ ]	Encloses optional elements
Angle brackets < >	Encloses a word or phrase that must be replaced with an appropriate value, or set of values. For example, <file name> would be replaced by an actual filename or path, and <userid> would be replaced by an actual user ID. However, many of the words or phrases in angle brackets can be expanded into more complicated syntax. For example, <change requests> can be replaced by CR, CRs, ChangeRequest, ChangeRequests, *ChangeRequest 4277, and so on. When you are not sure what can be used, see the VCMUtility “Cheat Sheet” topic in the Reference/CompareMerge section of the documentation. The “Cheat Sheet” provides the full syntax for phrases like <change requests>**.
Vertical bar \|	Separates alternate elements.
Prefixed with an asterisk *	Indicates the following element can be repeated.

Note: All options are case-insensitive (for example, Server is the same as server).

VCMUtility Command

VCMUtility [<options file>] [options] [options] [epwdfile file] [DifferenceReport file][UpdateReport file]

You can provide options in the specified <options file> (as the first parameter), command-line arguments, or both. Command-line arguments override any options found in the <options file>. In the <options file>, the option name should begin as the first character on a new line and exclude the leading -.

VCMUtility Options File

You can specify VCMUtility options in an options file whose name is passed as the first parameter of the VCMUtility command.

Example:

VCMUtility c:\VCMconfig.txt

Each option in the file must begin on a new line. Option names must begin in column 1 and be followed by at least one white space character. An option’s value can flow onto multiple lines by starting each continuation line with a blank or tab character. Blank lines are ignored. You provide comments by prefixing them with a double forward-slash (//).

Example:

// This is a comment
server jsmith:mypw@somehost:49201
type Rebase
include "/Cygnus/StarTeam/<StarTeam Core>/Server/Common/*.h" +ALL
  *.cpp	*.rc Makefile	// long value continued on a second line

// The line above was blank
save
 my—rebase-session				// value provided on a separate line

Command-line Parameters

VCMUtility options can be passed as command-line parameters by placing a dash in front of the option name. For example, the Server option can be provided as a command-line parameter -server. If an option has secondary "value" tokens, they must immediately follow the option name (without a dash).

Mixing Input Sources

VCMUtility options can be provided in an options file, with command-line parameters, or with a mixture of both. For example, commonly-used or "static" option values can be placed in the configuration file while "dynamic" values can be provided in command-line parameters.

A command-line parameter may specify the same option as defined in the configuration file. When a command-line argument specifies the same option as in the options file, the command-line option value overrides the configuration file option value. For example, if the configuration file specifies Source View1 but the command-line specifies -Source View2, then View2 is used as the source view.

Option Values with Unicode Characters

The encoding of option values passed as command-line arguments is controlled by the launching environment (for instance, command shell). Consequently, on systems where option values must be passed to the VCMUtility that require characters not expressible by the launching environment, those options must be passed by way of the options file.

When the options file does not begin with a byte-order mark (BOM), it is opened with the system default character set (for example, ANSI [Windows-1252] on Windows, UTF-8 on Linux). If the options file begins with a BOM, it is interpreted with the corresponding encoding. UTF-8 and UTF-16 encodings allow the full set of Unicode characters to be provided in the options file.

For reference, the BOM sequences are:

0xEFBBBF	UTF-8
0xFEFF	UTF-16 BE (big-endian)
0xFFFE	UTF-16 LE (little-endian)

Boolean Options

The default for all Boolean options (whose value can be True or False) is False. However, specifying a Boolean option without an option value is the equivalent to specifying the value True. Thus, a Boolean option can be enabled by simply including it. Example:

// Set these options to True
AutoLogon
BreakLocks

Abbreviations

In addition to their "long form" (shown in this document), most command and option names have one or more "short forms" or abbreviations. These alternate spellings help shorten VCMUtility command tails with lots of options. The full lists of abbreviations can be achieved by using the command -Help abbreviations. Example abbreviations are:

Help: H or ?.
ActiveProcessItem: ActivePI or API.
SourceLabel: SrcLabel or SL.

In most cases, a syntactic item spelled with mixed-case in this document can be abbreviated to its "capitals only" short form. For example, ManualMergeFiles can be MMF, or AutoMergeProperties can be AMP, and so on.

Exit Codes

The VCM utility will return the following exit codes to indicate the results of its execution:

0	No errors occurred.
1	A fatal error occurred.
2	Partial success. This result is returned when the compare phase was performed, but the commit could not be performed due to unresolvable conflicts.

VCMUtility Log Files

During its execution, the VCMUtility writes informational, warning, and error messages to the console window (standard out). For most operations, the VCMUtility also creates a log file that summarizes its operation. As with console window output, the log file is more detailed when the Verbose option is enabled. The log file is created for new VCM sessions and for the Import, Open, Replay, and Resume commands. However, the log file is not started unless command-line parameters and the options file, if used, have been parsed without errors. A log file is not created for the Help or Delete commands.

The VCMUtility log file is created in the user’s home directory (what Java identifies as user.home) with the following file name:

VCMUtility-YYYY-MM-DD_hh-mm-ss.log

YYYY-MM-DD and hh-mm-ss are the current date and time in the local time zone. The full path name of the log file is written to the console window when the log file is started.

VCMUtility Support for Change Packages

The VCMUtility supports change packages for any StarTeam configuration that has been upgraded to the 2009 release. Because change packages are persistent objects stored on the StarTeam Server, they offer many advantages and over VCM session (.vcms) and VCM export (.vcmx) files. Therefore, for StarTeam configurations that have been upgraded, change packages are preferred over session and export files for saving and resuming sessions. Correspondingly, the Save option without a parameter and the Open command are preferred over the Save option with a parameter, the Resume command, the Export command, and the Import command. However, for backward compatibility, the 2009 VCMUtility still supports commands that use VCM session files. See the Open command and the Save option for more information.