IBM Support

How to set up ClearCase Synchronous Request for Mastership

Question & Answer


How do you setup and use IBM Rational ClearCase synchronous request for mastership (SRFM)?


Prior to version 8.0, this information was not in the information center.


The information in this technote has been incorporated into the 8.0 version of the IBM Rational ClearCase Information Center.

Table of contents:

Synchronous request for mastership

Synchronous request for mastership (SRFM) allows a user to immediately checkout a file or directory version even if the branch is initially mastered at another ClearCase MultiSite replica in the VOB family, provided it is safe to do so. When invoked on a remotely mastered branch, the feature silently sends a request for mastership to the remote master. If any blocking conditions are encountered (check the "Restrictions" section on the reqmaster command reference) the SRFM request is denied, and the requesting user’s SRFM checkout fails. However, if no blocking conditions are encountered, the remote master transfers mastership as it would for any reqmaster request. In this case, the requesting user’s SRFM checkout succeeds, and the user can modify the file or directory. The SRFM checkout is said to be in a pending reserved state. No one else may perform a reserved checkout on that branch. However the user may not check in the file or directory until mastership arrives (by the normal MultiSite syncreplica process).

How to install and configure synchronous request for mastership
Before the users can start using SRFM, the ClearCase VOBs should be set up by the ClearCase administrators. Install the ClearCase patch release on every server machine that hosts VOBs that are to be available for SRFM, and on every client machine where users are to invoke SRFM.

The ClearCase administrator must raise the family feature level of every replicated VOB family where users will be allowed to use SRFM to Feature Level 6. To do this, the administrator must first raise the replica feature level of each replica in the VOB family to replica feature level 6, and then raise the family feature level to 6 at the sibling replica that masters the VOB object. Finally, the administrator must use syncreplica to send these changes to all members of the VOB family. See Raising the VOB family feature level and the cleartool chflevel man page for details.

Next, the ClearCase administrator must enable SRFM in a replica to make the functionality available to users at that site. SRFM is enabled on a per-VOB basis, and it must be enabled at every replica where the operation is to be supported. Use the cleartool protectvob command to enable or disable SRFM:

% cleartool protectvob [-srfm | -nsrfm] <vobtag>

In addition, the ClearCase administrator must configure and enable reqmaster in every VOB where the mastership of files or directories will be requested by SRFM.

Here is an example to enable/disable SRFM:

cleartool protectvob -srfm /var/tmp/repA

VOB "/var/tmp/repA" set to enable synchronous request for mastership.

cleartool protectvob -nsrfm /var/tmp/repA
VOB "/var/tmp/repA" set to disable synchronous request for mastership

How to use SRFM

In addition to protectvob, SRFM includes enhancements to the following commands:

Enhancements to checkout

% cleartool checkout –srfm <filename or directory name>

If SRFM has been enabled in the local replica, this form of checkout invokes a silent request for mastership of the branch if it is remotely mastered. If the request for mastership succeeds, the file or directory will have a pending reserved checkout, and the user can immediately begin to modify it. However, it is not possible to check in the file or directory until syncreplica imports mastership into the local replica.

For example, use cleartool checkout -srfm command to checkout a file:

cleartool checkout -nc -srfm f1.c

A syncreplica import will be required, to apply the change in mastership of the branch, before checkin can succeed

Checked out "f1.c" from version "/main/4".

cleartool checkin -nc f1.c

cleartool: Error: Unable to perform operation "checkin" in replica "original" of VOB "/var/tmp/repA".

cleartool: Error: Master replica of branch "/main" is "repB".

cleartool: Error: Unable to check in "f1.c".

Note that specifying -srfm -version will allow you to check out a version on a remotely mastered branch that is not selected by your view (for instance checking out a non-LATEST version on a branch while in a default view).

For example, use cleartool checkout -srfm command to checkout from a specific version:

cleartool checkout -nc -srfm -version f3.c@@/main/1  

A syncreplica import will be required, to apply the change in mastership of the branch, before checkin can succeed

cleartool: Warning: Version checked out ("/main/1") is different from version selected by view before checkout ("/main/4").

Checked out "f3.c" from version "/main/1".

Enhancements to descriptive commands

% cleartool lscheckout

% cleartool lshistory filename@@/branch

% cleartool lscheckout -arep -fmt "%n %On %Rf\n"  filename

