This chapter is intended for customers who are upgrading from previous versions
of Caché. Topics in this document include:
The following direct upgrade paths to Caché 5.0 are supported:
-
-
-
-
Caché 3.2, 3.2.1, 3.2.2, 3.2.3
-
-
-
-
Caché 2.1.6, 2.1.7, 2.1.8, 2.1.9
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:
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).
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:
-
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.
Any
.mac or
.inc routines are not
affected during the upgrade.
-
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.
-
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.
-
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.
-
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.
-
Check system integrity run a system integrity
check on existing directories to ensure there is no corruption in any of the databases.
-
Backup system before upgrading, InterSystems
recommends that you run a complete backup of your system. Use your customary full
operating system backup procedures.
The following files and directories are deleted during the installation of the
indicated components.
Files Deleted on Windows Upgrades
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:
-
-
Delete any DCP connections from the network table that you do not
need; they were only there to support clusters.
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:
-
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.
-
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:
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:
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.
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.
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:
-
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
-
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.
-
Run
^LABEL and follow the instructions for correcting
volume labels and links, starting with the primary volume, then each extension.
-
Post-Installation Upgrade Tasks
After the installation is complete, there are additional upgrade tasks:
-
-
Recompile Objects you must recompile
any Caché Objects applications after installation if you are upgrading from
a prior version of Caché. There are additional upgrade and compatibility issues
relating to Caché Objects that can be found in the
New
Caché Object Features chapter of these
Release Notes.
-
Adjust Database Memory Cache when upgrading
from Caché 4.04 or earlier, the size of the 2-KB global buffer pool remains
the same, and a minimal amount of 8-KB memory cache is allocated. If you plan on creating
new 8-KB databases or converting your old format (2 KB) to new format (8 KB), then
adjust your allocated database memory cache accordingly from the
General tab
of the
Caché Configuration Manager.
-
-
Upgrade CSP Gateway If your CSP Gateway
is on a separate machine from the Caché server you are upgrading, you must
also upgrade the CSP Gateway on that machine.
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:
-
Make sure that the current manager’s directory contains a valid
license key file. The
%SYSCONV utility starts several processes
to speed conversion of the databases, if permitted by your license type.
-
If you use National Language Support (NLS), configure your locale
properly on Caché before running the ISM conversion utility. After the upgrade,
you need to define any proprietary NLS tables you may have again.
To run the system conversion utility:
-
Start Caché, ensuring that no other users have access to Caché
during the conversion.
To disable other logins from Windows:
-
Start the Caché Control Panel (by clicking on the Caché
Cube and selecting it from the menu).
-
Right-click on the Caché installation and click
.
This displays the
System Properties dialog box.
-
-
At the Caché prompt, run the
%SYSCONV routine.
To convert all databases, change to the manager’s namespace,
%SYS,
and run:
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.
-
To check the status of the conversion, run:
Using GBLOCKCOPY for Upgrade Tasks
The
GBLOCKCOPY routine can be used to perform several tasks
associated with upgrading.
After you have performed the upgrade to Caché, you can use the
GBLOCKCOPY routine
to perform the following operations:
-
-
Convert other legacy databases to
CACHE.DAT databases.
-
Convert any 2-KB page size databases to 8-KB page size databases.
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.
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:
-
Get all users off the system.
-
Run
GBLOCKCOPY to copy the manager's database
to a different directory.
-
-
Copy the newly created database into the manager's directory.
-
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.
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:
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.
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 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.
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é.
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.
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.
The following limitations apply to Caché 5.0 or specific operating systems
running Caché:
-
-
Beginning with Caché 4.0, white space in Caché ObjectScript
is treated differently. This may cause customer code to receive syntax errors which
previously did not occur.
For example, in older versions, the expression:
If
1=0 **, did not receive a syntax error since the expression
1=0 is
never true and the rest of the line was not executed.
Now, with current white space behavior, that same expression is interpreted
as:
If 1=0**, which is indeed a syntax error.
Note:
InterSystems provides the
ZTRAP command to
force errors under specific conditions and does not recommend depending on a system's
handling of invalid code for error condition processing.
-
Any non-% variables used by embedded SQL statements within a Caché
ObjectScript procedure need to be added to the procedure's public variable list and
be
Newed within the procedure. While this is still a limitation
in Caché, a change has been made to the macro preprocessor to make it easier
to manually add these variables to the public and new lists.
When the
SQL Configuration setting
Retain SQL Statement as Comments in .INT Code is
Yes,
along with the SQL statement in the comment, the non-% variables used by the SQL statement
are listed in the comment text. This variable listing makes it easier to identify
and cut and paste the variable lists into the MAC code public list and a new list.
-
Distributed database capabilities, such as DCP, are not available
with new-format databases. This release offers ECP, which is distributed database
support for the new and old format databases.
-
Support for Unicode in global names is not yet fully operational and
should be avoided.
-
The F-DBMS is no longer included with this and subsequent Caché
releases. Instead, the F-DBMS is available from our Web site as a separate component.
-
CORBA is no longer supported.
-
Red Hat Linux 7.3 and 8.0 do not ship with the required version of
libg++.so.
You can confirm this by issuing the following command in the Caché bin directory:
$ ldd MQInterface.so
...
libg++-libc6.2-2.so.3 => not found
Before using the WebSphere MQ interface, you must create a symbolic link to
an existing library by issuing the following command in
/usr/lib:
# ln -s libg++.so.2.7.2.8 libg++-libc6.2-2.so.3
This may require root privileges.
-
The Caché RPM kit installs into
/usr/cachekit/5.0.
Your
/usr directory may be mounted read-only or may contain little
free space, so you may want to change the location. In Red Hat 8.0 (rpm-4.1-1.06),
there is a bug; the
--prefix,
--relocate, and
--badreloc RPM
relocation options are silently ignored. For example:
# rpm -ivh --prefix /usr/local/cachekit/5.0 cache-5.0-4.i386.rpm
Preparing... ### [100%]
1:cache ### [100%]
error: unpack of archive failed on file /usr/cachekit/5.0: cpio: mkdir failed
- Read-only file system
-
We
recommend that XP users follow these procedures to access mapped drives from the GUI
tools or from telnet sessions:
-
For remote mapped drives, enter the user name and password in your
configuration as before. In addition, edit the
ZSTU startup routine
and add this line for each drive you have mapped.
Set x=$zf(-1,"net use z: \\someshare")
-
For virtually mapped drives, add this line for each drive mapped with
the
subst command:
Set x=$zf(-1,"subst q: c:\somedir\someotherdir")
You cannot add more mappings after startup.
Important:
The above procedure is meant for development situations where only one user
is expected to log on to Windows, and the user name entered in your configuration
is the same user. In any other situation, such as a Terminal Server environment, the
results are unpredictable.
The following notice from Microsoft refers to this problem:
[Redirected Drives on Windows XP: On Windows XP, drive letters are not global
to the system. Each logon session receives its own set of drive letters A-Z. Thus,
redirected drives cannot be shared between processes running under different user
accounts. Moreover, a service (or any process running within its own logon session)
cannot access the drive letters established within a different logon session.]
Another approach to using the mapped drives is to start Caché like this:
\cachesys\bin\ccontrol start configname
With this approach you do not have to add anything to the
ZSTU routine,
and you do not have to enter a user name and password. In addition, drives you map
or map with a path using the
subst command after startup are
available. The limitation of this approach is that Caché only runs as long
as the user that starts Caché stays logged on.