Skip to main content

Caché 2016.2

This chapter provides the following information for Caché 2016.2:

New and Enhanced Features for Caché 2016.2

This section includes:

Major Developments

The following major, new features have been added to Caché for this release:

Support for Atelier, New Eclipse-Based IDE

This is the first Caché release that provides server support for Atelier, the new Eclipse-based IDE. The Atelier IDE brings together the powerful and popular Eclipse development environment and the InterSystems Caché database. Atelier allows you to develop Caché applications using a modern file-based IDE on a client system. Atelier handles uploading the application to the Caché server where it can be run and debugged.

The focus of future development will be on the new Eclipse based IDE. Studio will remain an option to install and developers can continue to develop code with it. However, it will be treated as a maintenance product and will not see new functionality added as we move forward with Atelier. Some minor bugs may not be addressed either depending on resources required versus the severity of the issue.

Atelier is available as a separate download in addition to Caché or Ensemble. You can choose to install either a stand-alone Rich Client Platform (RCP) application, or a plug-in that can be added to an existing Eclipse installation. Users of the RCP application can add additional Eclipse plug-ins. Atelier uses the Eclipse auto-update mechanism to help users get the latest changes. For information on downloading Atelier and for the Atelier documentation, see in a new tab, the Atelier home page.

Support for OAuth 2.0 and OpenID Connect

Starting with this release, Caché supports the OAuth 2.0 framework and OpenID Connect Core. Caché can act as a client, as a resource server, and as an authorization server. See Using OAuth 2.0 and OpenID Connect with Caché. Also see this articleé-open-authorization-framework-oauth-20-implementation-part-1Opens in a new tab posted on InterSystems Developer Community.

SQL/JSON Support

The SQL syntax has been enriched to support parts of the SQL/JSON standard. This allows to construct JSON data as a result from an SQL query. The functions supported are:

  • JSON_OBJECT—construct a JSON object for each encountered row.

  • JSON_ARRAY—construct a JSON array for each encountered row.

SQL Improvements

This release has the following SQL performance enhancements and improvements:

  • %Parallel—Improves performance of queries by breaking the query into chunks that can be executed in parallel on multiple processor systems. In this release the %Parallel infrastructure has the following improvements:

    • Lower overhead to breaking a query into chunks.

    • Caché dynamically breaks the query into a number of chunks based on the number of hardware threads that are available.

    • Increased number of query conditions that can be broken into chunks. For example, Caché can now break set looping constructs like IN (?, ?, ?) or %INLIST() into chunks.

    The result of these changes is that you can add %Parallel to most queries without extensive analysis. If Caché can improve the performance by breaking the task into chunks and using parallel processing, it will. If the query is not amenable to parallel processing or if the system only has a single hardware thread available, Caché recognizes this situation and does not incur the overhead of breaking the query into chunks.

  • Improved performance when iterating over list collections.

  • Frozen plans—allows you to freeze the plans while you make index and other changes.

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:

  • New REST API to access Caché source code files is available in this release. This API was implemented to provide access to the Atelier IDE, and it allows you to create IDEs and similar application. See Accessing Caché Source Code Files Using REST for details.

  • The DataCheck utility makes more efficient use of parallel processing in order to complete checks faster. The ^DATACHECK operator interface has an enhanced status page and start dialog for improved usability.

  • Caché is enhanced to use faster memory synchronization mechanisms (memory barriers) in certain critical execution paths. Data ingestion tests show more than 10% improved performance on Linux x86-64. The improvements apply to the following platforms:

    • Apple Mac OS X for x86–64

    • IBM AIX® for Power System-64

    • Microsoft Windows for x86–32, x86–64

    • Linux for x86–32, x86–64

    • Solaris for x86–64, SPARC-64

    These improvements do not affect the Itanium and Alpha platforms.

Caché 2016.2 Upgrade Checklist


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

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.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.

SQL Parallel Changes May Require Increase in Generic Memory Heap

In this release Caché uses InterProcess Queues (IPQ) in the Generic Memory Heap (gmheap) to process SQL parallel queries. Since these queries did not use this resource in previous releases, you may need to increase the size of the Generic Memory Heap. To increase its size, select System Administration>Configuration>Additional Settings>Advanced Memory and increase the gmheap size and restart Caché.

