Caché Release Notes and Upgrade Checklist
Upgrade Checklist for Caché 2017.2
[Home] [Back] 
InterSystems: The power behind what matters   
Class Reference   

The purpose of this chapter is to highlight those features of Caché 2017.2 that, because of their difference in this version, affect the administration, operation, or development activities of existing systems.

Those customers upgrading their applications from earlier releases are strongly urged to read the upgrade checklist for the intervening versions as well. This document addresses only the differences between 2017.1 and 2017.2.
If you are upgrading from Caché 2008.2 or an earlier version, you cannot upgrade directly to Caché 2017.2, but must first upgrade to a version between Caché 2009.1 and Caché 2016.2. For details, see Supported Upgrade Paths in the Caché Installation Guide.
The upgrade instructions listed at the beginning of this document apply to this version.
This section contains information of interest to those who are familiar with administering prior versions of Caché and wish to learn what is new or different in this area for version 2017.2. The items listed here are brief descriptions. In most cases, more complete descriptions are available elsewhere in the documentation.
Operational Changes
This section details changes that have an effect on the way the system operates.
Feature Tracker Enabled by Default for New Installs
Feature Tracker is a software utility in Caché that gathers statistics on software module usage. The statistics track whether or not software modules are present and used in a given Caché instance. Feature Tracker sends this information via https to InterSystems weekly. These statistics help us plan development and support. The information gathered does not include any application data. In previous releases, Feature Tracker was disabled by default. In this release, Feature Tracker is enabled by default for new installs. If you are upgrading an existing installation, the upgrade preserves the existing state of Feature Tracker.
If you wish to disable Feature Tracker, you suspend the task that runs it. For details, see How to Deactivate Feature Tracker in the Caché System Administration Guide.
Parallel Dejournaling Changes the Order of Dejournaling
This release includes parallel dejournaling, which makes it possible for up to four jobs to perform the dejournaling. A database is always dejournaled by a single job, so parallel dejournaling does not impact the order in which a single database is dejournaled. But it can change the order in which one database is dejournaled relative to the dejournaling in another database. This is because databases being updated by separate dejournaling jobs are likely to be at slightly different places in the dejournaling sequence; for example, database A may contain updates made on the primary at 11:45:30 when database B is only up to the updates from 11:45:28. For details, see Configuring Parallel Dejournaling in the “Mirroring” chapter of the Caché High Availability Guide.
Changes to Journal Buffer Pool Size
In this release, the journal buffer pool size is configurable and the default has been increased to 64MB. In previous releases, the default was 8MB on non-Unicode systems and 16MB on Unicode systems. An increase in this buffer pool size can improve efficiency, but it also increases the amount of data that may be lost if a system crash occurs.
Platform-Specific Items
This section holds items of interest to users of specific platforms.
There are no known platform-specific changes.
This section contains information of interest to those who have designed, developed and maintained applications running on prior versions of Caché.
The items listed here are brief descriptions. In most cases, more complete descriptions are available elsewhere in the documentation.
Class Changes
Class Deletions
The following classes were present in the previous version and have been removed in this release:
Removed Methods
The following methods were present in the previous version and have been removed in this release:
Removed Properties
The following properties were present in the previous version and have been removed in this release:
Removed Parameters
No parameters have been removed in this release that were present in the previous version.
Removed Indices
No indices have been removed in this release that were present in the previous version.
Modified Methods
The following methods have different signatures in this version of Caché:
Class Compiler Changes
Hard Errors in delete() are Reported with %Status Value
In previous releases, if the delete() method in the class compiler encountered a hard error, it would throw the error to the caller. In this release, these errors are handled by the delete() method, which reports the error to the caller with a %Status value.
DeepSee Changes
Change Default to Display Mode in DeepSee Listing Selection
In previous releases, if a DeepSee field was not explicitly declared %EXTERNAL(field) or %INTERNAL(field), DeepSee would display its internal value in the listing output. In this release DeepSee will use its external value. To have the internal value used, you must wrap the field in %INTERNAL().
Java and Gateway Changes
Do not use JMS Gateway as Message Listener
This release removes the JMSGateway class from the Java Gateway. This class was intended as an example on how to use the JMS listener in Ensemble. If you have used this class to implement a JMS listener, you should replace this with the mechanism demonstrated in the EnsLib.JavaGateway.JMSTest class.
Object Gateway Load^%apiGTW Does Not Make err Variable Public
In previous releases, the call to Load^%apiGTW would deliberately make the variable err public so that it could be used in the Management Portal and other InterSystems APIs. In this release, it does not automatically make it public but instead returns a status value. If your code depended on this previous behavior, you must explicitly define err as a public variable by calling:
Set err=$$Load^%apiGTW 
.NET Language Bindings
Replace SysList, SysListUtil, and CacheListRO Classes Used With ODBCx APIs
If you use the SysList, SysListUtil, and CacheListRO Classes directly with the ODBCx APIs, replace them with other classes that provide similar functionality. Although the classes have been deprecated, they have not yet been deleted. If you use these classes but not use them with any other ADO APIs, you can defer replacing them until it is convenient. But if you use them with the ODBCx APIs, you must replace them before using with this release.
Object Library
%RunJava Utility Class Removed
In this release, the %RunJava utility class has been removed. If you call methods in this class, you must replace them with calls to the utility methods in %Net.Remote.Service.
ObjectScript Changes
Limit Number of Subscripts for Indirection
In this release, applications are limited to 254 subscripts for indirection. It is unlikely that there is any existing code doing indirection with more than 254 subscripts. Such code would create nodes that are not easily accessible.
SQL Changes
Changes in API to Create QuickStatement
The QuickStatement class syntax has changed and the class was moved from cache-jdbc to cache-db jar. The new syntax is
QuickStatement qs = QuickStatement.createQuickStatement((CacheConnection) connection); 
If you use the previous syntax, “QuickStatement qs = (QuickStatement) rs.getObject("**QuickStatement**");”, you must update your code to the new syntax.
Changes in %Date LogicalToOdbc and LogicalToDisplay
In previous releases if a timestamp value was passed through %Date LogicalToOdbc or LogicalToDisplay, it was not altered. As part of a fix to support dates prior to December 31, 1840, this behavior has changed. In this release if a timestamp value was passed through %Date LogicalToOdbc or LogicalToDisplay, it removes the time portion of the value and returns only the date portion. If your application logic depends on the previous behavior, you may need to modify your code. For example, if you query data in Display or Odbc mode from a table linked to Oracle and use a function like CAST(field AS DATE) or TO_DATE(...), Oracle returns a datetime value. In this release, Caché converts it to a DATE.
Enforce REFERENCES Privileges for Foreign Keys
In previous releases, it was possible to create a foreign key constraint through a DDL statement without holding the REFERENCES privilege for the referenced table. In this release, for a user to define a foreign key constraint that references table T, the user must hold the REFERENCE privilege on table T, or the REFERENCE privilege on the column(s) of table T that are being referenced by the foreign key. If an application creates foreign keys without holding REFERENCES privileges, it will encounter errors.
System Changes
Change in oref Numbers Ordering
In this release, we have improved the efficiency of processing OREFs. As a consequence, the OREF number assignments, which were previously assigned in the order created are now assigned in an independent way. Consequently, if your code relies on the way in OREF numbers were assigned, you must modify the logic. The previous ordering was an implementation detail and was not a documented feature. For example, if OREF string values are used to index a Caché multidimensional array, the subscript order of the OREF string values will no longer have any relation to the order in which those OREF values were created. If an application is using OREF value order to control order of execution or order of data handling, then that application will need to be modified to use other techniques, like $INCREMENT or $SEQUENCE, to generate the desired ordering
Console Log Changes
In some cases, long console log messages that were broken into two messages in previous releases will now be written as a single message. If you have code that parses for specific messages in the console log, you should update it.
Web Services
SOAP Wizard Includes Option to Generate Shorter Array Names
In previous releases, the default type name for an array item includes both the item name and type name or the key name and type name, even when the names are identical. In this release, by default, if the item name and type name are the same, only one is included in the default array type name. Similarly, if the key name and type name are identical, only one is included in the default array type name. For example, in previous releases, an XML schema (or a WSDL for a web service) might include something like the following:
<element minOccurs="0" name="PropName" type="s01:ArrayOfSimpleObjectSimpleObject" xmlns:s01="mytypes"/>
As of this release, the schema or WSDL will instead include this:
<element minOccurs="0" name="PropName" type="s01:ArrayOfSimpleObject" xmlns:s01="mytypes"/>
In some cases, you can revert to the previous default behavior:
Change to Invoking Web Methods Using HTTP Requests
In previous releases you could call a Caché SOAP web service directly without making an HTTP SOAP request. This shortcut avoids using a SOAP client but it bypasses the security available using HTTP SOAP requests. This shortcut is used by the catalog and test pages that Caché generates for a SOAP web service class. InterSystems recommends that you not use this shortcut but always use a SOAP web client to generate an HTTP SOAP request to call Caché SOAP web services. If you have code that uses the %SOAP.WebServiceInvoke class in a URL to invoke a SOAP web service, InterSystems recommends that you replace this with an HTTP SOAP request generated by a SOAP client.
Although it is not recommended, you can continue to use this shortcut mechanism, but you must explicitly enable this access. To use the %SOAP.WebServiceInvoke class and the soap_method query parameter, you must:
XML Changes
XSLT2 Transformation Returns Error Status for Fatal Errors
In previous releases, when an XSLT2 transformation encountered a fatal error, it returned $$$OK. In this release, it correctly returns an error status. If your code relies on the default error handling, you may have to modify it to handle this change. If you have overridden the default with custom error handling, the custom error handling will continue to work as it did in previous releases.