syncreplica

Exports or imports update packets

Applicability

Product Command type
MultiSite multiutil subcommand
Platform
UNIX™
Windows™

Synopsis

  • Export an update packet:
    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 ] ]
    {     { –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 ...

  • Import an update packet:
    sync/replica


    –imp/ort
    [–cl/an clan-name ] [ –site site-name ] –fam/ily family-name
    –u/ser username [–p/assword ] password
    { –rec/eive[ –sc/lass storage-class ]
    | { packet-file-pname | staging-area-pname } ... }
    [ -plug/epoch ]

  • Cancel a synchronization in progress:
    sync·replica


    –cancel [ –force] [ –active ] –host hostname –job job-ID ]

Description

Synchronization of a replica with one or more sibling replicas is a three-phase process:

  1. At one site, a syncreplica –export command creates an update packet that contains changes that have occurred in the replica at that site (and perhaps other replicas, as well).
  2. The packet is sent to one or more other sites.
  3. At another site, a syncreplica –import command applies the changes in the update packet to its replica of the same database. This step occurs at all sites that receive the packet.

Contents of an update packet:

  • All changes that have occurred in the current replica since the last update generated for the destination replicas. (Changes already sent to the destination replicas are excluded from the packet).
  • Changes that have occurred in other replicas, which the current replica has received in previous update packets from those replicas, but has not already passed on to the destination replicas.

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.

Notes on the export phase

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.

Notes on the import phase

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.

Skipping packets

syncreplica –import does not process an update packet in the following situations:

  • The update packet contains changes that depend on other changes that have not yet been imported to this replica. This usually means that an update packet destined for this replica has not been sent or was lost during transport.
  • Problems were encountered processing an earlier physical packet in a multiple-part logical packet.

In these cases, syncreplica –import displays an explanatory message.

Update failures and replaying packets

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.

Deletion of update 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.

Hooks firing

HCL Compass hooks do not fire in response to changes made during packet import.

Handling naming conflicts

syncreplica resolves naming conflicts among objects created at different replicas.

Delayed updates

syncreplica does not inform HCL Compass users of the updates to replicas. All active users see updates within a few seconds, through the normal database-polling routines in HCL Compass.

Error handling for packet-delivery failures

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.

Restrictions

You must have Super User privileges.

Options and arguments: Export phase

Specifying the clan, site, and family

Default
Clan: First clan replicated at this site. If there is more than one dbset connection registered on this host, –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.

Specifying a user name and password

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.

Specifying the update packet size

Default
When you do not specify –maxsize, the shipping method you use determines the default packet size in these ways:
  • Packets created with –ship or –fship are no larger than the maximum packet size specified in the shipping.conf file (UNIX) or the MultiSite Control Panel (Windows).
  • Packets created with –out are no larger than 2 GB.
–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:
500k
500 kilobytes
20m
20 megabytes
1.5g
1.5 gigabytes

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 storage bay or staging area is limited.

Disposition of the update packet

Default
None. You must specify how the update packets created by syncreplica –export are to be stored and 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 and Linux™) 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 Linux and the UNIX system 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.

staging-area-pname
The directory where packet files are stored.

Handling packet-delivery failures

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 systems or Linux) or MultiSite Control Panel (Windows).

The date-time argument can have any of the following formats:

date.time | date | time
where:
date:
= day-of-week | long-date
time:
= h[h]:m[m][:s[s]] [UTC [ [ + | - ]h[h][:m[m] ] ] ]
day-of-week:
= today |yesterday |Sunday | ... |Saturday |Sun | ... |Sat
long-date:
= d[d]month[[yy]yy]
month:
= January |... |December |Jan |... |Dec

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 not valid.)

Examples
  • 22-November-2002
  • sunday
  • yesterday.16:00
  • 0
  • 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 is displayed 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.

Specifying the destination replicas

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.

Options and arguments: Import phase

Specifying the clan, site, and family

Default
Clan: First clan replicated at this site. If there is more than one dbset connection registered on this host, –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.

Specifying a user name and password

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.

Specifying the location of the update packets

Default
None.
–rec/eive [ –sc/lass storage-class ]
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 is displayed 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.

Examples

In these examples, the lines are broken for readability. You must enter each command on a single physical line.

Exports

  • At the boston_hub replica, generate an update packet for the sanfran_hub replica. Store the packet in c:\cqms\sanfran_hub_sync.xml.



    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

  • Place the packet file in a storage bay for shipping at some later time.



    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.

  • Similar to the preceding example, but ship the packet immediately.



    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.

Imports

  • Import all incoming update packets in the cq_storage storage class.



    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-34.xml

  • Process the update packet sanfran_hub_sync.xml at the sanfran_hub replica.



    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

  • Attempt to process the update packet sanfran_hub_sync.xml at the sanfran_hub replica before the sanfran_hub replica has been upgraded to the latest schema version.



    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.

  • Process all update packets in the incoming storage bay.



    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