Skip to main content
Previous sectionNext section

Upgrading InterSystems IRIS

This chapter is intended for customers who are upgrading from an earlier version of InterSystems IRIS® data platform.

Important:

Before upgrading, review the following documents:

Before Upgrading

The following upgrade tasks are necessary regardless of the platform on which you are upgrading and running InterSystems IRIS. Perform these tasks before you run the InterSystems IRIS upgrade procedures:

Note:

If you are upgrading to a Maintenance Release, the tasks marked with an asterisk (*) are optional. However, performing all task will ensure optimum performance.

  1. Read Upgrade Specifics in the chapter “General Upgrade Information” in the InterSystems IRIS Release Notes — Follow any specific recommendations that should be performed before installing.

  2. Read the InterSystems IRIS Data Platform Supported Platforms for the version of InterSystems IRIS to which you are updating — Check that your technologies are supported in the new version of InterSystems IRIS.

  3. Ensure that all source code for the application is available* — After an major upgrade, you must recompile all code under the new version of InterSystems IRIS or else provide code that has already been compiled under the new version. Otherwise, you will not be able to run your application after the upgrade.

    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).

  4. Save custom classes, routines and globals* — 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 and IRISTEMP databases are completely replaced.

  5. Save user files* — 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.

  6. Decide whether to create an installation manifest* — 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.

  7. Precompile any user code that runs on startup* — 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 of InterSystems IRIS 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.

  8. Obtain an updated license key* — See the “Managing InterSystems IRIS Licensing” chapter of the System Administration Guide for more information.

  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 the “Introduction to Data Integrity” chapter of Data Integrity Guide.

  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 the “Backup and Restore” chapter of Data Integrity Guide.

  11. Stop all Productions — If your system is running any productions, follow the instructions in the Stopping a Production section of the “Starting and Stopping Productions” chapter in Managing Productions.

Upgrading an Instance

This section describes the procedure to upgrade a single instance of InterSystems IRIS. Before proceeding, be sure to perform the tasks in the Before Upgrading section of this chapter. If you are upgrading a mirror or ECP configuration, also review the information in the Upgrading a Mirror and Upgrading ECP Configurations sections of this chapter.

The procedure you should follow depends on your operating system:

If you are using a manifest as part of your upgrade process, see the instructions in Creating and Using an Installation Manifest before performing the standard installation steps.

Caution:

Prior to beginning an upgrade of an InterSystems IRIS instance, it is essential that the instance be shut down cleanly. To verify that the shutdown was clean, examine the messages.log file after the shutdown finishes. If the log contains entries similar to the following, then the shutdown was clean:

...
05/03/19-14:24:13:234 (5204) 0 Journal restore not required at next startup
05/03/19-14:24:13:234 (5204) 0 Transaction rollback not required at next startup
...

If these entries are not present, the instance did not shut down cleanly. Please contact the InterSystems Worldwide Response Center before proceeding with the upgrade.

Windows Upgrade Procedure

The installer provides all the functionality required to upgrade to a new version of InterSystems IRIS. To instead perform a silent upgrade, which is necessary when using a manifest, review the information in the Running an Unattended Upgrade or Reinstall section of the “Installing InterSystems IRIS on Microsoft Windows” chapter of this guide.

To perform the upgrade:

  1. Double-click the installer file, for example, IRIS-win_x64.exe.

  2. The installer displays a list of all existing InterSystems IRIS instances on the host. Select the name of the instance you want to upgrade and click OK.

  3. When prompted for an IRIS license key, click License and browse for the new iris.key file. If the installer detects a new key file in the install-dir/mgr directory, it proceeds without prompting you for the license key.

  4. After the installer validates the license key, click Upgrade.

    Important:

    Do not interrupt the installation while it is in progress. If the upgrade fails with any error messages, correct the issues and restart the upgrade installation.

  5. After the upgrade is completed, click Finish.

  6. Examine messages.log, iboot.log, and ensinstall.log in the install-dir\mgr directory for any errors. If any fatal error is found, correct the error, and then run the installer again.

Important:

If your operating system is configured to use large memory pages, check the startup messages to make sure shared memory is being allocated in accordance with these settings. If you see a message similar to the following, reboot your server to avoid an out-of-memory situation.

Failed to allocate 592MB shared memory using large pages.  Switching to small pages.
Copy code to clipboard

UNIX®, Linux, and macOS Upgrade Procedure

