Skip to main content

Upgrade Compatibility Checklist for InterSystems IRIS 2022.1

This article lists the features of the 2022.1 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.

Administrative 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 2022.1.

PurgeBackupLog Has Improved Purging of Backup Logs

In previous releases, only backup logs within the file named "idpbackup.log" (created by running ^BACKUP from terminal) were being purged by the PurgeBackupLog task, whereas log files generated by running backups from the Management Portal were never purged. This change brings into sync the handling of backup logs run from the Management Portal and the Terminal. In addition, this changes the default number of days to purge logs from 7 to 30.

Changes affecting the different entry points for running backups are as follows:

  • Backups run from Management Portal: Backup logs will be created and named the same as they were before (according to the name of the task being run), but they will now be purged by the PurgeBackupLog task (before, they were never purged).

  • Backups run from Terminal (^BACKUP): Rather than appending each backup log into the same idpbackup.log file, each backup run will generate a new idpbackup_date_counter.log file. The PurgeBackupLog task will then delete these files individually rather than scanning and trimming the contents of the idpbackup.log file.

  • Backups run externally ($$BACKUP^DBACK()): The backup log file specified by the user in the arguments will be created newly or overwritten (rather than appending to it); if there is no file specified, the backup will generate a new idpbackup_date_counter.log file as for TUI backups. The PurgeBackupLog task will work as for TUI backups.

New Privileges Need to Purge Production Tasks

Administrators who will schedule Ens.Util.Tasks.Purge* tasks will now need to have the "%Ens_PurgeSchedule:USE" resource. This resource is granted by the "%EnsRole_Administrator" role, and can be added to custom roles. The "%Ens_MessageResubmit" and "%Ens_SequenceManager" resources no longer exist; however this should have no impact because they were not used anywhere in the system code, and no customer code should reference them directly.

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. (first in 2021.2)

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. (first in 2021.2)

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 the product. 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. (first in 2021.2)

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 2021.2 and then import them to this version, 2022.1. (first in 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. (first in 2021.2)

Some Tasks Removed from the Task Manager

Some of the automated maintenance tasks have been removed from the Task Manager and are now handled purely internally by the Work Queue manager. Specifically, the following tasks have been removed from the Task Manager:

  • Update SQL Query Statistics

  • Scan frozen plans

  • Cleanup SQL Statement Index

  • Resource Cleanup

Work Queue Settings Not Preserved on Upgrade

When upgrading from 2021.1 or earlier to 2022.1, 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 2022.1 are not compatible with the previous settings and cannot be converted. If you have defined settings, see the Using the Work Queue Manager and redefine the settings if necessary. (first in 2021.2)

Business Intelligence Changes

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. (first in 2021.2)

External Language SDK Changes

Change with XEP Unified Schema and Maximum String Length

Existing classes will be unaffected by this change; only classes newly generated by Unified Schemas will be affected. There should not be any new behavior except when using SQL or InterSystem IRIS Objects against these tables/classes. Prior to this change, the default MAXLEN=50 is used. With this change the size is not constrained to a maximum length of 50. There could be differences when querying string data that exceeds the 50 character default MAXLEN. There are no anticipated problems for existing XEP applications.

Cannot Bind SQL Character Type to ODBC Binary Field

If your code uses SQL_CHAR or SQL_WCHAR for binding into BINARY field you need to change it SQL_BINARY. This combination is unlikely to be used in code.

Accessing Install Directory on Windows from ODBC Requires Additional Privileges

Users in "Authenticated Users" group no longer are able to write files into the installation directory in locked down install without additional privileges.

xDBC Rejects Connections with Unsupported ListFormat

This release catches a connection error with an illegal ListFormat setting that was ignored by previous releases. If the server was configured with ListFormat 2 or 3, the connection will now be rejected. This setting was never supported by the clients and could result in inconsistent behavior or data loss if the connection was allowed.

Language SDK Unified Schema Caches will be Purged

When you upgrade to this release, all Language SDK Unified Schemas will be purged from the cache. This change does not require any change to your code, but each schema will be processed and cached the first time it is accessed.

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. (first in 2021.2)

.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. (first in 2021.2)

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.

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 or need to. (first in 2021.2)

Java Binding Collections Now Behave Consistently

Previously, in Java Bindings ArrayOfDataTypes and ListOfDataTypes did not behave consistently. In this release, there is a new behavior that will be a change for each type, but the behaviors are consistent with each other.

For ArrayOfDataType, previously when inserting elements there was a check to confirm the type matched the type of previously inserted elements, and would throw an error if that was the case. This change no longer checks this, as we are supporting arrays of multiple types. For both ArrayOfDataTypes and ListOfDataTypes, there used to be required conversions by the user for special types (Date, Time, and DateTime). Now, if the elementType is set to one of these types, the conversion is done automatically and the user receives an already-converted value.

Global Module Changes

Change in Behavior to Deprecated $view(n,-5)

The behavior of $view(n,-5) for even values of 'n' has changed when the block in the view buffer is a (type 8) data block. If the value to be returned (the value of node number n/2) is a big string, a <VALUE OUT OF RANGE> error will now be thrown. Prior to this change, the big string block numbers stored in the data block would be read in a best-effort attempt to return the big string value. That however could lead to unexpected behavior on systems if the database had changed in the interim. The unexpected behavior could include <DATABASE>, an invalid value, or under very rare circumstances, a cache coherency issue.

Code that uses this function may need to be reviewed and remedied as follows:

  • For callers of $view(n,-5) for even values of 'n' that intend to operate only on pointer blocks, but may have ended up with a data block in the view buffer due to concurrent changes to the database, either a) check that the block type in the header matches the expected type or (b) trap the error and treat <VALUE OUT OF RANGE> as invalid block.  Note that (a) is best practice and if not done then such code was already subject to bad behavior due to the possibility of getting an unexpected data block value that may be confused for a down pointer value.

  • For callers that intend to retrieve global values from a data block, either trap the error from $view(n,-5), or use $v(n,-6) to check the node type first. In either case, if the value is needed, get the current value by constructing the appropriate glvn (based on $view(n-1,-5)) to use $data or $get with indirection.

