This article describes the uses and procedures for running the Caché GBLOCKCOPY routine to copy globals.
Overview
GBLOCKCOPY is a Caché routine which performs fast global copies between databases. It can be run interactively to a 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. GBLOCKCOPY can be restarted at the point it left off if there is a system failure.
Note:
The GBLOCKCOPY routine should only be used on globals which are currently not being accessed with Set or Kill operations. Results in the destination global are unpredictable if Sets or Kills occur in the source global which is being copied to another database or namespace. Set or Kill operations may be performed on other globals in the source database where the copy is being performed. They may also be performed in the destination global, database, or namespace without affecting the copy.
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 one exception to this is if the global is of the following collations:
In these cases, the collation is automatically changed to Caché Standard.
Uses of GBLOCKCOPY
GBLOCKCOPY can be used for several different operations as follows:
Running GBLOCKCOPY
Before you run GBLOCKCOPY (or for that matter before you perform the 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. For ISM upgrades, do this before you perform the upgrade. For Caché 2-KB page size to 8-KB page size conversions, you can do this just before you run GBLOCKCOPY.
You can use the batch functionality of GBLOCKCOPY to set up a batch of conversions to run at the same time. Select the “Auto Create a Batch” option. This option looks through the ^SYS("UCI") global for a list of the databases on the system. If it detects that any of the databases are using a 2-KB page size then it gives the option to add it to the batch of conversions. Once the batch of conversions is set up, you can then select the option to run the batch. While the batch of conversions is running, you can monitor progress using the Monitor or Batch Report.
Note:
Users should be kept from accessing the databases as they are being converted with GBLOCKCOPY. The result of the database conversions will be unpredictable if they are accessed while GBLOCKCOPY is running. Databases on the same system which are not being converted with GBLOCKCOPY can be used safely.
The following is an example of using the “Auto Create a Batch” option:
%SYS>d ^GBLOCKCOPY

This routine will do a fast global copy from a database to another database or
to a namespace. If a namespace is the destination, the global will follow any
mappings set up for the namespace. 

 
1) Interactive copy
2) Batch copy
3) Exit
 
Option? 2
 
1) Manage Batches
2) Run a Batch
3) Restart a Batch
4) Add Processes to a running Batch
5) Stop a Running batch
6) Monitor Running Batch
7) Batch Report
8) Exit
 
Option? 1
 
1) Create a Batch
2) Edit a Batch
3) List Batches
4) Delete a Batch
5) Auto create a Batch
6) Exit
 
Option? 5
 
1) Convert 2K DB to 8K DB
2) Convert OPENM/ISM DB
3) Both
4) Exit
 
Option? 1
 
Batch name to auto create? CVT2K
 
Detected 2K c:\temp\a\CACHE.DAT, convert to 8K CACHE.DAT? Yes => Yes
Detected 2K c:\temp\x\CACHE.DAT, convert to 8K CACHE.DAT? Yes => Yes
Detected 2K c:\temp\z\CACHE.DAT, convert to 8K CACHE.DAT? Yes => No
 
Auto creating the following database conversions:
 
Convert 2K c:\temp\a\CACHE.DAT => 8K c:\temp\a\CACHE.DAT
Convert 2K c:\temp\x\CACHE.DAT => 8K c:\temp\x\CACHE.DAT
 
Confirm auto creation of batch CVT2K? No => yes
 
Database c:\temp\a\CACHE.DAT renamed to c:\temp\a\old\CACHE.DAT
Database c:\temp\x\CACHE.DAT renamed to c:\temp\x\old\CACHE.DAT
 
Batch Name: CVT2K  0 of 0 Processes running, 0 per directory
 # Source DB=>Destination DB/NS                  Last Update Done/ToDo/Err State
-- ----------------------------                  ----------- ------------- -----
 1 c:\temp\a\old\=>c:\temp\a\                                   0/  15/  0 Queue
 2 c:\temp\x\old\=>c:\temp\x\                                   0/  15/  0 Queue
 
Auto creation of batch CVT2K complete
 