The installation script, irisinstall, provides all the functionality required to upgrade to a new version of InterSystems IRIS. To instead perform a silent upgrade, review the information in the Unattended InterSystems IRIS Installation section of the “Installing InterSystems IRIS on UNIX®, Linux, and macOS” chapter of this guide.

Note:

If the profile of the user executing irisinstall has a value set for the CDPATH variable, the upgrade fails.

To perform the upgrade:

  1. If your installation kit is in the form of a .tar file, you must first uncompress it (see the “Uncompress the Installation Kit” section in the “Installing InterSystems IRIS on UNIX®, Linux, and macOS” chapter of this book).

  2. As a user with root privileges, start the installation procedure by running the irisinstall script, located at the top level of the installation files:

    # sudo sh /<pathname>/irisinstall
    
    Copy code to clipboard

    where <pathname> is the location of the installation kit, typically the temporary directory to which you have extracted the kit.

  3. The script displays a list of all existing InterSystems IRIS instances on the host.

  4. At the Enter instance name: prompt, type the name of the InterSystems IRIS instance you want to upgrade, and press Enter.

  5. When prompted for a license key file, type keypath\iris.key, where keypath is the location of the new iris.key file. If the installation script detects the new license key in the install-dir/mgr directory, the script proceeds without prompting you for the license key file.

  6. The installation script summarizes the upgrade options and again asks you to confirm the upgrade. Press Enter to continue with the upgrade.

    Important:

    Do not interrupt the installation while it is in progress. If the upgrade fails with any error messages, correct the issues and restart the upgrade installation.

  7. Examine messages.log, iboot.log, and ensinstall.log in the install-dir/mgr directory for any errors. If any fatal error is found, correct the error, and then run the installation script again.

After the upgrade finishes, the instance restarts and any installation manifest is run.

Important:

If your operating system is configured to use huge memory pages, check the startup messages to make sure shared memory is being allocated in accordance with these settings. If you see a message similar to the following, reboot your server to avoid an out-of-memory situation.

Failed to allocate 1468MB shared memory using Huge Pages. Startup will retry with standard pages.
Copy code to clipboard

Upgrading a Mirror

This section provides instructions for upgrading InterSystems IRIS instances, an application, or both on the members of an InterSystems IRIS mirror.

As noted in the “Mirroring” chapter of the InterSystems IRIS High Availability Guide, all failover and DR async members of a mirror must be of the same InterSystems IRIS version, and can differ only for the duration of an upgrade. Once an upgraded member becomes primary, you cannot make use of the other failover member and any DR async members (and in particular cannot allow them to become the primary) until the upgrade is completed.

Mirroring does not require reporting async members to be of the same InterSystems IRIS version as the failover members, although application functionality may require it; for more information, see InterSystems IRIS Instance Compatibility in the “Mirroring” chapter of High Availability Guide.

There are four mirror upgrade paths to choose from. To determine which procedure you should follow, review the factors in the Choosing Mirror Upgrade Procedure section below. The four procedures are located in the Mirror Upgrade Procedures section below.

Also review the following two sections about upgrading a mirror:

Important:

On Linux systems supporting systemd, although it is possible to use either systemctl commands or the /etc/init.d/ISCAgent script to manage the ISCAgent, you must choose one method and use it exclusively; the ISCAgent should always be stopped using the method with which it was started. For more information, see Starting the ISCAgent on Linux Systems in the “Mirroring” chapter of the InterSystems High Availability Guide.

When you upgrade InterSystems IRIS on such a Linux system, a running ISCAgent is automatically restarted using systemd. If you are using the /etc/init.d/ISCAgent script to manage the ISCAgent, stop the agent before performing the upgrade so that it is not automatically restarted, then restart it using the script after the upgrade.

Choosing Mirror Upgrade Procedure

There are two primary factors to consider in choosing the procedure appropriate for your mirror upgrade:

  • Are you upgrading to a maintenance release of the installed version of InterSystems IRIS, or to a new major version of InterSystems IRIS?

  • Does the upgrade involve changes to mirrored databases?

Whenever you upgrade to a maintenance release and are not making any application upgrades, you do not have to consider the second question; you can always use the simple Maintenance Release Upgrade procedure, which renders the mirror unavailable only for the time it takes to execute a planned failover.

However, when you upgrade from one major InterSystems IRIS version to another, perform application upgrades, or both, there is the possibility that your upgrade involves changes to mirrored databases. Such changes must occur on the functioning primary failover member as part of the upgrade procedure, while application access is disabled. As a result, the upgrade requires more downtime than if you are not making any mirrored database changes. (The changes are then replicated by the mirror on the backup and any async members.)

