This chapter is intended for customers who are upgrading from previous versions of Caché. Topics in this document include:
Supported Upgrade Paths
The following direct upgrade paths to Caché 5.0 are supported:
You may upgrade directly to Caché 5.0 from version 2.1.6 or above without converting existing databases.
The following conversion and upgrade paths to Caché 5.0 are supported:
After installing Caché, you must convert databases from the legacy format.
If you are using a previous InterSystems database product, such as Caché 2.0 or DSM 6.6, you must first upgrade to one of the previously listed versions and then proceed with the conversion and upgrade.
If you are upgrading a system that uses the InterSystems legacy relational database (referred to as the F-DBMS), you must either upgrade to Caché SQL or obtain the F-DBMS component from the InterSystems Worldwide Response Center (WRC).
Upgrade Tasks
Tasks necessary to upgrade from previous releases of Caché are grouped by the following topics:
Pre-Installation Upgrade Tasks
The following upgrade tasks are necessary regardless of the platform on which you are upgrading and running Caché. Perform these tasks before you run the Caché installation procedures:
  1. Save custom routines and globals — to prevent your own routines and globals in the %SYS namespace from being affected by the upgrade installation, ensure that they have names that begin with “Z”, “z”, “%Z”, or “%z”. All .int and .obj routines (except for Z*, z*, %Z*, and %z*) are deleted from the %SYS namespace when upgrading.
    On an upgrade, the CACHELIB, CACHETEMP, DOCBOOK, and SAMPLES databases are completely replaced.
    Any .mac or .inc routines are not affected during the upgrade.
  2. Save user files — additional files and directories are also deleted and/or replaced. Save any user files you may have put in these directories in a separate location before upgrading. See Files Deleted on Upgrade for the list.
  3. Export custom classes — classes in the %SYS namespace are not saved, even if they begin with “Z”, “z”, “%Z”, or “%z”. To save your classes when upgrading, export them before the upgrade and import them back into Caché when the upgrade is complete.
  4. Check routine labels — routines which used to compile with no errors, but had duplicate labels, now receive errors during compilation, but run without error. The previous utility to check all application routines for duplicate labels, %LBLRDEF, is not shipped with Caché 5.0.
  5. Check routine references — check all application routines for routine references over 8 characters (including function calls, DO routine calls, $ZT calls, and so on). Caché recognizes up to 63 significant characters in routine names, and this could possibly cause <NOROUTINE> errors at compile and/or run time.
  6. Check system integrity — run a system integrity check on existing directories to ensure there is no corruption in any of the databases.
  7. Backup system — before upgrading, InterSystems recommends that you run a complete backup of your system. Use your customary full operating system backup procedures.
Files Deleted on Upgrade
The following files and directories are deleted during the installation of the indicated components.
Files Deleted on Windows Upgrades
Installed Component File or directory deleted
Caché Application Development (Object utilities) <CacheSys>\Bin\Cache*.oca
<CacheSys>\Bin\CacheList.ocx
<CacheSys>\Bin\CacheQuery.ocx
<CacheSys>\Bin\VISM.ocx
Web Server (CSP) Gateway or Caché Engine <CacheSys>\CSP\broker\
<CacheSys>\CSP\cachelib\
<CacheSys>\CSP\RunTime\
Caché Engine Link Libraries <CacheSys>\Source\Cache\Win95\
<CacheSys>\Source\Cache\i386\
<CacheSys>\Source\Cache\alpha\
WebLink <CacheSys>\Weblink\Doc\
<CacheSys>\Weblink\Scripts\
<CacheSys>\Weblink\i386\
<CacheSys>\Weblink\alpha\
<CacheSys>\mgw.ini is renamed mgwsave.ini
Caché Engine <CacheSys>\Mgr\CacheLIB\cache.dat
<CacheSys>\Mgr\CacheLIB\cache.lck
Caché Tools and Utilities <CacheSys>\Dev\
<CacheSys>\CSP\samples\
Documentation <CacheSys>\Docs\
Replace <CacheSys> with the name of your installation directory. CacheSys is the default.
The following files and directories are deleted when upgrading Caché on UNIX and OpenVMS platforms:
Upgrading Caché on OpenVMS
There are other upgrade issues that pertain to OpenVMS systems:
Cleanup Cluster PIJ Files
Before upgrading a member of a Caché for OpenVMS cluster system to Caché 5.0, cleanly shut down all members of the Caché cluster and remove the CACHE.PIJ file. If you do not remove this file, the installation is not upgraded and error messages are written in the cconsole.log for startup:
Cache (2100036c) Tue Aug 1 14:28:59 2002
Activating Namespaces
Cache (21000404) Tue Aug 1 14:28:59 2002 Cluster image journal 
is incompatible with this version 
Cache (21000404) Tue Aug 1 14:28:59 2002 Unable to join the cluster 
Cache (21000404) Tue Aug 1 14:29:00 2002
ENQdaemon exited due to VMS error code (decimal) 0 
Cluster Configuration Changes
Prior to Caché 5.0 when configuring a Caché cluster it was necessary to define the network type for the cluster (UDP or Ethernet) and define DCP connections between the cluster members. This is no longer necessary. DCP over UDP or Raw Ethernet can still be used for Caché cluster network traffic by following the existing configuration procedures, but it is preferable to use ECP networking. ECP is the default for new installations.
After the upgrade to 5.0, a Caché cluster configuration needs to be changed manually. The changes are in two places:
The upgrade does not automatically make these changes because it cannot detect which DCP connections support clusters and which might be for communicating with machines that are still running a prior release of Caché. With ECP, networking the cluster automatically configures the network tables as needed; it is not necessary to define any ECP connections between the cluster members to support Caché clusters. However, the user cannot access the ECP connection created automatically. If the configuration requires ECP, to gain access to privately mounted databases on another cluster member, you must define those connections.
Prior to Caché 5.0 an OpenVMS remote system name, CLUSTER, was always defined which pointed at the cluster master or at the local system if the system did not join a Caché cluster. This has been removed. ECP should not be used to access cluster mounted databases because a connection pointing at a node which fails does not migrate to a surviving node.
Resident Memory Section Name
On OpenVMS systems, when using a resident memory section for the global buffer pool, the user has two options:
  1. Indicate the desired name of the section in the second comma-delimited piece of the residentmem parameter of the cache.cpf configuration file. This is useful to reserve physical memory using the SYSMAN utility, which now requires entry of the section name.
  2. Let the system choose a name for the section. In previous versions of Caché, the system used the name ISC_Shared_Memory, but since this was a fixed name, it was not compatible with multiple configurations. Caché 5.0 automatically creates a name based on the manager's directory so that multiple installations are supported more easily.
