chepoch

Changes epoch numbers

APPLICABILITY

SYNOPSIS

chepoch [ -c·omment comment | -cfi·le comment-file-pname | -cq·uery

| -cqe·ach | -nc·omment ]
{ [ -f·orce ] replica-selector [ replica-selector=value ... ] [ oid=value ... ]
| -actual [ -raise_only ] sibling-replica-selector ... }

DESCRIPTION

This command changes, in one replica, one or more of the epoch numbers that represent the replica's record of the states of other replicas. You cannot change a replica's own row because these epoch numbers record the actual state of the replica.

With -actual, chepoch contacts sibling replicas, retrieves their own epoch rows, and changes their rows in the current replica's epoch number matrix. This brings the current replica's epoch number matrix up to date with changes made at the sibling replicas. chepoch -actual works only between sites that have IP connections. If chepoch cannot contact a sibling replica, it prints an error and tries to contact the next replica you specified.

chepoch -actual detects whether the sibling replica or the current replica is missing oplog entries. If oplog entries are missing, the command prints one of the following messages:

Your replica ("replica-name") has fewer oplog entries for itself than "replica-selector" has for your replica.
To avoid permanent data loss, your VOB administrator must initiate the documented replica restoration procedure.

The replica "replica-name" has more oplog entries for "replica-selector" than "replica-selector" has for itself.
To avoid permanent data loss, its administrator must initiate the documented replica restoration procedure.

For more information about epoch numbers, see VOB Operations and the Oplog. For descriptions of scenarios using chepoch, see Cannot Find Oplog and Lost Update Packet.

RESTRICTIONS

Identities: You must have one of the following identities:

• VOB owner

• root (UNIX)

• Member of the ClearCase administrators group (Windows)

Locks: An error occurs if one or more of these objects are locked: VOB.

Mastership: No mastership restrictions.

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 the specified comment option.

SUPPRESSING INTERACTIVE PROMPTS. Default: Unless you specify -actual, you must confirm each epoch number change.

-f·orce

Suppresses confirmation steps.

SPECIFYING THE ROW TO BE CHANGED. Default: None. You must specify a replica.

replica-selector

Specifies the replica whose epoch row is to be changed; that is, changes the current replica's estimate of the state of replica-selector. Specify 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)

SPECIFYING THE CHANGES. Default: chepoch reads a set of replica-selector=value or oid=value pairs, one per line, from standard input. You can copy and paste lsepoch output, or type the data in the format described below. Extra white space is allowed. To terminate input, type a period character ( . ) and a carriage return (<CR>) at the beginning of a line.

replica-selector=value

oid=value

One or more arguments, where

replica-selector	Column of the epoch number matrix. This argument, along with the preceding replica-selector argument, specifies a particular location in the matrix.
oid	Object identifier for the replica. lsepoch prints OIDs in its output.
value	New epoch number to be entered at the specified matrix location.

SETTING A ROW USING THE REPLICA'S ACTUAL STATE. Default: None. You must specify a replica.

-actual [ -raise_only ] sibling-replica-selector ...

Contacts sibling-replica-selector, retrieves its actual state, and changes its row in the epoch number matrix of the current replica. Specify sibling-replica-selector in the form [replica:]replica-name[@vob-selector] (see the description of replica-selector).

With -raise_only, chepoch raises epoch numbers for the sibling replica but does not lower any of them. This option optimizes synchronization when packets have been sent from the current replica to the sibling replica but have not yet been imported.

For example, replica sanfran_hub has received but not imported a packet from replica boston_hub. At replica boston_hub, the administrator uses chepoch -actual to reset the epoch row for sanfran_hub and then sends another update packet to sanfran_hub. This packet contains all the operations in the packet waiting to be imported at sanfran_hub, plus any new operations. If the administrator uses chepoch -actual -raise_only instead, the new packet includes only the new operations.

EXAMPLES

• Change two columns in the current replica's row for the bangalore replica.

multitool chepoch bangalore boston_hub=950 sanfran_hub=2000
Change oplog ID in row "bangalore", column "boston_hub" to 950 [no] yes
Change oplog ID in row "bangalore", column "sanfran_hub" to 2000 [no] yes
Epoch row successfully set.

• Make the same change as in the preceding example, but bypass the confirmation steps.

multitool chepoch -force bangalore boston_hub=950 sanfran_hub=2000
Epoch row successfully set.

• Make the same change as in the preceding examples, specifying the changes as terminal input instead of as command-line arguments.

multitool chepoch bangalore
Enter specifications for epochs to change in row "bangalore"
(one per line)
oid:87f6265f.72d911d4.a5cd.00:01:80:c0:4b:e7=950
oid:0eaa6fc3.737d11d4.adbe.00:01:80:c0:4b:e7=2000
.
Change oplog ID in row "bangalore", column "boston_hub" to 950 [no] yes
Change oplog ID in row "bangalore", column "sanfran_hub" to 2000 [no] yes
Epoch row successfully set.

• Change an item in a replica's estimate of the state of the sydney replica, specifying the VOB family of the replica whose matrix is to be changed.

multitool chepoch -force sydney@\vob3 buenosaires=800
Epoch row successfully set.

• Set the current replica's estimate of the state of the tokyo replica to its actual state.

multitool chepoch -actual tokyo@/vobs/tromba
Entry for boston_hub changed from: 1400 to 1300
Entry for sanfran_hub changed from: 985 to 950
Entry for tokyo changed from: 2562 to 2000

• Update the current replica's epoch numbers for replicas boston_hub and sanfran_hub.

multitool chepoch -actual boston_hub@/vobs/dev sanfran_hub@/vobs/dev
Entry for boston_hub changed from: 1400 to 1300
Entry for sanfran_hub changed from: 985 to 1000

• Make the same change as in the previous example, but do not lower any of the numbers.

multitool chepoch -actual -raise_only boston_hub@/vobs/dev sanfran_hub@/vobs/dev
Entry for boston_hub unchanged from: 1400
Entry for sanfran_hub changed from: 985 to 1000

SEE ALSO

lsepoch, recoverpacket, restorereplica