ClearCase Reference Manual, Release 4.0, Windows

chmaster

Transfer mastership of VOB-database object

APPLICABILITY

ClearCase (cleartool subcommand), MultiSite (multitool subcommand)

SYNOPSIS

chmaster [ -c·omment comment | -cfi·le comment-file-pname | -cq·uery: | -cqe·ach | -nc·omment ]
{ master-replica-selector object-selector ...
| master-replica-selector [ -pname ] branch-or-element-pname ...
| -def·ault [ -pname ] branch-pname ...
| -def·ault brtype-selector ...
| -all [ -force old-replica-selector ] [ -l·ong ] master-replica-selector}

DESCRIPTION

NOTE: This command requires a view context.

Transfers the mastership of one or more objects from one VOB replica to another. Only the current replica is affected immediately; other replicas are notified of the mastership transfers through the normal exchange of update packets.

Mastership restricts some of the operations you can perform on an object. Enabling Independent VOB Development: Mastership in the chapter Introduction to MultiSite in the ClearCase MultiSite Manual describes mastership restrictions.

To limit use of this command to a certain set of users, you can create triggers. For more information, see Implementing Project Development Policies in Managing Software Projects with ClearCase.

RESTRICTIONS

Mastership Checking: An object's mastership can be changed only at its current mastering replica. Using both -all and -force overrides this restriction, but you must not use the -force option except in special circumstances. (See the description of the -all option.)

Permissions Checking: Restrictions depend on the kind of object:

element	Must be element creator, element owner, VOB owner, root user (UNIX), or member of the ClearCase group (Windows)
replica	Must be VOB owner, root user (UNIX), or member of the ClearCase group (Windows)
others	Must be object creator, object owner, VOB owner, root user (UNIX), or member of the ClearCase group (Windows)

See the permissions reference page in the ClearCase Reference Manual.

Locks: Restrictions depend on the kind of object:


For this object:	An error occurs if any of the following objects are locked:
Element	Element, element type
Branch	Branch, branch type
Type object	Type object
Hyperlink	Hyperlink type
Baseline	Baseline, VOB, replica, components associated with the baseline
Component	Component, VOB, replica

Other Restrictions: You cannot transfer mastership of a branch if the branch is checked out reserved or if it is checked out unreserved without the -nmaster option.

OPTIONS AND ARGUMENTS

EVENT RECORDS AND COMMENTS. Default: Creates one or more event records, with commenting controlled by the standard ClearCase user profile (default: -nc). See EVENT RECORDS AND COMMENTS in the multitool reference page. To edit a comment, use cleartool chevent.

-c·omment comment | -cfi·le comment-file-pname | -cq·uery | -cqe·ach | -nc·omment: Overrides the default with one of MultiSite's standard comment options.

SPECIFYING THE OBJECTS. Default: None.

master-replica-selector object-selector ...: Transfers mastership of objects specified with object-selector to the VOB replica specified with master-replica-selector. Specify master-replica-selector in the form [replica:]replica-name[@vob-selector]

replica-name

Name of the replica (displayed with lsreplica)

vob-selector

VOB family of the replica; can be omitted if the current working directory is within the VOB.

Specify vob-selector in the form [vob:]pname-in-vob

pname-in-vob

Pathname of the VOB-tag (whether or not the VOB is mounted) or of any file-system object within the VOB (if the VOB is mounted)

: Specify object-selector in one of the following forms:

`vob-selector`	vob:`pname-in-vob` where `pname-in-vob`	Pathname of the VOB-tag (whether or not the VOB is mounted) or of any file-system object within the VOB (if the VOB is mounted)
`attribute-type-selector`	[attype:]`type-name`[@`vob-selector`]
`branch-type-selector`	[brtype:]`type-name`[@`vob-selector`]
`element-type-selector`	[eltype:]`type-name`[@`vob-selector`]
`hyperlink-type-selector`	[hltype:]`type-name`[@`vob-selector`]
`label-type-selector`	[lbtype:]`type-name`[@`vob-selector`]
`hlink-selector`	[hlink:]`hlink-id`[@`vob-selector`]
`oid-obj-selector`	oid:`object-oid`[@`vob-selector`]
`replica-selector`	[replica:]`replica-name`[@`vob-selector`]
`baseline-selector`	[baseline:]`baseline-name`[@`vob-selector`]
`component-selector`	[component:]`component-name`[@`vob-selector`]

