Skip to main content

Using ^GBLOCKCOPY for Fast Global Copies

^GBLOCKCOPY is an InterSystems IRIS routine that performs fast global copies between databases. It has two modes of operation: Interactive and Batch. Interactive mode is a single process, while Batch mode allows you to run configure and run multiple processes in parallel. ^GBLOCKCOPY contains a built-in monitor and several reports to track the progress of global copies. You can restart ^GBLOCKCOPY at the point it left off if there is a system failure.

Note:

Because there is no locking or integrity checking for database blocks that are being copied, ^GBLOCKCOPY should be used to copy globals only when they are not being actively modified . Although Set or Kill operations may be performed on other globals in the source database where the copy is being performed, as well as in the destination global, database, or namespace without affecting the copy, results in the destination global are unpredictable if Sets or Kills occur in the source global that is being copied to another database or namespace.

When ^GBLOCKCOPY copies a global to a new database, it creates the global there with the same properties of the source global, including Protection, Journal attributes, Collation type, and Keep attributes.

Note:

The SYS.Database.Copy()Opens in a new tab class method provides functionality similar to ^GBLOCKCOPY.

Uses of ^GBLOCKCOPY

^GBLOCKCOPY can be used for several different operations as follows:

  • Copy single or multiple globals from a database to another database or namespace — You can select one or several globals to be copied into a destination database or namespace. If the global already exists in the destination database, data from the source global is merged into the existing data.

  • Split a global from a single database into multiple databases using subscript level mapping — By setting up a namespace with subscript level mapping (SLM) of a global, you can copy a global from a database into this new namespace and cause it to be split amongst the database which make up SLM.

  • Move a subscript-mapped global in many databases into one database — Create a new database which contains the entire global. Then set up several copies in a batch which will copy the global from all the different SLM databases into the new database.

  • Make a copy of a database — You may copy a database to another directory by copying all the globals to it.

  • Copy a global to another machine across ECP^GBLOCKCOPY supports copying a global across an ECP network connection to another machine. You need to set up an ECP connection to a remote machine, and a namespace mapping which points to it. Then select the “Copy from Database to Namespace” option and select the remote namespace as the destination of the copy.

  • Reclaim unused space in a database — If a large global is created then killed in a database, there may be a large excess of unused space in the database. You can remove this space by copying all the globals in the database to a new one, and then replacing the old database with the new database.

  • Reorganize the pointers in a database — If a database becomes fragmented because of block splits, you may want to reorganize the data in it to speed performance. You can do this by copying all the globals in a database into a new database, and then replacing the old database with the new database.

  • Change the collation of a global — If you want to change the collation of an existing global you are copying, you can create the global in the destination database with the desired default collation before running ^GBLOCKCOPY.

  • Import a Caché or legacy database or namespace into InterSystems IRIS — If you have a CACHE.DAT file or legacy database file you want to import to an IRIS.DAT database or namespace, simply select the directory where it exists as the source directory for the copy. The database is renamed IRIS.DAT, and the data is available to copy to the destination database or namespace.

Running ^GBLOCKCOPY

Before you run ^GBLOCKCOPY (or for that matter before you perform an upgrade), make a full operating system backup of your databases, and run an integrity check to ensure there is no corruption in any of the databases.

Note:

To make ^GBLOCKCOPY run faster, kill off any temporary and scratch data as well as any old data you do not require.

When running ^GBLOCKCOPY, you can copy all or only some globals from a specific database. The routine prompts for the names of the globals to copy. To refer to only some globals, the syntax is:

  • Inputting glonam selects the global “glonam” to be copied.

  • Inputting 'glonam deselects the global “glonam” if it is selected.

  • Inputting glonam1-glonam2 selects the range of globals from “glonam1” to “glonam2”.

  • Inputting 'glonam1-glonam2 deselects any global in the range from “glonam1” to “glonam2”.

The following are wildcard characters for selecting globals:

  • Use an ampersand (&) to match any single letter.

  • Use a number sign (#) to match single digit.

  • Use a question mark (?) to match any single character.

  • Use an asterisk (*) to match any number of characters.

Note:

You cannot use wildcard characters when specifying a range of globals.

When selecting a subsection of globals, you can also use the following inputs:

  • ? — lists informational inputs.

  • ?L — lists all available globals; specifies which have been selected with a number sign (#).

  • ?S — lists the currently selected globals.

  • ?H — lists the global selection syntax.

You can use the batch functionality of ^GBLOCKCOPY to set up multiple operations to run at the same time. When configuring a batch, you will be prompted for the total number of copy processes and the maximum number of copy processes per directory. You can run a maximum of one process per global. For Batch mode, the duration of the copy operation is proportional to the size of the largest global; storage latency and bandwidth are additional factors. While the batch of operations is running, you can monitor progress using the Monitor or Batch Report.

Note:

Users should be kept from accessing the databases while they are being processed by ^GBLOCKCOPY. The result of the database operations are unpredictable if they are accessed while ^GBLOCKCOPY is running. Databases on the same system which are not being processed by ^GBLOCKCOPY can be used safely.

FeedbackOpens in a new tab