% cleartool describe –fmt “%Rf\n” filename@@/branch/CHECKEDOUT

These commands report that a checkout is pending reserved, which means it was created using SRFM and cannot be checked in until mastership arrives.

cleartool lscheckout f1.c

--03-22T14:12  joe        checkout version "f1.c" from /main/4 (pending reserved)

cleartool lshistory f1.c@@/main
--03-22T14:12  joe        checkout version "f1.c" from /main/4 (pending reserved)
--03-22T14:08  joe        create version "f1.c@@/main/4"
--03-22T14:04  joe        create version "f1.c@@/main/3"
--03-22T14:02  joe        create version "f1.c@@/main/2"
--03-22T13:58  joe        create version "f1.c@@/main/1"
--03-22T13:54  joe        create version "f1.c@@/main/0"
--03-22T13:54  joe        create branch "f1.c@@/main"
--03-22T13:54  joe        create file element "f1.c@@"

cleartool lscheckout -arep -fmt "%n %On %Rf\n" f1.c

f1.c fbe93f9e.54b011e0.80ee.00:01:83:0b:8a:01 pending reserved

cleartool describe -fmt "%Rf\n" f1.c@@/main/CHECKEDOUT

pending reserved

Enhancements to uncheckout

% cleartool uncheckout <filename or directory name>

If a user creates a pending reserved checkout on a branch and then cancels the checkout, another user at the same site may issue a second checkout –srfm on the branch and begin modifying it, even if mastership has not yet arrived. Note that the second user must use the -srfm option; otherwise the checkout fails with a message that mastership is in transit to the local replica.

cleartool checkout -nc f2.c

cleartool: Error: Mastership is in transit to this replica. You may use -srfm option to do a pending reserved checkout. You may also use the -unreserved -nmaster option to do an unreserved, nonmastered checkout, but that may require merging before you can checkin.

cleartool: Error: Unable to check out "f2.c".

cleartool checkout -nc -srfm f2.c

Checked out "f2.c" from version "/main/4".

Use the following form of uncheckout to clear the srfm flag set on the branch of the checkedout version. When a user tries to checkout with -srfm option later, multitool silently sends again a request for mastership to the remote master (otherwise no request will be sent).

% cleartool uncheckout -nsrfm <filename or directory name>

cleartool uncheckout -rm -nsrfm f2.c

Checkout cancelled for "f2.c".

Restrictions on SRFM

In some situations, SRFM cannot transfer mastership. If SRFM determines that the remote master knows that the branch has later versions than the requesting replica knows, it returns an error status that causes the checkout to fail. This is necessary because allowing a pending reserved checkout to complete in this situation would cause a syncreplica import failure for the oplogs that create the later versions. However, it will initiate a MultiSite syncreplica to the requesting replica. Once the import is complete, the user may again checkout –srfm on the branch. Note that the user must use -srfm, since mastership has not yet been transferred; but then SRFM should complete normally.

cleartool checkout -nc -srfm -version f4.c

cleartool: Error: Unable to complete the checkout. Your site has incomplete information about this branch. Contact your administrator about synchronizing your site with the current master replica. Then you can try the checkout operation again.

cleartool: Error: Unable to check out "f4.c".

A similar situation arises if the remote master cannot find the version the user has requested. This would happen if the remote master had executed a cleartool rmver that uncataloged the version. In this case, SRFM returns a not found error status and the checkout fails. This is necessary because importing the rmver oplog would render the pending reserved checkedout version unusable, since the version on which it depends would have been deleted. If SRFM has been enabled at the remote master, it initiates a MultiSite syncreplica in this situation.

cleartool checkout -nc -srfm -version f5.c

cleartool: Error: The object was not found at the remote site. The changes at the remote site have not yet been propagated to your site. Try the checkout operation later.

cleartool: Error: Unable to check out "f5.c".

Change to default reqmaster behavior

Note that the default behavior for legacy reqmaster has been modified to automatically initiate a sync if the specified object OID is not found and SRFM has been enabled for the replica.

For information about using IBM ClearCase Global Monitor with SRFM enabled VOBs, refer to technote 1473921.

[{"Product":{"code":"SSSH27","label":"Rational ClearCase"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"Mastership: Reqmaster","Platform":[{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"","Edition":"","Line of Business":{"code":"LOB36","label":"IBM Automation"}}]

Document Information

Modified date:
16 June 2018