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.
The syntax for the command-line uses the following conventions.
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 -.
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
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).
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.
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:
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
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:
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.
The VCM utility will return the following exit codes to indicate the results of its execution:
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.
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.