Using ^GBLOCKCOPY for Fast Global Copies
^GBLOCKCOPY is an InterSystems IRIS routine that performs fast global copies between databases. It can be run interactively in the Terminal, or be set up in a batch to run one or more global copies as background jobs. ^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.
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.
The SYS.Database.Copy() 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. Since databases can now exceed 2 GB in size, this is a useful method for consolidating databases.
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.
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.
To make ^GBLOCKCOPY run faster, kill off any temporary and scratch data as well as any old data you do not require.
You can use the batch functionality of ^GBLOCKCOPY to set up a batch of operations to run at the same time. While the batch of operations is running, you can monitor progress using the Monitor or Batch Report.
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.