mkreplica

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

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.

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.

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.

Locks: This command fails if the database is locked (for example, during the upgrade process) or while another Rational 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; however, you should always run it at the working schema repository site to avoid the creation of multiple sites with the same name.

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 (Linux and 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.

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 (Linux and 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 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.

On Linux and the UNIX system, use the uname –n command to display the computer name. On Windows, the computer name is accessible from the System icon in the Control Panel. On Windows 2000, click the Network Identification tab. On Windows NT Server 2003, click the Computer Name tab.

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.

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

DB2®

Database Name

Oracle

SID (Oracle System Identifier)

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 Rational ClearQuest 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

DB2

–server server-name –dbologin dbo-name [ dbo-pwd ] [–connectopts connect-options ]

Oracle

–server server-name –dbologin dbo-name dbo-pwd [–connectopts connect-options ]

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

DB2

Database Name

Oracle

SID (Oracle System Identifier)

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.

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

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

if –vendor == DB2,

db-info := Database Alias (IBM® driver)

or Database Name (DataDirect driver)

db-params := -server server-name

-dbo/login dbo-name [ dbo-pwd ]

[ -con/nectopts connect-options ]

if –vendor == ORACLE,

db-info := Oracle SID

db-params := -server server-name

-dbo/login dbo-name [ dbo-pwd ]

[ -con/nectopts connect-options ]

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:

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

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