Caché Release Note and Upgrade Checklist Archive
Caché 2016.1
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

This chapter provides the following information for Caché 2016.1:

New and Enhanced Features for Caché 2016.1
This section includes:
Important New Features
Caché 2016.1 has the following important new features:
Improved JSON Processing Performance
JSON provides a lightweight mechanism to easily communicate structured data. In this release, you can use the new %Object and %Array classes to enable high performance parsing and generation of JSON-compliant content. The improved integration of JSON with ObjectScript allows you to efficiently convert between JSON and ObjectScript. For example, curly braces in JSON generate %Object instances in ObjectScript and square brackets generate %Array objects. Curly braces and square brackets can be arbitrarily nested and used with ObjectScript expressions for values. In this release, the JSON processing performance has improved to the point where you can have the benefit of the simplicity of working with JSON and have very efficient code. For information, see Using JSON in Caché.
For future development, InterSystems recommends that you use the %Object and %Array classes in place of %ZEN.proxyObject.
If you have existing code that is using JSON through Zen, you can gain improved efficiency with minimal code changes by using the new %ZEN.Auxiliary.altJSONProvider and %ZEN.Auxiliary.altJSONSQLProvider classes instead of the previous JSON provider classes, %ZEN.Auxiliary.JSONProvider and %ZEN.Auxiliary.JSONSQLProvider, which are still accessible, although no longer specifically documented.
Note:
In the %ZEN.Auxiliary.altJSONProvider and %ZEN.Auxiliary.altJSONSQLProvider classes, the %ConvertJsonToObject() method requires more memory than the corresponding method of the older classes. Specifically, the method in the new class requires twice as much memory as the JSON string used as input, because the method holds two copies of that data in memory.
The methods in the new %ZEN.Auxiliary.altJSONProvider and %ZEN.Auxiliary.altJSONSQLProvider classes always return standards-compliant JSON. Null data items project as JSON NULLs and strict JSON compliance is always enforced.
Normally, the newer classes simply ignore any flags that affect white space. The newer classes also ignore the u and q flags. In the interests of backwards compatibility, the new JSON provider has a fallback mode where, if the request fails, it will try again using the old jsonProvider logic. In that event, all of the old flags are used.
Improved SQL Performance
The performance of SQL commands is a critical component in how efficiently your Caché application handles large databases. We have been making significant improvements to Caché’s SQL performance. This release continues these improvements with the following new enhancements:
For details see UNION in Caché SQL Reference.
DeepSee REST Services and JavaScript Library
There are new REST services that provide access to the DeepSee engine. The services include data services for executing pivot tables and MDX queries and returning the results in JSON. There are also information services for getting lists of cubes, pivot tables, and cube information (dimensions, members, measures, and so on.)
For JavaScript developers, there is a new DeepSee JavaScript library that provides access to the DeepSee REST services.
For information on the REST services and the JavaScript library, see Tools for Creating DeepSee Web Clients.
Major Developments
The following major, new features have been added to Caché for this release:
New DeepSee Features
In addition to the REST services and JavaScript library, the following new features have been added to DeepSee in this release:
iFind Enhancements
This release provides the following iFind enhancements:
For information, see the chapter iFind Search Tool in Using iKnow.
iKnow Enhancements
An iKnow Architect page has been added to the System Management Portal for managing iKnow domains. This page allows you to define the static aspects of an iKnow domain, such as metadata and configurations, as well as the data locations to load data from. Domains can also be loaded (built) and emptied from this interface, leveraging the underlying Domain Definition infrastructure. For details, see Architect in Using iKnow.
Starting with this release, iKnow also supports Swedish and Japanese.
Zen Mojo Support of Twitter Bootstrap
In this release, Zen Mojo supports Twitter Bootstrap, a framework that helps you develop web pages. See the chapter Helper Plugin for Bootstrap in Using Zen Mojo Plugins.
.NET Entity Framework Support
In this release, Caché includes support for the .NET Entity Framework. The Entity Framework is an object-relational mapper that enables .NET developers to work with relational data using domain-specific objects. Caché supports Entity Framework versions 5 and 6. For details on the Caché support of Entity Framework, see Using the Caché Entity Framework Provider in Using .NET and the ADO.NET Managed Provider with Caché. For more information on the .NET Entity Framework, see http://www.asp.net/entity-framework.
ADO .NET Query Support of Cancel
This releases adds the ability to cancel an ADO .NET query.
Mirroring Improvements
This release has the following improvements in mirroring:
Security Enhancements
This release has the following security improvements:
Performance and Scalability Improvements
This release has the following performance improvements:
Windows x64 Support for Apache Version 2.4
This release provides Windows x64 native support for the Apache Version 2.4 web server.
Improved Utility Features
This release includes the following improved utilities:
Other Items of Note
In addition, many more lesser improvements and corrections are also included. In particular, if you are upgrading an existing installation, please review the detailed list of changes in the Upgrade Checklist.
Other minor areas of improvement include:
Caché 2016.1 Upgrade Checklist
Purpose
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.
Administrators
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:
SSL/TLS Configuration Changes
In previous releases, the screens for creating or editing an SSL/TLS configuration included a File containing Certificate Revocation List field. This field has been removed.
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:
YYYYYMMDD.NNN
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
UNIX®
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
Developers
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.