Important:

Following a major upgrade, InterSystems recommends that you recompile all classes in all application namespaces on the instance and some routines must also be recompiled (see Upgrade Specifics in the chapter General Upgrade Information in the InterSystems IRIS Release Notes). Any application upgrade you perform may require changes to application data. In either of these situations, your upgrade may result in changes to mirrored databases.

If you are upgrading to a major release, are performing application upgrades, or both, you must determine whether any of the following conditions apply:

  • Classes and routines are stored in mirrored databases that also contain application data; these must be recompiled on the primary (even if the application has not been upgraded).

  • Data in mirrored databases must be upgraded due to an application upgrade; these changes must take place on the primary.

If your major upgrade and/or application upgrade involves any of these conditions, use the Major Version Upgrade (Mirrored Database Changes) procedure, which renders the mirror unavailable only for the time it takes to execute a planned failover and make the required mirrored database changes.

If your upgrade does not involve any of the listed mirrored database changes, consider the Major Version Upgrade (No Mirrored Database Changes) procedure, which renders the mirror unavailable only for the time it takes to execute a planned failover.

If you have a significant planned maintenance window and minimizing mirror downtime is not a major concern, you may choose to use the simpler Major Version Upgrade with Planned Downtime procedure instead.

In the case of major upgrades, the general sequence of each procedure applies to upgrades of the mirror’s InterSystems IRIS instances, application code, or both; adapt individual steps depending on what you are upgrading.

Note:

Your circumstances may call for additional steps and details in a given procedure. If you are still unsure which procedure is appropriate for you, or whether a particular procedure is appropriate as stated, please contact the InterSystems Worldwide Response Center (WRC).

Adding Mirror Members During an Upgrade

If you plan to add members to a mirror, you may want to defer this until you plan to perform one of the upgrades described in this section and add members of the new version during the upgrade, so that you do not have to upgrade them later. You can always add members of a newer version to a mirror during an upgrade, provided you immediately continue with and complete the upgrade as described, with one restriction: once a member of the newer version becomes primary, it must remain primary until all other members have been upgraded.

Adding new members during an upgrade can be very helpful when migrating a mirror to new hardware. Rather than upgrading one of the failover members before failing over to it, you can install a new instance of the new version on the target system, add it to the mirror as a DR async member, promote it to backup and then fail over to it, thus migrating the mirror primary to the new system. By repeating this technique you can then migrate the remaining failover member. The procedures in this section include steps for adding a new backup of the new version as an alternative to upgrading the existing backup, to illustrate this approach.

Mirror Upgrade Terms

In the procedures in this section, the following terms are used:

Upgrade classes and routines

Recompile all classes in all application namespaces on the instance. This should be done after an InterSystems IRIS major version upgrade (as described in Post-Upgrade Tasks) and/or application upgrade, which may involve one or more of the following operations, depending on your situation:

  • As noted in the foregoing, when classes and routines exist in any mirrored database that also contains application data, they must be recompiled locally on the functioning primary failover member (regardless of whether they are modified by an application upgrade).

  • Classes and routines stored in nonmirrored routines databases that are separate from application data can be recompiled on a mirror member regardless of whether it is the current primary.

  • Classes and routines stored in separate nonmirrored routines database can also be “precompiled” by recompiling a copy of the database on a system that has already been upgraded to the target InterSystems IRIS release, then distributed to each mirror member following the upgrade.

System A

The mirror member that is initially the primary failover member.

System B

The mirror member that is initially the backup failover member.

System C

A newly-added DR async of the new InterSystems IRIS version that has been promoted to failover member.

Set no failover

Use the ^MIRROR routine to set the no failover state so that failover cannot occur; see Avoiding Unwanted Failover During Maintenance of Failover Members in the “Mirroring” chapter of the InterSystems IRIS High Availability Guide for instructions.

Perform a graceful shutdown

Use the iris stop command to shut the instance down cleanly (see Controlling InterSystems IRIS Instances in the “Using Multiple Instances of InterSystems IRIS” chapter of the InterSystems IRIS System Administration Guide).

Promote to failover member

Follow the procedure for promoting a DR async mirror member to failover member as described in Promoting a DR Async Member to Failover Member in the “Mirroring” chapter of the InterSystems IRIS High Availability Guide.

Viewing the Mirror Monitor

