Skip to main content
Previous sectionNext section

Upgrade Compatibility Checklist for InterSystems IRIS 2020.3

The purpose of this chapter is to highlight those features of the 2020.3 release of InterSystems IRIS® data platform that, because of their difference in this version, affect the administration, operation, or development activities of existing systems.

This document addresses the differences between the 2020.2 and 2020.3 versions of InterSystems IRIS. Customers upgrading their applications from earlier releases are strongly urged to read the upgrade checklist for the intervening versions as well.


The following changes are of special 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 2020.3. The items listed here are described in the following sections.


The following sections describe compatibility issues that are of interest to developers and administrators. Since developers typically administer development system, developers should read all issues.

Class Compiler — 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.

Class Compiler — 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.

Cloud Containers — 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.

Installation — 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. In previous releases, the default SuperServer port was 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.

Interoperability Productions — 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.

Interoperability Productions — Creating Interoperability Namespace with %Installer Changes

In previous releases if you used the %Installer.Installer 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>"
Copy code to clipboard

Interoperability Productions — 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.

Interoperability Productions — 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”.

Interoperability Productions — 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.

Interoperability Productions — 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.

Interoperability Productions — 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.

Interoperability Productions — X12 Changes

There are several changes in how X12 documents are handled:

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

Interoperability Productions — 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.”

Interoperability Productions — 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 PEX. For a description of PEX, see PEX: Developing Productions with Java and .NET.

InterSystems Cloud Manager — 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
Copy code to clipboard

Language Bindings — IRISNative and Gateway Changes

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

  • 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 IRIS side now gets a $list literal. Previously, the 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 IRIS. In previous releases, these were mapped to $c(0).

Language Bindings — 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.

Language Bindings — 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.

Language Bindings — 32-bit ODBC Driver Removed on UNIX®

In this release, the 32–bit ODBC drivers and 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.

Language Bindings SQL.JDBC — API Cleanup

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.

Objects — IDENTIFIEDBY Deprecated Use Parent/Child Relationships

The %Library.Persistent IDENTIFIEDBY parameter is deprecated. If you have used IDENTIFIEDBY to define relationships, you should replace it with a parent/child relationship.

Security — On Red Hat Linux Only Support FIPS Mode in Version 8.2 and Later

On Red Hat Linux, you can only use FIPS mode on Red Hat Linux version 8.2 and later. You cannot use this mode on earlier versions.

SQL — 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 ("") if they are defined. 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. If the variable was defined prior to the SELECT, or the SQL SELECT or FETCH sets the variable, 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.

SQL — 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.

SQL — 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.

System — $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.

System — GLOSTAT Changes

As part of a project to improve the performance of counters, certain GLOSTAT statistics have been changed:

  • %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

System — 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:

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

System — 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.”

Web Gateway — SSLCC_Protocol Parameter Changes

To allow for TLS 1.3, there are changes to the way you access the SSLCC_Protocol parameter. If you are using an external script or the Web Gateway registry methods (particularly %CSP.Mgr.GatewayMgr.GetServerParams or %CSP.Mgr.GatewayMgr.SetServerParams) to read/write the SSLCC_Protocol parameter in CSP.ini, you must adapt your code to use the SSLCC_Protocol_Min and SSLCC_Protocol_Max parameters instead.