1) Convert 2K DB to 8K DB
2) Convert OPENM/ISM DB
3) Both
4) Exit
 
Option? 4
 
1) Create a Batch
2) Edit a Batch
3) List Batches
4) Delete a Batch
5) Auto create a Batch
6) Exit
 
Option? 6
 
1) Manage Batches
2) Run a Batch
3) Restart a Batch
4) Add Processes to a running Batch
5) Stop a Running batch
6) Monitor Running Batch
7) Batch Report
8) Exit
 
Option? 2
 
Batch name to run? ?
 
Name    #  Source DB=>Destination DB/NS                       Globals  Status
----    -  ----------------------------                       -------  ------
CVT2K   1  c:\temp\a\old\=>c:\temp\a\                         All      Queue
        2  c:\temp\x\old\=>c:\temp\x\                         All      Queue
 
 
Batch name to run? CVT2K
How many copy processes do you want to run at once? 2 => 
How many of these copy processes do you want to run for each directory? 1 => 
Confirm copy? Yes => 
Performing Upgrade Tasks with GBLOCKCOPY
The GBLOCKCOPY routine can be used to perform several tasks associated with upgrading.
Using GBLOCKCOPY to Convert Databases
After you have performed the upgrade to Caché, you can use the GBLOCKCOPY routine to perform the following operations:
Note:
InterSystems recommends that users convert their existing 2-KB page size databases to 8-KB page size databases for improved performance. This conversion can happen either at the time of the upgrade, or anytime afterwards. Databases can be converted one or several at a time as down time and disk space permit.
Differences between %SYSCONV and GBLOCKCOPY
The %SYSCONV routine renames the MUMPS.DAT databases to CACHE.DAT, performs an in-place conversion of globals which stores the routine source and object code (no additional disk space is required), and then recompiles the routines. The databases still use a 2-KB page size. The %SYSCONV routine is only used for ISM 5.10/6.4 upgrades. The %SYSCONV routine runs slowly since it performs the upgrade without using additional disk space, and only moves single nodes of data at a time.
The GBLOCKCOPY routine requires enough free disk space to make a complete copy of the original database. The original database is renamed to CACHE.DAT in the old subdirectory of the original database. A new 8-KB database is created in the database directory. Then the data from the old directory is copied into the new database. After the conversion, the old database can be deleted by the user when the converted data has been validated. The GBLOCKCOPY routine runs quickly since it is not constrained to run in the same amount of disk space, and will move an entire block of data at a time. However, since it is moving all the data in the database rather than just the routine and object code (as %SYSCONV does), it may take more time to run than %SYSCONV, depending on the size of the database.
Note:
As databases are converted from a 2-KB page size to a 8-KB page size, the number of MB allotted to 2-KB buffers need to be shifted to 8-KB buffers in the Caché Configuration Manager.
Converting the Manager Database
After an upgrade, the Manager Database is left at a 2-KB page size. You can use GBLOCKCOPY to convert this to an 8-KB page size as follows:
  1. Get all users off the system.
  2. Run GBLOCKCOPY to copy the manager database to a different directory.
  3. Shut down Caché cleanly.
  4. Copy the newly created database into the manager directory.
  5. Restart Caché.
The following is an example:
%SYS>d ^GBLOCKCOPY
 
This routine will do a fast global copy from a database to another database or
to a namespace. If a namespace is the destination, the global will follow any
mappings set up for the namespace.
 
1) Interactive copy
2) Batch copy
3) Exit
 
Option? 1
 
1) Copy from Database to Database
2) Copy from Database to Namespace
3) Exit
 
Option? 1
Source Directory for Copy (? for List)? c:\cachesys\mgr
Destination Directory for Copy (? for List)? c:\temp\mgr
Database c:\temp\mgr\ does not exist
Do you want to create it? No => Yes
Database c:\temp\mgr\ created
All Globals? No => Yes
 
39 items selected from
39 available globals
 
Turn journaling off for this copy? Yes => Yes
Confirm copy? Yes => Yes