master-replica-selector [ -pname ] branch-or-element-pname ...: Transfers mastership of the specified branches or elements to the VOB replica specified with master-replica-selector. A branch pathname takes the form element-name@@/branch...; for example, foo.c@@/main/bugfix, and an element pathname takes the form element-name@@; for example, foo.c@@. If branch-or-element-pname has the form of an object selector, you must include the -pname option to indicate that pname is a pathname.

-a·ll [ -f·orce old-replica-selector ] [ -l·ong ] master-replica-selector: CAUTION: Incorrect use of the -force form of the command can lead to irreparable divergence among the replicas in a VOB family.

: Transfers to master-replica-selector mastership of all objects that are located in and mastered by the local replica. (MultiSite determines the local replica by using the vob-selector you specify as part of master-replica-selector. If you do not include a vob-selector, MultiSite uses the replica containing the current working directory.)

: If errors occur, the command continues. After finishing, it reports that not all mastership changes succeeded.

: With -long, chmaster lists the objects whose mastership is changing.

With -force, chmaster transfers mastership of all objects in the replica specified with old-replica-selector. Also, chmaster associates nonmastered checkouts with the new replica. Use this form of chmaster only when replica old-replica-selector is no longer available (for example, was deleted accidentally). Before entering this command, you must make sure that old-replica-selector masters itself or is mastered by the replica that it last updated. Then, enter the chmaster command at the last-updated replica. You must also send update packets from the last-update replica to all other remaining replicas in the VOB family. For more information, see the rmreplica reference page.

RETURNING MASTERSHIP OF BRANCHES TO DEFAULT STATE. Default: None.

-def·ault [ -pname ] branch-pname ...: Transfers mastership of branch-pname to the replica that masters the branch type. If branch-pname has the form of an object selector, you must include the -pname option to indicate that branch-pname is a pathname.

-def·ault brtype-selector ...: Removes explicit mastership of branches that are mastered explicitly by the local replica and are instances of the type brtype.

: NOTE: You can use this command only at the replica that masters the branch type.

EXAMPLES

At replica paris, transfer mastership of label type VERSION1.0 to the osaka replica.

multitool chmaster osaka lbtype:VERSION1.0 Changed mastership of "VERSION1.0" to "osaka"

At replica paris, transfer mastership of element list.c to the evanston replica.

multitool chmaster evanston list.c@@ Changed mastership of "list.c" to "evanston"

At the replica that is the master of replica osaka, make osaka self-mastering.

multitool chmaster osaka replica:osaka Changed mastership of "osaka" to "osaka"

At replica paris, transfer the mastership of branch bar.c@@\main\v3_dev to osaka.

multitool chmaster osaka bar.c@@\main\v3_dev Changed mastership of branch "\tromba\bar.c@@\main\v3_dev" to "osaka"

For all objects mastered by the local replica, transfer mastership to paris.

multitool chmaster -all paris Changed mastership of all objects

Same as the preceding example, but have chmaster list each object whose mastership is changing.

multitool chmaster -all -long paris Changed mastership of label type VERSION1.0 Changed mastership of replica osaka Changed mastership of all objects

Return mastership of a branch to the replica that masters the branch type, and then remove its explicit mastership.
At the replica that masters the branch:

multitool describe -fmt "%[master]p\n" brtype:v3_bugfix boston@\dev

multitool chmaster boston@\dev \dev\acc.c@@\main\v3_bugfix Changed mastership of branch "\dev\acc.c@@\main\v3_bugfix" to "boston@\dev"

multitool syncreplica -export -fship boston@\dev ...

At the replica that masters the branch type:

multitool syncreplica -import -receive ...

multitool chmaster -default brtype:v3_bugfix Changed mastership of branch type "v3_bugfix" to "default"