Prior to this change, when operating on a data block from a remote database, a big string value may have been returned as null.  With this change the behavior is the same for local and remote databases, throwing <VALUE OUT OF RANGE> error.


Although it is now an undocumented internal function, $view(n,-5) was, in a previous release, a documented function; consequently, it may still be used in legacy code.

Interoperability Production Changes

BPLs Calls Now Respect async="true" Setting

In previous releases, BPL calls with async="true" were run synchronously, not asynchronously. In this release, this setting is respected and the call be will run asynchronously. (first in 2021.2)

InterSystems Cloud Manager (ICM) Changes

ICM Has New Default InterSystems IRIS Web Server Port 57772

In this release, ICM uses a default web server port 57772. In previous releases, it used 52773. If your deployment expects the previous default port, you should override WebServerPort to match your existing deployment.

Journaling Changes

Journaling Files May Be Compressed

Although the journaling APIs, such as %SYS.Journal.File, automatically handle a journal whether it is compressed or not, any other code such as external scripts or code which uses %Library.File 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. With the journaling APIs, you should specify the filename as you have in the past - without the trailing 'z' as if none of the files are 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. (first in 2021.2)

In 2022.1, compression is enabled by default only for new installs. It can be enabled by the system administrator for upgrades.

Kernel Changes

Improve Storage Efficiency by Performing Kills in Ascending Order

In this release, a change increases the storage efficiency of the database following a KILL command — especially when purging large quantities of data from a database in ascending order. In the past programmers sometimes did KILLs in descending order when doing large purges of data. To improve storage efficiency, you should change such programs to do kills in ascending order as doing kills in ascending order will now almost always result in better efficiency and better performance. There should be less need to run the GCOMPACT utility to improve storage efficiency following large purges of data.

This change does cause a 128 byte increase in the shared memory allocation per global buffer. If you are using the 8k default buffer size, this is a 1.5% increase.

Change in Error Getting a Property when Dynamic Dispatch is Not Implemented

If a class does not implement dynamic dispatch and a method whose name ends with Get or Set is called and the method does not exist, the error is now <METHOD DOES NOT EXIST> instead of <PROPERTY DOES NOT EXIST>.

Kernel Change in When Class Components are Loaded Into Memory

In previous releases, class components were loaded in memory when they were accessed. With this change, class components are loaded when the class is initialized. This could lead to increased memory usage if class components are not being used. Otherwise, it only changes the point in which they are loaded into memory.

Changes to Random Number Generator Algorithm

This release changes the random number generator algorithm. In most cases, this does not impact compatibility, but if your application uses $zu(165) to specify a seed and relies on an expected sequence of random numbers, you will have to update your code with the new sequence. For example, the %Populate utilities will produce different results than prior versions with the same seed.

Change to Viewing Private Program Data on UNIX AIX

On UNIX AIX, a change in this release may cause 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,1). (first in 2021.2)


InterSystems strongly discourages users from using the $ZU(69,23,1) feature. This feature leaves Open M/SQL-UNIX open to abnormal termination of M processes and hangs due to programming errors.

Some Unneeded Windows-Only Time Functionality Removed

In previous releases a special function $ZU(76) was included to increase the accuracy of time returned by functions. This feature was added because of limitations in how Windows returned time values. Windows now returns more accurate time values and the special function is not needed. If you call $ZU(76), you should replace it with the appropriate time function such as $NOW or $ZTIMESTAMP. (first in 2021.2)

