mkreplica


Creates a replica

Applicability

Product
Command type
MultiSite
multiutil subcommand

Platform
UNIX
Windows

Synopsis

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

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 }...

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. For more information, see Creating Database Replicas.

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.)
  2. Note: Creating multiple replicas in one mkreplica –export command is more efficient than using multiple mkreplica –export commands.

  3. The packet is sent to one or more other sites.
  4. At each receiving site, a mkreplica –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 don’t need to create a vendor database for the schema repository. You can associate the new user database replica with the existing schema repository in 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. Note that creation of additional replicas is recorded in oplog entries. Existing replicas learn about a new replica through the standard synchronization mechanism. (See the syncreplica reference page).

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 ClearQuest 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 database 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. For more information, see Recovering from a Failed Import.

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 ClearQuest 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, but we recommend that you 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 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: 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
20m
1.5g
500 kilobytes
20 megabytes
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 a 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/or 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 (UNIX) 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. See the mkorder reference page.

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 (UNIX) or 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 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.

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. (See the chreplica reference page.)
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.
On UNIX, use the uname –n command to display the computer name. On Windows NT, the computer name is displayed in the Network Settings dialog box, which is accessible from the Network icon in the Control Panel. On Windows 2000, the computer name is displayed on the Network Identification tab in the System Properties dialog box, which is accessible from the System icon in the Control Panel.
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 Import

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 don’t 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
DB2
Database Alias
Oracle
SQL*Net Alias
SQL Server
Physical Database Name

–vendor vendor-type
The database vendor you are using. Supported vendor types are DB2, ORACLE, and SQL_SERVER.

db-params
The required database parameters are the same parameters needed to connect to any ClearQuest database. Note these when you create the vendor database to which you import the replica. For more information about how to create empty vendor databases and the parameters you will need, see the Installation Guide for Rational ClearQuest.

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
DB2
–dbologin dbo-name [ dbo-pwd ]
Oracle
–dbologin dbo-name dbo-pwd [ –connectopts connect-options ]
SQL Server
–server server-name –dbologin dbo-name [ dbo-pwd ]
–rwlogin rw-login [ rw-pwd ] [ –rologin ro-login [ ro-pwd ] ]

Note: Use –rologin only when creating a schema repository replica.

–data·base db-info
The user database information for the vendor database you are using.

Vendor database
dbinfo value
DB2
Database Alias
Oracle
SQL*Net Alias
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 pathname 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 clan at the site, –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 database
dbinfo value
DB2
Database Alias
Oracle
SQL*Net Alias
SQL Server
Physical Database Name

–vendor vendor-type
Enter the database vendor you are using. Supported vendor types are DB2, ORACLE, and SQL_SERVER.

db-params
The required database parameters are the same parameters needed to connect to any ClearQuest database. Note these when you create the vendor database to which you import the replica. For more information about how to create empty vendor databases and the parameters you will need, see the Installation Guide for Rational ClearQuest.

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
DB2
–dbologin dbo-name [ dbo-pwd ]
Oracle
–dbologin dbo-name [ dbo-pwd ]
[ –connectopts connect-options ]
SQL Server
–server server-name –dbologin dbo-name dbo-pwd
–rwlogin rw-login [ rw-pwd ] [ –rologin ro-login [ ro-pwd ] ]

Note: Use –rologin only when creating a schema repository replica.

–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 dialog box in the ClearQuest Designer.

Specifying the Location of the Replica-Creation Packet

packet-file-pname | packet-dir-path ...
Specifies a pathname 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

Imports

See Also

activate