Use the Mirror Monitor page in the instance’s Management Portal to review the status of the mirror and its members; see Using the Mirror Monitor in the “Mirroring” chapter of the InterSystems IRIS High Availability Guide for more information.

Mirror Upgrade Procedures

There are four mirror upgrade paths to choose from. To determine which procedure you should follow, review the factors in the Choosing Mirror Upgrade Procedure section. The four procedures are:

The first three procedures are designed to let you perform the upgrade you need with the shortest possible application downtime; they differ to accommodate different upgrade circumstances. The last, which is a bit simpler, can be used for any type of upgrade when minimizing downtime is not a priority.

Maintenance Release Upgrade

If you are upgrading to an InterSystems IRIS maintenance release rather than a new major InterSystems IRIS version and are not making any application changes, use the following procedure, which renders the mirror unavailable only for the time required to execute a planned failover:

  1. To prevent failover from occurring until the backup is fully upgraded, set no failover.

  2. Perform one of the following two operations:

    • Upgrade the existing backup:

      1. Perform a graceful shutdown of the backup (B).

      2. Upgrade the backup (B) with the new version of InterSystems IRIS. System B becomes backup.

    • Add a new backup of the new version:

      1. Install the new version of InterSystems IRIS on system C.

      2. Add system C to the mirror as a DR async member.

      3. Promote system C to failover member. System C becomes backup and System B becomes a DR async.

  3. Ensure that the backup (B or C) has become active by viewing the Mirror Monitor.

  4. Clear no failover.

  5. Perform a graceful shutdown of the primary (A). The mirror fails over and the backup (B or C) takes over as primary.

  6. Upgrade system A with the new version of InterSystems IRIS. System A becomes backup.

  7. If system C became primary and system B was demoted to DR async, upgrade system B.

Major Version Upgrade (Mirrored Database Changes)

If you are upgrading to a new major InterSystems IRIS version and/or performing an application upgrade and have determined that changes to mirrored databases are required (as described in Choosing a Mirror Upgrade Procedure), use the following procedure, which renders the mirror unavailable only for the time it takes to execute a planned failover and make the required mirrored database changes:

  1. To prevent failover from occurring until the backup is fully upgraded, set no failover.

  2. Perform one of the following two operations:

    • Upgrade the existing backup:

      1. Perform a graceful shutdown of the backup (B).

      2. Upgrade the backup (B) with the new version of InterSystems IRIS. System B becomes backup.

      3. Upgrade nonmirrored classes and routines on system B, if any.

    • Add a new backup of the new version:

      1. Install the new version of InterSystems IRIS on system C.

      2. Add system C to the mirror as a DR async member.

      3. Promote system C to failover member. System C becomes backup and System B becomes a DR async.

  3. Ensure that the backup (B or C) has become active by viewing the Mirror Monitor.

  4. Disallow new user access to the mirror using established practices at your site. Additionally, you must disable any application jobs that would normally start on system B when it becomes primary.

  5. Clear no failover.

  6. Perform a graceful shutdown of the primary (A). The mirror fails over and the backup (B or C) takes over as primary

  7. Upgrade mirrored classes and routines on the new primary (B or C). If an application upgrade requires further changes to mirrored databases, make these changes.

  8. Restore user access to the mirror.

  9. To prevent system A from taking over as primary until fully upgraded, set no failover

  10. Upgrade system A with the new version of InterSystems IRIS. System A becomes backup.

  11. Upgrade nonmirrored classes and routines on system A, if any.

  12. Clear no failover.

  13. If system C became primary and system B was demoted to DR async, upgrade system B and upgrade nonmirrored classes and routines on system B, if any.

Major Version Upgrade (No Mirrored Database Changes)

If you are upgrading to a new major InterSystems IRIS version and/or performing an application upgrade and have determined that changes to mirrored databases are not required (as described in Choosing a Mirror Upgrade Procedure), you may be able to use the following procedure.

This procedure is simplest for static applications where separate nonmirrored routines databases are always maintained. It can, however, be used even if the separate routines databases are normally mirrored by removing these databases from the mirror for the duration of the upgrade.

Important:

If the routines databases are normally mirrored, ensure that they do not contain any application data before removing them from the mirror.

