Exports or imports update packets
sync·replica –exp·ort [ –cl·an clan-name ] [ –site site-name ] –fam·ily family-name
–u·ser username [ –p·assword ] password
[ –max·size max-packet-size [ –lim·it num-packets ] ]
[ –nblocking ] [ –compress ]
{ { –sh·ip | –fsh·ip } –wor·kdir directory
[ –sc·lass storage-class ] [ –pex·pire date ] [ –not·ify email ]
| –out { packet-file-pname | staging-area-pname } }
replica ...
sync·replica –imp·ort [ –cl·an clan-name ] [ –site site-name ] –fam·ily family-name
–u·ser username [ –p·assword ] password
[ –nblocking ]
{ –rec·eive [ –sc·lass storage-class ]
| { packet-file-pname | staging-area-pname } ... }
Synchronization of a replica with one or more sibling replicas is a three-phase process:
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.)
syncreplica –export stores temporary files in the directory you specify with the –workdir option. This directory must not already exist and is deleted after the export packet is created.
An update packet is applied to the appropriate replicas associated with the synchronization server that received the packet. 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 database replica is not locked for normal database operations during the import phase, but it is locked for all other MultiSite operations.
syncreplica –import does not 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 database, causing the import to fail. After the database 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 Recovering from Lost Packets.
If a single invocation of syncreplica –import applies a packet successfully to all target replicas associated with the synchronization server, the update packet is deleted when the command completes its work. If the packet is processed with multiple syncreplica –import commands, it is not deleted.
ClearQuest hooks 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 Resolving Naming Conflicts.
syncreplica does not inform ClearQuest users of the updates to replicas. All active users see updates within a few seconds, through ClearQuest’s normal database-polling routines.
If a packet cannot be delivered, it is sent through the store-and-forward facility to the synchronization server for the originating replica. A mail message is sent to the store-and-forward administrator. This occurs after repeated attempts to deliver the packet have all 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.
You must have Super User privileges.
Default
Clan: First clan replicated at this site. If there is more than one clan at the site, –clan is required.
Site: Current site. If there is more than one site on this host, –site is required.
Family: No default; you must specify a family.
–cl·an clan-name
Name of the replica’s clan.
–site site-name
Name of the replica’s site.
–fam·ily family-name
User database family: Database name given to the user database when it was created.
Schema repository family: The family name is MASTR.
Default
You must specify a user name and password.
–u·ser user
Name of a user with Super User privileges.
–p·assword password
Password associated with the specified user.
Default
When you do not specify –maxsize, the default packet size depends on the shipping method you use:
–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
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 cq_default class in the shipping.conf file (UNIX) or the MultiSite Control Panel (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 synchronization servers associated in the replica database with the replica-name arguments. (Synchronization server 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.
–wor·kdir directory
A temporary working directory for syncreplica to use. This directory must not already exist and is deleted after the syncreplica export process finishes.
–sc·lass 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.
–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.
staging-area-pname
The directory where packet files are stored.
Default
If a packet cannot be delivered, it is sent through the store-and-forward facility to the synchronization server for 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
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 ...
Site name of the destination replica. You can specify one or more destination replicas. For example, boston_hub indicates that boston_hub will receive the update packet, while boston_hub bangalore indicates that both boston_hub and bangalore will receive the update packet.
Default
Clan: First clan replicated at this site. If there is more than one clan at the site, –clan is required.
Site: Current site. If there is more than one site on this host, –site is required.
Family: No default; you must specify a family.
–cl·an clan-name
Name of the replica’s clan.
–site site-name
Name of the replica’s site.
–fam·ily family-name
User database family: Database name given to the user database when it was created.
Schema repository family: The family name is MASTR.
Default
You must specify a user name and password.
–u·ser user
Name of a user with Super User privileges.
–p·assword password
Password associated with the specified user.
Default
None.
–rec·eive [ –sc·lass storage-class ]
Note: This option is useful only if you run syncreplica on the synchronization server.
Scans the current host’s storage bays. Any unprocessed update packets intended for replicas associated with 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 e-mail notification is not enabled, a message appears in the Windows Event Viewer.) Use mkreplica to import these replica-creation packets.
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.
In these examples, the lines are broken for readability. You must enter each command on a single physical line.
multiutil syncreplica -export -clan telecomm -site boston_hub -family SAMPL -user susan -p passwd -out c:\cqms\sanfran_hub_sync.xml sanfran_hub Multiutil: Packet file ‘c:\cqms\sanfran_hub_sync.xml’ generated
multiutil syncreplica -export -clan telecomm -site boston_hub -family DEV -user susan -p passwd -maxsize 500mb -workdir c:\work -ship -sclass cq_default sanfran_hub Multiutil: Packet file ‘C:\work\sync_BOSTON_HUB_26-March-02_10-55-16.xml’ generated multiutil: Shipping order “C:\temp\cqms\ms_ship\outgoing\sh_o_sync_BOSTON_HUB_26-March-02_10- 55-16.xml” generated.
multiutil syncreplica -export -clan telecomm -site boston_hub -family DEV -user susan -password p -maxsize 500mb -workdir c:\work -fship -sclass cq_default sanfran_hub Multiutil: Packet file ‘C:\work\sync_BOSTON_HUB_26-March-02_10-56-43.xml’ generated multiutil: Shipping order “C:\cqms\ms_ship\outgoing\sh_o_sync_BOSTON_HUB_26-March-02_10-56-43 .xml” generated. multiutil: Attempting to forward/deliver generated packets... multiutil: -- Forwarded/delivered packet C:\cqms\ms_ship\outgoing\sync_BOSTON_HUB_26-March-02_10- ---- NOTE: consult the NT event log for errors.
multiutil syncreplica -import -clan telecomm -site sanfran_hub -family DEV -user jcole -p passwd -receive -sclass cq_storage Multiutil: 4 transactions from boston_hub have been replayed into the MASTR database Multiutil: 2 transactions from boston_hub have been replayed into the DEV database Multiutil: Deleting packet C:\temp\cqms\ms_ship\incoming\sync_boston_hub_22-January-02_11-10-3 4.xml
multiutil syncreplica -import -clan telecomm -site sanfran_hub -family DEV -user jcole -p passwd c:\cqms\sanfran_hub_sync.xm Multiutil: 1 transactions from boston_hub have been replayed into the MASTR database Multiutil: 2 transactions from boston_hub have been replayed into the DEV database Multiutil: Deleting packet c:\cqms\sanfran_hub_sync.xml
multiutil syncreplica -import -clan telecomm -site sanfran_hub -family DEV -user jcole -p passwd c:\cqms\sanfran_hub_sync.xml Multiutil: The UPDATE_PACKET packet sent from boston_hub at 2002-01-22 15:15:50 is destined for schema revision 2, not 1; re-execute syncreplica after site admin has upgraded database. Multiutil: 2 transactions from boston_hub have been replayed into the MASTR database Multiutil: Preserving packet c:\cqms\sanfran_hub_sync.xml.
multiutil syncreplica -import -clan telecomm -site boston_hub -family DEV -user susan -p passwd -receive Multiutil: 1 transactions from SANFRAN_HUB have been replayed into the MASTR database Multiutil: 2 transactions from SANFRAN_HUB have been replayed into the DEV database Multiutil: Deleting packet C:\temp\cqms\ms_ship\incoming\sync_SANFRAN_HUB_07-February-02_11-24 -49.xml
mkorder, mkreplica, MultiSite Control Panel, shipping.conf