Creates a replica
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 }...
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:
Note: Creating multiple replicas in one mkreplica –export command is more efficient than using multiple mkreplica –export commands.
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.
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.
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.
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.
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.
Replica-creation packets are not deleted after import. After you import a replica-creation packet with mkreplica –import, you must delete the packet.
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.
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.
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.
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:
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:
Default
None.
–c·omments comments
Comments you want to store with this replica’s information.
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.
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.
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:
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.
hostname:site-name...
One or more arguments, each of which indicates one new replica to be created from this packet in another site.
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.
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.
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.
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.
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.
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.
–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.
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.
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.
In these examples, the lines are broken for readability. You must enter each command on a single physical line.
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
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
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
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
multiutil mkreplica -import -site sanfran_hub -repository sanfran_schemarepo -vendor SQL_SERVER -server sb_server -dbologin jcole passwd -rwlogin jcole passwd -rologin jcole passwd -database sanfran_userdb -vendor SQL_SERVER -dbologin jcole passwd -rwlogin jcole passwd
multiutil mkreplica -import -clan testing -site sydney -user bfife -p passwd -database syd_userdb -vendor SQL_SERVER -dbologin bfife passwd -rwlogin bfife passwd
activate