Home / Release Notes and Upgrade Checklist / Upgrade Compatibility Checklist for InterSystems IRIS 2019.1

Release Notes and Upgrade Checklist
Upgrade Compatibility Checklist for InterSystems IRIS 2019.1
Previous section           Next section
InterSystems: The power behind what matters   

The purpose of this chapter is to highlight those features of InterSystems IRIS™ 2019.1 that, because of their difference in this version, affect the administration, operation, or development activities that have changed from previous versions.
General Upgrade Information
The goal of each release is a smooth upgrade to new and improved functionality with no changes required to existing applications. However, because of error corrections, significant enhancements, or changes to applicable standards, this goal cannot always be met. In this case, InterSystems discloses all identified instances where changes to applications are necessary so that customers can gauge effort required to move to the new release.
This section highlights information of interest to those who are familiar with administering prior versions of InterSystems IRIS and wish to learn what is new or different in this area for version 2019.1. The items listed here are brief descriptions. More complete descriptions are in the following section.
This section contains information of interest to those who have designed, developed and maintained applications running on prior versions of InterSystems IRIS. Since developers typically administer development system, this section also includes administrative upgrade issues.
The items listed here are brief descriptions. In most cases, more complete descriptions are available elsewhere in the documentation.
API Management Changes
Replaced Class that Implements API Management
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.
Business Intelligence Changes
Change in %GetCubeMeasures Return Values
The second item in the %GetCubeMeasures() output list should be the caption. In previous releases, for calculated measures, it was returning the name not the caption as the second item. In this release, 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.
Recompile All Cubes
When you upgrade to this release, you must recompile all Business Intelligence cubes. There are two reasons for this:
Multicompile Setting and Asynchronous Operations
If you have disabled the Business Intelligence work queue manager’s ability to process jobs in parallel, any asynchronous business intelligence operation may fail. Since InterSystems recommends that you always enable the Business Intelligence work queue manager to process jobs in parallel, you should not encounter this problem.
Asynchronous Business Intelligence operations include %DeepSee.Utils:%BuildCube (asynchronous mode, the default), %DeepSee.ResultSet:%ExecuteAsynch, and Business Intelligence REST calls. If you have set the /multicompile qualifier to 0, you may see the following error after attempting an asynchronous Business Intelligence operation:
ERROR #5001: Can not detach from work queue which is not using workers
To enable parallel processing by setting the /multicompile qualifier, enter a command such as the following
do $system.OBJ.SetQualifiers("/multicompile=1", 1)
For more information on the /multicompile qualifier, see Using the Work Queue Manager.
Interoperability Production Changes
Interoperability Message Bank Changes
In previous releases, HTTP, REST and SOAP Generic messages were sent to the Message Bank as Ens.StreamContainer and did not provide 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.
Java Business Hosts Changes
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 method is:
public class javahostsOperation implements BusinessOperation {

  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:
Change to API Testing Presence of Interoperability Features
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.
Change to Ens.Util.XML.SecuritySignature Class
In previous releases, the Ens.Util.XML.SecuritySignature class extended the %XML.Security.Signature class. In this release, 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.
Queue Wait Time Calculation Change
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 as part of the queue waiting time. In rare cases, this could change how InterSystems IRIS behaves in responding to the QueueWaitTime alert setting.
SOAP Outbound Adapter Clears HTTP Header
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.
Change in Default Behavior for Validation in Add Router Wizard
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.
Developers Using Studio Need Additional Privilege for Stored Procedures
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
Change in Management Portal Display for Settings in Custom Category
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.
InterSystems Cloud Manager (ICM) Changes
Change in Behavior When Reprovisioning AWS Volumes
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.
Rancher Monitoring Requires Authentication
In previous releases, you could use Rancher monitoring without authentication, which InterSystems did not recommend because it is an insecure configuration. In this release, if you want to use Rancher monitoring, you can only use it with authentication.
Cannot Override Reserved Keys
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:
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.
Must Use Datastore Cluster for vSphere Storage Allocation
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.
Device Letter Assignments Changed
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.
iris-main Will Terminate After Errors
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.
Language Binding Changes
Java Native API Illegal Integers Now Throw Exceptions
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.
Inconsistent XEP Schemas Now Throw Exceptions
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.
Change with Java and .NET XEP Generated Id Property
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.
Changes to .NET Entity Framework Function Names
The following Entity Framework classes are renamed in this release:
Rare Change in Projection of XEP Classes
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.
Monitoring Changes
Remove Deprecated WMI and BMC Patrol Monitoring
This release excludes support for using the BMC Patrol monitoring tool and the Windows Management Integration (WMI) monitoring.
System Statistics Changes
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:
%Monitor.Process, MONLBL, PERFMON and similar performance monitoring tools are unaffected by this change and maintain their own counters.
Object Changes
MSM-Activate Support Removed
This release 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.
Attempting to Round %Integer in %xsd Package Now Causes Error
In previous releases, if you attempted to assign a non-integer number 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.
ReadLineIntoStream Returns Different Value At End
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.
%Set(key,value,"null") and %Push(value,"null") Changes
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 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.
Change %Save Ordering to Ensure Predictability
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.
Security Changes
^EncryptionKey Routine Menu Changes
The ^EncryptionKey routine has new menu choices for InterSystems IRIS 2019.1 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:
SQL Changes
Frozen Plans on Upgrade
When you upgrade InterSystems IRIS to a new major version, existing Query Plans are automatically frozen. This ensures that a major software upgrade will never degrade the performance of an existing query. For performance-critical queries, you should test if you can achieve improved performance. For details, see Software Version Upgrade Automatically Freezes Plans
in the InterSystems SQL Optimization Guide.
New Default for Parallel Queries Can Change Order
In this release, 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 InterSystems IRIS instance upgraded from version 2018.1, 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.
SQL Default Precedence Changed for New Installs
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).
SQL.JDBC Throws Error for Illegal Date Time Value
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.
SQL.JDBC May Use Fast Insert for SQLType Storage
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:
  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);
SQL.JDBC Delete Row Removes from Client and Corrects Cursor
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.
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.
SQL Efficiency Improvements Change Internal Storage
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.
IDENTITY Column Data Type Change
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.
Error in Query in Stored Procedure Found at Compile Time
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.
Preserve Data Types in Dynamic SQL Arguments
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.
Streams Changes
Streams are Locked for Longer Time
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.
Stream Clones are Not in Temporary Directory
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.
Unit Tests Changes
Autoload Resources are Deleted on Test Termination
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.
Utility Changes
Bulk Loader Gives Less Accurate Progress Report with Named Pipes
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 Services Changes
%NetHttpRequest May Require Extra Round Trip
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.

Previous section           Next section
View this book as PDF   |  Download all PDFs
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA
Content Date/Time: 2019-04-23 13:43:24