Skip to main content

Upgrade Compatibility Checklist for InterSystems IRIS 2021.1

This article lists the features of the 2021.1 release of InterSystems IRIS® that, because of their difference in this version, affect the administration, operation, or development activities of existing systems.

Some of these differences do not apply if you are upgrading from a 2020.1 maintenance release or a 2020.2, 2020.3, or 2020.4 continuous delivery release. These are indicated in the descriptions. Customers upgrading their applications from earlier releases are strongly urged to read the upgrade checklist for the intervening versions as well.

Customers upgrading their applications from earlier releases are strongly urged to read the upgrade checklist for the intervening versions as well.

The following sections contain the checklists for Administrators and Developers. Since developers typically administer their own systems, they should also read the section for administrators, especially the Issues Upgrading from Version 2020.2, 2020.3, or 2020.4 Due to TLS Changes.


This section contains information of interest to those who are familiar with administering prior versions of InterSystems IRIS and wish to learn what is new or different in this area for version 2021.1.

Issues Upgrading from Version 2020.2, 2020.3, or 2020.4 Due to TLS Changes

InterSystems IRIS 2020.2 through 2020.4 contained the new OpenSSLOpens in a new tab 1.1.1 security libraries with TLS 1.3, but this library is not in 2021.1. On some platforms we discovered that there were conflicts with older versions of the libraries installed by the operating system or other applications. Consequently, we have removed TLS 1.3 from this release. We will include TLS 1.3 support in a future release in a way that will avoid conflicts caused by having multiple versions of the library installed on the system.

This downgrade of the SSL libraries means upgrading from version 2020.2, 2020.3, or 2020.4 to version 2021.1 requires switching your instance to an earlier version of TLS. In addition to incompatible TLS API changes, there are significant configuration changes between TLS 1.2 and TLS 1.3. You would have to revert API changes and undo multiple configuration settings in order to successfully downgrade from TLS 1.3 to TLS 1.2. Depending on how you deployed your instance, this may or may not be possible. (If you are upgrading from 2020.1 or earlier, you may disregard this section.) You could also defer upgrading until TLS 1.3 support is included in a future release.

Upgrading a containerized instance running version 2020.2, 2020.3, or 2020.4 involves additional steps. When you upgrade the container to version 2021.1, the upgraded container will have no enabled protocols rendering it non-operational. To complete the upgrade, you must enable the protocols, as described below:

  1. Back up your configurations to have a record of which protocols are enabled.


    In releases 2020.2, 2020.3, and 2020.4, protocol values are stored using TLSMinVersion and TLSMaxVersion. These properties along with the Protocols property are stored and exported as bitmap values, as described in Configuration Definitions.

  2. Perform the container upgrade as usual. When finished, the new container is non-operational.

  3. Enable the necessary protocols recorded in the first step. Once you do, the container is operational once more.


Although Continuous Delivery (CD) releases are usually available in containers only, some customers have received installer kits for server platforms of 2020.2, 2020.3, and 2020.4. If you attempt to upgrade one of these instances to 2021.1, the installer will not allow you to proceed. It is possible to do a clean install of 2021.1 and then move your configuration information and databases to the new instance. Contact InterSystems Worldwide Response CenterOpens in a new tab (WRC) for more information about this procedure.

New External Language Servers Page Replaces Gateway Pages

In the management portal, the new External Language Servers page replaces the following pages:

  • Object Gateways

  • JDBC Gateways

  • XSLT Gateways

To access the new page, click System Administration > Configuration > Connectivity > External Language Servers. For details on the new page, see Managing External Server Connections.

Memory Usage Changes for Global and Routine Buffers

This release improves performance on newly installed systems where the database cache size has not been configured. Under most circumstances, you should carefully configure cache sizes and Configure Huge and Large Pages for optimal system performance. Configuring cache sizes is especially important for live production systems, systems with heavy loads, and systems with multiple instances.

