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. Also note the following points:
-
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.
-
It is not necessary to re-import any OpenAPI 2.0 specificationOpens in a new tab files.
-
It is not necessary to re-import any Web Service Definition (WSDL) files.
-
Cached queries are always purged during upgrade. They are recompiled and cached as needed.
-
If you did not configure your web server automatically during the installation process, you will need to connect it manually.
-
If your web server is using a port number other than 80, you will need to change the CPF WebServerPort and WebServerURLPrefix parameters to your web server’s port number in order to connect with your IDE.
-
If you upgraded from an instance with a private web server (2023.1 or older), you should disable and remove the private web server.
-
If you are on Linux or AIX® and are using huge or large pages, confirm that they are still being used:
In the <install-dir>/mgr/messages.log file, confirm there is a message indicating shared memory has been allocated using huge or large pages.
If huge/large pages are not enabled, you may need to adjust the allocation to account for increases in shared memory with the new version. After reallocating, restart your system to allow the changes to take effect. See Configuring Huge and Large Pages for details on this process.
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.
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 General Upgrade Information in the 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 and all routines in each namespace. See How to Compile Namespaces 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.
-
Recompile %SYS classes and routines — The %SYS namespace is skipped by default when compiling all classes and routines. Make sure you recompile this namespace as well. See How to Compile Namespaces for instructions. Only classes and routines beginning with “Z”, “z”, “%Z”, or “%z” will be preserved on upgrade. These classes and routines cannot be precompiled.
-
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:
-
Review query plans. When you upgrade to a new major version, existing Query Plans are automatically frozen. This ensures that a major software upgrade will never degrade the performance of an existing query. For performance-critical queries, you should test if you can achieve improved performance.
-
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 the 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 Windows Unattended Installation.
-
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 recompile 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.
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")
To compile the classes in a single namespace from the Terminal:
set $namespace = "<namespace>"
do $system.OBJ.CompileAll("u")
To compile the classes in the %SYS namespace from the Terminal:
set $namespace = "%SYS"
do $system.OBJ.CompileList("%Z*,%z*,Z*,z*","up")
If your namespaces contain mapped classes, include the /mapped qualifier in the call to CompileAllNamespaces() or CompileAll():
do $system.OBJ.CompileAllNamespaces("u /mapped")
do $system.OBJ.CompileAll("u /mapped")
Class compiler version utility
To assist customers in determining which class compiler version a class or classes in a namespace have been compiled with, InterSystems provides two assists
-
Method – $System.OBJ.CompileInfoClass(<classname>)
This method returns the version of the class compiler used to compile this <classname> and the datetime the class was compiled
-
Query – $System.OBJ.CompileInfo(<sortby>)
This query generates a report for the current namespace that includes all classes, the version of the compiler used to compile each one, and the datetime each was compiled. The first argument <sortby> may have the following values:
-
0 – the time the class was compiled
-
1 – the class name
-
2 – the version of InterSystems IRIS the class was compiled in
-
Compiling Routines
To compile the routines in all namespaces from the Terminal:
do ##Class(%Routine).CompileAllNamespaces()
To compile the routines in a single namespace from the Terminal:
set $namespace = "<namespace>"
do ##Class(%Routine).CompileAll()
To compile the routines in the %SYS namespace from the Terminal:
set $namespace = "%SYS"
do ##Class(%Routine).CompileList("%Z*,%z*,Z*,z*","up")