Caché Recent Upgrade Checklists
Caché 2016.1 Upgrade Checklist
[Back] [Next]
Go to:

The purpose of this section is to highlight those features of Caché 2016.1 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 2015.2 and 2016.1.

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 2016.1. The items listed here are brief descriptions. In most cases, more complete descriptions are available elsewhere in the documentation.
Version Interoperability
A table showing the interoperability of recent releases is now part of the Supported Platforms document.
Management Portal Changes
Performance Monitor Headings Changes
In previous releases, the PERFMON performance monitor had misleading headings on the report for metrics on blocks and buffers for big data reads and writes. For metrics 9, 16, and 23, the headings for these metrics indicated that they were for routine reads and writes. In this release, the headings correctly indicate that these metrics are for big data reads and writes. The headings for these metrics are now:
Operational Changes
This section details changes that have an effect on the way the system operates.
ECP Application Servers Maintain Connections Independently of TCP KeepAlive Setting
In previous releases, the TCP keepalive setting impacted how long ECP kept open the connection between the ECP application servers and the ECP data servers. If the data server became unavailable, this setting impacted the time it took to redirect the connection. The TCP keepalive no longer has any effect on maintaining connections between the ECP application servers and the ECP data server. If you have been adjusting the TCP keepalive at the operating system level on this basis, for example to allow for timely redirection of application server connections following a mirror primary outage and failover, you need no longer do so.
New Scheme for Naming Journaling Files May Impact Directory Names and Scripts
In order to increase the maximum amount of data that can be journaled per day, this release changes the scheme for naming journal files. The scheme for naming the first 999 journal files remains the same. It is:
Where YYYYYMMDD is the date and NNN is a number between 001 and 999. In previous releases, Caché could not create more than 999 journal files. In this release, Caché increases the number of digits in NNN to accommodate the number. For example, the 1st, 10th, 100th, 1000th and 10000th journal file created on 1/1/2015 would, respectively, have the names 20150101.001, 20150101.010, 20150101.100, 20150101.1000 and 20150101.10000.
In order to handle the longer file names, Caché limits the combined length of directory and prefix (if any) to 208 characters, which is 7 fewer than allowed before. If your sites uses very long directories and/or prefixes, you should change them to shorter ones.
In addition, if you have scripts that assume that journal files are named with three digits after the date, you may have to modify the script. For example, both the numeric and alphabetic sorting order of the file names does not match the chronological order because 20150101.1000 is sorted before 20150101.999.
Revised DataCheck Utility Changes Optimal Throttle Setting
In this release the DataCheck utility has been updated. Consequently, you may want to alter the Throttle setting to achieve optimum performance. The transition between settings is smoother. You may get better performance increasing the Throttle setting without consuming too much additional resources. Experimentation is the best way to determine an appropriate Throttle setting; it can be adjusted at any time and takes immediate effect.
Platform-Specific Items
This section holds items of interest to users of specific platforms.
Windows Installs and the CSP Gateway
In this release the unattended install uses the same defaults as the regular install. For example, if you use the unattended install, it does not install the CSP Gateway by default. To install the CSP Gateway in an unattended install, specify the CSP Gateway component in the ADDLOCAL property of the command line. To include all features, specify ADDLOCAL=ALL. See Running an Unattended Install in the Caché Installation Guide.
In a Windows install, it does not override CSP.ini if the IIS CSP Configuration is present. In previous releases, the install always overrides this file. Consequently, if CSP.ini was misconfigured, then the install will not correct the problem. To ensure that the install overrides CSP.ini, remove the IIS CSP Configuration before installing Caché.
In previous releases, when the CSP Gateway was installed, it would automatically configure Apache, if it was present on the system. In this release, you must manually configure Apache for the CSP Gateway. For details, see the CSP Gateway Configuration Guide.
Windows Management Instrumentation (WMI) Support Removed
This release does not support Windows Management Instrumentation (WMI). Consequently, we do not install the iscprov.dll library.
cdirectmgr Utility Omitted from Install
The cdirectmgr utility is no longer built and installed. This Windows utility provided direct control over server operation from a Windows COM/OLE or C++ client program. If you have been using the cdirectmgr utility, you should perform the same function using the cube.
Revised Warning Message For Abnormal Shutdowns
The warning message written to the console log during startup following an abnormal shutdown on Windows has been enhanced to report that the emergency (fast) shutdown procedure completed when Windows was shut down without a clean Cache shutdown. If the emergency (fast) shutdown procedure completed, the new console log message at the next startup will be:
06/18/12-03:30:40:421 (1856) 2 Previous system shutdown was abnormal, system forced down or crashed. Fast shutdown complete.
If the emergency (fast) shutdown procedure did not complete, the usual console log message at the next startup will be:
06/18/12-03:30:40:421 (1856) 2 Previous system shutdown was abnormal, system forced down or crashed.
Directory Change for /usr/bin in Installation
In this release, links for ccontrol and csession are in /usr/local/bin instead of /usr/bin. If your code has explicit reference to these links in /usr/bin, you must update your code to reflect the new location.
Installing CSP Gateway Automatically Updates Apache Configuration
In this release, the installer always restarts Apache when it updates the CSP Gateway binaries. In previous releases, the installer asked the user if Apache should be restarted. This change is only a compatibility issue for scripts or programs that automate the install process and are coded to expect the query dialog.
Mac OS X
Directory Changes in Installation
In this release, links for ccontrol and csession are in /usr/local/bin instead of /usr/bin. If your code has explicit reference to these links in /usr/bin, you must update your code to reflect the new location.
Restriction on Use of Caché eXTreme Features with OS X 10.11
Two features of Caché eXTreme, Java Globals API and in-memory XEP (eXTreme Event Persistence), cannot be used on OS X 10.11. Caché eXTreme provides external access through Java to Caché multidimensional data storage. You cannot use either the Caché eXTreme Java Globals API or the in-memory XEP on OS X 10.11 unless the OS X SIP (System Integrity Protection) feature is disabled.
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.
Routine Compiler Changes
Class Compiler Handles Long Class Names by Truncation
Although Studio prevents you from defining class names that exceed the allowed lengths, it is possible to generate code with names that are too long. In previous releases, this could result in a <NOROUTINE> error while compiling the class. In this release the class name is truncated to the maximum length.
Incremental Compile of Classes Feature Removed
In this release the /incremental compiler switch has been removed. In past releases, this switch instructed Caché to compile modified class methods only. Since the incremental compile provided only a minor reduction in compile time and actually produced less efficient code, this feature has been removed. If you specify the /incremental switch in this release, the compiler ignores the switch.
Compiler Disallows Illegal Class Names
In this release the class compiler produces an error if a class name contains either “||” (two vertical bars) or “.” (period). These symbols were not allowed in class names and typically, cause errors during execution, but were previously allowed by the class compiler.
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
The following parameters were present in the previous version and have been removed in this release
Also, the property parameter SELECTIVITY is now deprecated and is no longer shown in Studio or in the documentation. If the parameter is present, it has the same effect as in previous releases. Customers are encouraged to remove this property parameter from existing code.
Removed Indexes
The following indexes were present in the previous version and have been removed in this release
Modified Methods
The following methods have different signatures in this version of Caché:
Class Compiler Changes
This version of Caché continues the work begun in earlier releases of improving the class compiler. The changes that may require changes to applications are detailed in this section.
Language Binding Changes
There are no compatibility issues in this area.
SQL Changes
UNION %PARALLEL is not allowed in INSERT, UPDATE, and DELETE Queries
In past releases, %PARALLEL was not allowed in non-union INSERT, UPDATE, and DELETE Queries, but did not cause an error when you used %PARALLEL in a union INSERT, UPDATE, or DELETE query. The %PARALLEL did not work reliably in these queries. In this release, %PARALLEL is not allowed in either a union or non-union INSERT, UPDATE, and DELETE query. If you had used this construct in a previous release, it would not have caused an error message, but would likely have caused problems. You should remove any %PARALLEL option that is present in an INSERT, UPDATE, or DELETE query.
Fix to Floor Function Changes Returned Value
In previous versions, the ODBC Floor() function did not properly truncate values when the return type was a $list type 6 with an integer value and an SQLType Numeric (2) with zero scale. For example, the function could return “1234.” with an incorrect trailing decimal point. In this release, the Floor() function correctly truncates the number returning “1234” without the decimal point. If you have coded your application expecting this incorrect result and compensating for it, you should remove this correction code. This error only occurred with SQLType Numeric (2) and a zero scale. It did not occur with other types or nonzero scales.
Collation Expressions Are Checked for Errors
In this release Caché checks collation expressions for errors. In previous releases, Caché ignored these errors. In most cases, the error in the collation expression caused an error when using SQL, but it is possible that some collation expression errors did not cause an SQL error. In these cases, you will encounter an error in this release in code that appeared to execute successfully in previous releases.
Aggregate Functions Now Handle Zero-Length String Correctly
Aggregate Functions Now Handle Zero-Length String Correctly In this release, the XMLAGG() and LIST() aggregate functions handle 0-length strings correctly. If code relies on the incorrect way previous releases handled 0-length strings, it should be modified.
JDBC Data Models Have Significant Internal Changes to Support Read Ahead
This release contains many performance improvements for SQL JDBC data models. We do not know of any incompatibilities caused by these changes, but it is possible that implementation detail changes may influence behavior in unusual circumstances. We recommend that you test code that exercises this feature.
Changes To Locale And I/O Translation Tables
Functions Converting XML and ODBC Times Locale Change
The %Library.Time methods that are converting from XML and ODBC time formats used the current locale in previous releases. This caused a problem in locales where the decimal separator is not a . (period character) because XML and ODBC always uses a period character for this separator. In this release, these functions always use a period for the decimal separator. If you are calling these methods to set or evaluate XML or ODBC messages, there is no problem. But, if your code uses these methods in another context and expects the current locale’s decimal separator, you need to modify your code. The changed %Library.Time methods are: LogicalToXSD(), XSDToLogical(), LogicalToOdbc(), and OdbcToLogical().
The %Library.Time methods were inconsistent about truncating fractional seconds in previous releases. In this release, by default the methods always retain fractional seconds. There is a new PRECISION parameter that controls the number of decimal places to keep. If PRECISION equals 0, the time value will be rounded to the nearest second.
iKnow Changes
Compiling an iFind Index Requires Software License
The use of iFind has always required a valid iKnow license. Starting with this release, Caché will verify whether there is an iKnow-enabled license for your instance when you compile a class with an iFind index and an error will be thrown if you are not properly licensed for using iKnow. There is no strict need to recompile classes with iFind indices after upgrading to 2015.3, though it is generally recommended because it can provide improved optimizations.
Certain iFind Indexes Require Recompiling and Rebuilding
iFind indexes that use stemming or decompounding (INDEXOPTION != 0) have a changed compiled form. Consequently, after upgrading to this release, you must recompile and rebuild any existing indexes that use stemming or decompounding.
We recommend that you use the new %iFind.OriginalWord and %iFind.WordTransformation tables instead of relying on the specific mappings for stems and compounds. While using the specific mappings remain a supported feature, using the new tables is the recommended practice.
CSP Changes
There are no compatibility issues in this area.
SMTP, XML, Web Services, SOAP, And REST Changes
Converting from JSON to Object Error Handling Changed
In previous releases, the $fromJSON() function would fail silently but not return a valid object. In this release, if the function encounters an error condition, it throws an error. You should ensure that the error does not interrupt your application by including the $fromJSON() call in a try-catch block.
For example, if you had the following code to check that the $fromJSON() function returned a valid object:
  set obj = ##class(%AbstractObject).$fromJSON(source [,.stats]) 
  if ('$isobject(obj)) { 
    w "Compilation error occurred",! q 
You should replace it with a try-catch block such as:
  try { 
    set obj = ##class(%AbstractObject).$fromJSON("[1,2,WE WILL FAIL HERE") 
  } catch ex { 
    w "JSON Parsing error",! 
    w "Name = "_ex.Name,! 
    w "Code = "_ex.Code,! 
    w "Location = "_ex.Location,! 
Behavior in Entering SMTP Password Changed
In previous releases, Caché queried for the SMTP password only a single time. In this release Caché queries twice for the passsword and checks to see that the same password was entered to each prompt. This change eliminates the condition where Caché was attempting to use a null string as a password.
If you have written a script that responds to the password prompt, you must modify the script to handle the second password request.
DeepSee Changes
MDX Context is Provided without Encryption
In order to fix problems with some locales, this release does not persist the MDX context and does not encrypt it. If you are using custom action code in %OnDashboardAction that references the MDX context (pContext.mdx), you will have to modify your code and recompile. For example, if you have the following code to decrypt the MDX context:
Set tMDX = $$$cspDecode(%session.Key,pContext.mdx) 
You should replace it with the following that directly references the MDX context without decrypting it:
Set tMDX = pContext.mdx
If you do not make this change the cspDecode call causes an error.
New Option for Members with Numeric Names
If your cubes contain any levels that are based on source expressions and that have members with numeric names, it is possible to receive incorrect results in a very specific scenario.
The problem scenario is when a query uses an MDX range expression — for example, ([UnitsPerTransaction].[H1].[UnitsSold].&[7]:&[10])and one of the end point members does not exist. In such a scenario, DeepSee attempts to choose a different end point member. If the level is based on a source expression, DeepSee does not have the necessary information to choose a replacement member correctly and thus would sometimes choose the wrong member. In this scenario, it is necessary to provide additional information to indicate that DeepSee should treat the members as numeric.
InterSystems recommends that you review the level definitions in all your cubes and then do the following:
  1. If the level is based on a source property, no change is needed.
  2. If the level has members with purely numeric names, modify the cube in Studio and add castAsNumeric="true" to that level definition.
    This option is different from the Sort option, which does not affect how DeepSee searches for a new end point member.
  3. Recompile the cube class.
    It is not necessary to rebuild the cube.
  4. If you have previously encountered the problem scenario and if you might have results cached for the problem queries, reset the result cache.
    To reset the result cache, use the %Reset() method of %DeepSee.Utils. Note that this method also has an immediate impact on any users and is generally intended only for use during development. Also note that it affects only the current namespace.
pContext.mdx No Longer Encrypted
In previous releases, within the %OnDashboardAction() method, the underlying MDX query was provided in encrypted form. Specifically, when the data source is a pivot table, pContext.mdx contains the MDX query. In previous releases, it was necessary to use code like the following to decrypt the query:
 set myvariable = $$$cspDecode(%session.Key,pContext.mdx)
Now you can use code like the following instead:
 set myvariable = pContext.mdx
Scorecards Based on Pivot Tables with Crossjoins May Need to be Modified
This releases fixes a problem with scorecard widgets that are based on pivot tables with crossjoins. If you have a scorecard widget that meets all the following criteria, then you will need to edit the widget and reselect the properties for the scorecard. The criteria are:
You only need to edit the scorecard if all of the criteria are true. You do not need to edit a scorecard that has multiple measures or one that is based on a KPI.
Labels for Pivot Tables with a Single Measure
In prior releases, pivot tables were inconsistent in how they displayed measure headers if there was only one measure. A singe calculated measure always displayed a measure header, but a single non-calculated measure did not display a measure header. Pivot tables are now consistent in how they display measure headers. The default is to display a header for the measure if there is more than one measure (calculated or not calculated). The can be changed by using Measure Options.
If you have a pivot table with a single calculated measure and still want to see the measure header, use Measure Options and change Display Measure Headers to Always.
Zen Changes
Improved Handling of Long Labels and Titles May Change Output
This release improves how Zen handles long labels and titles and eliminates overlap between them. If the labels would take up more space than the chart itself, Zen displays the chart with the y axis titles only and suppresses the labels. In some cases, this improved handling of labels and titles changes the way charts are displayed.
Reports Now Require a Body Element
In this release the Zen Reports compiler requires that a report have a body element. In most cases, the error is useful and points to a report that needs to be fixed. In rare cases a valid report might not need a body element. These reports will not successfully compile. You should add a body element to these reports.
Zen Mojo Changes
There are no compatibility issues in this area.
System and Utilities Changes
Custom Callout Library Functions that Set TZ Need to be Modified
In order to make the time functions reentrant and secure, in certain environments you need to modify the code that sets the TZ environment variable. If you are running on Linux or Windows, you will need to add a call to tzset() after setting the TZ environment variable in a custom callout library function. The call to tzset() forces the update of the internal variables tzname, timezone, and daylight.
Changes to Output from Integrity Check May Cause Problems if Code is Dependent on Log Format
Improvements made to the integrity check, caused changes in the log output. If you have code that is dependent on the exact text in the log message, you need to revise it.
Lock Command Deferred Unlock ("D" mode) Changes
In previous releases, the behavior of "D" mode unlock was not well defined in the case of nested locks for the same lock node. This has been improved so that, "D" mode unlock respects the state of prior unlocks even when the prior unlocks were nested within an "outer" lock that is unlocked in "D" mode.
Unit Test Changes
New Assert Failure Macro
In this release, the new $$$AssertFailure macro unconditionally fails a test and logs the specified message. If the /debug qualifier was specified, the test will break in the debugger at that point. Following the convention of the other assertions, it returns 0, indicating failure. This macro is intended to replace the convention of asserting false, such as in a try block after an exception is expected in a test.
This is only a compatibility issue if you have subclassed the UnitTest class and the new macro conflicts with an extension to the base class.