However, when users initially evaluate InterSystems IRIS, they typically run it without configuring the database cache size. The new behavior in allocating memory on systems where cache size has not been configured is (first in 2020.3):

  1. When database cache (global buffers) is unspecified in the configuration, the instance auto-selects 25% of total physical memory for database cache. Previously, the calculation used 12.5% with an upper limit of 1GB (so effectively a flat 1GB for most systems). There is now no upper limit imposed. Additionally, this changes the calculation on Windows systems to be based on physical memory rather than "available" memory so that the behavior is consistent across restarts (and also consistent with Linux and UNIX® platforms).

    While this may result in a large allocation, If the instance isn't used to load a large amount of data, then most of this memory is not touched and, in most operating system environments, will not occupy physical memory. If the operating system has enough large pages available for this memory allocation, InterSystems IRIS will use them, and thus will occupy physical memory. In this case, however, that large page memory is known to be available. Control over use of large pages is available via the memlock configuration parameter.

  2. On startup, if database cache is unspecified, a message "Global buffer setting requires attention. Auto-selected 25% of total memory." will be emitted.

  3. Leaving routine cache (routine buffers) unspecified in the configuration no longer means a minimal amount routine cache (36MB) but instead is taken as 10% of the amount of global buffers with a minimum of 80MB and maximum of 1020MB. (More precisely, it's the number of global buffers multiplied by 8KB multiplie by 10%, so the simple 10% applies as long as only 8KB-size global buffers are used). This applies regardless of whether the database cache was configured or auto-selected as described above. In this way, most systems may be able to select only database cache size and leave routine cache size unaltered.

See Memory Management and Scaling for InterSystems IRIS for more information about memory management.

Cloud Containers Upgrade Checklist — Changes for the Arbiter Container with ISCAgent Using a Nondefault Port

The arbiter is an independent system hosting ISCAgent for mirror members (see Arbiter). By default ISCAgent uses port 2188. In previous releases you could specify a nondefault port by arguments such as $IRISSYS/ 2000, but in this release you must replace these arguments with -p 2000 to use port 2000. Using arguments other than -p will be ignored and the container will run with port 2188 (first in 2020.3).

InterSystems Cloud Manager (ICM) Upgrade Checklist

Only InterSystems API Manager (IAM) 1.5 and Later can be Used with ICM

In this release, ICM can only be used with the InterSystems API Manager (IAM) version 1.5 or later.

If you were using the Rancher or Weave Scope monitoring solutions with a previous ICM version, with this version you need to deploy these manually or use generic ICM commands.

The parameters in CPF have changed from the beta version. This change only impacts beta users of ICM.









JDBCGatewayPort Change

If you were overriding the JDBCGatewayPort parameter using the JSON field "JDBCGatewayPort", you should delete that parameter and instead do so directly in their custom CPF file (pointed to by "UserCPF"). For example:

%JDBC Server=JDBC,,53773

(first in 2020.3)

Installation Upgrade Checklist

Change to Default SuperServer Port

In this and future releases, the default SuperServer port is 1972. If this port is not available, then the default port will be 51773 or the next free port after this. This change was first in release 2020.3. In releases before 2020.3, the default SuperServer port was 51773.

If you are upgrading a system using the InterSystems Cloud Manager (ICM) and relied upon 51773, you may need to add the following override to your JSON defaults:

  "SuperServerPort": "51773"

If you are upgrading an instance of an earlier release with full installation kits on a server platform, this change does not impact you. The SuperServer port from the instance is preserved through the upgrade.

Installation Leaves Duplicate ODBC Driver on Windows

To allow both Caché and InterSystems IRIS to both exist on a system, the installer should not remove the Caché ODBC driver. On Windows a new InterSystems IRIS install may result in a duplicate entry for "IRIS ODBC Driver" in add/remove programs applet. You can safely uninstall the older "IRIS ODBC Driver".

How the Gateway Installer Treats an Existing CSP.ini File

In environments where a third party Web Server is running remotely, the Web Gateway installer tried to modify some settings in CSP.ini which could result in unwanted changes in terms of service accessibility. A review of the configuration after each upgrade was always recommended. In this release the Web Gateway installer will not modify an existing CSP.ini in any way. For details on configuring the web server and Web Gateway, see Configuring the Web Server and Web Gateway (first in 2020.2)

ISCAgent in Containers Upgrade Checklist

ISCAgent is now started automatically and is started on port 2188 by default in InterSystems IRIS containers. You can disable ISCAgent with "--ISCAgent false". You can control the port used with the new syntax "--ISCAgentPort <port>" instead of the previous syntax "--before /home/irisowner/irissys/ <port>".

Journaling Upgrade Checklist — ^JCONVERT Changes

^JCONVERT now creates and processes common journal files in the enhanced format, which supports long strings. It has a new prompt to control whether common journal files are created in the enhanced format or in the previous format. If you need to create common journal files that can be read by ^%JREAD or ^JCONVERT from a previous version, you must specify that you do not want the enhanced format.

Monitoring Upgrade Checklist — New Metrics in %Monitor.Process

This release has new metrics from %Monitor.Process and the counter index numbers have changed. The new metrics are MONBLKWAIT, MONBLKWAKE, MONMEMALLOC, and MONMEMFREE.

Tasks Upgrade Checklist — Task Termination Changes

In previous releases, tasks that were terminated by shutdown were marked as suspended. In this release, they are not marked as suspended by default. If you want tasks terminated by shutdown to be marked as suspended, set the new SuspendTerminated property.

Security Upgrade Checklist — Cannot Import Encryption Settings from Previous Releases

With this release, you cannot import security settings which were exported using ^SECURITY from a previous release; you must use the Management Portal to set the encryption settings. Also, if you export the system settings from this release, the encryption settings are not included; consequently, if you export system settings from this release and then import them into another instance of this release, you also must use the Management Portal to set the encryption settings.


This section contains information of interest to those who have designed, developed and maintained applications running on prior versions of InterSystems IRIS. Since developers typically administer development system, developers should also read the previous section for administrators.

The items listed here are brief descriptions. In most cases, more complete descriptions are available elsewhere in the documentation.

Object Gateway Changes

There are multiple changes in the Object Gateway:

  • The path to Java libraries on Windows and Linux has changed from IRIS\dev\java\lib\JDK18, to IRIS\dev\java\lib\1.8

  • The files needed for .NET Core 2.1 Gateway are IRISProviderCore21.dll and IRISGatewayCore21.dll

  • The files needed for .NET Core 2.1 PEX are IRISProviderCore21.dll, IRISGatewayCore21.dll, and IRISUtilsCore21.dll.

  • If you need to start these external language servers from the command line (as within a container), the commands for doing so have changed:

    dotnet IRISGatewayCore21.dll <PORT> "" "" ""
    java -Djava.system.class.loader=com.intersystems.gateway.ClassLoader -classpath <JARS> 
    com.intersystems.gateway.JavaGateway <PORT> "" "" ""
    python -m iris PythonGateway <PORT> "" "" ""

Business Intelligence Upgrade Checklist

Recompile Cubes

As part of a change to improve MDX query performance, this release stores certain cube-related data in a different location. This change requires that you recompile all cube classes that were created on a version prior to InterSystems IRIS 2021.1. If you do not recompile these classes, detail listings on those cubes will return no results.

If a cube is built using a temp table, you must recompile after upgrading before it is built or synchronized. A cube can be built using a temp table if the cube is built with a restriction on the maximum number of facts, has a build restriction, has an initial build order specified, or is based on a source table whose IdKey is not a positive integer.

In general, you should recompile all application code, including cubes, when you upgrade, but in these cases, not recompiling has known consequences.

Invalid Cube Names Cannot Be Compiled

In previous releases cube names that violated the documented rules could be successfully compiled though they may have caused other errors. In this release, these invalid cube names cause a compile error and must be corrected to successfully compile the cube (first in 2020.4).

Cube Detail Listing Access Change

If a business intelligence application relies on detail listing and the database is secured with SQL security, then the application must be running with SELECT privileges on the cube’s generated listing table (first in 2020.2). The default name for the generated listing table is cubeClassPackage_cubeClassName.Listing, such as HoleFoods_BudgetCube.Listing.

SQL and Web Service Projections Adopt New Terminology

This release adopts new terminology replacing master/slave with head/tail and BlackLists with SkipLists. In most cases, existing API calls will continue to work though you can update to the new terminology, but, if your code is explicitly checking for specific names in column heads or class reference entries or if you are using the Web Service projections of the %iKnow query APIs, you will need to adjust your code to account for these changes (first in 2020.4).

Class Compiler Upgrade Checklist

Error Handling Changes

This release improves the class compiler error handling of SQL relationship queries. Some errors that were not reported are now reported; consequently applications may behave differently when compiled or executed. But these new error messages can identify errors in relationship queries that should be fixed to achieve the intended results (first in 2020.3).

Locking Changes

In this release, the class compiler always uses a lock when compiling or loading to ensure that the operation is not interrupted by other events; consequently, the ‘l’ flag and the /lock qualifier are deprecated and will be ignored. This change should not impact any existing user code or procedures other than by avoiding errors in the operation (first in 2020.3).

CSP Upgrade Checklist

Handle Gateway Timeout Correctly

When the Gateway times out, the associated InterSystems IRIS processes should terminate. In some cases, this would not happen and the processes would continue. In this release, these processes are terminated correctly. If your application depends on this behavior to continue past this timeout, you should adapt your code to handle this situation (first in 2020.4).

Improved Handling of SameSite HTTP Option

Recent updates to browser security have changed handling of third-party cookies. These updates use the SameSite attribute to reduce the risk of cross-site request forgery (CSRF) attacks, unauthorized access to data, and other possible security issues. Chrome (starting with v.84) enforces stricter rules for SameSite behavior, and these rules can cause issues with existing websites and web applications. These issues may include login problems, the login page being displayed repeatedly, and page elements not displaying properly. In previous versions, Caché did not support modifications to the SameSite attribute; hence web applications running on these versions may have such issues.

This release solves these problems by setting the SameSite attribute for cookies and by allowing you to change the default setting; however, you may need to modify your code to customize values by setting the session cookie scope and the user cookie scope. Additionally, if you are using “SameSite=None”, you must ensure that your web application can support secure HTTPS connections (first in 2020.4).

CSP Pages Not Backed Up By Internal Routine Versioning

This is a change to an undocumented feature, routine versioning, that some customers may be using. If you are using routine versioning,, with this change CSP pages will not be backed up to the ^rBACKUP global.

Integrated ML Upgrade Checklist — Provider Changes

The H2OSA provider is no longer supported. If you have used it with a previous release, you must switch to a different provider.

Interoperability Upgrade Checklist

.NET Gateway Changes

The Interoperability .NET Gateway now supports Core 2.1 version and the default value is now 4.5 instead of 2.0. If your application is dependent on the default value and needs the 2.0 version, you must explicitly specify it (first in 2020.4).

X12 Schema Changes

This release includes additional keyfields in X12 schemas. In some places unnecessary schemas or incorrect loops have been removed. If your code relies on the existence of these incorrect elements of the schema, you must revise it (first in 2020.4).

Export Can Now Include Base Schemas

The Interoperability Production Code Export will now include custom base schemas if appropriate. The query EnumerateVDocSchemas now return also returns the Base value.

Error Checking on Timeout Setting

This release adds error checking to the timeout settings in the production configuration page. If the requested timeout interval exceeds 1 hour, the page treats it as an error and does not allow the setting. Since it is extremely unlikely that you would want to delay the instance shutdown for an hour, this is most likely an error. However, if you really need such an extended time to wait for the production component to stop, you can still set shutdown to be longer than an hour using a script that calls an Ens.DirectorOpens in a new tab method (first in 2020.2).

System Defaults Setting Checks Values

In previous releases, invalid values in the default system settings would not be checked until the values were applied in a production. This change ensures that system default settings are valid when specified. If you have invalid system default settings that were saved by a previous release, saving them in this release removes the values. Settings are validated by calling the IsValid() method of the appropriate class. If no IsValid() method is defined, then no validation is performed (first in 2020.2).

Activity Monitoring Changes

The activity monitoring pages (see Monitoring Activity Volume) now distinguish between days based on the combination of UTC and local time. This means when querying the Ens_Activity_Data.Days table for a specific TimeSlotUTC or TimeSlot it is necessary to check if there are 2 rows per unique TimeSlotUTC or TimeSlot : One row when TimeSlot is different from TimeSlotUTC and one row when TimeSlot is the same as TimeSlotUTC. The actual value is the sum of these two rows (first in 2020.3).

Creating Interoperability Namespace with %Installer Changes

In previous releases if you used the %Installer.InstallerOpens in a new tab class to make an interoperability production enabled namespace, it would set the node to a fixed portal URL. It now sets it to the empty string, which is the typically desired behavior. If you wish to set the node to a fixed portal URL, you can do this with the following:

 Set ^%SYS("Ensemble","InstalledNamespace",tNSUpper)="<fixed-url>"

(first in 2020.3)

Removal of Deprecated Java Business Hosts, Use PEX Instead

Java Business Hosts was deprecated in release 2019.3 and has been removed from this release. PEX replaces the Java Business Hosts feature. For information on migrating existing Java Business Hosts productions to use PEX, see the community article Migrate from Java Business Host to PEXOpens in a new tab. For a description of PEX, see PEX: Developing Productions with Java and .NET (first in 2020.3).

Custom Business Process Accessing %MessageSent or %MessageReceived Changes

In this release if custom business process code accesses the internal %MessagesSent or %MessagesReceived array then the class parameter SKIPMESSAGEHISTORY needs to be overwritten and set to 0 (first in 2020.3).

Message Viewer Changes for XML Objects

To improve efficiency in displaying XML-enabled objects, large XML objects may not be fully serialized in the message viewer Contents tab. To see the fully serialized value, you must now use the Full Contents link. For more information, see Changing the Character Limit for XML Messages in the Contents Tab (first in 2020.3).

PEX Class Changes

The PEX class hierarchy has changes to reduce errors when users overloaded methods rather than overrode them. In this release, all methods that should be overrode by user code are marked as abstract. If you define a subclass and do not override these methods, you will get a compile error. In previous versions, the compile would succeed but the user callback code would not execute correct because the default code would be called instead. The documentation stated that these methods were abstract and needed to be overridden but it was not enforced by the code (first in 2020.3).

PEX Library Changes

This release uses a different serialization library; it no longer uses the jackson library. Consequently, your production settings should point to the intersystems-utils-3.1.0.jar provided and not to the jackson library. If your code references the jackson library, you must update it or install the jackson library (first in 2020.3).

RecordMap Error Handling Changes

The error detection for the RecordMap service is now stricter with the ParseOnly flag selected. In previous releases, errors would be ignored with ParseOnly even if the AlertOnError flag was enabled. In this release, if the AlertOnError flag is enabled and a record fails validation, then an alert is sent even if ParseOnly is selected (first in 2020.3).

X12 Changes

There are several changes in how X12 documents are handled (first in 2020.3):

  • Change handling poorly formatted documents — improved handling of certain poorly formatted documents means that the issues with these documents are logged in the Event Log and then handled by sending an appropriate Reply document, rather than these documents resulting in the service failing and documents not being deleted. If you are relying on service failures to identify flaws in the X12 document, you should look at the Reply document instead.

  • Validation change — this change now includes code values in validations that were previously ignored. If you are using validation with the flags r, u, or t, then some errors that would have been missed in previous versions will now be caught. This change also adds a new segment, CTX-11, to the validation style schema for HIPAA_5010:999. This does not impact any code for setting the CTX-5() segment, but does mean that if a user has code for getting values from the CTX segments, and the document they are inspecting has a Business Unit Identifier, then that CTX segment will have to be accessed using path 2000().2100().CTX-11 instead of the 2000().2100().CTX-5() which is used for Segment Context. This makes no difference in either setting or getting values using the new style schema.

  • Change in allowed order of segments — this change allows segments to be in any order permitted by the standard rather than requiring them to be in the specific order as listed in the standard. This allows valid documents to pass validation where in previous releases, they would have failed. This change should not require any change in your code unless you were using the wrong property path to get the value from some segment to workaround this incorrect behavior, in that case you need to switch to using the correct property paths.

XML VDoc Character Escape Changes

In XML VDoc, when you use setValueAt() to set the value at a node, you can specify a value that consists of mixed content (that is, a value that consists of a mix of element and text nodes). This change ensures that if a < (left-angle) character appears without a closing XML /> or </, then the < is treated as normal text and is XML escaped (replaced by &lt;). In previous releases, this would have been treated as mixed content and would have caused an error. If you have code to handle this expected error, you should examine this case. See Using Mixed Content When Setting Paths (first in 2020.3).

GenericService Return Value Change for OneWay

Prior to this change for any custom code that subclassed EnsLib.HTTP.GenericService and had enabled OneWay an "HTTP/1.1 200 OK" would be returned to the caller. This is now corrected to ensure returning an "HTTP/1.1 202 Accepted" to the caller.

Language Bindings and Native SDK Upgrade Checklist

IRISNative and Gateway Changes

This release contains the following changes to the language bindings IRISNative API and to the gateway:

  • Changes to Native SDKs and IRISList:

    • If the underlying value is the empty string, getObject returns an empty string or zero-length byte array. If the underlying value is UNDEFINED, getObject returns a null.

    • For numeric types, if the underlying value is an empty string, get returns a 0 value.

    • getObject returns a byte array for type 1 (ASCII).

    If you use this feature, you will have to refactor and recompile your code. These changes have the following consequences:

    • Empty string is not converted to $char(0) and back as it was done in previous releases. Empty string is left as empty string. Note that this is different than the SQL semantics for empty strings.

    • An attempt to use empty string or empty byte[] as a subscript generates a <SUBSCRIPT> error.

    • No changes in setting null. set(null,) and set ("",) both result in empty string on server.

    • Getting undefined value will result in null.

    • Getting any numeric (int, double) value from "" returns 0. For methods and functions, the return value is null.

    • getByte from "" returns empty byte[0], getString from "" results in empty string.

    • GetObject from type 1 results in byte[0] in both the IRIS and IRISList classes.

    • GetDateTime from empty string returns null, where in previous releases it was throwing an exception.

    • getIRISList returns a valid object of length 0 for values 02 01, and returns a null object for 01.

    • Iterator returns an empty string if subscript is not found, where in previous releases a null was returned.

  • Projection of byte array in method arguments — In previous releases, byte arrays were projected as strings, but in this release they are projected as a proxy object. You can convert the proxy object to a %GlobalBinaryStream object (first in 2020.3).

  • Parameter order in IRISNative iris function and iris procedure change — In the previous version, there was a difference in the order of the parameters between the documentation and the implementation. In this release, the implementation has been updated to match the documentation (first in 2020.3). The parameter order is as follows:



    Where the implementation had the routineName parameter before the functionName parameter and the procedureName parameter. If you have coded these methods to the previous order, you must update the code. See function() and procedure() for details.

This release contains the following changes to the language bindings IRISNative API and to the gateways (first in 2020.3):

  • Access to the IRISReference class — you now have to use the accessor methods getValue() and setValue() to access the value. Previously, you could access the value directly

  • Object returned as IRISList — if a user method returns an object of IRISList, the InterSystems IRIS side now gets a $list literal. Previously, the InterSystems IRIS side would get a proxy object of %Net.Remote.Object. If your code is expecting an object of %Net.Remote.Object, you need to change it. There were significant problems including inefficiency with the previous behavior.

  • Private classes — in this release you cannot access private Java or .NET classes using public properties or methods. You must change the private classes to be public in Java or .NET if you want to continue using those properties and methods. This change fixes some errors and inconsistencies accessing private classes with public properties or methods.

  • %Net.Remote.Object property name change — in this release the %Net.Remote.Object internal Gateway property is renamed to %gateway. This is an internal property and should not be used, but if your code accesses it, you should change it to use the new name.

  • Empty strings — in this release, the language bindings map an empty string in the external language to an empty string in InterSystems IRIS. In previous releases, these were mapped to $c(0).

Changes to How Strings and Nulls are Handled in Java Native SDK

In this release the Java Native SDK has significant changes to how strings are handled in method and function calls, get() methods, and IRISList (first in 2020.4).

Decimal Type Changes

In this release $decimal is mapped to Decimal . NET and BigDecimal in Java and the scale is preserved. In previous versions, decimal was mapped to other types and scale was lost. In ADO.Net, if a decimal value was set as proxy by a previous version, it will not be accessible by a simple get in this and later versions. In Java if BigDecimal is set using a generic conversion to byte array, a simple get cannot decode it in this and later versions.

JAR File Name Changes

If your Java application has dependencies on the gateway JAR, you must change them to be dependent on the jdbc JAR.

Configuration Changes

If you are using the %Net.Remote.Object gateway APIs to configure Object gateways, you must now use the Config.Gateways APIs. The properties associated with the old values LineRecallEntries and LineRecallBuffer in the Config.config class have been removed. If you were setting these properties via the Config.Config APIs, you will now need to update the "history" property rather than these.

Removing Ability to Connect to Caché from .NET Provider or ODBC

In order to enable new features, neither the .NET Provider nor ODBC supports connections to Caché instances in this release. The .NET Provider can only connect to InterSystems IRIS instances version 2019.1 and later (first in 2020.3).

New Version of XEP Compatibility Issues

This release has a new version of XEP support, which includes enhanced indexing and a new underlying client/server communication method. Consequently, you cannot use a XEP from a previous version of InterSystems IRIS with this version as the server and you cannot use this version’s XEP with a previous version as the server. In addition, there may be some minor code changes that you need to make to any code that called the previous version of XEP support. See XEP Requirements and Configuration for details. For example, there is the following change:

XEP updateObject() method — the updateObject() method will now throw an exception if the object to be updated does not exist in the extent of the class. If your application depends on updateObject reverting to insert when the object does not exist then you will need to update the application to catch the exception and properly invoke the store() method to insert a new object (first in 2020.3).

32-bit ODBC Driver Removed on UNIX®

In this release, the 32–bit ODBC drivers libirisodbcu35.soand have been removed on UNIX® systems. If you have used these drivers, you should use the 64–bit equivalents and If you are switching over to the 64-bit unixODBC client driver (, you should also make sure you are using the 64-bit unixODBC driver manager and that your applications are built against 64-bit unixODBC. If your app or driver manager is 32-bit and is trying to use the 64-bit driver, this could cause unexpected problems. This change only impacts the 32-bit ODBC drivers built against the unixODBC driver manager. The 32-bit iODBC-based drivers are still included in the installation (first in 2020.3).


Typically, developers use the standard JDBC APIs, which are unchanged in this release, but some proprietary public classes and methods have moved or become more restricted in access permissions. These accessible proprietary classes and methods may have been used by customers in their applications, and will need to be updated.  For example, if your code is accessing directly the members of the ConnectionParameters class, you must update your code and use the getter and setter methods (first in 2020.3).

Natural Language Processing Upgrade Checklist — Treatment of Parentheses in Japanese Text

For Japanese text, parentheses () and their content may get indexed differently from previous versions, depending on the use of Katakana and number of characters within. While not strictly required, users are recommended to reindex their NLP domains with Japanese text to ensure uniformity of the output.

Objects Upgrade Checklist — IDENTIFIEDBY Deprecated Use Parent/Child Relationships

The %Library.PersistentOpens in a new tab IDENTIFIEDBY parameter is deprecated. If you have used IDENTIFIEDBY to define relationships, you should replace it with a parent/child relationship (first in 2020.3).

Security Upgrade Checklist

OAuth — Changes to OAuth2 GetUser and Login Signatures

This is a signature change to the method of GetUser and Login of the OAuth2.Server.Session. If you have manually subclassed this class and overloaded these methods, you should be aware that the system may attempt to pass them one additional (string) parameter when dispatching to user code from the core methods GetUser and Login (respectively) of OAuth2/Server/Auth (first in 2020.4).

OAuth — Change to Return Status

Prior to this change, OAuth calls returned a status of 200 whether or not the user login to authorize OAuth was successful. If the login wasn't successful, the login page was displayed again with status of 200. If the login was successful, the permissions page was displayed with status of 200.

After this change, OAuth calls now returns a status of 401 when the user login was unsuccessful. Customers working with OAuth, especially those who implement custom OAuth login pages, should be aware of this change. Although it is possible that this change could cause issues with custom code, for many customers, even those working in OAuth, this might not change anything or cause any issues.

OAuth — Change to AddOct Method

The rarely used method %OAuth2.JWKS.AddOct() no longer base64url decodes client secrets. If you make use of this method but still need to base64url decode the secrets they pass in, you should base64url decode it should do so before calling the method.

Removal of TLS 1.3

InterSystems IRIS 2020.2 through 2020.4 contained the new TLS 1.3 security libraries. On some platforms we discovered that there were conflicts with older versions of the libraries installed by the operating system or other applications. Consequently, we have removed TLS 1.3 from this release. We will include TLS 1.3 support in a future release in a way that will not conflict with older versions of the library that are installed on the system.

Cannot Use Old Versions of cvendian and cvencrypt

Due to encryption changes, you cannot use cvendian and cvencrypt utilities from previous versions on encrypted databases. Use the versions of cvendian and cvencrypt provided with this release (first in 2020.2).

SQL Upgrade Checklist


In previous releases an ORDER BY STATEMENT on INFORMATION.SCHEMA.STATEMENTS:Statement Column was automatically truncated to 150 characters. This automatic truncation has been removed to allow you to use more characters. However, in some cases having no truncation can cause a subscript error. To avoid this you should explicitly specify a truncation that will catch significant data, but will not be unlimited (first in 2020.4).

Map Selectability Changes for Mapped Table Definitions

In previous releases, if you set map selectability for a table definition that was mapped into another namespace, the map selectability setting was changed for the table definition in all namespaces. In this release, you only set the map selectivity for a single namespace (first in 2020.4).

Query — $SYSTEM.SQL Not Using SQLCODE to Return Error Status in Some Contexts

The error information formerly provided in SQLCODE from $SYSTEM.SQL.Statement ClearAll, ClearRelation, ClearSchema, ClearStatement, FreezeAll, FreezeSchema, FreezeRelation, FreezeStatement, UnfreezeAll, UnfreezeSchema, UnfreezeRelation, and UnfreezeStatement is now included in the return status. The error information provided by SQLCODE from $SYSTEM.SQL FreezePlans and ClearStatisticscan be found in the Errors parameter. SQLCODE has been removed from the PublicList in these contexts (first in 2020.4).

Improved Error Handling Catches Invalid Datetime Function Input

In previous releases some invalid inputs to datetime functions would not cause an error but would return a value. In this release these errors are caught and returned as errors. If your code does not handle errors in these functions, you should add error handling (first in 2020.4).

SQL.JDBC — Major Revision to Connection Pooling

In previous releases connection pooling was not a supported feature. This release contains a major revision to the connection pooling code and API, and this feature is now fully supported. If your code called the previous unsupported version, you should update it to ensure that it reflects the revised implementation (first in 2020.4).

SQL.JDBC — Changes to IRISCallableStatement.getBytes Behavior

To improve consistency between IRISCallableStatement.getBytes(String) and IRISCallableStatement.getBytes(Int), the behavior has changes. If you are calling IRISCallableStatement.getBytes(parameterName) and depend on the details of the previous behavior, you should replace the method call with a call to outputParameterList.getByteArray(parameters.getListOffset(parameterName)) (first in 2020.4).

SQL.xDBC Extensions — Significant Changes to UNIX XDEVshm Implementation

In order to fix problems in the previous implementation, the UNIX XDEVshm code has been rewritten. Although the basic functionality is unchanged, there may be minor changes in behavior. Consequently, if you use XDEVshm on the UNIX platform, you should test your code to ensure that it is not sensitive to these minor changes (first in 2020.4).

SELECT with INTO Clause Changes

This release contains a change to the behavior of an embedded SELECT statement with an INTO clause. If the execution of the SELECT statement results in SQLCODE=100, or in the case of a FETCH that results in SQLCODE=100, any INTO variables in the statement will be set to null (""). The variable will be set to "" when SQLCODE=100 or SQLCODE<0 is returned.

This is a change that might result in some applications requiring updating in order to avoid application errors, or incorrect results returned (first in 2020.3, modified in 2021.1).

In 2020.3 and 2020.4, if the INTO variable was undefined prior to the execution of the SELECT, and the SELECT does not set the variable (or any previous FETCH does not set the variable for cursor selects), the variable will remain undefined. In 2021.1 and later versions, the variable will be set to "" even if it was previously undefined.

Remove Unused Environment Variables

Some environment variables that were not used by SQL or the class compiler have been removed. These were not used by the product, but if you have referenced them, you should remove them from your application. The following variables are no longer defined in 2020.3: envRoutineSizeGet, envUseOldJavaGeneratorGet, envUseJavaGenerator1Get, envUseJavaGenerator2Get, envUseJavaGenerator3Get, envUseSortGet, and envTimeChangedGet. The following variables are still defined but return an error if you try to update the setting: envDefaultOHandleClassNameGet, envDefaultSerialStateClassNameGet, and envDefaultStorageClassNameGet (first in 2020.3).

Change to TuneTable and TuneSchema Defaults

In this release, the second argument of $SYSTEM.SQL.TuneTable and $SYSTEM.SQL.TuneSchema, update, now has a default=1. Prior to this change, the default was 0 for update. Calling $SYSTEM.SQL.TuneTable(tablename) and $SYSTEM.SQL.TuneSchema(schemaname) without specifying a value for update will result in a change of behavior from previous versions (first in 2020.3).

Import/Export Wizard Restricts File Extensions

The SQL import/export wizard checks that the file extension is either .txt or .csv. It will not let you import or export a file with a different extension (first in 2020.2).

Change in When Statistics Are Deleted

In previous releases, when you deleted a class or routine that contained an SQL statement, the statement index entry was removed. Since this entry is useful in generating statistics, it is no longer removed. To delete these statement index entries, select Clean stale on the SQL index page in the Management Portal (first in 2020.2).

Studio Upgrade Checklist

Use Web Server Configuration from Client Registry

In previous releases Studio ignored the web server configuration from the client registry and always queried the server for this information. In this release, it first queries the client registry for WebServerAddress, WebServerPort and WebServerInstanceName. If these are not defined in the client registry it will query the server. However if they are defined in the client registry but have incorrect values, you must correct them for Studio to function correctly (first in 2020.4).

%CSP.Page Changes Impact Studio

Classes that extend %CSP.Page, override the CSPURL or LOCATION parameters, and explicitly URL encode these parameters may be directed to the wrong web page when viewing the web page from Studio. This is not the case for any system classes, and the URL encoding these parameters is not a documented feature. This can be corrected by not explicitly URL encoding these parameters.

System Upgrade Checklist

Handle String Values in $SYSTEM.Event.Wait()

In previous releases, a $SYSTEM.Event.Wait() with a string value would cause no timeout. In this release, the string is converted to an integer and that is used as the timeout value. If the string is a nonnumeric string, it is treated as a zero timeout (first in 2020.4).

Remove extern Symbol zfedll From Include Files

There may be an unexpected incompatibility with any DLL that contains a source file that includes any of the following 4 statements:

#include iris-cdzf.h
#include iris-callin.h
#include cdzf.h
#include callin.h

Including any of these #include files formerly defined a extern symbol with the name zfedll. The purpose of this symbol is not documented and it is assumed that no other code in the DLL will reference this symbol. The extern symbol zfedll is no longer defined and any DLL that makes an unauthorized reference to the zfedll symbol will now get a link-time error reporting that the symbol is not defined (first in 2020.4).

Write Daemon Changes

These are minor changes unlikely to impact code. In the %SYS.ProcessQuery, $SYSTEM.Process, SYS.Process classes, the property Routine has the value "AUXWD" rather than "SWRTDMN" for the auxiliary write daemons. For the property JobType, which is documented as taking a value from, the definition in that include file is renamed from $$$SLWDTYPE to $$$AUXWDTYPE, and the numeric value is unchanged. In UNIX® systems, process names are changed from SWD1, SWD2, ... to AUXWD1, AUXWD2,...

$ZREFERENCE Variable Changes

In this release, the $ZREFERENCE variable, which contains the last global referenced, can have a different value after running %ETN error trap utility than it had in the same context in previous releases. If your code is parsing the $ZREFERENCE value to determine where the error information was written, you must modify your code to determine this information using the return value from LOG^%ETN or BACK^%ETN, which is a $LIST of the first two subscripts in the ^ERRORS global (first in 2020.3).


As part of a project to improve the performance of counters, certain GLOSTAT statistics have been changed (first in 2020.3):

  • %SYS.ProcessQuery property 'DataBlockWrites' and the equivalent $zu(67,38,pid) now counts any database block queued for writing by this process, whereas it previously counted only blocks internally typed as data blocks. This more accurately reflects the write load induced by this process than before (without adding the unnecessary complication of an additional statistic).

  • The undocumented $zu(190,6,0) and $zu(190,6,7) functions to zero system statistics are removed and now throw <FUNCTION>.

  • The iris stat -p32 columns formerly labelled 'rfcnt' and 'bfhit' are now labelled 'phyrd' and 'wdqbk' and they reflect, for the process in that row, the number of database reads and database blocks queued for writing respectively

Asynchronous I/O for Database Writes on Linux and UNIX® Systems

InterSystems IRIS on Linux has been enhanced to use Asynchronous I/O for writes to database files, as it always has on all UNIX® and Windows platforms. This is coupled with automatic use of direct I/O instead of buffered I/O. This change optimizes the disk I/O characteristics for database files, allowing higher scaling on busy systems without compromising application responsiveness. Of course, synchronization still occurs at key points to guarantee data integrity.

This change may require attention in certain configurations as file system buffering may have allowed InterSystems IRIS to perform acceptably with an under-configured database cache in previous versions. Check that database cache is sized appropriately on your system.

Additionally, InterSystems IRIS on Linux and all UNIX® platforms are enhanced to use asynchronous I/O for writing to the write image journal to provide optimal I/O characteristics. This change, however, requires no special attention.

For details, see Buffered I/O vs. Direct I/O (first in 2020.3).

Web Gateway Upgrade Checklist

Change in Return HTTP Error Codes for Redirects to Custom Pages

This release changes the status code returned when Web Gateway redirects to a custom error page. However, if your web application expects HTTP status 200 for these custom error redirections, you need to update it to handle 5xx codes (first in 2020.4).

Sites Using Nginx Must Rebuild and Reconfigure

If you use Nginx with the Web Gateway you must follow these steps to rebuild Nginx. If you do not use Nginx with the Web Gateway, you can ignore this issue.

If you are using Nginx with the default dynamic modules configuration (using and, note that we are now deprecating this configuration. The dynamic modules configuration will still function as before, but if you use the Web Gateway with Nginx you should rebuild and reconfigure Nginx to work with the Network Service Daemon (NSD) build of the Web Gateway instead. The NSD now supports WebSockets when used with Nginx, you can now migrate to the NSD even if you have a WebSocket application.

If you are already using Nginx with the NSD, you must still rebuild Nginx and edit its configuration to apply this change.

The steps you must follow are different if you are already using NSD or if you are migrating from dynamic module configuration.

If you are already using NSD:

  1. Install an updated version of the Web Gateway.

  2. Rebuild Nginx using the updated version of ngx_http_csp_module.c. See Nginx Web Servers for instructions on how to do this.

  3. Add the CSPNSD_pass directive to the Nginx configuration file to indicate the hostname/IP and port where the NSD is listening. For example, if your configuration file contains:

    location /csp {
        CSP On;

    and the NSD is listening at (the default), then change the configuration block to:

    location /csp {
        CSP On;
  4. Start up Nginx and the NSD.

If you are migrating to using Nginx with NSD from using Nginx with dynamic modules (,

  1. Install an updated version of the Web Gateway.

  2. Rebuild Nginx using ngx_http_csp_module.c instead of ngx_http_csp_module_sa.c. See Nginx Web Servers for instructions on how to do this.

  3. Remove the CSPModulePath directive from the Nginx configuration.

  4. Add the CSPNSD_pass directive to the Nginx configuration file to indicate the hostname/IP and port where the NSD is listening. For example, if your configuration file contains:

    location /csp {
        CSP On;

    and the NSD is listening at (the default), then change the configuration block to:

    location /csp {
        CSP On;
  5. Start up Nginx and the NSD. See Using the Network Service Daemon (NSD) and Using the NSD on UNIX, Linux, macOS for more information on how to manage the NSD.

This change also adds a few additional Nginx configuration directives that you should be aware of when migrating, and you should review whether their default values are acceptable for your workloads. If the default values are not acceptable, then specify your own value in the proper location{} block in the Nginx configuration file. These directives are:

  • CSPNSD_response_headers_maxsize — The maximum size of the HTTP headers in a response. An error is returned to the web client if a response header exceeds this size.

    • Syntax: CSPNSD_response_headers_maxsize size;

    • Default value: 8k

    • Context: location, if in location

  • CSPNSD_connect_timeout — Timeout for connecting to the NSD when a request is received from the web client.

    • Syntax: CSPNSD_connect_timeout time;

    • Default value: 300s

    • Context: location, if in location

  • CSPNSD_send_timeout — Timeout for a single send operation to the NSD when sending a request. The timeout is set only between two successive write operations, not for the transmission of the whole request.

    • Syntax: CSPNSD_send_timeout time;

    • Default value: 300s

    • Context: location, if in location

  • CSPNSD_read_timeout — Timeout for a single read operation from the NSD when reading a response. The timeout is set only between two successive read operations, not for the transmission of the whole response.

    • Syntax: CSPNSD_read_timeout time;

    • Default value: 300s

    • Context: location, if in location

An example configuration that uses all the new directives is the following.

location /csp {
    CSP On;
    CSPNSD_response_headers_maxsize 8k;
    CSPNSD_connect_timeout 300s;
    CSPNSD_send_timeout 300s;
    CSPNSD_read_timeout 300s;

(first in 2020.4)

Zen Upgrade Checklist — Very Large Integers Will Be Serialized as JSON Strings

In order to avoid problems with languages such as JavaScript that cannot use double precision floating point numbers to store integers and cannot handle a value greater than 2^53–1, these values are now serialized as JSON quoted strings. The behavior with values less than 2^53 is unchanged (first in 2020.4).

FeedbackOpens in a new tab