This procedure cannot be used with normally mirrored routines databases if ECP application servers connect to the mirror.

  1. Enact a code freeze and application configuration freeze to disallow application changes during the upgrade, using established procedures at your site, to ensure that routines databases are not modified during the upgrade.

  2. To prevent failover from occurring until the backup is fully upgraded, set no failover.

  3. Perform one of the following two operations:

    • Upgrade the existing backup:

      1. If the routines databases are mirrored, remove them from the mirror on system B.

      2. Ensure that the backup (B) has become active by viewing the Mirror Monitor.

      3. Perform a graceful shutdown of the backup (B).

      4. Upgrade the backup (B) with the new version of InterSystems IRIS. System B becomes backup.

      5. Upgrade classes and routines on system B.

    • Add a new backup of the new version:

      1. Install the new version of InterSystems IRIS on system C.

      2. Add system C to the mirror as a DR async member.

      3. Promote system C to failover member. System C becomes backup and System B becomes a DR async.

      4. If the routines databases are mirrored, remove them from the mirror on systems C and B.

      5. Ensure that the backup (C) has become active by viewing the Mirror Monitor.

  4. Clear no failover.

  5. Perform a graceful shutdown of the primary (A). The mirror fails over and the backup (B or C) takes over as primary.

  6. To prevent system A from taking over as primary until fully upgraded, set no failover.

  7. Upgrade system A with the new version of InterSystems IRIS. System A becomes backup.

  8. Upgrade any nonmirrored classes and routines on system A.

  9. If system C became primary and system B was demoted to DR async, upgrade system B and upgrade nonmirrored classes and routines on system B, if any.

  10. For any mirrored routines databases that you removed from the mirror on backup (B or C) before it became the new primary, do the following:

    1. Remove the routines databases from the mirror on system A.

    2. Add the databases to the mirror on the new primary (B or C), then back them up and restore them on the backup (A) and DR async (B, if C is the primary), using the procedures for adding an existing database to a mirror provided in Adding Databases to a Mirror in the “Mirror” chapter of the InterSystems IRIS High Availability Guide. Retain these backups, as they represent the first backups of newly-added mirrored databases; older backups made prior to the upgrade cannot be used to restore these databases in the event of disaster.

  11. Clear no failover.

Major Version Upgrade with Planned Downtime

If you are upgrading to a new major InterSystems IRIS version and/or performing an application upgrade and have a significant planned maintenance window that obviates the need to minimize mirror downtime, you may prefer to use the following simpler procedure, regardless of whether changes to mirrored databases on the primary are required:

  1. Disallow all user access to the mirror using established practices at your site. Additionally, you must disable any application jobs that would normally start on instance startup.

  2. Perform a graceful shutdown of the backup (B).

  3. Perform a graceful shutdown of the primary (A).

  4. Upgrade system A with the new version of InterSystems IRIS. System A becomes primary.

  5. Upgrade mirrored classes and routines on system A. If an application upgrade requires further changes to mirrored databases, make these changes.

  6. Upgrade nonmirrored classes and routines on system A, if any.

  7. Perform one of the following two operations:

    • Upgrade the existing backup:

      1. Upgrade system B with the new version of InterSystems IRIS. System B becomes backup.

      2. Upgrade nonmirrored classes and routines on system B, if any.

    • Add a new backup of the new version:

      1. Install the new version of InterSystems IRIS on system C.

      2. Add system C to the mirror as a DR async member.

      3. Promote system C to failover member. System C becomes backup.

      4. Upgrade system B with the new version of InterSystems IRIS. System B becomes a DR async.

      5. Upgrade nonmirrored classes and routines on system B, if any.

  8. If system C became primary and system B was demoted to DR async, upgrade system B and upgrade nonmirrored classes and routines on system B, if any.

  9. Restore user access to the mirror.

Upgrading ECP Configurations

In general, ECP application servers should be upgraded before the data servers they connect to. Application servers must have either local routines databases to recompile following upgrade or access to “precompiled” routines database (previously recompiled on a separate system running the target InterSystems IRIS version) on the data server.

Downtime can be minimized using rolling upgrades with users connecting to both upgraded and unupgraded application servers as well as the database server if one of the following is true:

  • There are no application changes.

  • There are application changes, but the new code does not generate any new data structures, meaning that old code can work with data generated by new code.

If the new application code can work against old data, but can generate new data structures not understood by the old code, follow this procedure:

  1. Upgrade the application servers on a rolling basis, but do not allow users to connect to an application server once it is upgraded. (Application server capacity is gradually reduced.)

  2. When enough application servers have been upgraded, restore user access to the upgraded application servers and end all user connections to the remaining (not upgraded) application servers and the data server (if need be), ensuring that users have no access to these systems until you enable it.

  3. Upgrade the remaining application servers, restoring user access to each application server after it is upgraded.

  4. Upgrade the data server and restore user access as needed. (Upgrading the data server causes a pause in application activity, the length of which depends on the amount of downtime involved in the upgrade.)

