Skip to main content

Upgrade Compatibility Checklist for InterSystems IRIS 2020.4

The purpose of this chapter is to highlight those features of the 2020.4 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.3 and 2020.4 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.

If you are administering systems, you should pay special attention to the following items:

Business Intelligence Upgrade Checklist

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.

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.

Need to Recompile Any Cube that Invokes UPDATEFACTSTEMP Task

If you have any cubes that invoke the UPDATEFACTSTEMP task, you must recompile them before the next build or background synchronization.

CSP Upgrade Checklist

Handle Gateway Timeout Correctly

When the Gateway times out, the associated 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.

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 set change the default setting; however, you may need to modify your code to customize values 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.

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"
Copy code to clipboard

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

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.

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

Native API Upgrade Checklist

Java Native API — Changes to How Strings and Nulls are Handled

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

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

Passwords Now Use SHA-2 Hashes

This release uses SHA-2 hashes for passwords instead of SHA-1; consequently, you cannot export a user with an SHA-2 password hash and import it into an earlier version of Caché or a version of InterSystems IRIS that does not use SHA-2 hashes for passwords. You can import a user with an SHA-1 password hash into this release or any release that supports SHA-2 hashes.

Changes to TCP TLS in FIPSMode

When FIPS mode is enabled TCP TLS will use operating system's libraries and the TLS1.1 and earlier protocols won't be supported. This change should not impact existing code but, if your existing TCP TLS code uses FIPSMode, you should test it to ensure that there are no subtle behavior changes.

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.

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.

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.

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.

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.

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

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

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.

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.

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
Copy code to clipboard

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.

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.

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;
    Copy code to clipboard

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

    location /csp {
        CSP On;
    Copy code to clipboard
  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;
    Copy code to clipboard

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

    location /csp {
        CSP On;
    Copy code to clipboard
  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;
Copy code to clipboard

Zen Upgrade Checklist

Zen — 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 ass JSON quoted strings. The behavior with values less than 2^53 is unchanged.

FeedbackOpens in a new window