Skip to main content

Upgrade Compatibility Checklist for InterSystems IRIS 2021.2

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

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.


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

Upgrading Containers and File Ownership Changes

If you are upgrading a durable %SYS from a previous release, all files in durable %SYS must be owned and writeable by user 51773:51773 before upgrading to this release. The InterSystems Kubernetes Operator (IKO) and the InterSystems Cloud Manager (ICM) handle this automatically. Locked-down container instances cannot be upgraded from a previous release to this release.

PasswordHash Can Only Be Used During Initial System Configuration

PasswordHash makes it easy to change system-wide passwords during the initial system configuration. The password change is effective before the instance is initialized. In previous releases, you could also use this feature to make system-wide password changes once the system was in use and no longer had the initial passwords. With this release, PasswordHash can only be used during the initial system configuration and cannot be used later to change passwords.

Cannot Connect With ECP to Older Releases By Default

By default, this release may compress compiled routines to improve efficiency. These compiled routines cannot be handled by previous releases of InterSystems IRIS. Consequently, it will not allow ECP connections to instances that do not support this feature. You may disable this feature system wide with $ZU(69,87,1). If you disable this feature, then this release will be able to connect through ECP with older releases.

Exporting and Importing Security Tables

In previous releases you could only export and import security tables between instances with the same major version, In this release, the security tables now have an embedded version number, which allows finer access over allowable imports. You can export security tables from version 2021.1 and then import them to this version, 2021.2.

Interaction between Delegated and Password Authentication

If your user authentication includes both delegated authentication and password authentication, you can choose either to call or not call ZAUTHENTICATE for password users. Typically, ZAUTHENTICATE is only used for delegated users and not for password users. But, if you want your ZAUTHENTICATE routine to also be called for password users, you should check the Always try Delegated Authentication in the System Administration > Security > System Security > Authentication/Web Sessions Options page in the Management Portal or by using the ^SECURITY utility (System Parameter Setup, Edit authentication options). The default for Always try Delegated Authentication is No and ZAUTHENTICATE is not called for password users.

Work Queue Settings Not Preserved on Upgrade

When upgrading from 2021.1 or earlier to 2021.2, the settings for "Work Queue Manager Categories" are reset to the system defaults, and any user-defined settings are deleted. The new settings in version 2021.2 are not compatible with the previous settings and cannot be converted. If you have defined settings, see Using the Work Queue Manager and redefine the settings if necessary.


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.

Runtime Plan Choice (RTPC) Default Has Changed

The default value for the RTPC parameter has changed from 0 to 1.

When RTPC is enabled (=1), InterSystems SQL queries can perform optimization based on outlier information. For further details on outlier selectivity, refer to Tune Table in the InterSystems SQL Optimization Guide

Journaling Files May be Compressed

Any code which tests for the existence of a journal file may need to be updated to be aware that the file might exist with a "z" at the end if it has been compressed.

The size column in the %SYS.Journal.ByTimeReverseOrder query is the size on disk. Previously the size on disk and the amount of journal data in a file were more or less the same but with compressed files this is no longer the case. $$$GetJrnDataSize(%jrnfile) in will return the amount of journal data in a file (from the journal file header) regardless of whether a file is compressed or not.

Compression is enabled by default during an upgrade from a version which did not support it.

If Compact Double is Enabled, All Clients Must Support It

Users who enable the Compact Double feature will need to ensure that all clients, such as xDBC and Native, have been upgraded to a version that supports Compact Double, otherwise they will fail to connect. Users who do not enable Compact Double will not be affected. In previous releases the Compact Double Feature was not available. If you do not enable it, you will be able to connect with all clients that you could in the previous version, but if you do enable it, you may not be able to connect with some of these clients.

.NET Compact Double Changes to IRISList

