Skip to main content

InterSystems IRIS® Incompatibility History (2022.2)

This document lists the incompatibilities for InterSystems IRIS, considering all releases up to and including 2022.2. These incompatibilities may require changes to code, configuration, or operation.

InterSystems News, Alerts, and Advisories

From time to time, InterSystems publishes items of immediate importance to users of our software. These include alerts, mission-critical issues, important updates, fixes, and release announcements. You can obtain the most current list at https://www.intersystems.com/support-learning/support/product-news-alerts/Opens in a new tab. InterSystems recommends that you check this list periodically to obtain the latest information on these issues.

Business Intelligence

DP-11381: Remove _PUBLIC ownership from generated listing tables

Category: Business Intelligence
Platforms: All
Version: 2020.2.0
Description: Listing tables are now generated so that they require explicitly assigned SELECT privileges.

For field list listings in a given cube, this will mean users must have SELECT privileges on both the source table for the cube and the generated <cube class>.Listing table for that cube.

For custom listings, SELECT privileges of user tables might be required to run the custom listing. If the custom listing uses the special $$$RESTRICT token, SELECT privileges on the <cube class>.Listing table will also be required.

DP-13501: Enforce valid cube name in cube compile

Category: Business Intelligence
Platforms: All
Version: 2020.4.0
Description: Before this change, cube names that violated the documented rules could be successfully compiled though they may have caused other errors. With this change, these invalid cube names cause a compile error and must be corrected to successfully compile the cube.

DP-14014: Must recompile cubes that invoke UPDATEFACTSTEMP

Category: Business Intelligence
Platforms: All
Version: 2020.4.0
Description: If you have any cubes that invoke the UPDATEFACTSTEMP task, you must recompile them before the next build or background synchronization.

DP-283945+PLUS: Removal of %DeepSee.TaskMaster agents and associated code

Category: Business Intelligence
Platforms: All
Version: 2019.1.0
Description: As part of the transition to Work Queue Manager %SYSTEM.WorkMgr agents, Business Intelligence %DeepSee.TaskMaster agents have been removed in this release. As a result, there are no longer low or high priority agents, as all agents are managed by %SYSTEM.WorkMgr and are created automatically when needed. In addition, associated methods like %SetAgentCount() and %GetAgentCount() have been deprecated.

DP-286613: Return calculated measure display names in %GetCubeMeasures output

Category: Business Intelligence
Platforms: All
Version: 2019.1.0
Description: The second item in the %GetCubeMeasures() output list should be the caption. Before this change, for calculated measures, this method returned the name, not the caption as the second item. With this change, the second item correctly contains the caption. If your code relied on the name being returned in the second item for calculated measures, you should update your code.

DP-288615+PLUS: Recompile all cube classes

Category: Business Intelligence
Platforms: All
Version: 2019.1.0
Description:

When you upgrade to this release, you must recompile all Business Intelligence cubes. There are two reasons for this:

  • In this release, the %DeepSee.Generator has improved the way deletes are handled when synchronizing. In order to incorporate this change, you must recompile all Business Intelligence cubes. If you do not recompile a cube, attempting to build this cube will encounter an error.
  • In previous releases, compiling %DeepSee.Generator would not catch the error of including a list-based level that also defines a range expression. Consequently, these constructs would cause an error during build causing missing data in the cube. In this release, these errors are found during compile time and the user can correct the error.

DP-289207: Change in ResultSet timing

Category: Business Intelligence
Platforms: All
Version: 2019.1.2
Description: To ensure consistency, this release has changes in the timing of setting the %DeepSee.ResultSet. Consequently, code that previously worked may be accessing the ResultSet before the operation completes. To ensure that the ResultSet has been set, test that ResultSetObj.%GetStatus() has a value of 100 before accessing the ResultSet value.

DP-402073: Must recompile cubes to see detail listings

Category: Business Intelligence
Platforms: All
Version: 2021.1.0
Description: As part of a change to improve MDX query performance, this change stores certain cube-related data in a different location. This change requires that you recompile all cube classes that were created on a version prior to this change. If you do not recompile these classes, detail listings on those cubes will return no results.

DP-403240: Cube <expression> cannot have a period character in its logical name

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

This change means that an intermediate expression in Architect can return an object with properties, rather than a single value.

DP-7373: Change in Advanced Filter Editor

Category: Business Intelligence
Platforms: All
Version: 2019.3.0
Description: This change introduces the potential for a new pair of server requests where previously the client JavaScript was completely responsible for the processing. If the client-server lag times are high, this can increase the time to process the request. Although it is possible that this request succeeded in earlier versions, this situation most likely would have resulted in an error.

DTB739: Add stronger concurrency protection to %DeepSee.ResultSet

Category: Business Intelligence
Platforms: All
Version: 2019.1.2
Description: This changes the way that the %DeepSee.ResultSet operates during concurrent executions to preserve the integrity of results. This provides much deeper inspection of the primary components of a particular query, requiring that each writer to the query cache secure a lock on the query key and all axis keys before being granted access to change anything in either the results or axis caches.

DTB818: Store initial axis text in axis cache for KPI/MDX context reference

Category: Business Intelligence
Platforms: All
Version: 2019.1.2
Description: The cell context passed to a %KPI plugin's %dsCellContext environment variable could lose useful information due to the fact that it was rebuilt from the pre-processed list of members that actually exist in the cube data. This variable now contains the original requested MDX text for the slicer.

Cloud

DP-10344+DP-10441: drop support for Docker CE on RHEL and SUSE

Category: Cloud
Platforms: All
Version: 2020.1.0
Description: This changes InterSystems Cloud Manager (ICM) in two ways that can impact upgrades:

  • ICM now supports Docker Community only on CentOS and Ubuntu. If you are using ICM with Red Hat Enterprise Linux or SUSE Linux and Docker Community, you must either switch to Docker Enterprise or switch to the CentOS or Ubuntu operating system.
  • ICM now stores the state directory in a different location. It now uses a default state subdirectory named "state". If you have scripts or custom code that reference the state directory, you should update the references to the new location.

DP-12268: Changes for the arbiter container with ISCAgent using nondefault port

Category: Cloud
Platforms: All
Version: 2020.3.0
Description: The arbiter is an independent system hosting ISCAgent for mirror members. By default, ISCAgent uses port 2188. Before this change, to specify a nondefault port, you used syntax like the following:

$IRISSYS/startISCAgent.sh 2000
With this change, you must instead use -p as follows:
$IRISSYS/startISCAgent.sh -p 2000
Using arguments other than -p will be ignored and the container will run with port 2188.

DP-12631: JDBCGatewayPort change

Category: Cloud
Platforms: All
Version: 2020.3.0
Description: If you were overriding the JDBCGatewayPort parameter using the JSON field "JDBCGatewayPort", you should delete that parameter and instead override the parameter directly in the custom CPF file (pointed to by "UserCPF"). For example:

[Gateways]
%JDBC Server=JDBC,127.0.0.1,53773

DP-13063: Change default superserver port

Category: Cloud
Platforms: All
Version: 2020.4.0
Description: 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"

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

DP-13503+PLUS: ICM can be used only with InterSystems API Manager (IAM) 1.5 and later

Category: Cloud
Platforms: All
Version: 2021.1.0
Description: With this change, ICM can only be used with the InterSystems API Manager (IAM) version 1.5 or later.

If you were using the Rancher or Weave Scope monitoring solutions with a previous ICM version, with this version you need to deploy these manually or use generic ICM commands.

The parameters in CPF have changed from the beta version. This change only impacts beta users of ICM.

Replace:

[Startup]
  EnableECP=1

with:

[Actions]
ModifyService:Name=%service_ecp,Enabled=1

Replace:

 [Startup]
  EnableIAM=1

with:

[Actions]
ModifyApplication:Name=/api/iam,Enabled=1
ModifyUser:Name=IAM,Enabled=1

DP-20597: ISCAgent now started automatically

Category: Cloud
Platforms: All
Version: 2021.1.0
Description: ISCAgent is now started automatically and is started on port 2188 by default in containers. You can disable ISCAgent with "--ISCAgent false". You can control the port used with the new syntax "--ISCAgentPort <port>" instead of the previous syntax "--before /home/irisowner/irissys/startISCAgent.sh <port>".

DP-287966: Change in behavior when reprovisioning AWS volumes

Category: Cloud
Platforms: All
Version: 2019.1.0
Description: In this release when you are provisioning on AWS, the ICM creates the WIJ and journal volumes only on nodes running complete InterSystems IRIS systems and they are not be created on Shard Master Application Server (AM), Shard Master Data Server (DM), Shard Query Server (QS), and Shard Data Server (DS) nodes. In previous releases, the ICM created WIJ and journal volumes on all nodes. When upgrading to this release, these unused nodes will be deleted. Typically this is not a problem, but if you made use of these volumes on some other type of node and stored data on them, you should save this data before these volumes are deleted by the upgrade.

DP-288101: Authentication required for Rancher monitoring

Category: Cloud
Platforms: All
Version: 2019.1.0
Description: Before this change, you could use Rancher monitoring without authentication, which InterSystems did not recommend because it is an insecure configuration. With this change, if you want to use Rancher monitoring, you can only use it with authentication.

DP-288836: Cannot override reserved keys

Category: Cloud
Platforms: All
Version: 2019.1.0
Description: In previous releases, you could override reserved keys in definitions.json. This caused unpredictable results. In this release, reserved keys can only be specified in defaults.json and cannot be specified in defintions.json. The reserved keys are:

  • "Label"
  • "Tag"
  • "Namespace"

In most cases overriding a reserved key causes the deployment to fail. In some cases, overriding "Namespace" did not cause a fatal error and the deployment succeeded. Although these deployments may continue to work after an upgrade, you should remove the override of the reserved key. Reprovisioning without removing the override will encounter an error.

DP-289409: Must use datastore cluster for vSphere storage allocation

Category: Cloud
Platforms: All
Version: 2019.1.0
Description: There are significant advantages in using a datastore cluster over using a bare datastore. Although the previous version allowed you to specify a datastore not in a cluster, in this release you must specify a datastore cluster. If you have "Datastore" in defaults.json or definitions.json, you must change it to "DatastoreCluster". If your datastore was not in a cluster, you must create one for it.

DP-289623: iris-main now terminates after errors

Category: Cloud
Platforms: All
Version: 2019.1.0
Description: In previous releases, iris-main would continue to execute after some errors. In this release, iris-main correctly terminates when a command or script it calls returns a non-zero exit status.

DP-289670: Change to device letter assignments

Category: Cloud
Platforms: All
Version: 2019.1.0
Description: Device names (for providers other than PreExisting) have all been shifted one letter forward in the alphabet to make room for the Docker block storage device. If you have explicitly included a device name in code or configuration, you should update the device name.

DP-404204: Upgrading containers and file ownership changes

Category: Cloud
Platforms: Cloud
Version: 2020.1.1
Description: The volume mounted for durable %SYS must now be writeable by user 51773 (irisowner), because cloning into that directory now happens as irisowner instead of root. When it isn't writeable, startup will fail. The cloud distribution now uses a non-root install, not a traditional installation. All files are now owned by 51773:51773 (aka irisowner:irisowner). The installation directory has not changed (still /usr/irissys). 

Before upgrading, users (excluding those using ICM or IKO) MUST chown their durable %SYS directory ($ISC_DATA_DIRECTORY) so that all files are owned by irisowner, for example:

chown -R 51773:51773 $ISC_DATA_DIRECTORY

This will most likely need to be done as root. IKO and ICM perform this ownership change automatically. 

For locked down images, the installation directory ($ISC_PACKAGE_INSTALLDIR) has changed from /home/irisowner/IRIS to /usr/irissys.

Upgrades with IRIS-lockeddown and IRISHealth-lockeddown between versions pre- and post- this change are not supported and will not succeed.

DP-404238: Limit use of PasswordHash to initial configuration

Category: Cloud
Platforms: Cloud
Version: 2021.1.1
Description: 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 change, PasswordHash can only be used during the initial system configuration and cannot be used later to change passwords.

Specifically, PasswordHash will only be processed if the existing hash matches a known, fixed value used to set the initial password.

DP-409557: ICM has new default WebServerPort 57772

Category: Cloud
Platforms: All
Version: 2022.1.0
Description: 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, using the JSON field "WebServerPort".

DP-413048: Remove Linux capability checking from iris containers

Category: Cloud
Platforms: Linux
Version: 2021.1.3
Description: This change removes the no-longer-necessary Linux capability checking from iris containers, to avoid incompatibilities with new versions of Docker.

This doesn't immediately affect ICM users because an older Docker version is set in Samples/defaults.json.

DP-5298: Custom code cannot assume root privileges running in Docker containers

Category: Cloud
Platforms: All
Version: 2019.3.0
Description: In release 2019.2 and earlier, the Docker container had a default root user, but in this release the container has a nonroot default user (irisuser, UID 52773) to improve container security. Consequently, any custom code that assumes that the default user has root privileges running in Docker containers will fail in this release. Processes which connect to an IRIS container (such as via JDBC) should not be affected unless they execute code that makes assumptions about rootlike privileges when dealing with files. Note that container-root already lacks, by default, many of the kernel capabilities usually held by host-root in noncontainer systems.

This change only applies to Docker images provided by InterSystems. If you create a Docker image using a noncontainer install, you can control the default user.

DP-8444: Change in location of container changePassword.sh script

Category: Cloud
Platforms: All
Version: 2019.3.0
Description: With this change, the container changePassword.sh script is in usr/irissys/dev/Container/ instead of /usr/irissys/dev/Cloud/ICM/. If you have any scripts that explicitly specify the location of this file, you should update those scripts.

Compatibility Features

DP-13783: ZEN: Very large integers now serialized as JSON strings

Category: Compatibility Features
Platforms: All
Version: 2020.4.0
Description: 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 as JSON quoted strings. The behavior with values less than 2^53 is unchanged.

CSP

SGM031: Support SameSite for CSP session and user cookies

Category: CSP
Platforms: All
Version: 2019.1.2
Description: When a server sets an HTTP(S) cookie, it can include an attribute called SameSite that affects the scope in which the cookie is sent. The options are as follows:

  • None - Send cookie with cross-site requests.
  • Lax - Send cookie with safe, top-level cross-site navigation.
  • Strict - Do not send cookie with cross-site requests.

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.

Before this change, it was not possible to modify the SameSite attribute, and web applications running on these versions may have such issues. This change allows you specify default values for the SameSite attribute, which will thereby prevent third-party cookie issues form arising.