Worker Job Changes May Require User Permissions Change

To improve efficiency, this release shares the worker jobs between all users. These worker jobs are started by the super server. This is different from the previous release where each worker job typically ran under the account of the user running Caché. Consequently, these jobs run under a different OS user compared to previous versions. If the OS user for the super server does not have the same file privileges as the current user, the worker jobs may not have the file permissions needed to access files. If this problem arises, you can solve it by giving additional permissions to the operating system user account, or, if the problem occurs in custom code, instruct the developer to pass “/multicompile=0” to the work queue manager. This parameter instructs the work queue manager to execute the worker job under the current user’s account.

^JCONVERT Journal Conversion Changes

In this release, ^JCONVERT no longer supports RAW format as an output format and the prompt for this format has been removed. In this release ^JCONVERT converts journal files only to the Variable/UTF8 format.

Although previous releases supported RAW format output, there were substantial limitations, such as not handling binary journal data. If you have used ^JCONVERT to produce RAW files, you should evaluate your conversion needs.


If you are running ^JCONVERT from a script, you must modify the script as the first prompt has been eliminated.

Increase in Shared memory for Global Buffers

In previous releases, automatic configurations were limited to 256 megabytes shared memory for global buffers. In this release, an automatic configuration may use up to 1 gigabyte of shared memory for global buffers. If you are running many instances on a single system, this increase in memory may limit the number of instances you can use. Typically, these configurations are used for test or development environments. Note that “automatic” configurations should not be used for productions systems or for producing performance benchmarks.

Platform-Specific Items

This section holds items of interest to users of specific platforms.


In previous versions when you uncompressed the .tar.gz compressed archive file, it placed all the files in the same top-level folder containing the compressed archive file. In this release, it creates a new directory with the same name as the compressed archive file (with the .tar.gz extension omitted) and places all of the extracted files in that directory.

If you use a script that uncompresses the archive file and then executes the install, you will have to modify the script to handle the new directory.

Mac OS X

In previous versions when you uncompressed the .tar.gz compressed archive file, it placed all the files in the same top-level folder containing the compressed archive file. In this release, it creates a new directory with the same name as the compressed archive file (with the .tar.gz extension omitted) and places all of the extracted files in that directory.

If you use a script that uncompresses the archive file and then executes the install, you will have to modify the script to handle the new directory.


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:

  • %Dictionary — CompiledSystemMethod, CompiledSystemMethodQuery, SystemMethodDefinition, SystemMethodDefinitionQuery

  • %EM.Session — AssignToMirrorGroup, CreateMirror, EditAborted, EditApproved, EditCompleted, UpdateInstances

  • %Library — AbstractObject, Array, Object

  • %SYSTEM — WorkIPQ, WorkMgrSend

Removed Methods

The following methods were present in the previous version and have been removed in this release:

  • %CSP.Documatic

    • RenderSystemMethodInfo

  • %EM.Session

    • AssignToMirrorGroup

    • CreateMirror

    • EditAborted

    • EditApproved

    • EditCompleted

    • UpdateInstances

Removed Properties

The following properties were present in the previous version and have been removed in this release:

  • %Dictionary.ClassDefinition

    • SystemMethods

  • %Dictionary.CompiledClass

    • SystemMethods

  • %Library.ClassDefinition

    • SystemMethods

  • %SYSTEM.WorkMgrIPQ

    • queueIdx

    • tailIdx

  • Security.SSLConfigs

    • CRLFile

Removed Parameters

The following parameters were present in the previous version and have been removed in this release:

No parameters were removed.

Removed Indexes

The following indexes were present in the previous version and have been removed in this release:

No indexes have been removed.

Modified Methods

