mkreplica

Creates a replica

Applicability

Product Command type
MultiSite multiutil subcommand
Platform
Windows®

Synopsis

  • Duplicate an existing database, generating a new replica object and a replica-creation packet:
    mkrep/lica


    –exp/ort[
    –cl/an clan-name ] [ –site site-name ] –fam/ily family-name
    –u/ser username [–p/assword] password
    [–max/size size ] [–c/omments comments ]
    [–size id-block-size ] [ –thres/hold id-block-threshold ]
    {
    {–sh/ip | –fsh/ip} -wor/kdir temp-dir-pname    
    [–sc/lass storage-class ]
    [ –pex/pire date-time ]
    [–not/ify e-mail-addr ]
    | –out packet-file-pname } hostname:site-name ...

  • Import a replica-creation packet to create a new user database replica and a new schema repository replica:
    mkrep/lica


    –imp/ort
    { –site site-name–repo/sitory db-info [ –vendor
    vendor-type ] db-params
    }
    { [ –data/base db-info [ –vendor vendor-type ] db-params
    [ –c/omments comments ] { packet-file-pname|packet-dir-path }...

  • Import a replica-creation packet to create a new replica in the same clan as the existing schema repository in the current site:
    mkrep/lica


    –imp/ort {
    [–cl/an clan-name ] [ -site site-name ] –u/ser username
    [–p/assword ] password { –data/base db-info
    [ –vendor vendor-type ] db-params
    [ –c/omments comments ] { packet-file-pname|packet-dir-path }...

Description

Note: Before replicating the first database of a clan, you must first activate the database set to which it belongs. You should also upgrade the databases you want to replicate to use the most recent version of the schema.

The mkreplica –export command may take a long time. The database and the schema repository are locked while an export is in progress. Make sure that all users are logged out before you run mkreplica –export.

The creation of a new replica is a three-phase process:

  1. The mkreplica –export command duplicates the contents of the specified user database and its associated schema repository. This generates a single logical replica-creation packet for transmission to one or more other sites. A logical packet can be divided into multiple physical packets. (If you use –fship or –ship, mkreplica also generates a shipping order file for each physical packet.)
    Note: Creating multiple replicas in one mkreplica –export command is more efficient than using multiple mkreplica –export commands.
  2. The packet is sent to one or more other sites.
  3. At each receiving site, a mkreplica –import command first validates that the replica-creation packet was exported from a system running the same operating system code page. If the code pages of the exporter and importer do not match, the new replica is not created. If there is no mismatch, the –import command uses the replica-creation packet to create a new replica. The new replica consists of two replicated databases, a schema repository, and a user database. This command varies if you are adding a user database replica to a family within the same clan of an existing schema repository.

Creating empty vendor databases

At each new site, the administrator must create empty vendor databases for the replica data. If this is the first replica in the new site, you need at least two empty vendor databases, one for the schema repository replica and one for the user database replica.

Note: If you are adding a new user database replica to an existing site, you do not need to create a vendor database for the schema repository. You can associate the new user database replica with the existing schema repository at your site.

Oplog information

When a database is replicated for the first time, the database's operation log (oplog) is enabled. All operations to be replicated are recorded in the oplog. Logging of operations continues until all replicas are deleted, leaving only the original database set. Creation of additional replicas is recorded in oplog entries. Existing replicas learn about a new replica through the standard synchronization mechanism.

Note: Before entering a mkreplica –export command, verify that MultiSite licenses are installed at the original site. After you activate the original database set, developers cannot access the database set without a MultiSite license (in addition to a HCL Compass license). A MultiSite license is also required to run mkreplica –export.

Allocating ID blocks to a replica

MultiSite controls how many record ID numbers are allocated to each replica. This allocation is done by using ID blocks (groups of IDs).

By default, each replica is given an ID block of 4096 IDs when it is created. When a replica reaches a threshold of 1024 IDs left to use, it is allocated another ID block of 4096 IDs to ensure that all IDs are unique. ID block allocation is handled internally by the working schema repository during synchronization.

Depending on the activity level of a replica family, it may be helpful to increase the size of the ID blocks that are allocated to a replica. For example, with the default settings, if you try to submit a large number of defects, the first 4096 are submitted successfully, but submissions after that fail.

To control how many IDs a replica is allocated, you can use the –size option combined with the –threshold option when you create a replica with the mkreplica –export command. You can modify these settings with the chreplica command.

Replica-creation packets

Each invocation of mkreplica –export creates a single logical replica-creation packet. (This is true even if you create several new replicas with one mkreplica command.) Each packet includes one or more replica specifications, each of which indicates the new replica's name and the synchronization server associated with the new replica.

The user database and schema repository are locked during the export phase.

The –maxsize option divides the single logical packet into multiple physical packets to conform to the limitations of the transfer medium.

Recovering from failed imports

If a replica import is interrupted or fails for any reason (a power outage, for example), you must delete the vendor databases, create new vendor databases for the failed import operation, and rerun mkreplica –import.

It is possible to have a successful import of the schema repository, but a failed import of the user database replica. In this case, you must delete and re-create the vendor database that was intended for the user database replica.

Cleaning up used packets

Replica-creation packets are not deleted after import. After you import a replica-creation packet with mkreplica –import, you must delete the packet.

Error handling for packet delivery failures

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.

Restrictions

Locks: This command fails if the database is locked (for example, during the upgrade process) or while another HCL Compass MultiSite operation is being performed.

Other: You cannot replicate a database to a host running a different version of MultiSite. You can run mkreplica –export at any site; however, you should always run it at the working schema repository site to avoid the creation of multiple sites with the same name.

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: Not applicable. When you run mkreplica, the associated schema repository of the user database family you specify is included in the replica-creation packet.

Default: None.

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 replica-creation packet size

Default
When you do not specify –maxsize, the default packet size depends on the shipping method you use:
  • Packets created with –ship or –fship are no larger than the maximum packet size specified in the MultiSite Control Panel.
  • Packets created with –out are no larger than 2 GB.

    The mkreplica command fails if it tries to create a packet larger than the size supported by your system.

–max/size size
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

Specifying a comment

Default
None.
–c/omments comments
Comments you want to store with this replica's information.

Specifying ID block allocation

Default
ID block size: 4096. ID block threshold: 25 percent.
–size id-block-size
Size of ID block. You can enter any number from 1 to 1023. The value of id-block-size is multiplied by 100 to obtain the actual ID block size. For example, to specify an ID block of 30,000, use the number 300; to specify an ID block of 25,000, use the number 250.
–thres/hold id-block-threshold
The number of record ID numbers allocated to the replica. id-block-threshold is specified as an integer representing a percentage. You can enter any number from 1 to 63. When the number of remaining record IDs to be used drops below the specified percentage of the current ID block size, an additional block is allocated.

Disposition of the replica-creation packet

Default
None. You must specify how the replica-creation packet created by mkreplica –export is to be stored and transmitted to other sites.
–shi/p –fsh/ip
Stores the replica-creation packet in one or more files in a store-and-forward storage bay. A separate shipping order file accompanies each physical packet, indicating how and where it is to be delivered.

–fship (force ship) invokes shipping_server to send the replica-creation packet. –ship places the packet in a storage bay. To send the packet, invoke shipping_server.

The disk partition where the storage bay is located (on the sending host and the receiving host) must have available space equal to or greater than the size of the replica-creation packet.

–wor/kdir temp-dir-name
A directory for use by mkreplica as a temporary workspace; it is deleted when mkreplica finishes. This directory must not already exist.
–sc/lass storage-class
Specifies the storage class of the packet and shipping order. mkreplica looks up the storage class in the MultiSite Control Panel (Windows) or the shipping.conf file to determine the location of the storage bay to use.

Default: mkreplica places the packet in the storage bay location specified for the cq_default class.

–out packet-file-pname
The name of the first physical replica-creation packet. Additional packets are placed in files named packet-file-pname_2, packet-file-pname_3, and so on.

The replica-creation packets are not delivered automatically; use an appropriate method to deliver them. You can create a packet using –out, and subsequently deliver it using the store-and-forward facility.

Handling packet-delivery failures

Default
If a packet cannot be delivered, it is sent through the store-and-forward facility 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 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.
–pex/pire date-time
Specifies the time at which the store-and-forward facility stops trying 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 ( MultiSite Control Panel (Windows).

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

date.time | date | time | now
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.

Replica specifications

Default
None.
hostname:site-name...
One or more arguments, each of which indicates one new replica to be created from this packet in another site.
hostname
The synchronization server for the new replica. hostname must be usable by hosts in different domains. It is used by the store-and-forward mechanism to determine how to route update packets to the replica. However, keep this information accurate even if your site does not use store-and-forward.

hostname can be either the IP address of the host, or the computer name, for example, minuteman. You may have to append an IP domain name, for example, minuteman.purpledoc.com.

site-name
Name by which the replica will be identified in multiutil commands. The site name must be an identifier and can be up to 50 characters long. This name must be unique within the respective clan: there cannot be two sites with the same name participating in the same clan.

Options and arguments: Import phase for schema repository and user database

Specifying the site and database information

Default
None.
–site site-name
The name of the site where the replica will be imported. The site name was given to the replica when it was exported. If you do not know the site name, contact the administrator at the exporting site.
–repo/sitory db-info
The database information for the vendor database you are using.
Vendor database
dbinfo value
SQL Server
Physical Database Name
–vendor vendor-type
db-params
The required database parameters are the same parameters needed to connect to any HCL Compass database. Note these parameters when you create the vendor database to which you import the replica.

When you import a replica, you must specify the database parameters of the vendor database for the schema repository replica and the vendor database for the user database replica. You must create these databases before importing a replica packet.

Vendor database
db-params value
SQL Server
–server server-name –dbologin dbo-name [dbo-pwd ] [–connectopts connect-options ]
–data/base db-info
The user database information for the vendor database you are using.
Vendor database
dbinfo value
SQL Server
Physical Database Name
–c/omments comments
Comments you want to store with the replica's information.

Specifying the location of the replica-creation packet

Default
None.
packet-file-pname | packet-dir-path ...
Specifies a path name of a replica-creation packet. For a logical packet that spans multiple disk files, mkreplica scans the directory containing packet-file-pname for related physical packets.

If you also specify one or more packet-dir-path arguments, mkreplica searches for additional packets in these directories.

Options and arguments: Import phase for user database import only

If you are adding a user database family to an existing clan, you need to create a vendor database for the user database replica only.

Specifying the clan and site

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.

–cl/an clan-name
Name of the replica’s clan.
–site site-name
Name of the replica’s site.

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 database information

–data/base db-info
The user database information for the vendor database you are using.
–vendor vendor-type db-params
if –vendor == SQL_SERVER,
db-info := Physical Database Name
db-params := -server server-name
-dbo/login dbo-name [ dbo-pwd ]
[ -con/nectopts connect-options ]

Specifying db-info and db-paramsfor DB2®, Oracle and Microsoft SQL Server

Each database vendor has a default port number:

Table 1. Default port numbers for database vendors
Vendor Default port
Microsoft SQL Server 1433

If your database uses a different port, you must specify it using the connect-options parameter. For example, if you have an Oracle database on port 1526, enter the following command:

multiutil mkreplica -imp -site SITEA -repo CQDEV -server cqsvr3 -vendor ORACLE -dbo admin_1 admin_1 -con PORT=1526 -data CQDEV -server cqsvr3 -vendor ORACLE -dbo admin_2 admin_2 -con PORT=1526 C:\TEMP\admin\mk_SITEA.xml

Important: For more information about the supported values for the vendor databases, see the "Vendor database properties" topic in the Administering section of the Help.

–c/omments comments
Comments you want to store with this replica's information. These comments are stored in the schema repository database at the importing site and are displayed in the Database Property window in the HCL Compass Designer.

Specifying the location of the replica-creation packet

packet-file-pname|packet-dir-path ...
Specifies a path name of a replica-creation packet. For a logical packet that spans multiple disk files, mkreplica scans the directory containing packet-file-pname for related physical packets.

If you also specify one or more packet-dir-path arguments, mkreplica searches for additional packets in these directories.

Default: None.

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 a replica-creation packet for the DEV family to create a new replica named sanfran_hub. The synchronization server for the new replica is goldengate.



    multiutil mkreplica -export -clan telecomm -site boston_hub -family DEV
    -u susan -p passwd -out c:\cqms\boston_hub.xml goldengate:sanfran_hub


    Multiutil: Packet file `c:\cqms\boston_hub.xml' generated

  • At the boston_hub replica, generate a packet that will create a replica of the LAB family database when imported at the sanfran_hub replica.



    multiutil mkreplica -export -clan telecomm -site boston_hub -family LAB
    -user susan -p passwd -out c:\cqms\lab.xml goldengate:sanfran_hub


    Multiutil: Packet file `c:\cqms\lab.xml' generated

  • At the tokyo replica, generate a replica-creation packet for the sydney replica and use –fship to forward the packet immediately.



    multiutil mkreplica -export -clan testing -site tokyo -family TEST
    -user masako -p passwd -fship -workdir c:\cqms\working -sclass
    cq_default taronga:sydney


    Multiutil: Packet file
    `c:\cqms\working\mk_TOKYO_29-January-02_09-47-27.xml' generated
    multiutil: Shipping order
    "C:\temp\cqms\ms_ship\outgoing\sh_o_mk_TOKYO_29-January-02_09-47-27.xml"
    generated.
    multiutil: Attempting to forward/deliver generated packets...
    multiutil:   -- Forwarded/delivered packet
    C:\temp\cqms\ms_ship\outgoing\mk_TOKYO_29-January-02_09-4

  • Similar to the preceding example, but place the packet file in a storage bay for shipping at some later time by the store-and-forward facility.



    multiutil mkreplia -export -clan telecomm -site boston_hub -family DEV
    -user susan -password passwd -c "make a new replica for sanfran_hub"
    -ship -workdir c:\temp\working -sclass cq_default
    -pexpire 22-November-2003
    goldengate:sanfran_hub

Imports

  • Import the new database replica sanfran_hub and its associated schema repository into Microsoft® Access databases.



    multiutil mkreplica -import -site sanfran_hub -repo
    c:\cqms\CQMasterB.mdb
    -vendor MS_ACCESS -data c:\cqms\CQUserB.mdb -vendor MS_ACCESS
    c:\cqms\boston_hub.xml


    Multiutil: Warning: Use of HCL Compass MultiSite with a Microsoft Access
    or SQL Anywhere database is not supported
    Multiutil: Warning: Use of HCL Compass MultiSite with a Microsoft Access
    or SQL Anywhere database is not supported
    Multiutil: Created the schema repository CQMS.telecomm.sanfran_hub
    Multiutil: Created the SAMPL database in CQMS.telecomm.sanfran_hub

  • Import the lab.xml packet sent from the boston_hub replica, which creates a replica of the LAB family database at the sanfran_hub replica.



    multiutil mkreplica -import -clan telecomm -site sanfran_hub -data
    c:\cqms\sanfran_hub_lab -vendor MS_ACCESS -user jcole -p passwd
    c:\cqms\lab.xml


    Multiutil: Warning: Use of ClearQuest MultiSite with a Microsoft Access
    or SQL Anywhere database is not supported
    Multiutil: 8 transactions from boston_hub have been replayed into the
    MASTR database
    Multiutil: Created the LAB database in CQMS.TELECOMM.SANFRAN_HUB

  • (The following two examples use SQL Server databases.) Import a new database replica sanfran_hub and its associated schema repository replica into SQL Server databases.



    multiutil mkreplica -import -site sanfran_hub
    -repository sanfran_schemarepo
    -vendor SQL_SERVER -server sb_server -dbologin jcole passwd
    -database sanfran_userdb -vendor SQL_SERVER
    -dbologin jcole passwd

  • Import a new user database replica that is part of the sydney site in the testing clan. The new user database replica is being imported into a SQL Server database.



    multiutil mkreplica -import -clan testing -site sydney -user bfife
    -p passwd -database syd_userdb -vendor SQL_SERVER
    -dbologin bfife passwd