If you supply the section name in a certain configuration, then this name is used instead of the system-generated one. InterSystems encourages the use of the SYSMAN utility to reserve a resident memory section in production environments to utilize shared page tables.
Upgrading Caché on UNIX/Linux
When upgrading a UNIX or Linux system from an earlier release of Caché, update the configuration file as follows. Edit the niceval line in the .cpf file; it has several different parameter counts depending on the version being upgraded. The line in the file resembles this:
niceval=-3,-2,-4,2,0,0
Although the last “,0” may not be present.
The fourth parameter in this list should be changed from a 2 to a 0 so that it reads:
niceval=-3,-2,-4,0,0,0
The above is how the niceval line appears if you create a new UNIX/Linux .cpf file in version 5.0 or you install Caché 5.0 as a new installation. Restart Caché for this change to take effect.
Important:
This change is essential for systems running ECP.
Upgrading from ISM
If you are upgrading to Caché 5.0 from ISM 6.4 or 5.10, run the preconversion routine, install Caché, and then convert the existing ISM database to a Caché database. The preconversion routine examines the current ISM configuration and builds a Caché configuration file that is used for the upgrade. This routine is included in the distribution media.
The Caché Installation Guide for OpenVMS and the Caché Installation Guide for UNIX and Linux describe the platform-specific details of running the preconversion routine.
If you migrate between platforms, either of the same or different endian types, the conversion utility cannot deduce the chaining between the primary and extension database volumes, which is based on the actual location of each file. The only way to indicate the new location is by relabeling each volume with the ^LABEL utility.
If there is only one volume, manual file renaming and label correction are not required.
The appropriate steps to convert a multivolume database are:
  1. If the database volumes have been copied from a machine with different endian orientation than the current one, run cvendian to convert them. Provide the directory names of all volumes in a single call to cvendian. For example:
        cvendian tstdir1/OPENM.DAT tstdir2/OPENM.EXT tstdir3/OPENM.EXT
  2. Manually rename the primary volume file to CACHE.DAT and each extension volume file to CACHE.EXT. You can do this before running step 1, if desired.
  3. Run ^LABEL and follow the instructions for correcting volume labels and links, starting with the primary volume, then each extension.
  4. Run START^%SYSCONV(primary_volume) as described in the Run the System Conversion Utility section that follows.
Post-Installation Upgrade Tasks
After the installation is complete, there are additional upgrade tasks:
Run the System Conversion Utility for ISM 6.4 or 5.10 Upgrades
Once the installation is complete on an ISM 6.4 or 5.10 upgrade, run the system conversion utility, %SYSCONV, from the system manager's directory. This automatically runs all required conversions and re-collates routine and object code globals. A converted database may use slightly more disk storage after conversion. Before running the %SYSCONV utility:
To run the system conversion utility:
  1. Start Caché, ensuring that no other users have access to Caché during the conversion.
    To disable other logins from Windows:
    1. Start the Caché Control Panel (by clicking on the Caché Cube and selecting it from the menu).
    2. Right-click on the Caché installation and click Properties. This displays the System Properties dialog box.
    3. On the System Access tab, check the Inhibit All sign-ons check box and click Apply.
  2. At the Caché prompt, run the %SYSCONV routine.
    To convert all databases, change to the manager’s namespace, %SYS, and run:
    %SYS> Do ALL^%SYSCONV
    
    To convert a single database, run:
    %SYS> Do START^%SYSCONV(<directory-name>)
    
    The ALL^%SYSCONV procedure upgrades only databases recorded in the UCI list. To convert a database that is not in the UCI list, use the START^%SYSCONV procedure.
  3. To check the status of the conversion, run:
    %SYS> Do STATUS^%SYSCONV
    
