Upgrade Compatibility Checklist for InterSystems IRIS for Health 2021.2
The purpose of this chapter is to highlight those features of the 2021.2 release of InterSystems IRIS for Health® data platform 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.
This section highlights information of interest to those who are familiar with administering prior versions of InterSystems IRIS for Health 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 for Health. 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 the 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 for Health. 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.
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 %syJrninc.inc 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.
FIPS Mode Must Match Operating System FIPS Mode
If you attempt to start InterSystems IRIS for Health in FIPS mode, the operating system must support FIPS mode and have been booted with FIPS mode enabled. Otherwise, InterSystems IRIS for Health will not start and you must either enable FIPS mode in the operating system or not enable it in InterSystems IRIS for Health.
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".
SQL PURGE QUERIES BY AGE and FREEZE BY ID Changes
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:
PURGE [QUERIES] BY DAYS value
[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:
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 -9223372036854775810
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 an 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 for Health 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.
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.