If you have questions or concerns about how to upgrade your ECP configuration, please contact InterSystems Worldwide Customer Support (WRC).

Post-Upgrade Tasks

The post-upgrade tasks required depend on whether you have upgraded to a new major version of InterSystems IRIS or to a maintenance release of the installed version.

Note:

If you changed an instance from 8–bit to Unicode during the upgrade, InterSystems IRIS does not automatically convert your databases. You need to do this conversion yourself; for more information, see the Database Portability section in the “Namespaces and Databases” chapter of Orientation Guide for Server-Side Programming.

Maintenance Release Post-Upgrade Tasks

When the upgrade is complete, if your system runs any productions, follow the instructions in the Starting a Production section of the “Starting and Stopping Productions” chapter in Managing Productions to restart the productions.

Typically, maintenance release upgrades do not require you to change external files and clients, or to recompile classes and routines. However, the Studio version on a client must be the same or later than the InterSystems IRIS server version to which it connects.

If you choose to recompile, review the information in the Major Version Post-Installation Tasks section.

Major Version Post-Installation Tasks

After upgrading InterSystems IRIS to a new major version, it is important to follow the guidance provided in the Upgrade Specifics section in the “General Upgrade Information” chapter of InterSystems IRIS Release Notes. You must also perform the following tasks (if you have not already done so as part of one of the previous procedures in this chapter):

  • Recompile Classes and Routines — InterSystems recommends that customers recompile all classes contained in each namespace. Some routines also require recompilation. See the How to Compile Namespaces section below for instructions. You may have your own tools and procedures for this purpose, taking into account any dependencies and other needs particular to the instance that was upgraded.

  • Regenerate Proxy Classes — You must regenerate any proxy classes you had generated in the upgraded instance by following the instructions in the appropriate guides in the InterSystems IRIS Language Bindings set.

    This item does not apply to web services and web clients; it is not necessary to re-import any Web Service Definition (WSDL) files.

  • Clear browser cache — Your browser cache may contain JavaScript files that are no longer compatible with the installed version of InterSystems IRIS and may cause errors; clear your browser cache immediately after completing the upgrade.

The following tasks may be necessary depending on your environment and the components you use:

  • Restart Productions — If your system runs any productions, follow the instructions in the Starting a Production section of the “Starting and Stopping Productions” chapter in Managing Productions.

  • Upgrade Studio Clients — The Studio version on a client must be the same or later than the InterSystems IRIS server version to which it connects.

  • Upgrade Web Gateway — If your Web Gateway is on a separate machine from the InterSystems IRIS server you are upgrading, you must also upgrade the Web Gateway on that separate machine. You can accomplish this by following the Windows Upgrade Procedure in this chapter, or performing a silent installation with the ADDLOCAL property as discussed in Running an Unattended Installation section of the “Installing InterSystems IRIS on Microsoft Windows” chapter of this book.

  • Update web server files — Following upgrades you must deploy these using established practices at your site.

How to Compile Namespaces

After an upgrade, you must compile the code in each namespace so that it runs under the new version of InterSystems IRIS. If the compiler detects any errors, you may need to re-compile one or more times for the compiler to resolve all dependencies.

After your code compiles successfully, you may want to export any updated classes or routines, in case you need to run the upgrade in any additional environments. Importing these classes or routines during future upgrades allows you to update your code quickly, minimizing downtime.

Note:

If you are using a manifest as part of your upgrade process, you can compile your code from within the manifest. See the instructions in the Perform Post-Upgrade Tasks section of the Creating and Using an Installation Manifest appendix of this guide.

Compiling Classes

To compile the classes in all namespaces from the Terminal:

do $system.OBJ.CompileAllNamespaces("u")
Copy code to clipboard

To compile the classes in a single namespace from the Terminal:

set $namespace = "<namespace>"
do $system.OBJ.CompileAll("u")
Copy code to clipboard
Compiling Routines

Only custom routines need to be compiled manually. Routines generated from classes are compiled automatically when you compile the classes.

To compile the routines in all namespaces from the Terminal:

do ##Class(%Routine).CompileAllNamespaces()
Copy code to clipboard

To compile the routines in a single namespace from the Terminal:

set $namespace = "<namespace>"
do ##Class(%Routine).CompileAll()
Copy code to clipboard