Using GBLOCKCOPY for Upgrade Tasks
The GBLOCKCOPY routine can be used to perform several tasks associated with upgrading.
See the article entitled Using the Caché GBLOCKCOPY Routine for additional information.
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 at the time of the upgrade, or at any time afterwards. Databases can be converted one or several at a time, as downtime and disk space permit.
The following section describes how to convert the manager's database using the GBLOCKCOPY routine.
Convert the Manager's Database
After an upgrade, the manager's 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's database to a different directory.
  3. Shut down Caché cleanly.
  4. Copy the newly created database into the manager's 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

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 moves 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 (megabytes) allotted to 2-KB buffers must be shifted to 8-KB buffers in the Caché Configuration Manager.
Compatibility Issues
The following issues apply to using different versions of Caché concurrently and changes from previous releases of Caché that may affect your operating procedures. Please review these topics to determine if and how they impact your system:
Interoperability
When using the Caché Configuration Manager on a client to configure a Caché server, the version of Caché on the client PC in most cases, must be the same or a later version of the Caché system it manages. See the Supported Caché Version Interoperability section of the Caché Supported Platforms document for specific information.
On Windows platforms, after installing Caché 5.0 on a system that has previous versions of Caché installed:
Automatic Routine Recompilation
Routine object code for version 5.0 is not compatible with previous versions. Because of this, during the Caché installation, all routines in all databases on the system are recompiled. Only the .INT code is recompiled, while .MAC code is not. If routines exist in object code only form, then they cannot be recompiled. When they are run, the user receives a <RECOMPILE> error.
Caché also supports an automatic recompile feature. If an old database is mounted on a 5.0 system and a routine is executed from it, the routine is recompiled (if the source code exists) to the new object code format and then run. This prevents the user from receiving a <RECOMPILE> error.
If you are upgrading a network of Caché systems using DCP, you can use this recompile feature so you can run in a mixed version environment. You can first upgrade the client machines to 5.0. When they reference a routine from the older server, the routine is recompiled on the client and run. The recompiled code is not stored back to the server, which allows the server to continue to run the older version.
Backup Files
The format of BACKUP archives often differs between major releases of Caché. In particular, the format for 4.1 is incompatible with prior versions. Changes from this release permit 4.1 backups to be restored on 5.0, but not vice versa. It is also worth noting that backups contain endian-dependent data, so restoring one made on different hardware may not succeed, especially if the respective endian types are not the same.
Write Image Journal Files
Write image journal files (named CACHE.WIJ) are not compatible between Caché 5.0 and any earlier versions of Caché.
Note:
If the old system did not shut down cleanly, restart Caché to do a recovery before you upgrade to the new version of Caché.
If Caché is running, the upgrade installation stops Caché, runs WIJ recovery, and removes the WIJ file. Do not remove the WIJ file manually. The installation procedure prompts for permission to remove the WIJ if it becomes necessary.
Journal Files
Journal files are not compatible between Caché 5.0 and any earlier versions of Caché.
After upgrading, the journal purge utility does not recognize journal files in the old format and may complain that there are corrupt journal files. To avoid this error, move the old journal files to a backup directory using the appropriate operating system commands before beginning the upgrade.
If you need to restore an older journal file to Caché 5.0, you can use the JConvert and %JRead routines.
Shadowing
When shadowing between different versions of Caché, in compatible mode (previously called record mode), all versions of Caché between 3.1 and 5.0 (inclusive) are compatible in either direction. Mixing 8-bit and Unicode versions, however, is not supported. All existing versions of Caché, from 2.1 and later (except 3.0), can shadow a 2.x server, but Caché 2.1 cannot shadow a server from later versions of Caché.
Clusters
On OpenVMS systems, it is not possible for Caché 5.0 systems to cluster with earlier Caché version systems due to PIJ file version upgrade incompatibilities.
When upgrading to Caché 5.0 on an OpenVMS cluster system, the PIJ file must be deleted or moved manually due to file incompatibilities. The upgrade procedure cannot convert the existing PIJ file because it does not know the status of the other nodes that use the same file.
Caché 4.1 and Caché 5.0 clusters can coexist on the same hardware, but they cannot cluster together. If these clusters need to communicate with each other they need to use DCP.
Collation Changes
From earlier releases, there is a significant change in how collation is handled in Caché 4.1 and Caché 5.0. Collation is now inherited in the following way:
You can specify the default collation for all globals in a database when you create that database. If you do not specify a collation, then the database is created with the default collation.
When you create a global implicitly, the collation for that global is the collation of the database. Reference the Setting Collation in Conjunction with National Language Support (NLS) article for specifics on how to specify a different collation than the database default.
Limitations
The following limitations apply to Caché 5.0 or specific operating systems running Caché: