Exports or imports update packets
sync·replica –exp·ort [ –max·size max-packet-size [ –lim·it num-packets ] ]
[ –c·omment comment | –cfi·le comment-file-pname | –cq·uery | –cqe·ach | –nc·omment ]
{
{ –shi·p | –fsh·ip } [ –scl·ass storage-class ] [ –pex·pire date ] [ –not·ify e-mail-addr ]
| –tap·e raw-device-pname
| –out packet-file-pname
}
replica-selector ...
sync·replica –imp·ort [ –invob VOB-selector ]
[ –c·omment comment | –cfi·le comment-file-pname | –cq·uery | –cqe·ach | –nc·omment ]
{ –rec·eive [ –scl·ass storage-class ]
| –tap·e raw-device-pname
| { packet-file-pname | staging-area-pname } ...
}
Note: The –tape option is valid only on UNIX.
Synchronization of an existing replica with one or more sibling replicas is a three-phase process:
Step 3 occurs at all sites that receive the packet.
Contents of an update packet:
In all cases, syncreplica –export creates a single logical update packet for use at all the specified destinations; the packet can be used to update those particular replicas only.
MultiSite is designed for efficient updating of replicas. syncreplica –export attempts to exclude operations that have been sent previously. (However, there is no harm in sending an operation multiple times to the same replica; the first operation is imported and subsequent identical operations are ignored.)
The replica is not locked during the export phase; in fact, the syncreplica –export command fails if the VOB is locked. Therefore, you must not schedule synchronizations during VOB backups (when the VOB must be locked). See also Retrying Synchronization When the VOB Is Locked.
syncreplica –export stores temporary files in the directory specified by the TMPDIR environment variable on UNIX and the TMP environment variable on Windows. If you use the sync_export_list script to export update packets, you can use the –workdir option to specify the directory.
An update packet is applied to the appropriate replica on the host on which you import it, unless you restrict processing with the –invob argument. syncreplica consults the VOB registry in the current region to determine the locations of these replicas’ storage directories. Thus, you do not have to specify particular replicas or storage locations.
The import process applies update packets in the correct order. Therefore, you can specify packets in any order on the command line.
The VOB replica is not locked during the import phase. Synchronization fails if the VOB is locked. See also Retrying Synchronization When the VOB Is Locked.
syncreplica –import stores temporary files in the directory specified by the TMPDIR environment variable on UNIX and the TMP environment variable on Windows. If you use the sync_receive script to import update packets, you can use the –workdir option to specify the directory.
syncreplica –import refuses to process an update packet in the following situations:
In these cases, syncreplica –import displays an explanatory message.
In some cases, syncreplica –import begins to apply operations to a replica, but fails with an error message. For example, another process may have locked the VOB, causing the import to fail. After the VOB is unlocked, you can run syncreplica –import to process the entire update packet again.
There is no harm in importing update packets that have already been processed successfully; the same change will not be made twice.
For more information about update failures, see Troubleshooting MultiSite Operations.
If a single invocation of syncreplica –import applies a packet successfully to all target replicas on the host, the update packet is deleted when the command completes its work. If the packet is processed with multiple syncreplica –import –invob commands, it is not deleted.
If a VOB replica preserves identities and permissions, syncreplica –import maintains the consistency of identities and permissions information for elements mastered by the VOB family’s identities- and permissions-preserving replicas. For each such element, an error occurs if the element’s group is not on the group list of the importing replica (on UNIX) or is not the same as the group of the importing replica (on Windows).
If a VOB replica preserves permissions only, syncreplica –import maintains the consistency of permissions information for elements mastered by the VOB family’s identities- and permissions-preserving replicas and permissions-preserving replicas. Changes to identities for existing elements are ignored during import. New elements are assigned to the owner of the VOB at the current site, and the group of all new elements is the primary group of the VOB. (This is true even if the root user or a member of the ClearCase administrators group imports the packet.)
If a VOB replica is nonpreserving, changes to identities and permissions of existing elements are ignored during import. New elements are assigned to the owner of the VOB at the current site, and the group of all new elements is the primary group of the VOB. (This is true even if the root user or a member of the ClearCase administrators group imports the packet.) Permissions set when the element is created are preserved, but subsequent permissions changes are ignored. Identities and permissions changes made at nonpreserving replicas are not propagated to other replicas.
Data containers from the update packets are placed in storage pools according to the standard element assignments. If the pool assignment for a new element cannot be determined, the element is assigned to the VOB’s default source pool.
ClearCase triggers do not fire in response to changes made during packet import.
syncreplica resolves naming conflicts among objects created at different replicas. For more information, see Conflict Resolution.
syncreplica does not inform any views (not even the view from which you enter the command) of the updates to replicas. All active views see updates within a few seconds, through their normal VOB-polling routines. You can force a view to recognize VOB updates by entering a cleartool setcs –current command.
By default, synchronization exports and imports fail if the VOB is locked. To allow syncreplica to retry a synchronization when it encounters a lock, set the CLEARCASE_VOBLOCKWAIT environment variable to the amount of time (in minutes) for syncreplica to keep trying to write to the VOB. During that time, syncreplica retries the write operation every minute. If the time elapses and the VOB is still locked, syncreplica exits with an error.
Note: syncreplica waits only if it detects the lock before it starts processing operations. If an administrator locks the VOB during processing, syncreplica exits with an error.
Identities: You must have one of the following identities:
Locks: An error occurs if one or more of these objects are locked: VOB.
Mastership: No mastership restrictions.
Other: You must run syncreplica on the host where the VOB storage directory resides.
Default
If you do not specify –maxsize, the default packet size depends on the shipping option:
–max·size max-packet-size [ –lim·it num-packets ]
The maximum size for a physical packet, expressed as a number followed by a single letter. For example:
The –limit option limits the number of packets syncreplica generates; each packet is no larger than max-packet-size. Use this option when the disk space for your shipping bay or staging area is limited.
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.
Default
None. You must specify how the update packets created by syncreplica –export are to be stored and/or transmitted to other sites.
If you use –ship or –fship and omit the –sclass option, syncreplica places the packet in the storage bay location specified for the –default class in the shipping.conf file or MultiSite Control Panel. By default, this location is /var/adm/rational/clearcase/shipping/ms_ship on UNIX and ccase-home-dir\var\shipping\ms_ship on Windows.
–shi·p
–fsh·ip
Stores the update packet in one or more files in a store-and-forward storage bay; syncreplica creates a separate shipping order for each physical packet, indicating how and where it is to be delivered. The destinations are the host names associated in the VOB database with the replica-name arguments. (Replica-name/host-name associations are created with mkreplica –export and can be changed with chreplica.)
Using –fship (force ship) invokes the shipping server to send the update packet immediately. Using –ship does not invoke this server. To run shipping_server to send packets in storage bays, schedule sync_export_list –poll with the schedule command. (See the schedule reference page in the Command Reference.)
–scl·ass class-name
Specifies the storage class of the packet and shipping order. syncreplica looks up the storage class in the shipping.conf file on UNIX or the MultiSite Control Panel on Windows to determine the location of the storage bay to use.
–tap·e raw-device-pname (UNIX)
Writes the update packets to the specified tape device, which must be local to the host on which you enter the syncreplica command. You are prompted to load a separate tape for each physical packet. Use the –maxsize option to ensure that syncreplica does not exceed the capacity of the tapes you are using. Only one physical packet can be placed on each tape, regardless of packet size.
Caution: Be sure to deliver a packet created with –out or –tape to its specified destinations promptly. If a replica has not yet received and applied this packet, it may not accept any subsequently generated packets from your replica until the first packet is received and processed.
–out packet-file-pname
The name of the first update packet. Additional physical packets, if any, are placed in files named packet-file-pname_2, packet-file-pname_3, and so on.
The update packets are not delivered automatically; use an appropriate method to deliver them.
You can create a packet using –out, and deliver it using the store-and-forward facility. See the mkorder reference page.
Default
If a packet cannot be delivered, it is sent through the store-and-forward facility back to the administrator at the site of the originating replica. A mail message is sent to the store-and-forward administrator. This occurs after repeated attempts to deliver the packet have failed, and the allotted time has expired; it can also occur when the destination host is unknown or a data file does not exist. The store-and-forward configuration settings specify the expiration period, the e-mail address of the administrator, and the notification program.
–pex·pire date-time
Specifies the time at which the store-and-forward facility stops attempting to deliver the packet and generates a failure mail message instead. This option overrides the expiration period specified for the storage class in the shipping.conf file (UNIX) or MultiSite Control Panel (Windows).
The date-time argument can have any of the following formats:
date.time | date | time | now
where:
Specify the time in 24-hour format, relative to the local time zone. If you omit the time, the default value is 00:00:00. If you omit the date, the default value is today. If you omit the century, year, or a specific date, the most recent one is used. Specify UTC if you want the time to be resolved to the same moment in time regardless of time zone. Use the plus (+) or minus (-) operator to specify a positive or negative offset to the UTC time. If you specify UTC without hour or minute offsets, the default setting is Greenwich Mean Time (GMT). (Dates before January 1, 1970 Universal Coordinated Time (UTC) are invalid.)
Examples:
22-November-2002
sunday
yesterday.16:00
8-jun
13:00
today
9-Aug.10:00UTC
–not·ify e-mail-address
The delivery-failure message is sent to the specified e-mail address.
If a failure occurs on a Windows host that does not have e-mail notification enabled, a message appears in the Windows Event Viewer. The message includes the e-mail-address value specified with this option and a note requesting that this user be informed of the status of the operation. For information about enabling e-mail notification, see the MultiSite Control Panel reference page.
Default
None.
replica-selector ...
Specifies the replicas to which you want to send update packets. These replicas must be in the same VOB family. Specify replica-selector in the form [replica:]target-replica-name[@source-vob-selector]
Default
Updates all replicas that are on the current host and are specified in the update packets. With –tape, you must specify a VOB replica to be updated.
–invob vob-selector
Updates the replica in the VOB family specified by vob-selector; all other replicas specified in the update packets are ignored. 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)
|
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.
Default
None.
–rec·eive [ –scl·ass storage-class ]
Scans the current host’s storage bays. Any unprocessed update packets intended for this host are applied to the appropriate replicas on the host. With –sclass, syncreplica scans only the storage bays of the specified storage class.
If syncreplica finds any replica-creation packets, it sends mail to the store-and-forward administrator. (If the current host is a Windows host and there is no valid host specified in the SMTP Host box in the ClearCase Control Panel, a message appears in the Windows Event Viewer.) Use mkreplica to import these replica-creation packets.
–tap·e raw-device-pname (UNIX)
Reads a single packet from the tape device, and applies it to the replica of the VOB specified with –invob. The tape device must be local to the importing host.
packet-file-pname | staging-area-pname ...
Processes each packet-file-pname as an update packet. For each staging-area-pname specified, locates all previously unprocessed update packets in the directory and applies them to the appropriate replicas.
multitool syncreplica –export –out c:\tmp\boston_hub_packet1 boston_hub@\dev Generating synchronization packet c:\tmp\boston_hub_packet1
multitool syncreplica –export –ship boston_hub@\dev Generating synchronization packet c:\Program Files\Rational\ClearCase\var \shipping\ms_ship\outgoing\sync_bangalore_19-May-02.09.33.02_3447_1 - shipping order file is c:\Program Files\Rational\ClearCase\var\shipping\ms_ship\outgoing\sh_o_sync_ba ngalore_19-May-02.09.33.02_3447_1
multitool syncreplica –export –fship boston_hub@\dev Generating synchronization packet c:\Program Files\Rational\ClearCase\var \shipping\ms_ship\outgoing\sync_bangalore_19-May-02.09.33.02_3447_1 - shipping order file is c:\Program Files\Rational\ClearCase\var\shipping\ms_ship\outgoing\sh_o_sync_ba ngalore_19-May-02.09.33.02_3447_1 Attempting to forward/deliver generated packets... -- Forwarded/delivered packet c:\Program Files\Rational\ClearCase\var \shipping\ms_ship\sync_bangalore_19-May-02.09.33.02_3447_1
multitool syncreplica –import /usr/tmp/boston_hub_packet1 Applied sync. packet /usr/tmp/boston_hub_packet1 to VOB /net/minuteman/vobstg/dev.vbs
multitool syncreplica –import –receive Applied sync. packet c:\Program Files\Rational\ClearCase\var \shipping\ms_ship\incoming\sync_boston_hub_19-May-02.09.45.01_7634_ 1 to VOB \\ramohalli\vobs\dev.vbs
mkorder, mkreplica, MultiSite Control Panel, shipping.conf, sync_export_list
Troubleshooting MultiSite Operations