This release adds support for the Compact Double feature for .NET client technologies: ADO, XEP IRISNative, and the Object Gateway (External Language Server). If your code is connecting to a .NET server with Compact Double enabled and your code includes IRISList and you want the values stored as compact doubles, you must modify the IRISList to enable compact double. If you do not want to have IRISList store compact double values, you do not need to change your code to connect with a server that supports compact double.

Application code can check if Compact Double is enabled for the connection by checking the "IsCompactDoubleEnabled" field on the IRISADOConnection object. You can use this value to control whether a new IRISList enables compact double with the following:

IRISList list = new IRISList(connection.ServerEncoding, connection.IsCompactDoubleEnabled);

Attempting to store a compact double on a server where it is disabled will produce an error. If you embed an IRISList within another, the compact double state must be the same in both.

For more details, see List Compression in $DOUBLE, ListFormat, and Class IRISList.

FIPS Mode Must Match Operating System FIPS Mode

If you attempt to start InterSystems IRIS in FIPS mode, the operating system must support FIPS mode and have been booted with FIPS mode enabled. Otherwise, InterSystems IRIS will not start and you must either enable FIPS mode in the operating system or not enable it in InterSystems IRIS.

Changes to Security.Events:ListAll Query Arguments

The Security.Events:ListAll query is a public API though it is mostly used internally. If you are using it, you may need to update your code to handle the changes in the arguments. It has been changed to now only accept three arguments (Filter, OwnerFlag, Flags) instead of five (EventSources, EventTypes, Events, OwnerFlag, Flags). Therefore, after upgrading, you will have to make changes everywhere you call ListAll if you specify more multiple arguments.

Instead of searching EventSources, EventTypes, and Events separately, ListAll now combines the Source, Type, and Name of each event into one forward slash-delineated string and searches just that string. This means that the Filter argument essentially combines EventSources, EventTypes, and Events into one.

If a you are only using one of EventSources, EventTypes, or Events, you can pass that value into the new ListAll as the Filter parameter and the query's behavior shouldn't change.

If you are using more than one of EventSources, EventTypes, and Events, you will have to make changes. The simplest thing to do is to combine the previous fields into one by putting a forward slash in between each field. For example, if you have EventSources="%System" and EventTypes="%Login" you can now use Filter="%System/%Login". Unfortunately, the new ListAll can't combine EventSources and Events without also having an EventType. So TO specify EventSources="%System" and Events="Logout" you need to also have an EventType, for example: Filter="%System/%Login/Logout".

Run-Time Plan Choice (RTPC) Optimization Enabled by Default

The new Run-Time Plan Choice (RTPC) optimization is enabled by default. For some queries, however, this may not be the best choice. See Adaptive SQL Optimizer for details on RTPC and review whether you wish to use this optimization.


If you use any of the following PURGE or FREEZE constructs, you must ensure that you specify the value with a literal not with an identifier:


  • [UN]FREEZE BY ID value

If you have used these constructs and have specified the value with an identifier, you must update your code to avoid errors.

Business Intelligence Analytics Cubes Cannot Have “.” Character in Logical Name in Expression

With this release, any cube <expression> element which uses the "." (period) character in the logical name will throw a compile error. Cubes which were successfully compiled in a previous release will still function exactly as they did before until they are recompiled. You should update the cube <expression> element to remove any “.” characters and recompile so that future compiles will succeed.

%ZEN.Dialog Classes Not Allowed By Default

In this release %ZEN˙.Dialog classes cannot be run in web applications unless the web application is enabled for analytics, the namespace is enabled for interoperability productions, or it is explicitly enabled for the web application. To explicitly enable %ZEN.Dialog classes, enter the following:

Set ^SYS("Security","CSP","AllowPrefix",application,"%ZEN.Dialog.")=1

Changes to How ZWRITE Displays IEEE Doubles

There are minor changes in the way ZWRITE displays IEEE double-precision floating-point values. The new formatting is more readable and provides better cutting and pasting output values. This should not impact most code, but, if your code is looking for specific text in ZWRITE output, you may have to modify it to handle these changes.

