chepoch

Changes epoch number estimates

Applicability

Product Command type
MultiSite multitool subcommand
Platform
UNIX®
Linux
Windows®

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 a replica's epoch number estimates for other replicas. You cannot change a replica's own epoch numbers because they 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 the Help. For descriptions of scenarios using chepoch, see the Help.

Restrictions

Identities: You must have one of the following identities:
  • VOB owner
  • root (Linux® and the UNIX® system)
  • Member of the VersionVault 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 VersionVault 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. If you do not specify a vob-selector, the command uses the current VOB.
replica-selector
Specifies the replica whose estimated epoch numbers are 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 IDs in row "bangalore" [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 IDs in row "bangalore" [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