InterSystems IRIS® Upgrade Checklist (2024.1)
This document is meant to help you assess the impact of upgrading to the InterSystems IRIS 2024.1 extended maintenance (EM) release. It lists the incompatibilities since 2023.1.0. 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.
Fixed Security Issues
DP-426809
CWE: CWE-1021: Improper Restriction of Rendered UI Layers or Frames
Severity: Medium
CVSS Score: 5.9
Version: 2024.1.0
FIXED: An attacker may be able to create a malicious page that embeds/displays management portal pages and tricks users into clicking on options that instead perform unrelated actions on unrelated pages/servers (clickjacking).
Embedded Python
- Make IRIS collections more pythonic
- Speed up ResultSet dataframe() Method and translate SQL nulls("" not $lb(,)) and SQL Empty ($C(0)) correctly as None and "" when generating typed python lists
- Disallow ByRef/Output qualified language=python method arguments
DP-421423: Make IRIS collections more pythonic
Category: Embedded Python
Platforms: All
Version: 2023.2.0
Previously, when InterSystems IRIS collection types (like %Collection.AbstractList) were projected into Python, there were some differences that prevented the objects from having identical characteristics to a standard Python object of the corresponding type. This issue has been resolved.
DP-425088: Speed up ResultSet dataframe() Method and translate SQL nulls("" not $lb(,)) and SQL Empty ($C(0)) correctly as None and "" when generating typed python lists
Category: Embedded Python
Platforms: All
Version: 2023.3.0
The ResultSet dataframe() method now returns a fixed view of InterSystems SQL data, in particular translating SQL nulls as None and SQL empty strings as "" when generating a typed python list.
DP-426579: Disallow ByRef/Output qualified language=python method arguments
Category: Embedded Python
Platforms: All
Version: 2024.1.0
A compile error is now thrown when an argument to a method is defined as ByRef or Output if language=python; previously, no error was raised. This is because Python does not support these kinds of parameters.
Global Module
DP-424362: Increase number of BlkSrch_ENQ, BlkSrch_DEQ and LRU resources
Category: Global Module
Platforms: All
Version: 2023.3.0
This change improves high-end scalability by increasing the count of various resources, like BlkSrch_ENQ, BlkSrch_DEQ, and LRU. This increase reduces resource contention and increased shared memory by a marginal number of megabytes.
Installation
- changes to Unix installer platform detection
- Replace %Service_Native on upgrade and new install
- check for AVX and BMI extensions in Windows and Unix installers
- Unable to launch documentation from the cube
DP-422913: changes to Unix installer platform detection
Category: Installation
Platforms: AIX
Version: 2023.3.0
Users that perform an installation in unsupported environment for testing purposes must explicitly set the ISC_PACKAGE_PLATFORM environment variable to the platform name.
DP-425275: Replace %Service_Native on upgrade and new install
Category: Installation
Platforms: All
Version: 2024.1.0
Instances that previously used %Service_Native in roles such as %Developer or %Manager must review the roles and consider if they also need %Native_Transaction or %Native_Concurrency.
DP-429502: check for AVX and BMI extensions in Windows and Unix installers
Category: Installation
Platforms: UNIX®
Version: 2024.1.0
The installers on Unix and Windows machines check for support for Advanced Vector Extensions (AVX) and bit manipulation instruction sets (BMI sets). If the CPU does not support these extensions, the installation (or upgrade) will abort with an error message.
To avoid any trouble with installing this version (or upgrading to it), ensure that your processor has these extensions.
DP-429584: Unable to launch documentation from the cube
Category: Installation
Platforms: All
Versions: 2023.2.0, 2023.3.0, 2024.1.0, 2024.1.1, 2024.2.0
If you are using Windows IIS as your web server or have upgraded from either 2023.2 or 2023.3, then you cannot open documentation through the launcher by default. To manually create a workaround, see the "Connect Your Web Server Manually" section of "Access the Management Portal and Other Built-in Web Applications Using Your Web Server."
IntegratedML
DP-416690: Make H2O default model type align better with AutoML
Category: IntegratedML
Platforms: All
Version: 2024.1.0
This change alters the default model type selection process for the H2O provider to better match the AutoML provider.
Previously, for date/time columns, the system would implicitly choose a regression model. For numeric columns, the system would choose a classification model if all values were integers and a regression model if there was at least one non-integer. Now, for both date/time and numeric columns, the model chosen depends on how many unique values are in the column and how many total values are in the column. If there are relatively few unique values, the system selects classification; otherwise, it selects regression.
Interoperability
- [Interoperability] System Default Settings now supports PoolSize, Enabled, TestingEnabled and ActorPoolSize
- [Interoperability] BPL SQL action to return status error if generated embedded sql reports an error
- [Interoperability] Business Process %MasterPendingResponses structure change
- Honor Business Operation use of overridden OnFailureTimeout setting of ..Retry to 1
DP-421559: [Interoperability] System Default Settings now supports PoolSize, Enabled, TestingEnabled and ActorPoolSize
Category: Interoperability
Platforms: All
Version: 2023.3.0
System Default Settings previously ignored any entries that matched an item's Enabled or PoolSize setting or a production's ActorPoolSize or Testing Enabled setting. With this change, the System Default Settings no longer ignore such entries.
DP-423063: [Interoperability] BPL SQL action to return status error if generated embedded sql reports an error
Category: Interoperability
Platforms: All
Version: 2023.3.0
The BPL SQL action now returns an error status if the generated SQL commands return a SQLCODE error. This allows the use of the BPL error handling mechanisms.
DP-423783: [Interoperability] Business Process %MasterPendingResponses structure change
Category: Interoperability
Platforms: All
Version: 2023.3.0
Business process %MasterPendingResponses list has been converted from a list to a parent/child relationship with Ens.BP.MasterPendingResponse and appropriate indices. Any custom code that iterated over the internal %MasterPendingResponses using GetAt() with sequential number iteration to the count value should be modified to use the parent/child collection methods of the class, such as Previous() and GetNext(). After an upgrade, any incomplete business process thread data must be converted using the Ens.BP.Utils.Upgrade.UpgradePendingResponsesStorage() method.
DP-426490: Honor Business Operation use of overridden OnFailureTimeout setting of ..Retry to 1
Category: Interoperability
Platforms: All
Versions: 2023.1.3, 2024.1.0
If custom Business Operations implemented OnFailureTimeout and that method sets ..Retry to 1, then the operation will not continue to retry beyond the FailureTimeout value.
Journaling
DP-426382: Ensure proper behavior of ExternalFreeze w.r.t. Write Daemon suspension
Category: Journaling
Platforms: All
Version: 2024.1.0
This change causes two methods to throw errors that they previously did not.
The ExternalFreeze() method now returns the error "ERROR #7338: System is already suspended" if the system is suspended with no request to suspend for over 10 seconds. Previously, ExternalFreeze() simply returned success in this case.
The ExternalThaw() method now returns the error "ERROR #7339: System is not suspended" if the system is not suspended and there is no request to suspend it. Previously, ExternalThaw() simply returned success in this case.
Kernel
- Remove unneeded loop from getint8()
- POWER7 processor no longer supported
- Allow any Unicode character as an identifier
- Add resources to control Native API access
- Add resource for XEP/Persister functions
DP-419453: Remove unneeded loop from getint8()
Category: Kernel
Platforms: All
Version: 2023.2.0
Previously, converting an out-of-range IEEE binary floating point value to an integer could produce a
DP-421917: POWER7 processor no longer supported
Category: Kernel
Platforms: AIX
Version: 2023.2.0
This change removes compatibility with AIX systems using a POWER7 or earlier processor. The new minimum is POWER8.
DP-423015: Allow any Unicode character as an identifier
Category: Kernel
Platforms: All
Version: 2023.3.0
Any new routine or class names can contain any Unicode character as part of the identifier.
DP-423341: Add resources to control Native API access
Category: Kernel
Platforms: All
Version: 2024.1.0
This change adds four new resources to control access to the Native API. They are included in the %Developer and %Manager roles with User permission. The resources are %Native_GlobalAccess, %Native_ClassExecution, %Native_Transaction, and %Native_Concurrency.
This change also makes the Persistor 1.0.0 jar and the .NET XEP 2.1.0 artifact incompatible with the current release. Contact the WRC for further information.
DP-424059: Add resource for XEP/Persister functions
Category: Kernel
Platforms: All
Version: 2024.1.0
Previously, the %Service_Native resource controlled usage of XEP functions. As this resource no longer exists, users now require the %Service_DirectLoad:USE resource to use XEP functions. This new resource is included in the %Developer role with User permission by default.
Licensing
DP-427878: disable TRAP_LICENSE SNMP trap for MONITOR
Category: Licensing
Platforms: All
Version: 2024.1.0
This change removes "license request exceeded available allocation" messages generated by various license failues, which were largley duplicates of the "license limit exceeded" messages.
Object - Entity Framework
DP-423018: Add Delimited Identifiers support in Entity Framework
Category: Object - Entity Framework
Platforms: All
Version: 2023.3.0
Previously in Entity Framework, all identifiers were quoted when parsing the SQL statement. However, if delimited identifiers are turned off on InterSystems IRIS, then this causes a syntax issue.
This change will not quote identifiers if delimited ids are turned off on the IRIS side.
This change requires users to ensure the delimited id setting is consistent across the databases they connect to.
Object Compiler
DP-423075: BUILD INDEX: Changes for Map Selectability
Category: Object Compiler
Platforms: All
Version: 2024.1.0
This change adds a new parameters, pKeepSelectability, to the %BuildIndices and %BuildIndicesAsync methods. See the Class Reference for more information.
It also adds support for a KEEP SELECTABILITY option to the BUILD INDEX SQL command. If this option is specified, after a successful index build, the map remains not selectable if it had been not selectable before the index build.
This is a change in the behavior of the BUILD INDEX command. When KEEP SELECTABILITY is not specified and the build is selectable, the index map is set as selectable. If you need an index map to remain not selectable aftter a successful index build, you must specify KEEP SELECTABILITY in the SQL statement.
Object Library
- Inherit routes in %CSP.REST UrlMap
- Write %UnitTest results directly to ^UnitTest.Result
- Add source location to %UnitTest.Result.TestAssert
DP-423147: Inherit routes in %CSP.REST UrlMap
Category: Object Library
Platforms: All
Version: 2023.3.0
This change removes the %CSP.Rest.ResolveTarget() method and makes the %CSP.Rest.DispatchMap() method Internal.
DP-424964: Write %UnitTest results directly to ^UnitTest.Result
Category: Object Library
Platforms: All
Version: 2023.3.0
%UnitTest.Manager now writes results directly to ^UnitTest.Result, where it can be accessed by other processes as it is generated. As a result, the TempLogIndex property no longer exists, as no temporary log is written. This changed behavior means that any subclasses of %UnitTest.Manager that uses the TempLogIndex property or relies on the generation of a temporary log needs to be updated.
DP-425574: Add source location to %UnitTest.Result.TestAssert
Category: Object Library
Platforms: All
Version: 2023.3.0
Unit tests log all TestAsserts to the console and store them in ^UnitTest.Result for structured access to the data. This change adds a mapping between a TestAssert and the location within the test class it came from by adding a new Location field in the %UnitTest.Result.TestAssert table, which helps with debugging test failures.
ObjectScript
DP-424951: $ZHOROLOG to use montonic clock
Category: ObjectScript
Platforms: All
Version: 2023.3.0
The change makes $ZHOROLOG use a monotonic clock, meaning the utility does not go backward due to NTP or daylight savings time. The time elapsed according to $ZHOROLOG may diverge from time elapsed as seen by taking changes of the real time as reported by $h, $ztimestamp, or $now; any code that expects those changes to be equivalent may need to be updated.
DP-428798: Fixed copy file errors on Unix systems
Category: ObjectScript
Platforms: UNIX®
Versions: 2022.1.5, 2023.1.4, 2024.1.0
This change fixes an issues that resulted in a failed copy (using the Library.File.CopyFile() method) on Unix systems when the destination does not exist.
It also adjusts the return codes for multiple failure cases when using Library.File.CopyFile().
ODBC
- ODBC. Do not convert data from BINARY to WCHAR
- ODBC. Do not accept TRANSACTION_SERIALIZABLE for SQL_ATTR_TXN_ISOLATION
DP-422960: ODBC. Do not convert data from BINARY to WCHAR
Category: ODBC
Platforms: All
Version: 2023.2.0
Previously, when converting BINARY data to the ASCII representation, it was initially converted into WCHAR. This has been changed, such that the ODBC driver now converted BINARY data directly to the ASCII representation.
DP-427540: ODBC. Do not accept TRANSACTION_SERIALIZABLE for SQL_ATTR_TXN_ISOLATION
Category: ODBC
Platforms: All
Version: 2024.1.0
When setting the connection attribution for SQL_ATTR_TXN_ISOLATION, the server now only accepts two values, SQL_TXN_READ_UNCOMMITED and SQL_TXN_READ_COMMITTED. Previously the system accepted SQL_TXN_SERIALIZABLE and internally converted it to SQL_TXN_READ_COMMITTED, but this conversion has been removed.
Security
- HTML encode REST error messages
- web gateway secret management for cloud
- Add %Admin_OAuth2_Client permission
- Add %Admin_OAuth2_Server and %Admin_OAuth2_Registration resources
- Tighten OAuth2 JWT security requirements
- SQL: kill INTO Array when SQLCODE'=0
DP-422560: HTML encode REST error messages
Category: Security
Platforms: All
Versions: 2022.1.4, 2023.1.1, 2023.2.0
Previously, error messages returned from REST APIs were not HTML encoded. This issue has been corrected.
DP-423672: web gateway secret management for cloud
Category: Security
Platforms: UNIX®
Version: 2023.3.0
Unix® users with passwords that start with { and end with } for Web Gateway server configurations will need to change them, or they will be interpreted as commands. Other platforms are not affected.
DP-424657: Add %Admin_OAuth2_Client permission
Category: Security
Platforms: All
Version: 2023.3.0
This change adds the %Admin_OAuth2_Client permission, which gives minimum permissions to a system that uses InterSystems IRIS as a client to an OAuth2 authorization server.
Any custom roles that had %Admin_Secure and fit this use case need to be updated to contain this resource.
DP-424919: Add %Admin_OAuth2_Server and %Admin_OAuth2_Registration resources
Category: Security
Platforms: All
Version: 2024.1.0
This change introduces two new resources OAuth 2.0 access. The %Admin_OAuth_Server resource controls the management of configurations that use InterSystems IRIS as an authentication server. The %Admin_OAuth2_Registration resource controls the management of clients when InterSystems IRIS is the authorization server.
DP-425110: Tighten OAuth2 JWT security requirements
Category: Security
Platforms: All
Version: 2023.3.0
This change makes "RS256" the default value for the SigningAlgorithm field in the OAuth2.Configuration class. Additionally, %OAuth2.Server.JWT now returns an error if no signing algorithm is defined for a JWT access token. the JWTToObject() method of the %OAuth2.JWT class no longer considers unsigned an unencrypted JWTs to be valid. However, this behavior can be overridden by using the new AcceptUnsecured parameter.
DP-427034: SQL: kill INTO Array when SQLCODE'=0
Category: Security
Platforms: All
Version: 2024.1.0
With this change, an output array created by an Embedded SQL statement reverts to its initial state if SQLCODE '= 0. Any pre-existing nodes that contained data still have that data, but no new data is added.
SQL
- Make INSERT OR UPDATE fail if the unique value belongs to a super class
- Fix, refactor and optimize SQL <explain statement> error processing
- Allow predicate pushdown for foreign tables with QUERY clauses
- Remove quote/quoteall from %occUtility
- Update Native resource checks in CheckBindingsAccess()
- SQL LOAD DATA changes for %NOINDEX and BULK
- Refactor and optimize the '$SYSTEM.SQL.Explain(...)' API/method
- Treat canonical numbers better for GREATEST/LEAST
DP-419630: Make INSERT OR UPDATE fail if the unique value belongs to a super class
Category: SQL
Platforms: All
Version: 2023.2.0
When users that have a class structure where there is a unique constraint in a super class attempt to INSERT OR UPDATE in the subclass, the command will now fail. Previously, this behavior did not throw an error, although an UPDATE would silently have been ignored.
DP-421723: Fix, refactor and optimize SQL <explain statement> error processing
Category: SQL
Platforms: All
Version: 2023.3.0
This change causes errors that arise from EXPLAIN statements to occur during query runtime, rather than compilation.
DP-422284: Allow predicate pushdown for foreign tables with QUERY clauses
Category: SQL
Platforms: All
Version: 2023.3.0
Useres must explicity ensure that column names provided for a QUERY-based foreign table are the same as the names in the QUERY clause of the CREATE FOREIGN TABLE commands or must provide a VALUES clause which specifies the names of the columns returned by the QUERY clause.
DP-424443: Remove quote/quoteall from %occUtility
Category: SQL
Platforms: All
Version: 2023.3.0
This change removes the internal $$quote and $$quoteall functions, which were included as internal-only utilities that were never intended for use in user-written code. Any user-written code that relied on these functions must be modified.
DP-424489: Update Native resource checks in CheckBindingsAccess()
Category: SQL
Platforms: All
Version: 2024.1.0
This change updates Native resource checks performed by the system to ensure the user has proper access.
DP-424924: SQL LOAD DATA changes for %NOINDEX and BULK
Category: SQL
Platforms: All
Version: 2024.1.0
Prior to this change, a LOAD DATA statement that specified %NOINDEX would build the indexes for the table automatically at the end of the run. This is no longer the case.
If LOAD %NOINDEX DATA or LOAD BULKT %NOINDEX DATA is executed, it is up to the caller to explicitly run BUILD INDEX on the table at a later time to populate in indexes.
Indexes for the table are built after all records are loaded when the %NOINDEX option is omitted.
DP-426466: Refactor and optimize the '$SYSTEM.SQL.Explain(...)' API/method
Category: SQL
Platforms: All
Version: 2024.1.0
This change alters the return type of $SYSTEM.SQL.Explain(); it now returns a refactored string, instead of an array.
To get the query plan as an array, use either $SYSTEM.SQL.ShowPlan(), $SYSTEM.SQL.ShowPlanAlt(), or specify the "PRINT-ARRAY" value for the format term of the qualifier parameter of the $SYSTEM.SQL.Explain() method to return the plan parameter as an array.
DP-427583: Treat canonical numbers better for GREATEST/LEAST
Category: SQL
Platforms: All
Version: 2024.1.0
It is possible that results returned from GREATEST and LEAST over JDBC would previously compare NUMERIC values incorrectly because they were treated as strings.
For example, GREATEST(?,1000), where ? is bound with a NUMERIC that is padded with zeroes to the right in order to attain the correct scale. In this case, the bound parameter may be less that 1000, but would have returned as greater than 1000.
System
- New Super Server
- Increase lock hash buckets by 4 times.
- Show correct variable name in %STACK and ^ERRORS when passed by reference
- Clear naked indicator after a subscript error
- Add -mavx flag to intel/amd platforms
- Fix syntax error in %STACK when ambiguous variable name
DP-412345: New Super Server
Category: System
Platforms: All
Version: 2024.1.0
The SSLSuperServer Property in the Security.System class has been removed. If you manipulate or change this property via class methods, you will need to update that code to refer to the Security.Servers class instead.
DP-425794: Increase lock hash buckets by 4 times.
Category: System
Platforms: All
Version: 2024.1.0
This change improves the performance and scalability of the LOCK command, especially on large systems. However, the time to service an unsubscripted lock request increases; note that unsubscripted locks should be avoided in high-frequency usage pattens.
This change also increases the size of shared memory allocated at startup by approximately 3 MB.
DP-426106: Show correct variable name in %STACK and ^ERRORS when passed by reference
Category: System
Platforms: All
Version: 2024.1.0
Previously, the incorrect variable name could be displayed for NEW commands and DO arguments when the execution stack includes variables passed by reference. The issue has been resolved.
DP-426460: Clear naked indicator after a subscript error
Category: System
Platforms: All
Version: 2024.1.0
The naked indicator is now cleared after a global SUBSCRIPT error. Such a naked reference that may have worked previously will now get a NAKED error.
DP-427700: Add -mavx flag to intel/amd platforms
Category: System
Platforms: All
Version: 2024.1.0
This change makes it possible to generate AVX in the Intel platform.
DP-431249: Fix syntax error in %STACK when ambiguous variable name
Category: System
Platforms: All
Versions: 2024.1.0, 2024.1.1, 2024.2.0
NOTE: This change impacts kits based on which operating system it is installed on. In particular, this change impacts upgrades to 2024.1.0 on Ubuntu platforms; once Ubuntu platforms have upgraded to at least a 2024.1.0 instance, upgrades to future instance do not introduce this incompatibility. However, on Windows and AIX platforms, this change impacts upgrades to 2024.1.1 or 2024.2.0 kits. Once Windows and AIX platforms have upgraded to at least a 2024.1.1 or 2024.2.0 instance, upgrades to future instances do not introduce this incompatibility.
In some cases when an argument is passed by reference, the stack dump is unable to distinguish between the actual and formal variable names, so it reports both of them as actual/formal. This could cause a syntax error that prevented the entire stack from being saved for future error reporting.
VDoc - XML
DP-423225: [Interoperability] XML VDoc to pass back error encountered creating output from use of internal stream
Category: VDoc - XML
Platforms: All
Version: 2023.3.0
Previously, errors encountered when generating out using internal stream were suppressed. This behavior has been changed so that such errors are now reported. These errors must be handled appropriately, either through code changes or production configurations.
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.