The following methods have different signatures in this version of Caché:

  • %CSP.UI.Portal.SQL.Home

    • old method: doReferenceTo (newtable) As (none)

    • new method: doReferenceTo (newtable, type) As (none)

  • %CSP.UI.Portal.SQL.Utils

    • old method: SQLExecuteQuery (pText:%String(MAXLEN=""), &pClassName:%String, pRuntimeMode:%Integer=2, pDialect:%String="Cache", pObjectSelectMode:%Boolean=0, %caller:%String="", &tGlobals) As %String

    • new method: SQLExecuteQuery (pText:%String(MAXLEN=""), &pClassName:%String, pRuntimeMode:%Integer=2, pDialect:%String="Cache", pObjectSelectMode:%Boolean=0, %caller:%String="", &tGlobals, &tLines, &tDiskRead) As %String

  • %CSP.UI.SQL.RunQueryPane

    • old method: DrawResult (&tRS:%ResultSet, tGlobals:%String, tStart:%String) As (none)

    • new method: DrawResult (&tRS:%ResultSet, tGlobals:%String, tStart:%String, tLines:%String, tDiskRead:%String) As (none)

    • old method: ExecuteResultSet (pParam:%String, &pRS:%ResultSet) As %Status

    • new method: ExecuteResultSet (%pParam:%String, &%pRS:%ResultSet) As %Status

  • %DeepSee.Component.Widget.widget

    • old method: printSVGContent (svgFrameId, parms) As (none)

    • new method: printSVGContent (svgFrameId, parms, svgContent) As (none)

  • %DeepSee.Component.deepseeSvgImageProvider

    • old method: parseSize (sizeStr) As (none)

    • new method: parseSize (size) As (none)

    • old method: prepareFilterTable (filterNames, filterValues) As (none)

    • new method: prepareFilterTable (filterNames, filterValues, parms) As (none)

  • %DeepSee.ResultSet

    • old method: %PrepareKey (pCubeName:%String, pQueryKey:%String) As %Status

    • new method: %PrepareKey (pCubeName:%String="", pQueryKey:%String="", pPrepareMDX:%Boolean=0) As %Status

  • %DeepSee.UI.FolderManager

    • old method: ExportItems () As %String

    • new method: ExportItems (pUseContainerClass:%Boolean, pContainerClassName:%String="") As %String

  • %EM.Session

    • old method: IsEditable (groupName:%String, serviceName:%String) As %Boolean

    • new method: IsEditable (groupName:%String, serviceName:%String) As %String

  • %EM.Session.IsEditable

    • old method: Invoke (%Client, %Action, groupName:%String, serviceName:%String) As %Library.Boolean

    • new method: Invoke (%Client, %Action, groupName:%String, serviceName:%String) As %Library.String

  • %Iterator.Array

    • old method: %OnNew (oref:%Library.AbstractObject) As %Status

    • new method: %OnNew (oref:%Library.DynamicAbstractObject) As %Status

  • %Library.GTWCatalog

    • old method: SQLProceduresExecute (&QHandle:%Binary, dsn:%String, pname:%String, schname:%String, catalog:%String="") As %Status

    • new method: SQLProceduresExecute (&QHandle:%Binary, dsn:%String, pname:%String, schname:%String="", catalog:%String="") As %Status

  • %Net.Provision.Configure

    • old method: AuthenticateWithKeyPair (username:%String, publickeyfile:%String, privatekeyfile:%String, passphrase:%String) As %Status

    • new method: AuthenticateWithKeyPair () As %Status

    • old method: AuthenticateWithUsername (username:%String, password:%String) As %Status

    • new method: AuthenticateWithUsername () As %Status

    • old method: Provision (cachekitfile:%String="") As %Status

    • new method: Provision () As %Status


    • old method: CompileList (&list:%String="", qspec:%String="", &errorlog:%String) As %Status

    • new method: CompileList (&list:%String="", qspec:%String="", &errorlog:%String, &updatedlist:%String) As %Status

  • %SYSTEM.WorkMgr

    • old method: Clear (timeout:%Integer=5) As %Status

    • new method: Clear (timeout:%Integer=0) As %Status

    • old method: WaitForComplete (qspec:%String) As %Status

    • new method: WaitForComplete (qspec:%String, errorlog:%String) As %Status

  • %SYSTEM.WorkMgrIPQ

    • old method: Decode (data:%String, qspec:%String, &AtEnd:%Boolean) As %Status

    • new method: Decode (qspec:%String, &AtEnd:%Boolean) As %Status

  • %Studio.Project

    • old method: realCompile (qstruct, &%errorlog:%String, &itemlist:%String) As %Status

    • new method: realCompile (qstruct, &%errorlog:%String, &itemlist:%String, &updatedlist:%String) As %Status

  • %Studio.SASchemaClass

    • old method: GetSchemaForClasses (&pClassList:%String, pNode) As %Status

    • new method: GetSchemaForClasses (&pClassList:%String) As %Status

    • old method: loopGlobal (pStream:%Stream.Object, pNode:%String) As %Status

    • new method: loopGlobal (pStream:%Stream.Object) As %Status

  • %ZEN.Auxiliary.altJSONProvider

    • old method: %ArrayToAET (&pMetaData, &pData) As %AbstractObject

    • new method: %ArrayToAET (&pMetaData, &pData) As %DynamicAbstractObject

    • old method: %GetTypeInfo (pClass:%String, pProperty:%String) As %Object

    • new method: %GetTypeInfo (pClass:%String, pProperty:%String) As %DynamicObject

    • old method: %ObjectToAET (pObject:%RegisteredObject, &oVisited, pLevel:%Integer=0, pFormat:%String="acelo") As %AbstractObject

    • new method: %ObjectToAET (pObject:%RegisteredObject, &pVisited, pLevel:%Integer=0, pFormat:%String="acelo") As %DynamicAbstractObject

    • old method: %TestForNestedObjects (pObj:%Array) As %Boolean

    • new method: %TestForNestedObjects (pObj:%DynamicArray) As %Boolean

  • %ZEN.Auxiliary.jsonMDXProvider

    • old method: %ConstructNewDynamicArray () As %Array

    • new method: %ConstructNewDynamicArray () As %DynamicArray

    • old method: %ConstructNewDynamicObject () As %Object

    • new method: %ConstructNewDynamicObject () As %DynamicObject

  • SYS.DataCheck.DestinationSYS.DataCheck.Destination

    • old method: Start () As %Status

    • new method: Start (restartworkflow:%Boolean) As %Status

