Pre-Upgrade Steps

Step 1: Review Incompatibilities

Review the following documents and prepare to address any incompatibilities:

• InterSystems Upgrade Impact ChecklistOpens in a new tab (or the Incompatibility HistoryOpens in a new tab) — a list of incompatibilities between versions that may affect your release.

• Special Considerations When Upgrading — a list of considerations particular to upgrading this specific version.

• InterSystems Supported Platforms — the supported platforms for this version. Your technologies should be checked against this to determine if they are still supported.

Step 2: Confirm Source Code Availability

Optional for Maintenance Releases

After a major upgrade, you must recompile all class code under the new version or else provide class code that has already been compiled under the new version. Otherwise, you will not be able to run your application after the upgrade. It is recommended that you recompile any routine code.

Check that you have the code for any classes running in deployed mode (which you can place under deployed mode again when the upgrade is complete), as well as the code for custom routines not generated from classes (*.mac or *.int).

Step 3: Save Custom Classes, Routines, and Globals

Optional for Maintenance Releases

On an upgrade, the IRISSYS database is modified. To prevent your own classes, 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.

Similarly, on an upgrade, the IRISLIB, IRISTEMP, and ENSLIB databases are completely replaced.

Step 4: Save User Files

Optional for Maintenance Releases

To ensure that your user files are not deleted or replaced during the upgrade, save them in the install-dir\mgr\User directory, which is the only directory that is not subject to modification during an upgrade.

Step 5: Examine Huge/Large Page Allocations

On Linux and AIX® systems, the huge/large page allocation must be greater than the shared memory allocation; otherwise, your system will not use huge/large pages which can cause performance issues.

If your current huge/large pages allocation is exactly equal to your system’s shared memory allocation, you should reallocate huge/large pages before upgrading, adding several additional MB, to account for any upward change in shared memory allocation between versions. For details, see Configuring Huge and Large Pages.

Step 6 (Optional): Create an Installation Manifest

Optional for All Releases

A manifest is useful for silent installs, as you can invoke the post-upgrade tasks to run as soon as the upgrade is complete, eliminating the need for interactive steps. See Creating and Using an Installation Manifest for more information.

Step 7: Precompile User Code That Runs on Startup

Optional for Maintenance Releases

If your application calls any user code at instance startup (using %ZSTART, ZAUTHENTICATE, or other means), you must precompile it on an instance of the new version and use an installation manifest to install it as part of the upgrade process. If you do not, the instance will fail to start up.

Step 8: Obtain an Updated License Key

Optional for Maintenance Releases

See Managing InterSystems IRIS Licensing for more information.

Step 9: Check System Integrity

Run a system integrity check on existing directories to ensure there is no corruption in any of the databases. For more information, see Introduction to Data Integrity.

Step 10: Back up the System

Before upgrading, InterSystems recommends that you run a complete backup of your system using your customary full operating system backup procedures. If the upgrade is not successful, you may need to restore from this backup. For information about backups, see Backup and Restore.

Step 11: Stop Productions and Disable Auto-Start

If your system is running any productions, follow the instructions in Stopping a Production and disable auto-start so that you can recompile code before starting productions up again.