VCMUtility Commands

This topic defines VCMUtility functionality in terms of its utility execution commands. Each VCMUtility execution performs one command.

In this topic:

VCMUtility Command

VCMUtility [<options file>] [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>, start option names in column 1 and exclude the leading "-"

Back to top

VCMUtility Command Types

This section contains the VCMUtility command types. The default command type is a new VCM session.

Back to top

New Session Command

By default, each VCMUtility execution begins a new VCM session unless the Help, Open, Replay, Resume, Delete, or Import command is explicitly given.

Back to top

Help Command

?

Help [<option>]

Displays the VCMUtility Help. If you provide an <option>, help specific to that topic is displayed. For example, Help MMF would provide help on the ManualMergeFiles option.

Back to top

Delete Command

Delete <VCM session file>

Specifies that the session stored in the specific <VCM session file> is to be deleted. All intermediate files (for example, merged result files) and the session file itself are deleted. However, if the session was previously saved as an uncommitted change package in the target view, the change package object is not deleted.

Back to top

Import Command

Import <VCM exchange file>

The Import command is identical to the Resume command except that the <VCM exchange file> passed to it must be a VCM exchange file (.vcmx) previously created by an Export command. The imported VCM session is resumed where it left off:

• The compare phase is performed if it has not yet successfully completed.
• Manual merging is performed if ManualMergeFiles is specified and existing file merge conflicts exist.
• The target view "merge preview" is checked out if CheckoutPreview is specified and commit has not yet been performed.
• The differences report is generated if ReportDiffs is specified and commit has not yet been performed.
• The commit phase is performed if CommitMerge is True and commit has not yet been performed.
• The update report is generated if ReportUpdates is specified and commit has been performed.

Export and Import can be used together to "transport" a VCM session from one workstation to another. For example, one user could create a new VCM session, resolve all conflicts, then Export the session. The resulting archive file could then be transferred to a test machine, where the Import command can be used with the CheckoutPreview option (with CommitMerge set to False) to check out, build, and test the target merge "preview". If tests succeed, the test machine could then execute a Resume command and set CommitMerge to True.

Back to top

Open Command

Open <Change Package name>

Resumes a VCM session previously saved as a change package with the given name. This option is only available on servers that support change packages. The specified name must be the default or user-specified name of a saved, uncommitted change package belonging to the specified Project and TargetView, which are required. Also, the session must not be locked by another user, which typically indicates that it has already been opened by that user.

For additional information, see the Name, Save, Import, and Resume commands.

Back to top

Replay Command

Replay <Change Package name>

Creates a new VCM session by "replaying" a previously-committed change package to a new target view. This command is only available when the server supports change packages. The named Change Package must belong to the project specified by the Project option and the view identified by the SourceView option. (Since committed change packages "belong" to the target view they update, the target view of the change package to be replayed is always the source view for the new session.)

When the Replay command is used, the TargetView should be specified, allowing the MergeType of the new session to be chosen automatically based on the relationship between the two views:

• If the target view is a child of the source view, a Rebase session is performed.
• If the target view is the parent of the source view, a Promote session is performed.
• Otherwise, a Replicate session is performed.

Alternatively, you can specify a MergeType of Promote, in which case the target view is not needed.

A replay VCM session attempts to make the same changes in the new target view that were made in the specified change package. This means that the source scope of the new VCM session is automatically chosen. Consequently, the Include and Exclude options are not allowed. In a replay session, some changes made in the original change package might not be possible in the new target view (such as when a new version is already present). Some changes may need to be applied in a different way (for example, Move-and-Merge instead of Merge), and new conflicts could appear (such as Merge instead of Repin). The replay session can be committed only if no unresolved conflicts occur.

Back to top

Resume Command

Resume <VCM session file>

Specifies that the session saved in the given <VCM session file> is to be resumed instead of creating a new session. This is typically used to perform the commit phase of a previous session for which only the compare phase was performed. A session that has already been committed can also be resumed, but only to generate a difference report. For more information, see the Export option and the Import command.