Studio Changes

Deployed Methods are Marked as Read-Only

In previous releases, Studio ignored datatype classes that processed with the $system.OBJ.MakeClassDeployed() method. In this release, they are visible in Studio but are marked as Read-Only.


DeepSee Uses Locale Setting for Displaying Date-Time Values

In this release, if you specify that dates should be displayed using the current locale, DeepSee displays the date according to the locale. For example, in previous releases, a date would be displayed in the “mmm dd y” format but in this release will be displayed in the “mm/dd/y” format. You can revert to the previous behavior by specifying that the current locale should not be used for dates or by explicitly specifying a format. To specify that the current locale should not be used for dates, select System Administration > Configuration > National Language Settings > Locale Definitions and select No for Use locale date/time/number formats for locale-name.

DeepSee Changes to Tracking Update Status in ^OBJ.DSTIME

To avoid a race condition, this release tracks the status of class updates in a different location. If your application does both of the following, you will need to update it to reflect these changes:

  • Reads the log of updates to a class from ^OBJ.DSTIME.

  • Uses DeepSee to build or synchronize cubes based on that class.

If your application does both of these, you should change the reference from ^OBJ.DSTIME to ^DeepSee.Update. The ^DeepSee.Update global contains the same log of the update status as was previously stored in ^OBJ.DSTIME. The %PurgeDSTIME method now clears the ^DeepSee.Update global. The ID entries for a class stored in the ^OBJ.DSTIME global are killed with each update to any cube based on that class.

Individual IDs are stored under an identical structure to the ^OBJ.DSTIME buffer:

^DeepSee.Update(class,counter,ID) = updateType


IsEnsembleNamespace Method Accepts Parameter

In this release, the %Library.EnsembleMgr IsEsembleNamespace() method allows you to specify the name of the namespace as a parameter. The method returns 1 if the namespace is enabled for Ensemble and 0, if not. If you do not specify a parameter, the method’s behavior is unchanged—it returns the value for the current namespace. In previous releases this method did not accept a parameter, but, if you specified a parameter, the method would always return a 0.