With this change, the product will explicitly set SameSite both for CSP session cookies and any cookie set via the %CSP.Response.SetCookie() method.

    Two new fields have been added for customizing web applications:
  • Session Cookie Scope
  • User Cookie Scope
  • These fields are displayed in Management Portal's Edit Web Application window, alongside "Use Cookie for Session" and "Session Cookie Path."

    Session Cookie Scope controls the default SameSite value for session cookies associated with the given web application. User Cookie Scope controls the default SameSite value for user-defined cookies created with %CSP.Response.SetCookie(). Session Cookie Scope and User Cookie Scope can be set to None, Lax, or Strict. System web applications and new or upgraded user applications default to Strict for both new fields.

    The %CSP.Response.SetCookie() method also accepts SameSite as an argument, which overrides the default value. You can use this new argument to exercise more fine-grained control over your cookies.

    You should configure grouped applications to use the same Session Cookie Scope setting. Additionally, if you are using "SameSite=None", the web application needs to support secure (HTTPS) connections.

    CSP Server

    DP-416562: Correct WebSocket handling of low-level errors

    Category: CSP Server
    Platforms: All
    Version: 2022.1.1
    Description: This fix corrects a bug in the error handling for web socket connections. If an error was encountered before the CSP server dispatched to the WebSocket class, then the error would be ignored. Now the CSP server will call the Error() method in the WebSocket class. Similarly, for authentication failures, the server will call Login(). Note that by default, Login() just calls Error(). 

    The websocket will also now abort the connection if OnPreServer() returns an error. Previously errors were ignored.

    DP-416563: Do not allow navigation to %-CSP pages from the /csp/sys/oauth2/ application

    Category: CSP Server
    Platforms: All
    Version: 2022.1.1
    Description: This change modifies the default configuration to disallow access to %-CSP pages from the /csp/sys/oauth2/ application.

    DataMove

    DP-413775: Change a few DataMove APIs

    Category: DataMove
    Platforms: All
    Version: 2021.1.3
    Description: Several of the DataMove API's have been changed to add a new first parameter "Name" in the DataMove.API class as follows:

    MapInitialize(Name as %String, Namespaces As %String)
    MapGlobalsCreate(Name as %String, Namespace As %String, GblName As %String, ByRef Properties As %String)
    MapGlobalsDelete(Name as %String, Namespace As %String, GblName As %String) As %Status
    MapGlobalsModify(Name as %String, Namespace As %String, GblName As %String, ByRef Properties As %String)
    

    Customer will need to update their scripts to add this new parameter.

    Drivers

    DRIVERS-2019: ODBC, JDBC, and ADO.net drivers not compatible with Caché/Ensemble

    Category: Drivers
    Platforms: All
    Version: 2019.1.1
    Description: In previous releases, you could use the InterSystems IRIS ODBC, JDBC, and ADO.net drivers with Caché/Ensemble servers as well as with InterSystems IRIS servers. This release introduces changes that make that no longer possible. With a Caché/Ensemble server, you can only use an ODBC, JDBC, or ADO.net driver that is supplied with a Caché or Ensemble release. You can continue to use InterSystems IRIS ODBC, JDBC, and ADO.net drivers with earlier versions of InterSystems IRIS.

    Embedded Python

    DP-409755: Remove $system.Python.Install()

    Category: Embedded Python
    Platforms: All
    Version: 2021.2.0
    Description: This change removes $system.Python.Install().

    To install Python packages for your system, you should only use

    pip3 install
    

    Gateways

    DP-13977+PLUS: Decimal type changes

    Category: Gateways
    Platforms: All
    Version: 2021.1.0
    Description: In this release, $decimal is mapped to Decimal . NET and BigDecimal in Java and the scale is preserved. In previous versions, decimal was mapped to other types and scale was lost.

    in ADO.Net, if a decimal value was set as proxy by a previous version, it will not be accessible by a simple get in this and later versions.

    In Java, if BigDecimal is set using a generic conversion to byte array, a simple get cannot decode it in this and later versions.

    Gateways - .NET

    DP-10361: Change in handling of nullable types

    Category: Gateways - .NET
    Platforms: All
    Version: 2020.1.0
    Description: This release changes the way the gateway handles nullable types so that they are handled correctly. For example, in .NET, if you declare a parameter to be of type long? and the gateway receives an empty string, it now sets the parameter to null, where in previous releases the gateway set the parameter to a 0 value. If your code does not handle null values, you can fix it by changing the parameter type to one that does not include null values, such as long.

    DP-407501: 32-bit processes and external language servers

    Category: Gateways - .NET
    Platforms: All
    Version: 2021.1.1
    Description: External language servers that do not have "Exec 32" checked will change from executing as a 32-bit process to executing as a 64-bit process when started from the Management Portal. This will only affect you if you are loading external assemblies compiled for x86 and did not check the Exec 32 box of the server definition.

    DP-409705: Refresh .NET versions

    Category: Gateways - .NET
    Platforms: All
    Version: 2022.1.1
    Description: This change refreshes the .NET Versions to align with the versions that are still in support by Microsoft. We have removed versions that are no longer in support by Microsoft (.NET Framework 2.0, 4.0 and 4.5, and .NET Core 1.0 and 2.1).

    We have also added support for two versions: .NET Framework 3.5 and 4.6.2. 

    This change also updates the assembly versions so they match the new versions we support.

    The new assemblies will be under a different path, so projects that use the path to the dll location under the IRIS install location will need to update the path to correspond to the new versions. For example, a previous path would be:

    <IRIS install location>\dev\dotnet\bin\v4.5\InterSystems.Data.IRISClient.dll

    That location will no longer exist under the new installation, and should be changed to:

    <IRIS install location>\dev\dotnet\bin\v4.6.2\InterSystems.Data.IRISClient.dll

    In terms of compatibility between versions, the new 4.6.2 version is backwards compatible and the applications will run on systems that have any .NET Framework 4.x installed.

    However, .NET Framework is not forwards-compatible, so if customers have applications that target .NET Framework 4.5, they cannot use one of our .NET Framework 4.6.2 libraries as a dependency. Their options are:

    • Change the target framework of their application to be at least 4.6.2. .NET Framework 4.5 has been out of support by Microsoft so this will also ensure users are using a supported language version.
    • Use the .NET Framework 3.5 version of our library. Users might lose access to certain features/functionality that was introduced in version 4.0.
    • Use old versions of our library that target 4.5. These will not contain the latest bug fixes or functionality, but users will not need to modify the dependencies of their applications.

    Gateways - Java

    DP-13572: JAR file change

    Category: Gateways - Java
    Platforms: All
    Version: 2021.1.0
    Description: If your Java application has dependencies on the Gateway JAR, you must change them to be dependent on the JDBC JAR.

    Global Module

    DP-410470: Change in behavior to deprecated $view(n,-5)

    Category: Global Module
    Platforms: All
    Version: 2022.1.0
    Description: Although it is now an undocumented internal function, $view(n,-5) may still be used in legacy code.

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

    Note that before 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.

    IDEs

    DP-13459: Studio now uses web server configuration from client registry

    Category: IDEs
    Platforms: All
    Version: 2020.4.0
    Description: In previous releases, Studio ignored the web server configuration from the client registry and always queried the server for this information. With this change, Studio first queries the client registry for WebServerAddress, WebServerPort and WebServerInstanceName. If these are not defined in the client registry, Studio will query the server.

    However, if these are defined in the client registry but have incorrect values, you must correct them for Studio to function correctly.

    DP-20650: %CSP.Page changes impact viewing web page from Studio

    Category: IDEs
    Platforms: All
    Version: 2021.1.0
    Description: Classes that extend %CSP.Page, override the CSPURL or LOCATION parameters, and explicitly URL encode these parameters may be directed to the wrong web page when viewing the web page from Studio. This is not the case for any system classes, and the URL encoding these parameters is not a documented feature. This can be corrected by not explicitly URL encoding these parameters.

    DP-416045: Correct Studio bug with View Web Page for a class that had a fully qualified LOCATION parameter

    Category: IDEs
    Platforms: All
    Version: 2022.1.2
    Description: This change fixes a bug in which the View Web Page option did not work for a class whose LOCATION parameter is a full path with the scheme prepended (http:// or https://).

    Installation

    ALE3322: convert ODBC DSNs in Caché or Ensemble to InterSystems IRIS conversion on Windows

    Category: Installation
    Platforms: Windows
    Version: 2019.1.2
    Description: In a Windows conversion from Caché or Ensemble to InterSystems IRIS, the conversion will update all user and system ODBC DSN to use IRIS ODBC driver. All DSN which use SAMPLES namespace will be deleted.

    DP-12790: Restore default superserver port number to 1972

    Category: Installation
    Platforms: UNIX®
    Version: 2020.3.0
    Description: 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.

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

    DP-403425: Installer leaves duplicate ODBC driver

    Category: Installation
    Platforms: Windows
    Version: 2021.1.0
    Description: To allow both Caché and InterSystems IRIS to both exist on a system, the installer should not remove the Caché ODBC driver. On Windows, a new InterSystems IRIS install may result in a duplicate entry for "IRIS ODBC Driver" in add/remove programs applet. You can safely uninstall the older "IRIS ODBC Driver".

    DP-408131: Accessing install directory on Windows from ODBC requires additional privileges

    Category: Installation
    Platforms: Windows
    Version: 2022.1.0
    Description: Users in "Authenticated Users" group no longer are able to write files into the installation directory in locked down install without additional privileges.

    IntegratedML

    DP-13043: Remove support for H2OSA provider

    Category: IntegratedML
    Platforms: All
    Version: 2020.3.0
    Description: The H2OSA provider is no longer supported. If you have used it with a previous release, you must switch to a different provider.

    Interoperability

    DP-10957: System defaults setting now checks values when specified

    Category: Interoperability
    Platforms: All
    Version: 2019.1.1
    Description: In previous releases, invalid values in the default system settings would not be checked until the values were applied in a production. This change ensures that system default settings are valid when specified. If you have invalid system default settings that were saved by a previous release, saving them in this release removes the values. Settings are validated by calling the IsValid() method of the appropriate class. If no IsValid() method is defined, then no validation is performed.

    DP-11139: Changes in X12 validation schema paths

    Category: Interoperability
    Platforms: All
    Version: 2020.1.0
    Description: To enhance the validation feature, this release changes the validation schema paths for hierarchical structures. If you have code specifying these paths, you will need to update them to correspond to these changes. For example, a segment in the 2000B loop of HIPAA_5010:837 would have had path 2000B.segName before, but is now 2000A.2000B.segName.

    DP-11192: Error checking on timeout settings

    Category: Interoperability
    Platforms: All
    Version: 2020.2.0
    Description: This release adds error checking to the timeout settings in the production configuration page. If the requested timeout interval exceeds 1 hour, the page treats it as an error and does not allow the setting. Since it is extremely unlikely that you would want to delay the instance shutdown for an hour, this is most likely an error. However, if you really need such an extended time to wait for the production component to stop, you can still set shutdown to be longer than an hour using a script that calls an Ens.Director method.

    DP-11323: Make PEX callback methods abstract

    Category: Interoperability
    Platforms: All
    Version: 2020.3.0
    Description: The PEX class hierarchy has changes to reduce errors when users overload methods rather than override them. With this change, all methods that should be overridden by user code are marked as abstract. If you define a subclass and do not override these methods, you will get a compile error. Before this change, the compilation 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 this was not enforced by the code.

    DP-11557: XML VDoc character escape changes

    Category: Interoperability
    Platforms: All
    Version: 2020.3.0
    Description: 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 <).

    Before this change, 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.

    DP-11796: PEX library changes

    Category: Interoperability
    Platforms: All
    Version: 2020.3.0
    Description: With this change, we use a different serialization library and we no longer use 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.

    DP-12116: Contents tab of Message Viewer now limits output for XML-enabled objects

    Category: Interoperability
    Platforms: All
    Version: 2020.3.0
    Description: 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.

    An XML comment will be displayed if the contents are truncated.

    DP-12412+DP-13124: Better handling of X12 documents

    Category: Interoperability
    Platforms: All
    Version: 2020.3.0
    Description: 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 work around this incorrect behavior; in that case you need to switch to using the correct property paths.

    DP-12524: Change default of SKIPMESSAGEHISTORY in Ens.BusinessProcess to true

    Category: Interoperability
    Platforms: All
    Version: 2020.3.0
    Description: With this change, 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.

    This MessagesSent and MessagesReceived logging information is separate from the Ens.MessageHeader objects that are created for the requests sent and responses received by a business process. The Ens.MessageHeader objects are not controlled by the SKIPMESSAGEHISTORY parameter.

    DP-12559: Activity monitoring changes

    Category: Interoperability
    Platforms: All
    Version: 2020.3.0
    Description: The activity monitoring pages 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.

    DP-12609: Changes to creating interoperability namespace with %Installer

    Category: Interoperability
    Platforms: All
    Version: 2020.3.0
    Description: Before this change, 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)=""
    

    DP-12694: RecordMap error handling changes

    Category: Interoperability
    Platforms: All
    Version: 2020.3.0
    Description: The error detection for the RecordMap service is now stricter with the ParseOnly flag selected. Before this change, errors would be ignored with ParseOnly even if the AlertOnError flag was enabled. With this change, if the AlertOnError flag is enabled and a record fails validation, then an alert is sent even if ParseOnly is selected.

    This change also corrects the situation when previously no batch would be sent if the FatalErrors setting was equal to ParseOnly and the last record failed to save and there was at least one good record in the batch.

    DP-12727: X12 schema changes

    Category: Interoperability
    Platforms: All
    Version: 2020.4.0
    Description: 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.

    DP-12945: .NET version change

    Category: Interoperability
    Platforms: All
    Version: 2020.4.0
    Description: 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.

    DP-13935: Return value change for OneWay EnsLib.HTTP.GenericService

    Category: Interoperability
    Platforms: All
    Version: 2021.1.0
    Description: Before this change, for any custom code that subclassed EnsLib.HTTP.GenericService and had enabled OneWay, an "HTTP/1.1 200 OK" would be returned to the caller. This is now corrected to ensure returning an "HTTP/1.1 202 Accepted" to the caller.

    DP-280650: Messages bank changes

    Category: Interoperability
    Platforms: All
    Version: 2019.1.0
    Description: Before this change, HTTP, REST and SOAP Generic messages were sent to the Message Bank as Ens.StreamContainer and did not include the HTTP headers. This change causes these messages to be sent to the Message Bank as an XML projection and includes the HTTP headers. Unchanged from previous releases, you cannot resend these Generic messages. If you have code that assumes that these messages are stored as StreamContainer, you should modify the code.

    DP-286249: Java Business Host changes

    Category: Interoperability
    Platforms: All
    Version: 2019.1.0
    Description: The Java Business Hosts BusinessOperation OnInit method has been enhanced and the method arguments have changed. The OnInit method now gets information about the production though a Production object returned in a parameter. To enable this, you must now specify credentials when creating the BusinessOperation in the same way that you specify them for the BusinessService.

    The new Java com.intersystems.gateway.bh.BusinessOperation.OnInit() method is:

    public class javahostsOperation implements BusinessOperation {
    

    @Override public boolean OnInit(Production arg0) throws Exception { // TODO Auto-generated method stub return false; } ...

    The Production object is passed to the BusinessOperation OnInit method in the same way that it is provided to the BusinessService OnInit method. In InterSystems IRIS 2018.1.1 the OnInit method parameter is an array of strings that provides only some of the information available from the Production object.

    If you have Java Business Hosts code from the previous version, you must update the code to use the new method parameter.

    There are the following other changes in Java Business Hosts:

    • In order to access the Java Business Hosts portal page, the user needs either the %Ens_JBH or %Ens_Code privilege.
    • In previous versions, Java Business Services and Operations always used Ens.StreamContainer messages within the production. In this release, they use Ens.StringContainer messages for strings unless the string is very large. In that case, they use Ens.StreamContainer messages.

    DP-287038: Remove %CSP.Util.EnsStart class

    Category: Interoperability
    Platforms: All
    Version: 2019.1.0
    Description: The class %CSP.Util.EnsStart has been removed. Any application calling the method ##class(%CSP.Util.EnsStart).IsEnsembleInstalled() must be changed to call ##class(%EnsembleMgr).IsEnsembleInstalled(). Note that on InterSystems IRIS, this method will always return true.

    DP-288154: Change to Ens.Util.XML.SecuritySignature class

    Category: Interoperability
    Platforms: All
    Version: 2019.1.0
    Description: Before this change, the Ens.Util.XML.SecuritySignature class extended the %XML.Security.Signature class. With this changee, it no longer extends this class. You can continue to call ValidateSAML() in Ens.Util.XML.SecuritySignature, but if you called any other methods in Ens.Util.XML.SecuritySignature, you must change your code to call %XML.Security.Signature directly.

    DP-288880: Change in queue wait time calculation

    Category: Interoperability
    Platforms: All
    Version: 2019.1.0
    Description: To improve the efficiency of the Ens.MonitorService, this release changes the way the queue wait time is calculated. For business hosts with a pool size of 1, the amount of time the active message has taken to be processed is now counted s part of the queue waiting time. In rare cases, this could change how InterSystems IRIS behaves in responding to the QueueWaitTime alert setting.

    DP-289579: SOAP outbound adapter clears HTTP headers

    Category: Interoperability
    Platforms: All
    Version: 2019.1.0
    Description: The SOAP Outbound Adapter should clear the SOAP client HTTP headers after completion of the SOAP call. In previous releases, it was only clearing the HTTP headers after a successful call and was not clearing them after a failure. In this release, the SOAP Outbound Adapter clears the SOAP client HTTP headers after each Invoke(), InvokeMethod(), or InvokeWithSOAPBody() call, whether the call succeeds or fails. If you are using the SOAP wizard to generate the class, there is no compatibility issue. If you have created custom code that uses the SOAP Outbound Adapter and relied on the HTTP headers not being cleared, you should modify your code to ensure that the headers are set correctly before each call.

    DP-290238: New default behavior for validation in Add Router Wizard

    Category: Interoperability
    Platforms: All
    Version: 2019.1.0
    Description: In this release, the validation default has changed when creating a new router with the Add Router wizard. This does not impact any existing routers that were created with the previous wizard. In the previous release, if you left the validation field empty for routers that support validation, such as an X12 router, validation was disabled. In this release, if you leave the field blank in the wizard, validation is set to the value specified in system defaults, if one is specified. Otherwise, it gets the default value, which enables validation for routers that support it. The wizard has a new check box to disable validation.

    DP-291017: Display change for settings in custom category

    Category: Interoperability
    Platforms: All
    Version: 2019.1.0
    Description: If a user defines a property in a Business Host or Adapter class, they can also include it as a setting, by adding it to the SETTINGS parameter. Within the SETTINGS parameter, if the property name is followed by ":" and additional text, that second piece is used as the category under which the settings will be displayed in the Settings tab on the Production Configuration page. There are some predefined categories, such as Info, which is displayed as "Informational Settings", and Alerting, which is displayed as "Alerting Control", but the user can also create a custom category. In previous releases, if the category specified for a setting was a custom setting, the word "Settings" would always be appended to the specified name as the display category. In this release, the category will be displayed as specified without "Settings" appended to it. If you want to have the word Settings included in the category as displayed, you should add it to the category in the SETTINGS parameter.

    DP-292072: Studio users need added privilege to run stored procedures

    Category: Interoperability
    Platforms: All
    Version: 2019.1.0
    Description: In this release, developers using Studio will need execute privileges on stored procedures for some actions. This privilege is Ens_Config.Production_Extent. If a developer has the role %EnsRole_Developer or %EnsRole_Administrator, then the developer has this privilege.

    DP-292364: Production export includes custom base schemas

    Category: Interoperability
    Platforms: All
    Version: 2021.1.0
    Description: The Interoperability Production Code Export will now include custom base schemas if appropriate. The query EnumerateVDocSchemas now return also returns the Base value.

    DP-404469: New privilege needed to schedule Ens.Util.Tasks.Purge* tasks

    Category: Interoperability
    Platforms: All
    Version: 2022.1.0
    Description: To schedule Ens.Util.Tasks.Purge* tasks, the user must have the %Ens_PurgeSchedule:USE privilege, which is granted by the %EnsRole_Administrator role, and which can be added to custom roles. The %Ens_MessageResubmit and %Ens_SequenceManager resources no longer exist; no customer code should have referenced them directly.

    DP-405689: DTL calls now respect async="true" setting

    Category: Interoperability
    Platforms: All
    Version: 2021.2.0
    Description: 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.

    DP-412625: Interoperability XML virtual document schema correction when collapsing single child generation

    Category: Interoperability
    Platforms: All
    Version: 2022.2.0
    Description: When a schema has a generation of single properties, the collapse mechanism could lead to the final child node not being represented properly in the schema. This is now corrected.

    DP-412629: Improve XML Virtual Document support for 'any' element

    Category: Interoperability
    Platforms: All
    Version: 2022.1.1
    Description: Before this change, when setting XML data to an 'any' element of an XML Virtual Document, the 'any' tag would be included in the output.

    Also when using a sub-transform, the XML representation used to set to a target property of element type 'any' would not include the top level. This is also corrected. The correction is to the EnsLib.EDI.XML.Document SetSubDocument() method.  This method inserts the XML representation of pSubDocument into the target document at the path specified by pPropertyPath. The XML representation is the GetValueAt using "/1" as the property path except if the target Property Path where the sub document is to be set is of type "any" then the XML representation of pSubDocument retrieved  will be the full document including top element i.e. path "/"

    DP-413564: Correct Interoperability Reply Code Action D triggering Alert On Error if retried

    Category: Interoperability
    Platforms: All
    Version: 2022.2.0
    Description: The Interoperability Reply Code Action D would only trigger an Alert On Error if there had not been a prior action [R(etry)]. This is now corrected. If for example the Reply Code Action is E=RD and Alert On Error is enabled, then an alert will be sent for the Retry and also the Disabling if the failure timeout is reached.

    DP-414056: Prevent end user naming of Interoperability Host Names with reserved leading underscore

    Category: Interoperability
    Platforms: All
    Version: 2022.2.0
    Description: With this change, host names cannot start with an underscore (_) character. If a production includes hosts whose names have the leading underscore, there is a compilation error when you compile the production class.

    DP-415945: Interoperability Java and DotNet Gateway services modifications for core api change

    Category: Interoperability
    Platforms: All
    Version: 2022.1.1
    Description: The classes EnsLib.JavaGateway.Service and EnsLib.DotNetGateway.Service have a new exposed setting in the Production Configuration page of "External Language Server Name" (property %gatewayName).

    The value of External Language Server Name is a name given in the Management Portal at System > Configuration > External Language Servers

    For an EnsLib.JavaGateway.Service, it can be %Java Server or a custom Java type entry. (Note that when used with a SQL Business Service or Operation that uses JDBC, it is still a Java type entry and not JDBC type)

    For an EnsLib.DotNetGateway.Service, it can be %DotNet Server or a custom .NET type.

      Once External Language Server Name is specified, it supersedes the settings in Server and Port and the associated gateway configuration settings such as classpath , heartbeat, use passphrase and JVM.

    Note it is now not possible to start a gateway that uses a passphrase without using an External Language Server Name.   The superclass EnsLib.JavaGateway.Common used by Services and Operations that use the gateway now identifies if the associated Java Gateway specifies an External Language Server Name  and uses that value rather than the Server and port values to connect to the relevant proxy gateway. 

    It is intended that there will be no need for EnsLib.JavaGateway.Service and EnsLib.DotNetGateway.Service items at a later date.

    DP-5315: EnsLib.HTTP.GenericMessage now explicitly defines XMLNAME parameter as well as XMLTYPE

    Category: Interoperability
    Platforms: All
    Version: 2019.1.1
    Description: With this change, Ens.StreamContainer and its subclasses can be deserialized from XML. Ens.StreamContainer and subclasses EnsLib.HTTP.GenericMessage,EnsLib.SOAP.GenericMessage,EnsLib.REST.GenericMessage and Ens.MFT.StreamContainer can now be deserialized from XML. This means for example they can be resent from the Message Bank or tested in the DTL editor.

    As part of the correction, EnsLib.HTTP.GenericMessage now explicitly defines XMLNAME parameter as well as XMLTYPE. If you have defined any custom subclasses, you need to modify them to account for this change; override the XMLNAME parameter as required for your code.

    DP-6920: New X12 validation may impact previously ignored flags

    Category: Interoperability
    Platforms: All
    Version: 2019.1.1
    Description: This change adds element-level validation for X12 documents.

    The behavior for existing X12 validation flags in routers is unchanged. However, in the unlikely event that you have specified extra validation flags that were not previously valid, the behavior may change. If you specified a nonexistent validation flag, it would have been ignored, but if the flag now matches a new validation flag, the specified validation will be performed.

    For a list of the new validation flags, see Validation in Routing X12 Documents in Productions.

    DP-8848: Changes in syncresponses array in BPLs

    Category: Interoperability
    Platforms: All
    Version: 2019.4.0
    Description: The syncresponses array was not being correctly populated with the callresponses. Instead the process's response object was being used. It is unlikely that custom code will rely on syncresponses containing the response object. However, if this is the case then reworking of the code will be necessary.

    DP-8962: Changes to EnsLib.EDI.Segment class

    Category: Interoperability
    Platforms: All
    Version: 2019.4.0
    Description: This change removes the RawContent property from the EnsLib.EDI.Segment class.

    If you have subclassed EnsLib.EDI.Segment and are making use of the RawContent property (this would require creating the getter method RawContentGet()), then you now have to add RawContent to the list of properties in your custom class since it would no longer be inheriting this property from EnsLib.EDI.Segment.

    DP-9264: Changes in X12 acknowledgment documents

    Category: Interoperability
    Platforms: All
    Version: 2019.4.0
    Description: This change corrects the values of many fields in X12 Acknowledgement (997 and 999) Documents that are created as a reply to incoming X12 documents.

    • GS07 (Responsible Agency Code) is now set to "X" (ASC X12) instead of blank
    • GS08 (Version / Release / Industry Identified Code) for 999 replies is now set to 005010X231A1
    • ST03 (Implementation Convention Reference) for 999 replies is now set to 005010X231A1 instead of the Implementation Guide of the original document
    • IK502 (Implementation Transaction Set Syntax Error Code) is now set only if there is an error code
    • AK905 (Functional Group Syntax Error Code) is now set only if there is an error code

    This change also moves the X12 Business Service setting 'LocalApplicationID' into the Acknowledgement section to make it more visible, and changes the initial expression to '@:@' because this is much more likely to yield the desired results.

    Setting LocalApplicationID to '@:@' results in using the original Document's ISA07 (Interchange ID Qualifier) and ISA08 (Interchange Receiver ID) as the values for the reply Document's ISA05 (Interchange ID Qualifier) and ISA06 (Interchange Sender ID).

    DP-9292: Changes in display of host status

    Category: Interoperability
    Platforms: All
    Version: 2019.4.0
    Description: The meaning of the running status display in the Production Configuration page has changed because the changes to support source control for productions has involved a slightly different possible state. The status in the production configuration diagram for items that are enabled but not running, either because the item has a schedule and is currently stopped or if the item has been temporarily stopped, has changed. These items now have the status stopped which means that the item dot is shown light green as per the existing legend: Not running, enabled.

    Therefore 'Not running' can apply if the production is stopped or if the item is not running but the production is running.

    DP-9515: HL7 parser event log warning replaced by TraceCat entry when segment name pattern unexpected

    Category: Interoperability
    Platforms: All
    Version: 2019.4.0
    Description: With this change, in order to see information about unexpected HL7 segment names, you must now set ^Ens.Debug("TraceCat","parse") to 1. Previously, the HL7 Parser would create an event log warning for unexpected HL7 segment names.

    Note validation of the message is not affected.

    DP-9767: Changes for existing applications that will use dynamic gateway in place of legacy gateway

    Category: Interoperability
    Platforms: All
    Version: 2020.1.0
    Description: This change allows existing applications that use the legacy gateway to switch to the new Dynamic Gateway by regenerating the proxy classes. Proxy classes generated with this new style are called Recast Gateway. Proxy classes generated with the old style are now called Legacy Gateway.

    To generate Recast Gateway proxy classes for a specific namespace, set the following global:

    set ^%SYS("Gateway","Remote","Recast",namespace)=1

    Or to generate Recast Gateway proxy classes for all namespaces, set the following global:

    set ^%SYS("Gateway","Remote","Recast")=1

    Then re-import all the proxy classes. The first global governs Recast behavior for one namespace only while the second global governs Recast behavior for all namespaces that don't have their own setting. The import utility will automatically mark all the no-recast generated classes as out-of-date and re-import all the classes in the inheritance hierarchy.

    All of the proxy classes have to be regenerated together. The Recast Gateway proxy classes cannot be mixed with Legacy Gateway proxy classes.

    The Recast Gateway generated proxy classes have the same generated interface as the Legacy Gateway proxy classes. Runtime behavior is compatible. The only known differences are in the area of fixing erroneous behaviors in Legacy Gateway, Dynamic Gateway enhancements, and in handling of runtime type mismatches. The following are the runtime differences:

    • Difference in dispatching overloaded method of the same argument count. Recast Gateway uses a new method overloading resolution algorithm that's in Dynamic Gateway. The detailed behavior is:

      • In Dynamic Gateway, when dispatching a method, first look for the method under the number of runtime parameters. If the number of methods found is unique, gateway has found thetarget.
      • If there are more than one method that match the runtime parameter count, then disambiguate further on parameter types.
      • Only use the $list type for runtime type. don't use runtime values.
      • $list only gives three primitive types, STRING ($list type 01, 02), INTEGER ($list type 04, 05) and DOUBLE ($list type 06, 07, 08) , plus OREF ($list type 25, 26) type.
      • Divide all Java/.NET primitive types (and their boxed types) into 3 type families based on $list types.
      • Check to see if each actual type is a match for the corresponding formal type.
      • In this check, an actual type can match more than one formal type. For example, runtime type INTEGER is a match for formal type short, int, long or boolean.
      • At the end of the process, if there is only one method left that matches with all actual types, then the search is successful. If none is left, search has failed to find an overloaded method. If more than one is left, then there is an unresolvable ambiguity.
      • Same algorithm applies to constructors.
      • Currently, when overloading is not involved, ignore runtime types. Just convert parameters (of any actual type) to their corresponding formal type. In order to have a consistent behavior, logic says, if a particular formal parameter has no type variations, then the actual type check is skipped. In another word, only use actual type to disambiguate if there is any ambiguity to begin with, and this applies on each parameter independently.
      • Any missing or undefined parameter (which results in UNDEFINED in $list) is a match for any formal type.
      • Non-primitive formal types are matched to actual parameter objects (OREF type in $list) using "instanceof" check.
      • At runtime, users can coerce a parameter's $list type in order to influence overloading resolution. Usually, a straight-up literal has the $list type of what it appears, for example m("ABC") is a STRING type, m(123) is an INTEGER type and m(3.14) is a DOUBLE type. To force a particular type on a variable with unknown type, do the following:

        1. m(x_"") forces the parameter to be a STRING.
        2. forces the parameter to be an INTEGER.
        3. m($double(x)) forces the parameter to be a DOUBLE.
      Note, this algorithm is different from how Legacy Gateway works. Legacy Gateway parses the actual value of the parameters in order to guess the runtime type. This guessing is inherently inaccurate. Sometimes, Legacy Gateway failed to dispatch because the guess is wrong, other times, Legacy Gateway dispatches successfully even when clear ambiguities exist.

    • Difference in support for pass-by-reference. Recast Gateway uses pass-by-reference support implemented in Dynamic Gateway, which makes it somewhat different from the limited support of pass-by-reference in Legacy Gateway.

      Pass-by-reference works in the Dynamic Gateway and recast Gateway as follows:

      • C# method declares method parameter pass-by-reference with "ref" or "out" keywords
      • At runtime, IRIS user calls the corresponding proxy method with .variable syntax (IRIS pass-by-reference syntax)
      • Modified values of the C# pass-by-reference parameters will be sent back to IRIS and assigned into user's pass-by-reference variable.
      • This is only in .NET as Java doesn't support pass-by-reference.
      • This works for primitive datatypes as well we objects.
      • When the parameter is an object, this support is for "pass-by-reference" in .NET per se, which means when the parameter variable is assigned a new object, that new assignment is passed back to IRIS variable.
      The different behavior in the Legacy Gateway is:
      • Legacy pass-by-reference doesn't support datatypes - objects only.
      • Legacy pass-by-reference doesn't support "ref" keyword - "out" keyword only.
      • Legacy pass-by-reference doesn't require .variable syntax
      • At runtime, Legacy pass-by-reference variable must not be null OREF.
      • Callee code cannot change the pass-by-reference parameter to a different type - i.e. cannot change to an object of a subclass.
      With all the difference described above, what works the same is the basic simple case. For example, variable x is a proxy of a Person object in .NET, say with firstName equals to "Isabella". Then call a method in .NET that declares this parameter with "out" keyword and the method changes the parameter assignment to a new Person object with firstName equals to "Mia". IRIS user calls the method with (.x), and after the call, x.firstName will equal to "Mia".

      But these gateway work very differently internally. After a pass-by-reference parameter is changed, instead of sending the modified value back to IRIS, Legacy Gateway simply changes the oref-registry. This implementation has some unexpected side-effects: Using the above example, if we set y=x before the call. After calling m(.x), not only x.firstName is changed, y.firstName is also changed to "Mia". This side-effect is highly undesirable. Fixing the behavior of this side-effect in Recast is one of difference in behavior.

    • Constructor with array arguments are not working properly in Legacy Gateway. It is working properly in Recast Gateway, together with updating array contents just like any other methods.
    • Properties with underscore in the name as prefix or suffix are not working properly in Legacy Gateway. It is working properly in Recast Gateway.
    • Methods with varargs work mostly the same. In Legacy Gateway, overloaded method with varargs do not work properly. Recast Gateway works properly on all vararg and overload combinations.
    • Array of Objects do not work properly in Legacy Gateway, It works properly in Recast Gateway.
    • Recast Gateway is more dynamic. In most cases, modification to Java code doesn't require the proxy classes to be regenerated. For example, after generating Recast proxy classes, user can modify the Java class to add methods or change signature of Java methods. The existing Recast proxy classes will work with the new Java classes without being regenerated. In fact, most of the generated methods in Recast Gateway proxy class don't need to be there at all. The proxy class works just fine without them. The methods are there mostly for documentation purposes, as Legacy Gateway users are used to looking at the proxy class to see which methods are there.
    • Recast Gateway supports Reverse Proxy which comes with Dynamic Gateway. In Recast Gateway, IRIS objects passed to Java/.NET methods will arrive as objects of IRISObject which are reverse proxy objects on which users can access properties and methods on the IRIS side. In Legacy Gateway, IRIS objects arrive in Java/.NET, sometimes as Strings, ometimes as null, but overall, was not a supported behavior.

    DPP-847: Removal of deprecated Java Business Hosts -- use PEX instead

    Category: Interoperability
    Platforms: All
    Version: 2020.4.0
    Description: This change removes Java Business Hosts, a feature that was deprecated in release 2019.3. 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.

    JDBC

    DP-11994+PLUS: API Cleanup

    Category: JDBC
    Platforms: All
    Version: 2020.3.0
    Description: 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.

    DP-12762: Newly supported connection pooling for JDBC

    Category: JDBC
    Platforms: All
    Version: 2020.4.0
    Description: Before this change, connection pooling was not a supported feature. This change 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.

    DP-13164: Change to IRISCallableStatement.getBytes(String)

    Category: JDBC
    Platforms: All
    Version: 2020.4.0
    Description: 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)).

    DP-13515: If compact double is enabled, all clients must support it

    Category: JDBC
    Platforms: All
    Version: 2021.2.0
    Description: 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.

    DP-286960+DP-291907: SQL.JDBC delete row removes from client and corrects cursor

    Category: JDBC
    Platforms: All
    Version: 2019.1.0
    Description: In previous releases, if a row was deleted from updateble ResultSet, it would not be consistently deleted from the client. In this release, the deleted row will be deleted from the client. If your code depended on the previous behavior and assumes that the row would not be deleted, you should update your code. This release also ensures that cursor movements take into account deleted rows so that the client row index matches the server persistent Row ID.

    DP-290054: SQL.JDBC may use fast insert for SQLType storage

    Category: JDBC
    Platforms: All
    Version: 2019.1.0
    Description: In this release, fast insert is enabled by default if the platform supports it. Using fast insert with the SQLType storage of literal values should not have any compatibility impact for most users.

    You can explicitly disable fast insert by setting the ConnectionOption property to 1 or 0, as shown in the following example:

      Class.forName("com.intersystems.jdbc.IRISDriver");
      IRISDriver driver = (IRISDriver) Class.forName("com.intersystems.jdbc.IRISDriver").newInstance();
      String url="jdbc:IRIS://localhost:1972/user/";
      Properties p = new Properties();
      p.setProperty("FeatureOption", "0");
       /* 0 disables fast insert and delete,
          1 enables fast delete but  disables fast insert, 
          2 enables fast Insert but disables fast delete,  
          3 enables both fast insert and fast delete */
      p.setProperty("user", "_SYSTEM");
      p.setProperty("password", "SYS");
      Connection c=driver.connect(url, p);
    

    DP-291669: SQL.JDBC throws error for illegal date/time values

    Category: JDBC
    Platforms: All
    Version: 2019.1.0
    Description: The JDBC 4.1 standard does not allow Set/Get Date to Time and Time to Date columns. Although the previous release of InterSystems IRIS server correctly produced an exception on the set, it did not produce an exception on the get, and the client did not validate either. This release validates both get and set and throws an exception 17004 "Invalid column type". If your code explicitly tests for the "Field validation failed" exception text that was formerly returned for the set or relies on the get to not generate an exception and return a dummy value, you should update your code.

    DPP-367: Need new drivers for new SQL syntax features

    Category: JDBC
    Platforms: All
    Version: 2021.2.0
    Description: 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.

    Journaling

    DP-413465: Return meaningful error from ##class(%SYS.Journal.History).GetHeader()

    Category: Journaling
    Platforms: All
    Version: 2022.2.0
    Description: In the case where the journal log contains no or bad version info, ##class(%SYS.Journal.History).GetHeader() (and its direct or indirect callers such as ##class(Journal.Restore).CheckJournalIntegrity()) now returns a meaningful error such as "Journal log <path> missing version", which is also compatible with the existing $System.Status facility. The old return value in this case, "0v", is obscure in meanings and incompatible with the existing $System.Status facility.

    DP-9521+DP-287295+DP-292255: Changes for dejournaling

    Category: Journaling
    Platforms: All
    Version: 2019.4.0
    Description: There are several dejournaling changes, which have some impact on system administration:

    • On systems configured with a database cache larger than 128GB, a dejournaling task (which applies database updates in the journal to databases during a journal restore or when the backup failover member of a mirror is synchronized with the primary) may employ more updater processes than in previous versions, and therefore use more system resources. If your instance is close to resource limits, this may cause problems.
    • Previous versions of Caché or InterSystems IRIS allowed fewer databases to be mounted at one time than the current version. Any journal files created after an instance has passed the old limit are therefore incompatible with previous versions of Caché or InterSystems IRIS. For example, they could not be used to run a journal restore after restoring databases from backup to an instance of a previous version. However, journal files created by previous versions are compatible with this version.
    • Parallel Dejournaling has been enhanced to allow multiple jobs to process separate globals within a single database rather than being restricted to processing only separate databases in parallel. This affects the ordering of updates that can be seen when dejournaling has been started but not yet completed. For details, see Restore Globals From Journal Files Using ^JRNRESTO in the description of Data Integrity Journaling and Configuring Parallel Dejournaling in the description of Configuring Mirroring for high availability.

    JSON

    DP-410199: ##class(%DynamicAbstractObject).%FromJSON("") returns "" instead of an error

    Category: JSON
    Platforms: All
    Version: 2022.2.0
    Description: A call on ##class(%DynamicAbstractObject).%FromJSON("") will return the empty string, "", instead of throwing an exception for "Premature end of data".   However, %FromJSON(arg) will still throw that error if (1) arg is a %Stream containing no additional characters; if (2) arg is a file name referencing a %File that contains no characters; or if (3) arg is an ObjectScript string containing only white space characters or is otherwise an incomplete JSON string.

    Note:  a call on DynamicObject.%ToJSON() that does not signal an error will always return an ObjectScript string containing at least two characters, e.g., [] or {}.

    Any code expecting %FromJSON("") to throw an error will need to be modified to special check for "" being passed as an argument to %FromJSON(arg).

    Kernel

    DP-10339: Add protection check to modify the keep flag or growth block of a global

    Category: Kernel
    Platforms: All
    Version: 2020.1.0
    Description: This change requires write access in order to modify the keep flag or growth block of a global. If your code attempts to modify these characteristics without write access, it will fail with a <PROTECT> error.

    DP-10904: Journaling files may be compressed

    Category: Kernel
    Platforms: All
    Version: 2021.2.0
    Description: The system can now automatically compress journal files after they are created to reduce the amount of space consumed by older journal files. Compressed files have a 'z' appended to their name. Any code which scans for journal files by name needs to be updated to cater for this change (if compression is enabled).

    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.

    DP-12215: GLOSTAT changes

    Category: Kernel
    Platforms: All
    Version: 2020.3.0
    Description: 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.

    DP-12307: Asynchronous I/O for database writes on Linux and UNIX®

    Category: Kernel
    Platforms: UNIX®
    Version: 2020.3.0
    Description: With this change, the product on Linux uses 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 the product to perform acceptably with an under-configured database cache in previous versions. Check that database cache is sized appropriately on your system.

    Additionally, the product on Linux and all UNIX® platforms now uses 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.

    DP-12577: Memory usage changes for global and routine buffers

    Category: Kernel
    Platforms: UNIX®,macOS
    Version: 2020.3.0
    Description: This change 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 the product, 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:

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

  • On startup, if database cache is unspecified, a message "Global buffer setting requires attention. Auto-selected 25% of total memory." will be emitted.
  • 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.
  • See Memory Management and Scaling for InterSystems IRIS for more information about memory management.

    DP-13047: Support FIPS mode for libcrypto.so.1.1 in Red Hat Linux 8.2

    Category: Kernel
    Platforms: Linux
    Version: 2020.1.1
    Description: On Red Hat Linux, you can only use libcrypto.so.1.1 FIPS mode on Red Hat Linux version 8.2 and later. You cannot use this mode on earlier versions.

    DP-13055: %ETN could change null subscript setting

    Category: Kernel
    Platforms: All
    Version: 2020.3.0
    Description: 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.

    DP-13195: Remove extern symbol zfedll from include files

    Category: Kernel
    Platforms: UNIX®
    Version: 2020.4.0
    Description: 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
    
    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.

    DP-13424: Cannot connect with ECP to older releases by default

    Category: Kernel
    Platforms: All
    Version: 2021.2.0
    Description: 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 don't support this feature; specifically, if you attempt to connect to older instances, the result will be an error.

    You may disable this compression 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.

    DP-13552: Handle string values in $SYSTEM.Event.Wait()

    Category: Kernel
    Platforms: All
    Version: 2020.4.0
    Description: In previous releases, a $SYSTEM.Event.Wait() with a string value would cause no timeout. With this change, 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.

    DP-13698: Changes to TCP TLS in FIPSMode

    Category: Kernel
    Platforms: All
    Version: 2020.1.1
    Description: 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.

    DP-13931: Minor write daemon changes

    Category: Kernel
    Platforms: UNIX®
    Version: 2021.1.0
    Description: These are minor changes unlikely to impact code. In the %SYS.ProcessQuery, $SYSTEM.Process, SYS.Process classes, the property Routine has the value "AUXWD" rather than "SWRTDMN" for the auxiliary write daemons. For the property JobType, which is documented as taking a value from %syPidtab.inc, the definition in that include file is renamed from $$$SLWDTYPE to $$$AUXWDTYPE, and the numeric value is unchanged. In UNIX® systems, process names are changed from SWD1, SWD2, ... to AUXWD1, AUXWD2,...

    DP-20621: ^JCONVERT changes

    Category: Kernel
    Platforms: All
    Version: 2021.1.0
    Description: ^JCONVERT now creates and processes common journal files in the enhanced format, which supports long strings. It has a new prompt to control whether common journal files are created in the enhanced format or in the previous format. If you need to create common journal files that can be read by ^%JREAD or ^JCONVERT from a previous version, you must specify that you do not want the enhanced format.

    DP-275329: Task termination change

    Category: Kernel
    Platforms: All
    Version: 2021.1.0
    Description: In previous releases, tasks that were terminated by shutdown were marked as suspended. With this change, they are not marked as suspended by default. If you want tasks terminated by shutdown to be marked as suspended, set the new SuspendTerminated property.

    DP-290643: System statistics revisions for better scalabililty

    Category: Kernel
    Platforms: All
    Version: 2019.1.0
    Description: To improve performance of large-scale systems, the statistics reported by the system utilities have changed. In most cases this will not cause any compatibility issues; however, if your code explicitly examines the statistics output for specific data, you may have to update your code to adjust for these changes. The following minor changes are visible:

    • The ^GLOSTAT utility no longer offers detailed block type statistics and no longer asks the question "Should detailed statistics be displayed for each block type? No =>". Additionally a bug is corrected in ^GLOSTAT that caused remote reads and remote cache efficiency to be incorrect (usually zero).
    • The Management Portal System Dashboard is enhanced to show private global references and updates and WIJ writes, in the same way that ^GLOSTAT does. The detailed block type statistics page, 'Disk and Buffer Statistics', is no longer available.
    • The ability to zero statistics (from ^GLOSTAT and the Management Portal) is not available. This capability is not compatible with the more efficient statistics collection.
    • The class SYS.Stats.Disk, which accesses the detailed block type statistics, reports all as zero; the class reference is updated to reflect this. The class SYS.Stats.Global, which accesses the main global statistics, continues to function as before and is enhanced to include write image journal writes as a property called 'WIJWrites'. Additionally, the internal class SYS.Metrics was previously exposed (unintentionally) as a public API; it is now properly marked as internal-only and it no longer reports values for detailed block type statistics.
    • The WS-Monitoring and BMC Patrol facilities that report the detailed block type statistics, report them zero or null. BMC Patrol, WMI, and SNMP monitoring facilities lock counts (total, success, and fail) also report as zero.
    • The iris stat -g1 is updated to include more fields that were previously only available in ^GLOSTAT displays. Some statistics that were available via the iris stat -c option are no longer available.

    Note:%Monitor.Process, MONLBL, PERFMON and similar performance monitoring tools are unaffected by this change and maintain their own counters.

    DP-401740: (Windows) Greater precision in $ZNOW and $ZTIMESTAMP

    Category: Kernel
    Platforms: Windows
    Version: 2021.2.0
    Description: With this change, 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 these functions are not needed. If you call these functions, you must update your code.

    DP-401894: Improve storage efficiency by performing kills in ascending order

    Category: Kernel
    Platforms: All
    Version: 2022.1.0
    Description: This 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.

    DP-404334: Quote $ZF() shell commands on Windows

    Category: Kernel
    Platforms: Windows
    Version: 2021.1.1
    Description: Windows shell commands must be enclosed in quotes if there are quoted arguments along with a quoted command path. Those quotes will now be added by $ZF(-1), $ZF(-2), and $ZF(-100,"SHELL").

    DP-405025: Changes to rounding of ObjectScript decimal floating-point values

    Category: Kernel
    Platforms: All
    Version: 2021.2.0
    Description: 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.

    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.

    DP-406134: Change to error signalled by dynamic objects and arrays

    Category: Kernel
    Platforms: All
    Version: 2021.2.0
    Description: 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.

    DP-407539: Improvements to purging backup logs

    Category: Kernel
    Platforms: All
    Version: 2022.1.0
    Description: 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, and log files generated by running backups from the Management Portal were never purged. This change makes the handling of these logs consistent: purging purges both kinds of logs. 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.

    DP-408501: Replace random number generator algorithm in $Random with Splitmix64

    Category: Kernel
    Platforms: All
    Version: 2022.1.0
    Description: Before this change, $random used a pseudo random number generator algorithm. With this change, we replace it with Splitmix64, a fast pseudo random number generator algorithm that can pass rigorous statistical tests of its randomness.

    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.

    DP-409100: Run object destructors when a .Net application quits

    Category: Kernel
    Platforms: All
    Version: 2021.1.3
    Description: Actions performed by an object's %OnClose method, such as unlocking a record in a persistent class, were not being performed in a timely manner for a client/server application using .Net, JDBC, etc.

    DP-409851: Change to viewing private program data on AIX

    Category: Kernel
    Platforms: AIX
    Version: 2021.2.0
    Description: With this change, on AIX, you will receive 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).

    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.

    DP-410050: Correct a rare bug on class initialization

    Category: Kernel
    Platforms: All
    Version: 2021.1.3
    Description: This change corrects a very rare bug that could cause the wrong version of a class to be loaded into memory. This could lead to increased memory usage if class components are not being used. Otherwise, it only changes the time at which they are loaded into memory.

    DP-410087: Change in error when dynamic dispatch is not implemented

    Category: Kernel
    Platforms: All
    Version: 2022.1.0
    Description: 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>.

    DP-410225: Add more fields for audit log entry in structured logging

    Category: Kernel
    Platforms: All
    Version: 2022.2.0
    Description: Before this change, when the LOGDMN process scanned the audit log, it persisted only the following audit event fields to the log file: EventSource,EventType,GroupName,Namespace

    With this change, the LOGDMN process 1) includes all the fields as seen in the details of ^SECURITY for an audit log record and 2) improves audit log scanning process to one pass for better performance.

    Log entry parsing, parameter matching, and value extraction might break if your code relies on the previous behavior.

    DP-412202: Changes to $zversion String and GetPlatform() for Linux

    Category: Kernel
    Platforms: Linux
    Version: 2022.1.0
    Description: 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.

    DP-413544: Change ZBREAK so %Destruct stepping is ON by default

    Category: Kernel
    Platforms: All
    Version: 2022.2.0
    Description: When debug stepping is enabled and an object reference is closed, the debugger will now step into the %Destruct and %OnClose methods. Previously this stepping was disabled by default. This stepping may be turned off with the command ZBREAK /NOSTEP:DESTRUCT.

    DP-6736: Maximum frame depth reduced on 32-bit Unicode

    Category: Kernel
    Platforms: UNIX®
    Version: 2019.1.1
    Description: This change fixes a problem caused if a second <FRAMESTACK> error is encountered when TRY/CATCH catches a <FRAMESTACK> and tries to create the error object. This condition lead to the process terminating. This was an issue only on non-Windows 32-bit Unicode platforms.

    This change is unlikely to cause problems unless your code created conditions that were very close to the previously allowed frame depth.

    This was an issue only on non-Windows 32-bit Unicode platforms.

    Language Bindings - Native

    DP-10835: New version of XEP

    Category: Language Bindings - Native
    Platforms: All
    Version: 2020.3.0
    Description: This change provides a new version of XEP support, which includes enhanced indexing and a new underlying client/server communication method. Consequently, you cannot use an XEP from a previous version of the product with this version as the server and you cannot use this version' 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.

    DP-12437+PLUS: IRISNative and Gateway Changes

    Category: Language Bindings - Native
    Platforms: All
    Version: 2021.1.0
    Description: This release contains the following changes to the language bindings IRISNative API and to the gateway:

    • Changes to Native SDKs and IRISList :

      • If the underlying value is the empty string, getObject returns an empty string or zero-length byte array. If the underlying value is UNDEFINED, getObject returns a null.
      • For numeric types, if the underlying value is an empty string, get returns a 0 value.
      • getObject returns a byte array for type 1 (ASCII).
      If you use this feature, you will have to refactor and recompile your code. These changes have the following consequences:
      • Empty string is not converted to $char(0) and back as it was done in previous releases. Empty string is left as empty string. Note that this is different from the SQL semantics for empty strings.
      • An attempt to use empty string or empty byte[] as a subscript generates a <SUBSCRIPT> error.
      • No changes in setting null. set(null,) and set ("",) both result in empty string on the server.
      • Getting undefined value will result in null.
      • Getting any numeric (int, double) value from "" returns 0. For methods and functions, the return value is null.
      • getByte from "" returns empty byte[0] , getString from "" results in empty string.
      • GetObject from type 1 results in byte[0] in both the IRIS and IRISList classes.
      • GetDateTime from empty string returns null, where in previous releases it was throwing an exception.
      • getIRISList returns a valid object of length 0 for values 02 01, and returns a null object for 01.
      • Iterator returns an empty string if subscript is not found, where in previous releases a null was returned.
    • Projection of byte array in method arguments — In previous releases, byte arrays were projected as strings, but in this release they are projected as a proxy object. You can convert the proxy object to a %GlobalBinaryStream object (first in 2020.3).
    • Parameter order in IRISNative iris function and iris procedure change — In the previous version, there was a difference in the order of the parameters between the documentation and the implementation. In this release, the implementation has been updated to match the documentation (first in 2020.3). The parameter order is as follows:

      iris.function(functionName,routineName,*args)

      iris.procedure(procedureName,routineName,*args)

      Where the implementation had the routineName parameter before the functionName parameter and the procedureName parameter. If you have coded these methods to the previous order, you must update the code. See function() and procedure() for details.

    DP-12548: Modify string handling in Java Native and IRISList

    Category: Language Bindings - Native
    Platforms: All
    Version: 2020.4.0
    Description: This change modifies how the Java Native API handles strings in method and function calls, get() methods, and IRISList.

    • An empty string will not be converted to $c(0) and back. Empty string will be empty string.
    • An attempt to use empty string or empty byte[] as subscript will generate <SUBSCRIPT> error.
    • No changes in setting null. set(null,) and set ("",) both will be resulted in empty string on server.
    • Getting undefined value will result in null.
    • get any numeric (int, double) value from "" return 0. It will return null for Methods/Functions/
    • getByte from "" return empty byte[0], getString from "" will result in empty string.
    • getObject from type 1 will result in byte[0] in both - IRIS and IRISList.
    • getDateTime from empty string will return null, before it was throwing an exception.
    • getIRISList will return a valid object of length==0 for values 02 01, null object for 01.
    • Iterator will return empty string if subscript is not found, before null was returned.

    DP-13952: .NET compact double changes to IRISList

    Category: Language Bindings - Native
    Platforms: All
    Version: 2021.2.0
    Description: 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.

    DP-287344+DP-287596: Change with Java and .NET XEP generated Id property

    Category: Language Bindings - Native
    Platforms: All
    Version: 2019.1.0
    Description: In this release, InterSystems IRIS includes a generated id property in the schema to solve a problem with bulk upload. This should not cause a compatibility problem in most cases. If your schema runs into a problem caused by this change, you can remove the id notation.

    DP-291641: Java Native API illegal integers now throw exceptions

    Category: Language Bindings - Native
    Platforms: All
    Version: 2019.1.0
    Description: In previous releases, the client would convert illegal integers into a valid integer value. For example '123ABC' would be converted to 123 and 'Hello' would be converted to 0. This causes problems because the server would return errors for these illegal integers. In this release, illegal integers throw exceptions in the client. You may need to modify your code to handle these exceptions.

    DP-292105: Rare change in projection of XEP classes

    Category: Language Bindings - Native
    Platforms: All
    Version: 2019.1.0
    Description: In rare cases, importing an XEP schema produces a different class hierarchy in this release, specifically determining whether the class is serial or persistent. In these cases, the class projected by the previous release was incorrect.

    Language Bindings - Object

    DP-4782: Inconsistent XEP schemas now throw exceptions

    Category: Language Bindings - Object
    Platforms: All
    Version: 2019.1.0
    Description: Serial classes cannot have IDkeys, but in previous versions, a class annotated with both @Embedded and @Id did not throw an exception. A schema with a class annotated in this way would not have worked correctly, but it would not have thrown an exception. In this release, it throws an exception.

    DP-9200+DP-9533: IRISList and DBList Changes

    Category: Language Bindings - Object
    Platforms: All
    Version: 2019.4.0
    Description: Custom code using construct like createIRISList() or IRIS.createIRISList() should be changed to IRISList.createIRISList()

    Behavior of DBList::toString has been modified. Before this change, both 01 and 02 01 were displayed as "null", and now 02 01 is displayed as "empty". Since toString is intended as a debugging tool, this change is unlikely to impact custom code.

    DP-9922+PLUS: IRISNative and Gateway Changes

    Category: Language Bindings - Object
    Platforms: All
    Version: 2020.3.0
    Description:

    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 - Third Party

    DP-287537: Rename some public Entity Framework classes

    Category: Language Bindings - Third Party
    Platforms: All
    Version: 2019.1.0
    Description: This change renames some customer-visible classes in Entity Framework. The classes updated are:

    CacheFunctions              => IRISFunctions
    CacheMigrationSqlGenerator  => IRISMigrationSqlGenerator
    CacheTableExistenceChecker  => IRISTableExistenceChecker
    

    Language SDK

    DP-407972: Language SDK unified schema caches will be purged

    Category: Language SDK
    Platforms: All
    Version: 2022.1.0
    Description: 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.

    Management Portal

    DP-401580: New External Language Servers page replaces gateway pages

    Category: Management Portal
    Platforms: All
    Version: 2021.1.0
    Description:

    In the management portal, the new External Language Servers page replaces the following pages:

    • Object Gateways
    • JDBC Gateways
    • XSLT Gateways

    To access the new page, click System Administration > Configuration > Connectivity > External Language Servers. For details on the new page, see Managing External Server Connections.

    Migration

    DP-6784: New license needed for legacy features Caché Direct and WebLink

    Category: Migration
    Platforms: All
    Version: 2019.1.1
    Description: Caché Direct and WebLink are legacy features that are available to customers who have applications dependent on these features in earlier InterSystems products. If you are using these features in your application, you must get a new license from InterSystems that enables them. If you install release 2019.1.1 or later and do not have this new license, client connections to InterSystems IRIS will fail, and a LoginFailure event will be added to the Audit log.

    RFD2070: New license needed for legacy features Caché Direct and WebLink

    Category: Migration
    Platforms: All
    Version: 2019.1.1
    Description: Caché Direct and WebLink are legacy features that are available to customers who have applications dependent on these features in earlier InterSystems products. If you are using these features in your application, you must get a new license from InterSystems that enables them. If you install release 2019.1.1 or later and do not have this new license, client connections to InterSystems IRIS will fail, and a LoginFailure event will be added to the Audit log.

    Monitoring

    DP-13951: New metrics in %Monitor.Process

    Category: Monitoring
    Platforms: All
    Version: 2021.1.0
    Description: This change adds new metrics from %Monitor.Process, and the counter index numbers have changed. The new metrics are MONBLKWAIT, MONBLKWAKE, MONMEMALLOC, and MONMEMFREE.

    DP-291587: Remove WMI and Patrol monitoring

    Category: Monitoring
    Platforms: All
    Version: 2019.1.0
    Description: This change removes support for using the BMC Patrol monitoring tool and the Windows Management Integration (WMI) monitoring.

    DP-405941: %Monitor.Process now uses same metric names as ^PERFMON and &MONLBL

    Category: Monitoring
    Platforms: All
    Version: 2021.2.0
    Description: Modified %Monitor.Process to use the same list of metric names that the ^PERFMON and ^MONLBL routines use. If your code identifies metrics by name, you should modify it to use the new set of names.

    DP-413960: Limit PERFMON collection (index) numbers

    Category: Monitoring
    Platforms: All
    Version: 2022.1.2
    Description: Limit all PERFMON collections to 64k. Before this change, use of collections >65535 would silently fail; now an error is returned.

    NLP

    DP-13514: Replace legacy terminology

    Category: NLP
    Platforms: All
    Version: 2020.4.0
    Description: 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.

    DP-401903: Update of the Japanese language model

    Category: NLP
    Platforms: All
    Version: 2021.1.0
    Description: For Japanese text, parentheses () and their content may get indexed differently from previous versions, depending on the use of Katakana and number of characters within. While doing so is not strictly required, users are recommended to reindex their NLP domains with Japanese text to ensure uniformity of the output.

    Object

    DP-8357: Improve %FromJSON() error checking

    Category: Object
    Platforms: All
    Version: 2022.1.0
    Description: The %FromJSON() method would accept numeric input with an illegal format (a few example arrays [0e] and [-].) In the past this very deviant numeric syntax did not generate an error. However, some illegal numeric syntax is accepted by some third party JSON decoders by making minor corrections to illegally numeric syntax. Example arrays that will be accepted and corrected by the %FromJSON(....) method are: (1) [-5.] will become [-5.0] and (2) [-.5] will become [-0.5].  Also, the maximum input length for a JSON numeric string has been increased to 1022 characters.

    Object - .NET XEP

    DP-411367: Change with XEP unified schema and maximum field length

    Category: Object - .NET XEP
    Platforms: All
    Version: 2022.1.0
    Description: 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.

    Object - Java Binding

    DP-409204: Java binding collections now behave consistently

    Category: Object - Java Binding
    Platforms: All
    Version: 2022.1.0
    Description: 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.

    Object Compiler

    DP-20560: Deprecate the 'l' flag and /lock qualifier in class compilation

    Category: Object Compiler
    Platforms: All
    Version: 2020.3.0
    Description: With this change, 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.

    DP-20566: Improve error handling in relationship queries

    Category: Object Compiler
    Platforms: All
    Version: 2020.3.0
    Description: 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.

    DP-288486: Report error in stored procedure during compilation

    Category: Object Compiler
    Platforms: All
    Version: 2019.1.0
    Description: In this release, if you have a query with an error in a stored procedure, the error is reported when you compile the stored procedure. In previous releases, the error would not stop compilation but could cause problems when you executed the query.

    Object Library

    DP-10209: JSON adapter %Status value changes

    Category: Object Library
    Platforms: All
    Version: 2020.1.0
    Description: For some conditions the value returned in %Status has changed. Under some circumstances, where the JSON adapter previously set the %status value to the <METHOD DOES NOT EXIST> system error returned by the %JSONExport method, it now sets %status to

    ERROR #9411: A class referenced by a %JSONENABLED class must be a subclass of %JSON.Adaptor"
    

    DP-10482: Improve error handling for %File.TempFilename

    Category: Object Library
    Platforms: All
    Version: 2020.1.0
    Description: The ##class(%File).TempFilename method now returns an empty string instead of a negative return code when there is an error. The new third argument receives the error code in case of an error. If your code is checking the return value for a negative error code, you must change it to check for an empty string and use the third argument to report the error code.

    DP-20958: %Net.SMTP no longer sends email if server doesn't support authentication

    Category: Object Library
    Platforms: All
    Version: 2021.2.0
    Description: Before this release, if you used %Net.SMTP to try to authenticate to an SMTP server that did not support authentication, %Net.SMTP would send the email. Now in the same scenario, %Net.SMTP will return the following error and will not send the email:

    ERROR #6166: Server does not support authentication

    Users who prefer the old behavior and want to continue the exchange unauthenticated after a failed authentication attempt can set the new IgnoreFailedAuth property of %Net.SMTP to true. Users who do not use authentication with SMTP as well as users who do not want to continue with an unauthenticated exchange if authentication fails don't need to do anything.

    DP-282230: Streams locked for longer period of time

    Category: Object Library
    Platforms: All
    Version: 2019.1.0
    Description: In this release, InterSystems IRIS locks streams earlier in the process of reading them. This ensures that the stream does not change after reading information about the stream, such as the size of the stream. This change may cause concurrency issues when multiple jobs are reading the same stream. In most cases, the stream will only be locked for a slightly longer time and this will be handled by your code that handles lock timeouts. However, if your code opens a stream and then delays before reading the stream or never reads the stream, this change can significantly increase the lockout time. This increases the chances of deadlock when multiple jobs are reading the same stream.

    DP-283137: Stream clones no longer created in temporary directory

    Category: Object Library
    Platforms: All
    Version: 2019.1.0
    Description: In this release the %FileCharacterStream %ConstructClone method creates the clone file in the same directory as the original file. In previous releases, it would incorrectly create the clone in a temporary directory. If you have code that assumes the file will be created in the temporary directory, you should update your code.

    DP-285619: Change class names for storage classes

    Category: Object Library
    Platforms: All
    Version: 2018.1.1
    Description: Updated the following storage class names:

    %CacheStorage -> %Storage.Persistent
    %CacheSQLStorage -> %Storage.SQL
    %CacheSerialState -> %Storage.Serial
    %CacheShardStorage -> %Storage.Shard
    %Compiler.Storage.Cache -> %Compiler.Storage.Persistent
    %Compiler.Storage.CacheExtent -> %Compiler.Storage.Extent
    %Compiler.Storage.CacheSerial -> %Compiler.Storage.Serial
    %Compiler.Storage.CacheSQL -> %Compiler.Storage.SQL
    %Compiler.Storage.Extent -> %Compiler.Storage.CustomExtent
    %Compiler.Storage.Serial -> %Compiler.Storage.CustomSerial
    %Compiler.Storage.Generator.Cache -> %Compiler.Storage.Generator.Persistent
    

    Added conversion of the old to the new name in the class dictionary upgrade. This is performed automatically in %Dictionary class save, and logic for UDL import now also performs this dictionary upgrade.

    The original names have been removed. If customer classes subclass these old names they should update to the new names.

    DP-286395: Change in Location of temporary files

    Category: Object Library
    Platforms: All
    Version: 2019.1.0
    Description: This release changes the way %Library.File.TempFileName() creates temporary files. Before this change, the method just returned the filename and, typically, the file would later be created in the InterSystems IRIS temporary directory. With this change, the TempFileName() method creates the temporary file on disk and uses the operating system temporary directory rather than the InterSystems IRIS temporary directory.

    DP-287329: Remove server side MSM-Activate support

    Category: Object Library
    Platforms: All
    Version: 2019.1.0
    Description: This change removes support of MSM-Activate. If your code uses MSM-Activate, it will not be able to connect to an InterSystems IRIS server. You must replace the MSM-Activate code with other code to connect to the server.

    DP-290939: Unit test: Autoload resources are deleted on test termination

    Category: Object Library
    Platforms: All
    Version: 2019.1.0
    Description: In previous releases, if multiple autoload nested directories were created for a test, not all the levels of directories would be deleted when the unit test completed. In this release all autoload resources will be deleted. If you developed code that assumed that the directories would be retained, you should update your code.

    DP-291411: ReadLineIntoStream() returns different value at end

    Category: Object Library
    Platforms: All
    Version: 2019.1.0
    Description: If you call the %Stream ReadLineIntoStream() method on a stream with AtEnd set, it now returns an empty string "" at the end. In previous releases, it returned a newly created %Stream.TmpCharacter stream that contains no characters. If your code relied on the previous behavior, you must update it.

    DP-291883: Attempting to round %Integer in %xsd package now causes error

    Category: Object Library
    Platforms: All
    Version: 2019.1.0
    Description: In previous releases, if you attempted to assign a non-integer value to an integer in the %xsd package, it would not consider it an error but would silently truncate the value to an integer. This is not the expected behavior. In this release, InterSystems IRIS treats this as an error. If your code relies on the previous behavior, you should update it to avoid this error condition.

    DP-292449: In %Net.Http, GetJson() replaces getJSON()

    Category: Object Library
    Platforms: All
    Version: 2021.2.0
    Description: In %Net.Http, 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.

    DP-402085: OAuth — change to AddOct method

    Category: Object Library
    Platforms: All
    Version: 2021.1.0
    Description: The rarely used method %OAuth2.JWKS.AddOct() no longer base64url decodes client secrets. If you make use of this method but still need to base64url decode the secrets they pass in, you should base64url decode it before calling the method.

    DP-405034: %Net.SMTP checks server identities by default

    Category: Object Library
    Platforms: All
    Version: 2019.1.2
    Description: This change fixes a bug where the SSLCheckServerIdentity property in %Net.SMTP defaulted to false, but was documented as defaulting to true. The property now defaults to true and is in alignment with documentation. This means that, when connecting to an SSL/TLS secured web server, %Net.SMTP will check that the certificate server name matches the DNS name used to connect to the server and fail if they don't match. This is the behavior specified in RFC 2818 section 3.1.

    As a result, when connecting to an SSL/TLS secured web server, the default behavior of %Net.SMTP will now be to fail if the certificate server name does not match the DNS name used to connect to the server.

    This change is unlikely to cause compatibility issues, but it is possible that when using %Net.SMTP to send messages you might have issues connecting to an SSL/TLS enabled server. If this happens, and you understand the security trade-offs, you can set SSLCheckServerIdentity to 0 to restore the previous behavior.

    DP-410183: Fix XML generation when a class extends another class in a different XML namespace

    Category: Object Library
    Platforms: All
    Version: 2022.2.0
    Description: This change corrects a problem with XML generation when a class extends a class in a different XML namespace. Specifically, if a class A in namespace N1 with ELEMENTQUALIFIED=0 extends a class B in namespace N2 also with ELEMENTQUALIFIED=0, and class B contains a property of type C in namespace N2, when you generate XML for an instance of class A, previously the element for Class C would be qualified with namespace N2, when it should in fact be unqualified.

    For example:

    Class dp.ActualType Extends dp.n1.BaseType
    {
    Parameter ELEMENTQUALIFIED = 0;
    Parameter NAMESPACE = "urn:sdk-test/n2";
    Parameter XMLNAME = "ActualType";
    Property ActualProp As %String(MAXLEN = "", XMLNAME = "ActualProp") [ Required ];
    }
    

    Class dp.n1.BaseType Extends (%RegisteredObject, %XML.Adaptor)
    {
    Parameter ELEMENTQUALIFIED = 0;
    Parameter NAMESPACE = "urn:sdk-test/n1";
    Parameter XMLNAME = "BaseType";
    Parameter XMLSEQUENCE = 1;
    Property BaseProp As dp.n1.BasePropType(XMLNAME = "BaseProp") [ Required ];
    }
    

    Class dp.n1.BasePropType Extends (%RegisteredObject, %XML.Adaptor)
    {
    Parameter ELEMENTQUALIFIED = 0;
    Parameter NAMESPACE = "urn:sdk-test/n1";
    Parameter XMLNAME = "BasePropType";
    Parameter XMLSEQUENCE = 1;
    Property Tag As %String(MAXLEN = "", XMLNAME = "Tag") [ Required ];
    }
    
    Exporting an instance of ActualType previously would produce XML like:

    <?xml version="1.0" encoding="UTF-8"?>
    <s01:ActualType xmlns:s01="urn:sdk-test/n2">
    	<s02:BaseProp xmlns:s02="urn:sdk-test/n1">
    		<Tag></Tag>
    	</s02:BaseProp>
    	<ActualProp>myvalue</ActualProp>
    </s01:ActualType>
    
    But it should produce (note the namespace for the BaseProp element):
    <?xml version="1.0" encoding="UTF-8"?>
    <s01:ActualType xmlns:s01="urn:sdk-test/n2">
    	<BaseProp xmlns:s02="urn:sdk-test/n1">
    		<Tag></Tag>
    	</BaseProp>
    	<ActualProp>myvalue</ActualProp>
    </s01:ActualType>
    

    DP-412418: In %RoutineMgr:StudioOpenDialog query for /mapped=0 use the data database for globals not the routine database

    Category: Object Library
    Platforms: All
    Version: 2022.2.0
    Description: The %RoutineMgr:StudioOpenDialog query, which is used by a large number of interfaces, turns patterns into lists of items in the IRIS system. One of the pattern extensions it supports is '.gbl' to reference globals. When you called this with for example '\*.gbl' and the qualifier /mapped=0 (which is normally the default) it would search for globals in the routine database but it should have been searching the default data database as well for globals as routines/classes are found from patterns like '\*.mac' or '\*.cls'.

    With this change, the query will result in *.gbl finding globals in the data database for /mapped=0 where as before it would only find ones in the routine database. It is unlikely customers are relying on this behavior.

    DP-412853: Add %FromJSONFile(); do not load files in %FromJSON()

    Category: Object Library
    Platforms: All
    Version: 2022.2.0
    Description: Previously ##class(%DynamicAbstractObject).%FromJSON() would accept three types of inputs:

    • a stream object
    • a JSON formatted string
    • a filename on the server containing JSON
    If the input was a string that could not be parsed as a JSON object or array, then the method tried to treat it as a filename. This is a security concern because naively written code could allow an attacker to load data from any JSON formatted file accessible on the server.

    This has been fixed by creating a new method that expects an input string containing a filename:

    ClassMethod %FromJSONFile(str) As %DynamicAbstractObject
    

    The %FromJSON() method no longer loads a file. If the input is a stream, the method works as before.

    Object Storage

    DP-11351: %Persistent IDENTIFIEDBY parameter marked as Deprecated

    Category: Object Storage
    Platforms: All
    Version: 2020.3.0
    Description: The %Library.Persistent IDENTIFIEDBY parameter is deprecated. If you have used IDENTIFIEDBY to define relationships, you should replace it with a parent/child relationship.

    DP-290244: Change %Save() ordering to ensure predictability

    Category: Object Storage
    Platforms: All
    Version: 2018.1.2
    Description: This change revises the internal algorithm determining object graph linearization during a %Save to remove a random element, ensuring that identical graphs of connected objects will be persisted in a consistent order. User code should make no assumptions about this order, as it is dependent on the internal implementation of %Save() which may change in future releases.

    DP-292178: Changes to %Set and %Push with null values

    Category: Object Storage
    Platforms: All
    Version: 2019.1.0
    Description: In this release, the behavior of the %DynamicArray and %DynamicObjects %Set(key,value,"null") methods and the %DynamicArray %Push(value,"null") method has changed when the value is not an empty string. In previous releases, these methods signalled <ILLEGAL VALUE> if 'value' was not "". In this release, these methods have the following behavior:

    • If 'value' is the empty string, then the JSON value 'null' is assigned to the keyed element.
    • If 'value' is not the empty string then that value is assigned to the keyed element of the Array/Object without any conversion and no error is signalled.

    If your code, depended on the <ILLEGAL VALUE> being signalled, you must modify your code to test if the keyed element has a value other than "", and, in that case, signal the error.

    DP-7523: Class compiler reports error if global name length is greater than 31 characters

    Category: Object Storage
    Platforms: All
    Version: 2019.3.0
    Description: This change adds compiler validation to ensure that the global names defined for DataLocation, IdLocation, IndexLocation, StreamLocation, CounterLocation, and VersionLocation are all within the global name length supported by the system (currently 31 characters). In previous releases, these global names were silently truncated to 31 characters. This could cause collisions between global names in the same class. These collisions would cause what appears to be references to separate globals to actually reference the same global.

    During class compilation, an error will be reported if any of the global names used for the class are longer than the supported length. For example:

    Compiling class %UnitTest.Result.TestInstance ERROR #9101: 
    Global name 'UnitTest.Result.TestInstanceStream' for 'StreamLocation' is too long, 
    must be no more than 31 characters in length.
    [ConstructAddresses+60^%ocsExtentCache:BUILDSYS] > 
    ERROR #5030: An error occurred while compiling class '%UnitTest.Result.TestInstance' 
    [compile+59^%occClass:BUILDSYS]
    

    This change will most likely result in classes that need to be modified upon upgrade. This more commonly occurs on systems that were converted from Caché or Ensemble using the in-place conversion if the classes were first defined using %CacheStorage and the class names were fairly long.

    ObjectScript

    DP-402912: Fixes problem where errors within ZWRITE command are not raised to caller's error trap

    Category: ObjectScript
    Platforms: All
    Version: 2021.1.1
    Description: This change fixes a problem where errors within ZWRITE command are not raised to caller's error trap.

    Now ZWRITE throws some errors that were ignored before, but they are serious show-stopper errors that should not happen in a normal environment.

    DP-404892: Changes to how ZWRITE displays IEEE doubles

    Category: ObjectScript
    Platforms: All
    Version: 2021.2.0
    Description: 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.

    DP-410011: ZWRITE preserves $ZR unless a global arg is given

    Category: ObjectScript
    Platforms: All
    Version: 2022.1.0
    Description: 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.

    ODBC

    DP-11014+PLUS: Remove ability to connect to Caché from .NET Provider or ODBC

    Category: ODBC
    Platforms: All
    Version: 2020.3.0
    Description: 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.

    DP-11827: 32-bit ODBC driver removed on UNIX®

    Category: ODBC
    Platforms: UNIX®
    Version: 2020.3.0
    Description: With this change release, the 32-bit ODBC drivers libirisodbcu35.so and odbcgatewayu.so have been removed on UNIX® systems. If you have used these drivers, you should use the 64-bit equivalents libirisodbcur6435.so and odbcgatewayur64.so.

    If you are switching over to the 64-bit unixODBC client driver (libirisodbcu6435.so), 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.

    DP-408254: Do not allow insert SQL_CHAR or SQL_WCHAR values into BINARY field

    Category: ODBC
    Platforms: All
    Version: 2022.1.0
    Description: If your code uses SQL_CHAR or SQL_WCHAR for binding into a BINARY field, you need to change it to SQL_BINARY. This combination is unlikely to be used in code.

    DP-409303: Convert TIME_STRUCT to POSIX

    Category: ODBC
    Platforms: All
    Version: 2022.2.0
    Description: On insert TIME_STRUCT into POSIX field (1093), the ODBC driver will convert TIME_STRUCT to POSIX with default date 1-1-1900.

    Platforms

    DP-412390: Require minor OS version in installs on Red Hat and SUSE

    Category: Platforms
    Platforms: UNIX®
    Version: 2022.1.1
    Description: Installation on Red Hat 7 x64 will require minor version 9 or above.

    Installation on Red Hat 8 x64 and ARM64 will require minor version 2 or above.

    Installation on SUSE 15 x64 will require minor version 3 or above.

    PLATFORMS-CENTOS-7: Centos 7 no longer supported as a developer platform

    Category: Platforms
    Platforms: All
    Version: 2022.2.0
    Description: In this release, Centos 7 is no longer supported as a developer platform.

    PLATFORMS-CENTOS-8: Centos Stream 8 now supported as a developer platform

    Category: Platforms
    Platforms: All
    Version: 2022.2.0
    Description: In this release, Centos Stream 8 is supported as a developer platform.

    PLATFORMS-ICU-691: ICU 69.1 & Xerces 3.2

    Category: Platforms
    Platforms: All
    Version: 2022.1.1
    Description: In this release, ICU has been updated to version 69.1. Also the current Xerces version is now 3.2.

    PLATFORMS-MACOS11: macOS 11

    Category: Platforms
    Platforms: macOS
    Version: 2021.2.0
    Description: As of this release, the product is supported on macOS 11 and higher.

    PLATFORMS-NET: Add .NET 5, .NET 6 support, remove .NET Core 1

    Category: Platforms
    Platforms: UNIX®
    Version: 2022.1.0
    Description: This release adds support for .NET 5 and .NET 6. Also it removes support for .NET Core 1.

    PLATFORMS-POWERPC: PowerPC chip sets no longer supported

    Category: Platforms
    Platforms: AIX
    Version: 2022.2.0
    Description: This release drops support for the older PowerPC chip sets. For IBM AIX, the product is now supported only on POWER Systems (POWER 7 and higher).

    PLATFORMS-RH7: Remove RH7 support

    Category: Platforms
    Platforms: UNIX®
    Version: 2022.2.0
    Description: This release removes support for Red Hat 7.x.

    PLATFORMS-RH9: Add RH9 support

    Category: Platforms
    Platforms: UNIX®
    Version: 2022.1.2
    Description: This release adds support for Red Hat 9.x.

    PLATFORMS-UBUNTU-1804: Remove Ubuntu 18.04 support

    Category: Platforms
    Platforms: UNIX®
    Version: 2022.2.0
    Description: This release removes support for Ubuntu 18.04.

    PLATFORMS-UBUNTU-2204: Add Ubuntu 22.04 support

    Category: Platforms
    Platforms: UNIX®
    Version: 2022.1.1
    Description: This release adds support for Ubuntu 22.04.

    Security

    DP-11245: Passwords now use SHA-2 hashes

    Category: Security
    Platforms: All
    Version: 2020.4.0
    Description: With this change, the product 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 the product 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.

    DP-11677: Rename IAM_API role to %IAM_API

    Category: Security
    Platforms: All
    Version: 2020.1.0
    Description: The IAM_API role has been renamed to %IAM_API.

    DP-12141: Cannot use old versions of cvendian and cvencrypt

    Category: Security
    Platforms: All
    Version: 2020.2.0
    Description: The maximum length of encryption ID is now increased from 63 to 64, and the encryption ID should not contain wide characters.

    As a result, you cannot use cvendian and cvencrypt utilities from previous versions on encrypted databases. Use the versions of cvendian and cvencrypt provided with this release.

    DP-12897: Method signature changes in OAuth2.Server.Session

    Category: Security
    Platforms: All
    Version: 2020.4.0
    Description: This change includes a change to the signatures of the GetUser() and Login() methods of the OAuth2.Server.Session class. 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

    DP-13887: FIPS mode must match operating system FIPS mode

    Category: Security
    Platforms: All
    Version: 2021.1.0
    Description: 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.

    DP-276687: ^EncryptionKey routine menu changes

    Category: Security
    Platforms: All
    Version: 2019.1.0
    Description: The ^EncryptionKey routine has new menu choices that may require changes to scripts for previous versions. The changes in the menus are primarily associated with support for storing keys on a KMIP (key management interoperability protocol) server and support for modifying the encryption status of a database. Changes include:

    • If you have configured a connection to a KMIP server, there is an additional choice (5) in the main menu, Manage KMIP server.
    • If you have configured a connection to a KMIP server, then, in the Database encryption > Activate database encryption keys menu, the options differ from the menus in previous versions; there are multiple numbered options instead of only the prompt for the key file.
    • If you have configured a connection to a KMIP server, then, in the Database encryption > Configure InterSystems IRIS startup options menu, there is a Unattended key activation with a KMIP server choice and submenu.
    • In the Database encryption menu, there is a Modify encrypted status of existing database choice and submenu.
    • If you have configured a connection to a KMIP server, then, in the Data element encryption > Activate data element encryption keys menu, the options differ from the menus in previous versions; there are multiple numbered options instead of only the prompt for the key file.

    DP-402686: Changes to Security.Events:ListAll query arguments

    Category: Security
    Platforms: All
    Version: 2021.2.0
    Description: 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 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".

    DP-403547: OAuth server now returns 401 for invalid credentials instead of 200

    Category: Security
    Platforms: All
    Version: 2021.1.0
    Description: Prior to this change, IRIS returned a status of 200 whether or not the user login to authorize OAuth was successful. If the login wasn't successful, the login page was displayed again with status of 200. If the login was successful, the permissions page was displayed with status of 200.

    IRIS now returns a status of 401 when the user login was unsuccessful. Customers working with OAuth, especially those who implement custom OAuth login pages, should be aware of this change.

    DP-404283: Changes to enabling %ZEN.Dialog classes

    Category: Security
    Platforms: All
    Version: 2019.1.2
    Description: 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-name,"%ZEN.Dialog.")=1

    Also, with this change, any web application that is enabled for analytics or interoperability will have %ZEN.Dialog.* classes enabled by default.

    DP-406389+DP-406711: Add versions to security tables

    Category: Security
    Platforms: All
    Version: 2021.2.0
    Description: In previous releases, you could only export and import security tables between instances with the same major version. Now the security tables have an embedded version number, which allows finer access over allowable imports. You can export security tables from versions 2021.1 and 2021.2 and then import them to this version, 2022.1.

    DP-408241: Change in permissions needed to run Task Manager tasks

    Category: Security
    Platforms: All
    Version: 2022.1.0
    Description: Now %SYS.TaskSuper requires %Admin_Manage:Use in order to modify the ExecuteCode field of %SYS.Task.RunLegacyTask. Previously this check was only done in the Management Portal page.

    The Management Portal page now checks for %Admin_Secure:Use in order to set the RunAsUser to a user other than the current user. Previously it incorrectly checked for %Admin_Manage:Use (TaskSuper checks %Admin_Secure).

    DP-408293: Web Gateway now uses PBKDF2 to hash passwords

    Category: Security
    Platforms: All
    Version: 2022.1.0
    Description: 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.

    DP-412937: Audit log improvements

    Category: Security
    Platforms: All
    Version: 2022.2.0
    Description: The audit log has been corrected as follows, for better usability:

    • Background tasks started in the Portal are now audited with a TaskStart and TaskEnd audit record. Previously there was just a JobStart and JobEnd logged, but it did not specify what task was being run.
    • Started and stopping of %SYS.WorkQueue jobs are excluded from the audit log.
    • Starting and stopping of %Service_WebGateway jobs are excluded from the audit log.

    DP-413405: Revert Security.Events:ListAll() to preserve backwards compatibility

    Category: Security
    Platforms: All
    Version: 2022.1.0
    Description: Previously, DP-402686 added a new query called ListByFilter() to the Security.Events class and then reconfigured the ListAll() query to call this new query. In doing so, it changed the signature of ListAll(), which broke backwards compatibility.

    This change reverts Security.Events:ListAll() to what it was before DP-402686. Then, to maintain the SMP fix that DP-402686 introduced, it changes the SystemEvents and UserEvents SMP pages to call the ListByFilter() query instead of ListAll().

    As a result, the backwards compatibility of Security.Events:ListAll() has been restored.

    DP-414613: SECURITY: Require new %Secure_Native Resource:USE for Native API calls

    Category: Security
    Platforms: All
    Version: 2022.2.0
    Description: There is a new system Resource called %Service_Native.  The system-defined roles %Developer and %Manager have the USE permission on this resource by default.

    %Service_Native controls whether the user can issue Native API calls via Java, .NET, Python, and Node.js.  In order to use the Native API, the user must have the %Service_Native:USE permission.

    DP-414811: Add JWTAudience field to OAuth2 clients

    Category: Security
    Platforms: All
    Version: 2022.2.0
    Description: This change adds the ability for an IRIS OAuth2 client to manually configure the value to use in the "aud" header when using the private_key_jwt and client_secret_jwt authentication methods, as well as for the JWT Authorization grant type. 

    This can be done with the new JWTAudience property in the OAuth2.Client class. This can be configured via the "Audience" field in the OAuth2 Client Configuration page in the Management Portal.

    For new OAuth2 client configurations, this will default to use the Authorization server's token endpoint. If it is not defined (e.g., for existing configurations) it will continue to use the Authorization server's issuer endpoint. 

    NOTE: IRIS Authorization servers prior to DP-414485 require clients to use the issuer endpoint. This means that in order to for newly created IRIS OAuth2 clients running on a system with this change to authenticate with an IRIS OAuth2 Server without DP-414485, the user will need to manually configure the JWT Audience.

    DP-8893: Cannot delete %SYS.PhoneProvider that is in use

    Category: Security
    Platforms: All
    Version: 2019.4.0
    Description: In this release, you cannot delete a %SYS.PhoneProvider if it is in use. Some deleted operations that previously succeeded will now fail. This is an intentional feature but could cause some unexpected behavior in unusual cases.

    TLS-2021: Removal of TLS 1.3

    Category: Security
    Platforms: All
    Version: 2021.1.0
    Description: InterSystems IRIS 2020.2 through 2020.4 contained the new TLS 1.3 security libraries. On some platforms, we discovered that there were conflicts with older versions of the libraries installed by the operating system or other applications. Consequently, we have removed TLS 1.3 from this release. We will include TLS 1.3 support in a future release in a way that will not conflict with older versions of the library that are installed on the system.

    SQL

    DP-10106: Sybase TSQL dialect variable names are now case sensitive

    Category: SQL
    Platforms: All
    Version: 2020.1.0
    Description: Sybase TSQL dialect now properly supports case sensitive variable names in procedure code. For example, the following declares two different variables:

    declare @myvariable varchar(255)
    declare @MyVariable varchar(255)
    

    Before this change, in TSQL Sybase dialect, if you declared a variable in one case, and referenced it in another, it would work. For example, the following did work but no longer works in the Sybase dialect:

    @declare @A int select @a = 1
    

    NOTE: When using MSSQL dialect, variable names are case insensitive. The code defining myvariable and MyVariable will produce an error if compiled with MSSQL dialect, but the code declaring variable A and referencing variable a will work in MSSQL dialect.

    DP-10720: Remove unused environment variables

    Category: SQL
    Platforms: All
    Version: 2020.3.0
    Description: 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. As of this change, the following variables are no longer defined:

    envRoutineSizeGet
    envUseOldJavaGeneratorGet
    envUseJavaGenerator1Get
    envUseJavaGenerator2Get
    envUseJavaGenerator3Get
    envUseSortGet
    envTimeChangedGet
    
    The following variables are still defined but return an error if you try to update the setting:
    envDefaultOHandleClassNameGet
    envDefaultSerialStateClassNameGet
    envDefaultStorageClassNameGet
    

    DP-11269: Changes to TuneTable and TuneSchema defaults

    Category: SQL
    Platforms: All
    Version: 2020.3.0
    Description: With this change, the second argument of $SYSTEM.SQL.TuneTable and $SYSTEM.SQL.TuneSchema (update) now has a default=1.

    Before this change, the default was 0 for update. Calling $SYSTEM.SQL.TuneTable(tablename) and $SYSTEM.SQL.TuneSchema(schemaname) without specifying a value for the second argument will result in a change of behavior from previous versions.

    DP-11573: SQL Import/Export wizard now restricts file extensions

    Category: SQL
    Platforms: All
    Version: 2019.1.2
    Description: With this change, the SQL Import/Export wizard ([System Explorer] -> [SQL] -> [Wizards] -> [Data Import/Export]) will only allow the user to import from or export to files on the server with an allowed extension. Allowed extensions are: .txt, .csv. Previously any file on the system could be used. When importing from or exporting to a file on the client system, filenames are not restricted.

    DP-12017: SELECT with INTO clause changes

    Category: SQL
    Platforms: All
    Version: 2020.3.0
    Description: This change modifies 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 change might result in some applications requiring updating in order to avoid application errors, or incorrect results returned.

    DP-12603: Corrections to datetime functions to disallow invalid input

    Category: SQL
    Platforms: All
    Version: 2020.4.0
    Description: Before this change, some invalid inputs to datetime functions would not cause an error but would return a value. Now these errors are caught and returned as errors. If your code does not handle errors in these functions, you should add error handling.

    DP-13700: $SYSTEM.SQL not using SQLCODE in some contexts

    Category: SQL
    Platforms: All
    Version: 2020.4.0
    Description: 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 ClearStatistics() can be found in the Errors parameter. SQLCODE has been removed from the PublicList in these contexts.

    DP-13850: Map selectability changes for mapped tables

    Category: SQL
    Platforms: All
    Version: 2020.4.0
    Description: Before this change, 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. With this change, you only set the map selectivity for a single namespace.

    DP-13937: Remove truncation to 150 characters on INFORMATION.SCHEMA.STATEMENTS:Statement column

    Category: SQL
    Platforms: All
    Version: 2020.4.0
    Description: 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.

    DP-14007: SELECT with INTO clause changes when SQLCODE'=0

    Category: SQL
    Platforms: All
    Version: 2021.1.0
    Description: 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 (""). The variable will be set to "" when SQLCODE=100 or SQLCODE<0 is returned.

    DP-286376: SQL default precedence changed (new installs)

    Category: SQL
    Platforms: All
    Version: 2019.1.0
    Description: In this release the default SQL precedence is set to ANSI operator precedence on new installs. If your code is depending on strict left-to-right precedence and you are running on an install upgraded from an earlier system, there is no problem. But, if you transfer your code to a system with a new install, you can set the precedence to strict left-to-right by calling $system.SQL.SetANSIPrecedence(0). If you want to change an upgraded system to use ANSI precedence, call $system.SQL.SetANSIPrecedence(1).

    DP-286844: New default for parallel queries can change order of results

    Category: SQL
    Platforms: All
    Version: 2019.1.0
    Description: With this change, the default is to enable automatic parallel execution of queries (where supported) in new installs. Consequently, queries without an ORDER BY clause may return results in a different order than the same query would in previous versions. To guarantee the order of results for any query, include an appropriate ORDER BY clause. If your code assumes the order of results of a query without an ORDER BY clause, you may run into this problem. If you are using an instance upgraded from before this change, you will not run into this problem because the upgrade retains the previous setting of not using automatic parallel queries. But if you transfer your code to a system with a new install, you could run into this problem.

    DP-289304: Preserve data types in dynamic SQL arguments

    Category: SQL
    Platforms: All
    Version: 2019.1.0
    Description: In processing dynamic SQL, the previous versions replaced literal with parameters but lost data type information. This caused some conversion errors. This release corrects this problem by preserving the data type information, but consequently, the data type of the resultset may be different in this release from the previous release. If your code assumes the data type of the resultset, you may have to update it to accommodate this change.

    DP-289316: IDENTITY column datatype change

    Category: SQL
    Platforms: All
    Version: 2019.1.0
    Description: In this release an identity column created via DDL that does not explicitly specify a data type defaults to a BIGINT data type. In previous releases, it defaulted to an INTEGER data type. If you have code that relies on this default, you should update it.

    DP-289996: SQL efficiency improvements change internal storage

    Category: SQL
    Platforms: All
    Version: 2019.1.0
    Description: In this release, InterSystems IRIS stores empty values in lists more efficiently. In previous releases, it stored empty values as a null string, but in this release, it stores it as a null. From SQL access, there is no compatibility issue, but if you access the underlying global storage structure and expect to find a null string, you may get a <NULL VALUE> error.

    DP-291519: TRUNCATE TABLE command %ROWCOUNT change

    Category: SQL
    Platforms: All
    Version: 2019.1.0
    Description: For better performance, the TRUNCATE TABLE command has been enhanced to delete the entire extent of the target table at once instead of row-by-row. In these cases, the resulting %ROWCOUNT value will be -1 rather than a count of rows that were deleted.

    DP-402901: SQL PURGE QUERIES BY AGE and FREEZE BY ID changes

    Category: SQL
    Platforms: All
    Version: 2021.2.0
    Description: 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 [CACHED] QUERIES BY AGE 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.

    DP-405610+DP-408694: (New installs) default DDL type mapping for TIMESTAMP is %Library.PosixTime

    Category: SQL
    Platforms: All
    Version: 2021.2.0
    Description: 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.

    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.

    DP-406218: Runtime Plan Choice (RTPC) is now enabled by default

    Category: SQL
    Platforms: All
    Version: 2021.2.0
    Description: 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.

    Note that for some queries, this may not be the best choice. See Adaptive SQL Optimizer for details on RTPC and review whether you wish to use this optimization.

    DP-406452: For READ UNCOMMITTED, build and run separate queries

    Category: SQL
    Platforms: All
    Version: 2022.2.0
    Description: Improve the generated code for embedded SQL and %SQL.Statement dynamic SQL by building separate queries based on the partition's isolation mode. If the partition is in READ UNCOMMITTED, we can build parallel queries which can be a major performance improvement. We also do not need to generate runtime logic checking the isolation mode and then re-reading data for READ COMMITTED in the default READ UNCOMMITTED queries.

    As part of this change, we added logic so we can find frozen plans for these queries if they were frozen before the partition isolation mode was added to the query.

    The isolation mode is added with a SQL comment option that looks like this:

    /*#OPTIONS { "IsolationLevel":0 } */
    

    Two compatibility issues should be noted:

    1) This change may cause queries to be run in parallel automatically based on the auto-parallel heuristics. If a query does not specify a strict ordering of results (no ORDER BY, for example) then SQL is allowed to return results in any order it wishes and in this case running a query in parallel will cause the order of results to be different on each run of the query. If the user needs the results in a specific order they should include an ORDER BY clause in the query or add the %NOPARALLEL keyword to the query.

    2) For %SQL.Statement with this change, the process isolation level will be determined when we prepare the query and not when we execute. This is different from the previous behavior where the process isolation level was taken from the query execution time. Customers do not normally change process isolation level with queries already prepared so it is unlikely this will cause problems, but it is a change in behavior.

    DP-408485+PLUS: Corrects bugs in the SQL 'EXPLAIN' feature

    Category: SQL
    Platforms: All
    Version: 2022.1.2
    Description: This change refactors the SQL EXPLAIN feature in order to fix multiple bugs. The SQL EXPLAIN statement is now fully supported via the following interfaces:

    • Embedded SQL  [Both <select stmt: single row> and <select stmt: multi row> (e.g. DECLARE)]
    • Dynamic SQL  [e.g. %SQL.Statement class]
    • SQL Shell [do $SYSTEM.SQL.Shell()]
    • Management Portal [System Explorer -> SQL -> Query]
    • JDBC
    Given the newly refactored code, it should be possible for future enhancements to add more interfaces that support our SQL *EXPLAIN* statement.  The next and possibly most logical new interface for which we should add support is via ODBC.

    Our SQL *EXPLAIN* statement is best described via the following BNF:

    <explain> ::= EXPLAIN [ <explain option list> ] [ INTO <host ref> ] <selct>
       -- <selct> denotes the SELECT Statement, which is the only valid query currently supported with <explain> 
    <explain option list> ::= [ <alt option ] [ <stat option> ]
    <alt option>  ::= ALT | ALL
    <stat option> ::= STAT | STATS
                      -- The <stat option> and <alt option> can be specified in any order
    

    <decl> ::= DECLARE <ident> CURSOR FOR <selct> [ FOR <updtcls> ] | DECLARE <ident> CURSOR FOR <explain> [ FOR <updtcls> ]

    The following examples show how the SQL *EXPLAIN* statement can be used:
    // --- Returns the query plan as an XML string ---
    EXPLAIN SELECT Name,DOB FROM Sample.Person where Name [ 'Q'
    // --- Returns the query plan and performance stats (by module) as an XML string ---
    EXPLAIN STAT SELECT Name,DOB FROM Sample.Person where Name [ 'Q'
    // --- Returns the alternate query plans as an XML string ---
    EXPLAIN ALT SELECT Name,DOB FROM Sample.Person where Name [ 'Q'
    // --- Returns the alternate query plans and performance stats as an XML string ---
    EXPLAIN ALT STAT SELECT Name,DOB FROM Sample.Person where Name [ 'Q'
    
    This change also enhances the following methods/APIs within the %SYSTEM.SQL class that relate to the SQL *EXPLAIN* statement:
    • GetSQLPlan(sqlStr,showStats,planType,sqlPlan)
    • RefactorSQLPlan(planRef)    (Previously named: CollectPlans(planRef) )
    • Explain(sql,qualifiers,dynargs,plan)
    DP-408808: When FETCH call has two sets of INTO variables, fetch results into both sets of variables

    Category: SQL
    Platforms: All
    Version: 2022.1.0
    Description: This change restore behavior of embedded SQL when DECLARE <name> CURSOR has INTO variables and the FETCH also has INTO variables. A previous change unintentionally modified the behavior so that the code updated only the DECLARE <name> CURSOR variables.

    This change restores the previous behavior of updating both sets of variables.

    DP-411232: New %DROP_UNOWNED SQL admin privilege

    Category: SQL
    Platforms: All
    Version: 2022.2.0
    Description: In previous releases, if a user held the %DROP_TABLE or %DROP_VIEW administrative privilege, the user would be able to drop a table or view that the user did not own. In this release, in order to drop a table or view, the user must either be the owner of the table or view or must hold the %DROP_UNOWNED administrative privilege (which is new in this release).

    DP-412103: SQL STRING(...) function now correctly handles nulls and empty strings

    Category: SQL
    Platforms: All
    Version: 2022.2.0
    Description: This change modifies the SQL *STRING(...)* function code generator to work correctly for any number of parameter values, including NULL and the empty string (which is represented internally as $char(0)), and to generate more efficient code.

    Prior to this change, the SQL *STRING(...)* function would return a NULL value ("") if ANY of the parameters are NULL, which was incorrect. In this scenario, the NULL value is meant to be treated as an empty-string ('') if other parameters are present. 

    Now the logic of SQL *STRING(...)* is in line with the _Sybase SQL Anywhere_ definition, and will return the concatenation of all parameters, treating NULL parameters as the empty-string ('') as in the following example:

    SELECT STRING('This', ' ', NULL, 'now', ' ', 'works!') INTO :testdata
    SELECT STRING('This', ' ', '', 'now', ' ', 'works!') INTO :testdata
    

    With this change, each of these SQL statements set the testdata variable equal to "This now works!"

    DP-412300: Add %NOJOURN SQL Admin priv & disable transactions with %NOJOURN SQL keyword

    Category: SQL
    Platforms: All
    Version: 2022.2.0
    Description: With this change, users must now hold the %NOJOURN SQL Admin privilege in order to use the %NOJOURN keyword in INSERT [ OR UPDATE ], UPDATE, DELETE, BUILD INDEX, or fast insert statements. Also, the %NOJOURN flag for INSERT [ OR UPDATE ], UPDATE, DELETE, and fast insert statements now explicitly turns off transactions. Transactions are implicitly skipped when journaling is disabled, but this change optimizes mirrored environments because mirrors must keep journalling enabled so that data can be propagated to backups. Also, this change fixes a bug where %NOLOCK SQL Admin priv was not checked when %NOLOCK is used in BUILD INDEX statements.

    DP-414622: Require %Development:USE privilege for DDL statements that invoke external language code

    Category: SQL
    Platforms: All
    Version: 2022.2.0
    Description: There are a number of DDL statements in which a user can call ObjectScript or Python (and in some cases Java and DotNet) code. The following shows an example:

    CREATE TABLE Test.MyTable(MyField VARCHAR(100), MyOtherField INT COMPUTECODE OBJECTSCRIPT \{set {MyOtherField} = +$h / 2})
    

    Before this code, there was no check that the user executing such DDL statements had %Development:USE privileges.

    With this change, a user who does not have %Development:USE permissions will encounter a privilege violation (SQLCODE -99) error and the DDL will fail. The DDL statements affected are CREATE METHOD/PROCEDURE/FUNCTION/QUERY/TRIGGER, and CREATE/ALTER TABLE where the user specifies ObjectScript DEFAULT or COMPUTECODE for a column.

    The only scenarios in which a user without proper permissions can still execute such DDL statements are as follows:

    • The DDL is executed via embedded SQL (embedded SQL does not do privilege checks)
    • The code being run explicitly specifies no privilege checking, for example, a %SQL.Statement prepared with nocheck-priv or run with %ExecDirectNoPriv().

    DP-6859: Queries from Management Portal run in background

    Category: SQL
    Platforms: All
    Version: 2019.3.0
    Description: Starting with this release, if you issue a query from the SQL Explorer page in the Management Portal, the query is executed in the background. While this enables query cancellation and avoids web request timeouts, it also means certain legacy stored procedures that depend on foreground execution and write to the current device may no longer display this logging information properly.

    DP-8539: Universal cached queries for SQL

    Category: SQL
    Platforms: All
    Version: 2020.1.0
    Description: This release improves SQL performance by caching all SQL queries. To achieve this, queries are compiled when they are first used, not when the class or routine containing the query is compiled. The environment at runtime when the SQL query is compiled can be slightly different from the class or routine compile-time environment. The compiler stores information when the class or routine is compiled that allows it to compile the SQL query in most cases without error.

    In rare cases, SQL queries can contain macros defined in include files. If the class or routine was compiled in one namespace and the SQL query is compiled in a second namespace and the second does not contain the include file, the compilation will encounter an error. If this occurs, then you must add the include file to the second namespace.

    DP-9412: Changes in TRUNCATE TABLE transactions

    Category: SQL
    Platforms: All
    Version: 2019.4.0
    Description: TRUNCATE TABLE no longer initiates transactions when executed in AUTOCOMMIT_ON or AUTOCOMMIT_OFF mode. If you need the ability to rollback a TRUNCATE TABLE command, you must start your own transaction prior to executing the truncate table.

    This change allows TRUNCATE TABLE to work much faster when the table contains millions of rows and the killing of the globals for the table no longer needs to be journaled.

    DP-9570: TSQL parser changes

    Category: SQL
    Platforms: All
    Version: 2019.4.0
    Description: Prior to this change, if you had defined:

    ^%SYS("tsql","SET","ANSI_NULLS")="OFF"
    

    ^%SYS("tsql","SET","QUOTED_IDENTIFIER")="OFF"
    

    The TSQL parser would have behaved as if these settings were ON. Now that this has been corrected, if your code was really relying on either of these settings being ON, and if those settings are OFF, the run-time behavior of your procedure may be different.

    SDK048: SQL Import/Export wizard now restricts file extensions

    Category: SQL
    Platforms: All
    Version: 2019.1.2
    Description: With this change, the SQL Import/Export wizard ([System Explorer] -> [SQL] -> [Wizards] -> [Data Import/Export]) will only allow the user to import from or export to files on the server with an allowed extension. Allowed extensions are: .txt, .csv. Previously any file on the system could be used. When importing from or exporting to a file on the client system, filenames are not restricted.

    SQL.Query Processing

    MAK5205: Changes to when SQL statement indexes are Removed

    Category: SQL.Query Processing
    Platforms: All
    Version: 2020.1.1
    Description: Previously when all routines/classes that contained a SQL statement were removed, the statement index entry was also removed. This meant that all lightweight SQL statistics were also removed when the routine/class that contained the SQL statement was removed. It is often very useful to have access to this historic information and in addition if the statement was frozen it was not removed, so this change modifies the behavior to always keep the SQL statement index entry (and lightweight SQL statistics) when the containing routine/class is deleted.

    A new button has also been added to SQL statement index page in the system management portal called 'Clean stale' which will run a task to remove all statement index entries that are not frozen where the containing routine/class is no longer present or no longer contains this SQL statement.

    This change does not impact how your code is executed, but in order to remove the index entries, you have to use the Management Portal.

    TRW1706: Collation changes that can impact query processing

    Category: SQL.Query Processing
    Platforms: All
    Version: 2020.1.1
    Description: Concatenations of expressions that are coercible to a common collation (for example, string constants or parameters concatenated with commonly collated fields) will now be collated as the common collation. This change could lead to conditions that previously evaluated to false for certain values now evaluate to true. For example, the following condition will evaluate to true:

    ' ' || field LIKE 'A'

    where field has a value 'a'. It is unlikely that any code is dependent on having a false value for this condition.

    System

    DP-404256: CSP pages not backed up by internal routine versioning

    Category: System
    Platforms: All
    Version: 2021.1.0
    Description: This is a change to an undocumented feature, routine versioning, that some customers may be using. If you are using routine versioning, with this change CSP pages will not be backed up to the ^rBACKUP global.

    DP-407254: Update interaction between delegated and password authentication

    Category: System
    Platforms: All
    Version: 2021.1.1
    Description: This fixes an issue with authentication ordering when delegated and password authentication are enabled. 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 <b>Always try Delegated Authentication</b> in the <b>System Administration > Security > System Security > Authentication/Web Sessions Options</b> page in the Management Portal or by using the ^SECURITY utility (System Parameter Setup, Edit authentication options).

    The default for <b>Always try Delegated Authentication</b> is No and ZAUTHENTICATE is not called for password users.

    DP-408802: Remove experimental database compression from CreateDatabase() method

    Category: System
    Platforms: All
    Version: 2021.2.0
    Description: 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.

    Please note this experimental feature is independent of the journal compression and stream compression features, which are unaffected by this change.

    DP-415808: CPF file changes related to gateways

    Category: System
    Platforms: All
    Version: 2022.1.1
    Description: This change updates the Gateways section of the CPF file to reorganize the fields for each gateway type, and to add a resource field.

    For each gateway type, the CPF file no longer has heartbeat properties. For all types except Remote, there is a new default Resource field. The UsePassphrase property has been removed.

    DP-9437: Changes to TCP /BINDTO behavior

    Category: System
    Platforms: All
    Version: 2019.4.0
    Description: If your application uses TCP device with /BINDTO option for outgoing connection, you may find the OPEN will fail if the IP does not exist in the local system.

    Tools

    DP-12771: Configuration API changes

    Category: Tools
    Platforms: All
    Version: 2021.1.0
    Description: If you are using the %Net.Remote.Object gateway APIs to configure Object gateways, you must now use the Config.Gateways APIs. The properties associated with the old values LineRecallEntries and LineRecallBuffer in the Config.config class have been removed. If you were setting these properties via the Config.Config APIs, you will now need to update the "history" property rather than these.

    DP-290726: With named pipes, the Bulk Loader does not report line count

    Category: Tools
    Platforms: All
    Version: 2019.1.0
    Description: To improve the handling of named pipes, the Bulk Loader does not attempt to count the number of lines in the file. This decreases the accuracy of the progress report but improves the performance of the utility.

    Web Gateway

    DP-11838: No longer modify existing CSP.ini for external web server

    Category: Web Gateway
    Platforms: All
    Version: 2020.2.0
    Description: Before this change, in environments where a third party web server is running remotely, the Web Gateway installer tried to modify some settings in CSP.ini which could result in unwanted changes in terms of service accessibility. A review of the configuration after each upgrade was always recommended.

    With this change, the Web Gateway installer will not modify an existing CSP.ini in any way.

    DP-11979: Web sockets with SharedConnection=1 can now time out

    Category: Web Gateway
    Platforms: All
    Version: 2019.1.2
    Description: In previous releases, a web socket connection with SharedConnection=1 would never time out. With this change, this connection will time out if it is inactive for the CSP session timeout.

    DP-12747: SSLCC_Protocol parameter changes for TLS 1.3

    Category: Web Gateway
    Platforms: All
    Version: 2020.1.1
    Description: 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.

    DP-13182: Sites using Nginx must rebuild and reconfigure

    Category: Web Gateway
    Platforms: UNIX®
    Version: 2020.4.0
    Description: 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 CSPx.so and CSPxSys.so), 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;
      }
      
      and the NSD is listening at 127.0.0.1:7038 (the default), then change the configuration block to:
      location /csp {
          CSP On;
          CSPNSD_pass 127.0.0.1:7038;
      } 
      
    4. Start up Nginx and the NSD.

    If you are migrating to using Nginx with NSD from using Nginx with dynamic modules (CSPx.so, CSPxSys.so):

    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;
      }
      
      and the NSD is listening at 127.0.0.1:7038 (the default), then change the configuration block to:
      location /csp {
          CSP On;
          CSPNSD_pass 127.0.0.1:7038;
      } 
      
    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, ot 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_pass 127.0.0.1:7038;
        CSPNSD_response_headers_maxsize 8k;
        CSPNSD_connect_timeout 300s;
        CSPNSD_send_timeout 300s;
        CSPNSD_read_timeout 300s;
    }
    

    DP-13734: Handle gateway timeout correctly

    Category: Web Gateway
    Platforms: All
    Version: 2020.4.0
    Description: When the Gateway times out, the associated IRIS processes should terminate. In some cases, this would not happen and the processes would continue. With this change, 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.

    DP-13874: Return HTTP error codes for redirects to custom error pages

    Category: Web Gateway
    Platforms: All
    Version: 2020.4.0
    Description: This changes the status code returned when Web Gateway redirects to a custom error page. If your web application expects HTTP status 200 for these custom error redirections, you need to update it to handle 5xx codes.

    DP-405460: Modify IRIS to use the hash of the CPF in place of the timestamp

    Category: Web Gateway
    Platforms: All
    Version: 2021.2.0
    Description: IRIS now sends a hashcode instead of a timestamp to indicate whether the server configuration has been changed, and the Web Gateway now accommodates these hashcodes in addition to timestamps from older servers.

    A newer standalone Web Gateway connecting to older IRIS instances functions as before. An old Web Gateway connecting to newer IRIS instances is not and has historically not been supported, but with this change it's particularly important for customers to keep their Web Gateway up to date. Old Gateways don't handle the hash from newer IRIS instances and thus will not update their server configurations.

    DP-410079: Make Maximum_Server_Connections a flat limit

    Category: Web Gateway
    Platforms: All
    Version: 2022.2.0
    Description: This change makes Maximum Server Connections a flat limit instead of a per-process limit. The strategy is to implement a throttle in cspTCPIPOpenSession, tallying connections on the same server in addition to the session-ID-based tally. This change also makes it so that the Maximum Server Connections configuration field is displayed and used even in the non-threaded/multi-process case. Additionally, processes with status Server and Private now count toward the total server connection tally.

    Customers who have multi-process web server architectures (e.g., Apache Prefork MPM) may need to adjust their Maximum Server Connection settings to accommodate more connections. The Web Gateway does not take responsibility for the underlying web server configuration. To support the same number of IRIS server connections as before, simply multiply the original maximum connection limit by the web server's maximum number of processes. (In Web Gateway Management, see Server Configuration -> Maximum Server Connections.)

    DP-7204: Fix a number of WebSocket thread-safety issues

    Category: Web Gateway
    Platforms: All
    Version: 2019.1.2
    Description: Fix a number of WebSocket thread-safety issues that resulted in occasional lost messages and dropped connections.

    If you are using Nginx with the default dynamic modules configuration (using CSPx.so and CSPxSys.so), note that we are now deprecating this configuration. The dynamic modules configuration will still function as before, but everyone using the Web Gateway with Nginx is urged to 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, so migration to the NSD is now doable 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.

    Migration instructions if you are already using Nginx with the NSD

    1. Install an updated version of the Web Gateway.
    2. Rebuild Nginx using the updated version of ngx_http_csp_module.c. See https://docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=GCGI_ux#GCGI_nginx_unnsd 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; }
      
      and the NSD is listening at 127.0.0.1:7038 (the default), then change the configuration block to
      location /csp { CSP On; CSPNSD_pass 127.0.0.1:7038; }
      
    4. Start up Nginx and the NSD.
    Migration instructions if you are using Nginx with dynamic modules (CSPx.so, CSPxSys.so)
    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 https://docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=GCGI_ux#GCGI_nginx_unnsd 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; } and the NSD is listening at 127.0.0.1:7038 (the default), then change the configuration block to

      location /csp

      { CSP On; CSPNSD_pass 127.0.0.1:7038; }

    5. Start up Nginx and the NSD. See https://docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=GCGI_atypical_windows#GCGI_usingnsd and https://docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=GCGI_atypical_unix#GCGI_usingnsdunix 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.

    Syntax: CSPNSD_response_headers_maxsize size;
    Default: CSPNSD_response_headers_maxsize 8k;
    Context: location, if in location
    Description: 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_connect_timeout time; Default: CSPNSD_connect_timeout 300s; Context: location, if in location Description: Timeout for connecting to the NSD when a request is received from the web client.

    Syntax: CSPNSD_send_timeout time; Default: CSPNSD_send_timeout 300s; Context: location, if in location Description: 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_read_timeout time; Default: CSPNSD_read_timeout 300s; Context: location, if in location Description: 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.

    An example configuration that uses all the new directives is the following.

    location /csp
    

    { CSP On; CSPNSD_pass 127.0.0.1:7038; CSPNSD_response_headers_maxsize 8k; CSPNSD_connect_timeout 300s; CSPNSD_send_timeout 300s; CSPNSD_read_timeout 300s; }

    Web Services

    DP-286593: %NetHttpRequest may perform extra round trip

    Category: Web Services
    Platforms: All
    Version: 2019.1.0
    Description: In this release, a new authentication process for %Net.HttpRequest changes the existing %Net.HttpRequest support for Basic authentication. In previous releases, setting the Username property as a side-effect returns a Basic Authorization header. This behavior will only continue for HTTP 1.0 responses. For HTTP 1.1 responses an unsolicited Authorization header will never be sent unless the InitiateAuthentication property is set. For HTTP 1.1 responses will result in a 301 status response with a WWW-Authenticate header indicating Basic and possibly other schemes. The next request will then send the proper Authorization header. Consequently, existing code will continue to work but there may be an extra round trip.

    DP-288990: Replaced class that implements API management

    Category: Web Services
    Platforms: All
    Version: 2019.1.0
    Description: The package %Net.APIManagement has been removed. Instead, see the new class %REST.API, which provides similar options. The %REST.API class is not formally supported in InterSystems IRIS 2019.1, but is planned for formal support soon.

    Work Queue Manager

    DP-404679: Some tasks removed from the Task Manager

    Category: Work Queue Manager
    Platforms: All
    Version: 2021.2.0
    Description: 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

    DP-411063: Work Queue settings removed on upgrade to 2021.2

    Category: Work Queue Manager
    Platforms: All
    Version: 2021.2.0
    Description: When upgrading 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, redefine them if necessary.

    xDBC

    DP-13358: Re-implement UNIX XDEVshm

    Category: xDBC
    Platforms: UNIX®
    Version: 2020.4.0
    Description: 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 behavior. 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.

    xDBC Server

    DP-408030: xDBC rejects connections when server ListFormat is not supported

    Category: xDBC Server
    Platforms: All
    Version: 2022.1.0
    Description: This change corrects 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.

    For Additional Help

    If you need assistance with evaluating how upgrading to this extended maintenance (EM) release will affect your applications, systems, or related plans, please contact the InterSystems Worldwide Support Center:

    • Phone:  +1.617.621.0700
    • Fax:  +1.617.734.9391
    • Email:  support@intersystems.com

    Current release notes (and complete product documentation) can be found online at https://docs.intersystems.com.

    FeedbackOpens in a new tab