Skip to main content

Converting MSM Globals

Caché provides several mechanisms for converting your MSM data.

Converting Selected Globals

Caché offers the following methods for converting individual globals or groups of globals, rather than an entire database:

  • Set up a network between MSM and Caché. Use either the MERGE command or ^%GCOPY to transfer globals from the MSM database to the Caché database.

  • Use %GS or %FGS to save individual or groups of MSM globals in MSM format.

    • For %GS-format global saves, use ^%GI to import the data. It is more reliable to use the ANSI ^%GS entry point, especially if the globals can contain control characters.

    • For %FGS-format global saves, use ^%SYS.GIFMSM to import the data.

Preserving MSM String Collation

By default, Caché uses the Latin-1 subset of Unicode collation. The Latin-1 subset follows the same collation rules as MSM’s default numeric collating sequence. You do not need to do any preliminary work to convert numerically collated MSM globals since Caché’s Unicode collation will be backward compatible with this format. However, since you cannot reference string collated globals across DDP from Caché, you will need to prepare Caché in order to convert MSM globals that use a string collation.

For example, suppose that you need to convert a string collated global called ^XYZ. There are two ways you can do this conversion:

  1. Create the ^XYZ global using the ^%SYS.GCREATE utility. This option is recommended unless you want to convert all MSM globals with a string collation type.

    • Change to the appropriate namespace.

    • Invoke ^%SYS.GCREATE, and select type129 (string collation) when prompted for the globals collation sequence.

    • Convert as described previously in “Converting Selected Globals”.

  2. Change the characteristics of the process performing the conversion to use string collation.

Enabling Null Subscript Support in Caché

By default, Caché does not allow the use of null subscripts in your global data. It is strongly recommended that you modify your application and data so that null subscripts are not used.

There are two ways you can convert MSM globals that contain null subscripts.

  • Enable null subscript support interactively:

    • For the issuing process only, run the command:

      Set x=$ZU(68,1,1)
      
    • For all processes in the system, run the command:

      Set x=$ZU(69,1,1)
      
    • Convert as described previously in “Converting Selected Globals”.

  • Enable null subscript support at each Caché startup for all processes. To do so, add the following line of code to either ^ZSTU or SYSTEM ^%ZSTART:

    Set x=$ZU(69,1,1)
    

    Then restart Caché and convert as described previously in “Converting Selected Globals”.

Converting Globals by Database

If you plan to convert all globals in a particular volume group or UCI at once, it is recommended that you convert it in its entirety, rather than convert individual globals or groups of globals. Converting an entire UCI or volume group at once is not only a much faster process, but it also drastically reduces the risk of error.

  1. Make sure that any incompatible MSM globals have been already converted:

  2. Back up your MSM databases.

  3. Run ^VALIDATE on your MSM database to ensure physical integrity.

  4. If converting in block mode, run ^RECOVER to ensure that there are no unused blocks that are still marked as allocated in their map blocks. (If globals have been removed from the global directory block but ^RECOVER has not been run, %MSMCVT will see this data as valid global data and convert it to Cache data).

  5. Run ^OLC on your MSM database to maximize global efficiency. This will help the conversion’s overall performance.

  6. Kill any MSM system or user-defined scratch globals.

  7. Ensure that the database to be converted is not active, either by shutting down MSM or by dismounting the database.

  8. Use either binary-mode FTP, network copy, or tape to move your MSM database over to the machine hosting Caché. You can put this database in any directory you wish.

  9. Configure as many global buffers as possible on your Caché system, and then start Caché.

  10. Make sure your local destination database(s) and namespace are ready (as described previously in “Creating a Namespace Configuration”).

  11. From the new namespace, run the ^%MSMCVT utility. At the prompt, enter the path and filename of your MSM database. When you run the conversion, your database is converted into a Caché database in the current namespace.

  12. If you are importing data from several MSM databases into one Caché namespace, run the utility repeatedly from the same namespace, once for each database.

Running %MSMCVT in Block Mode

^%MSMCVT can run in two modes, block mode and non-block mode. There is a prompt during the setup that says "Convert with block mode?" If you answer "No" to this prompt ^%MSMCVT will use non-block mode. The difference is important:

  • In block mode, ^%MSMCVT scans through the entire database sequentially, block by block, looking for data blocks that are marked as allocated in the corresponding map block. When it finds one, it sets it into the new Caché database.

  • In non-block mode, ^%MSMCVT converts the database global by global (which allows you to avoid converting some globals if you want) and follows the tree for each global.

Running ^RECOVER on the MSM side is an absolute requirement if you use block mode conversion, unless you are 100% sure that you have no "orphan" blocks in the MSM database from previous repair work. An "orphan" block is a block that is marked as allocated in its map block but is not a part of any valid global tree. This can happen if a block was cut out of a tree during database repair, but the block was never unallocated in the map. If there are orphan blocks and ^RECOVER is not run, old data that was not visible in MSM will be present in Caché, and will be indistinguishable from valid data.

If you run ^%MSMCVT in non-block mode ^RECOVER is not required (and in fact will make no difference).

FeedbackOpens in a new tab