Changed X12 Responses to Conform to Implementation Guides for Batch Transactions

In this release, the X12 business services sends a 999 response for X12 batch transactions only for the transaction types where the 999 response is specified in the Implementation Guides. Ensemble sends a 997 response for other X12 batch transactions. In Ensemble 2014.1 though Ensemble 2016.1, the X12 business services sent a 999 response for any incoming batch with a version greater than or equal to 5010. The behavior in Ensemble 2016.2 is the correct behavior, but if your code expects the 999 response, you can override the OnConstructReply() method in a custom X12 Business Service class in order to construct the 999 response document.

Specifically, the X12 Business Services construct 999 responses only for X12 batch transactions which have one of the following as their Industry Identifier Code (associated Transaction Set Identifier Codes indicated in parentheses):

   005010X187 (269) 
   005010X279 (270/271) 
   005030X209 (274) 
   005040X254 (275) 
   005010X212 (276/277) 
   005010X214 (277CA) 
   005010X217 (278) 
   005010X218 (820) 
   005010X220 (834) 
   005010X221 (835) 
   005010X222 (837P) 
   005010X223 (837I) 
   005010X224 (837D) 
Efficiency Improvements May Cause Production Configuration Page to Display Stale Data

The Ensemble production configuration periodically queries the production status and also tests whether the production needs updating. These checks lead to locks on core runtime data. In this release, the production configuration page reduces the amount of time it is holding locks. This improves the production efficiency but may cause stale production status or update information to be displayed. Even if the page is displaying stale update information in the hover tip, selecting update always uses the current value, not the stale value being displayed.

Prevent User from Editing Documents When Prohibited by Source Control

In this release, the Ensemble editors support source control and do not allow the user to modify a document when the source control system marks it as read-only. If the user opens a document when it is not checked out, it is displayed as read-only. To edit the document, the user must check out the document from source control and refresh the editor. If the document was checked out when the user opened it, but is later marked read-only by the source control system, the user will not be able to save the document and must use Save As to rename it. The following Ensemble editors now have this behavior:

  • BPL Editor

  • DTL Editor

  • Rule Editor

  • Record Mapper

  • Complex Record Mapper

  • Data Lookup Tables

  • Record Mapper

Changes in how XML Schema Global Storage

In this release, we have changed the internal global storage used for XSD. Although it was not a documented feature, in previous releases it was possible to make direct access to the array nodes in the virtual XSD global storage. This access no longer works in this release. It is possible to access this data using the GetContentArray() API.

This change reduces the storage needed to represent the XSD. A side-effect of this change is that if you re-import large schemas, extensive journaling could be recorded as the obsolete schema data is removed.

JSON Dynamic Object

Changes to JSON Dynamic Object Classes

In this release we have made substantial changes to the JSON dynamic object classes that were introduced in Caché 2016.1. See the Developer Community article JSON changes in Caché 2016.2 ( in a new tab for a detailed description of these changes. This article also provides guidance on how to update any code that you have written that works with the Caché 2016.1 JSON dynamic object classes.

Utilities Changes Utility Output Directory Change

In this release, the CacheHung utility removes the output file from the current directory after moving it to the instance/mgr directory. In previous releases, this utility copied the output file to the instance/mgr directory but left it in the current directory. If you have scripts that assumes that the output file is in the current directory, you should modify them.


If the current process does not have write permissions to the instance/mgr directory, then the move fails and the output file is left in the current directory.

ReturnUnusedSpace Now Always Returns Valid %Status Values

Although SYS.Database.ReturnUnusedSpace returns %Status, in prior versions it also had documented -1 and -2 as possible return values. Those values were returned when certain conflicting database operations were in progress (expansion and backup for example), but other conflicting operations would be returned as a proper error status. The interface has been updated to return all failures as proper %Status returns, including failures due to an expansion or backup in the same directory. Code that calls ReturnUnusedSpace should be inspected to ensure that the %Status return is handled properly.

FeedbackOpens in a new tab