Changes to Rounding of ObjectScript Decimal Floating Point Values

This release contains a slight improvement in rounding of ObjectScript decimal floating-point. One particular significand value,

-9223372036854775808 was sometimes rounded to 

when that rounding was not supposed to happen.

Changes to SSLCheckServerIdentity Property

In this release, the SSLCheckServerIdentity property in %Net.SMTP now defaults to being on. This is the behavior that was documented and is the behavior described in RFC 2818 section 3.1. This also matches the behavior of SSLCheckServerIdentity in other contexts. However, if you are to send messages might find that this change prevents them from connecting to an SSL/TLS enabled server. If this happens, you can set SSLCheckServerIdentity to 0, but should be aware of the security tradeoffs.

(New Installs) Default DDL Type for TIMESTAMP Is %Library.PosixTime

In new installations, the default DDL Mapping for type TIMESTAMP has been changed from %Library.TimeStamp to %Library.PosixTime. This does not affect instances which were upgraded from a previous release. If you port code from a previous release to a new installation of this release, you may need to modify code to handle this change.

DTLs Calls Now Respect async="true" Setting

In previous releases, DTL calls with async="true" were run synchronously, not asynchronously. In this release, this setting is respected and the call be will run asynchronously.

%Monitor.Process Now Uses Same Metric Names as PERFMON and MONLBL

In previous releases %Monitor.Process had a different set of names for metrics. In this release, it uses the same metric names as PERFMON and MONLBL. If your code identifies metrics by name, you should modify it to use the new set of names.

Change to Error Signalled by Dynamic Objects and Arrays

ObjectScript Programs that used to catch <PROPERTY DOES NOT EXIST> error when $GET/$DATA was applied to a %DynamicObject or %DynamicArray element must now instead catch the <ILLEGAL CLASS> error. Since $GET/$DATA always signals an error when applied to existent or nonexistent Dynamic Object elements it is unlikely that there are any programs that are deliberately generating this error signal and testing for it.

Removal of Experimental Database Compression

In this release, we have removed the experimental database compression feature, originally introduced for a limited set of platforms in 2020.2. Continued internal benchmarking as well as user testing confirmed a very high filesystem-level fragmentation of database files, which led to unexpectedly long wait times for certain database operations. Please note this experimental feature is independent of the Journal Compression and Stream Compression features introduced with this release.

Need New Drivers for New SQL Syntax Features

Although existing SQL code will continue to work with the previous JDBC and ODBC drivers, if you want to use the new SQL Syntax features, such as SQL LOAD, you’ll need to update your JDBC or ODBC driver to the one provided with this release. Some applications, such as DBeaver, come with an InterSystems IRIS driver included, but you can still point it to a newer version of the library if you want/need.

Change to Viewing Private Program Data on UNIX AIX

A change in this release may cause on UNIX AIX a <PROTECT> error when you attempt to view private program data that is outside of the instance’s partition. You can get this error from the $VIEW function or the VIEW command. You can enable viewing and avoid the error by calling $ZU(69,23).

Removal of CreateDatabase Option for Experimental Database Compression

This release removes an experimental feature, database compression, because the minor savings in storage did not justify the increased compute load. This removal should not impact any existing code unless you called ##class(SYS.Database).CreateDatabase() and included the compression engine parameter. If you did, you must remove this parameter or you will get a <PARAMETER> error.

(Windows) Greater Precision in $ZNOW and $ZTIMESTAMP

On Windows, $ZNOW and $ZTIMESTAMP have more digits of precision than in previous releases.

Also, previous releases included the special functions $ZU(136,21,0), $ZU(136,21,1), and $ZU(136,21) for use on Windows, to work around limitations in how Windows returned time values. Windows now returns more accurate time values and this function is not needed. If you call these functions, you must update your code.

FeedbackOpens in a new tab