Changes to $zversion String and GetPlatform() for Linux

The $zv string will now include the Linux distribution version. If your code parses this string, you may have to modify it to handle this change. This string is also returned by the GetPlatform() method of %SYSTEM.Version class.

Monitoring Changes

%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. (first in 2021.2)

Object Changes

%Net.SMTP No Longer Sends Email if Server Does Not Support Authentication

Before this release, if you used %Net.SMTPOpens in a new tab to try to authenticate to an SMTP server that did not support authentication, %Net.SMTPOpens in a new tab would send the email. Now in the same scenario, %Net.SMTPOpens in a new tab will return error ERROR #6166: Server does not support authentication and will not send the email.

(First in 2021.2)

In %Net.Http, GetJson() Replaces getJSON()

In %Net.HttpOpens in a new tab, the new GetJson() replaces the getJSON() method. The new method has the following signature:

classmethod GetJson(requestURL As %RawString = "", request As %String(MAXLEN="")="") 
            as %DynamicAbstractObject 

You should examine existing code and make changes as needed. (First in 2021.2)

%FromJSON() Method Does Not Allow Illegal Numeric Values

Applications currently accepting illegal JSON numeric format with the %FromJSON(...) method will require modification now that %FromJSON(...) will signal an error for that illegal syntax. (first in 2021.2)

An exception is that JSON decimal constants that are illegal because they are missing a required leading or trailing 0 digit are not signaled as errors. Instead the missing 0 digit is supplied. E.g., {“minus5”: -5. } is treated as { “minus5”: -5.0} and {“minusHalf”: -.5 } is treated as {“minusHalf”: -0.5 }.

ObjectScript Changes

ZWRITE Preserves $ZR by Default

In this release, ZWRITE has the following new behavior:

  • If you ZWRITE a local variable (defined or not): ZWRITE will always preserve the original $ZR value. In previous releases, $ZR could be set to an unexpected value overwriting the previous $ZR value.

  • If you ZWRITE a global with or without a subscript, it will always set $ZR to be that global reference, defined or not. In previous releases ZWRITE a global would vary how it set $ZR depending on whether the global was defined with or without a subscript.

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. (first in 2021.2)

Changes to Rounding of ObjectScript Decimal Floating Point Values

This release contains a slight improvement in rounding of ObjectScript decimal floating-point. One specific value of the IEEE floating point significand:

-9223372036854775808 was sometimes rounded to -9223372036854775810

when that rounding was not supposed to happen. (first in 2021.2)

This error does not involve IEEE ($DOUBLE) binary floating-point representation. It only involves ObjectScript decimal floating-point representation.

Certain computations using a decimal significand of -2**63 (or -9223372036854775808), especially multiplications by a power of 10, were incorrectly rounded up to ‑9223372036854775810 when -9223372036854775808 is the exact answer.  This has been fixed. Note that the positive valued significand of +9223372036854775808 does not exist so it is always rounded up to 9223372036854775810. This means that ‑(9223372036854775808) does not equal ‑9223372036854775808 because the first expression is rounded up before the negation operator is applied.

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. Note that $GET and $DATA can only be applied to multidimensional properties and multidimensional variables. $GET and $DATA cannot be applied to elements of a %DynamicArray/%DynamicObject nor to class object properties without the [MULTIDIMENSIONAL] attribute. (first in 2021.2)

Security Changes

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 must 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. (first in 2021.2)

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. (first in 2021.2)

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

Changes to SSLCheckServerIdentity Property

In this release, the SSLCheckServerIdentity property in %Net.SMTPOpens in a new tab 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 send messages, you might find that this change prevents you from connecting to an SSL/TLS enabled server. If this happens, you can set SSLCheckServerIdentity to 0, but be aware of the security tradeoffs. (first in 2021.2)

SQL Changes

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. (first in 2021.2)

(New Installs) Default DDL Type Mapping 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. (first in 2021.2)

If a field has a datatype of %Library.DateTime, the fastinsert optimization will not be used and execution will be slower. You can resolve this issue by updating the datatype to use PosixTime, which is recommended over DateTime.

System Changes

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. (first in 2021.2)

Removal of Experimental Database Compression from CreateDatabase() Method

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. (first in 2021.2)

Web Gateway Changes

Web Gateway Now Uses PBKDF2 to Hash Passwords

The Web Gateway provides a feature where if a plain-text password is written to CSP.ini directly, the Web Gateway encodes the password at startup. This feature will no longer work if the plain-text password starts with the string "PBKDF2|".

The CSPpwd utility is recommended if you want to avoid this limitation.

Zen Changes

%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

(first in 2021.2)

FeedbackOpens in a new tab