Skip to main content

Release and Upgrade Information for Caché 2012.1

This chapter provides the following information for Caché 2012.1:

New and Enhanced Features for Caché 2012.1

The following major new features have been added to Caché for the 2012.1 release:

In addition, many more localized improvements and corrections are also included. In particular, if you are upgrading an existing installation, please review the detailed list of changes in “Caché 2012.1 Upgrade Checklist.”

Rapid Application Development

iKnow Technology

iKnow is a new technology addition to Caché that considerably enriches the ability of applications to analyze, handle, and use unstructured (textual) data. Without needing any predetermined expertise or knowledge about the data, iKnow automatically discovers the most important information locked in your unstructured data and opens it up for automated interpretation and exploitation.

Classic approaches to unstructured data analysis typically use keyword-based searching to match possible word groups to pre-built dictionaries and language models. Keeping this data current with the text requires continued, and often intensive, effort and ongoing maintenance.

The vision behind the iKnow approach is that unstructured data is composed of two different types of elements: concepts and relationships (expressing links between concepts). iKnow automatically discovers this information in your unstructured data and opens it up for interpretation and exploitation by end users, business intelligence analysis, and business processes. It can be used for any situation where there is the need to automatically transform unstructured data into structured views of concepts and how they relate topics to one another.

The iKnow technology is accessed through an easy-to-use interface that consists of a set of system classes defined in the %iKnow package. The capabilities are exposed in three different ways: as a set of Objectscript methods, a set of SQL stored procedures, and a set of web services.

Performance And Scalability

Improvements To Stream Performance

The %Library.GlobalBinaryStreamOpens in a new tab, %Library.GlobalCharacterStreamOpens in a new tab, %Stream.GlobalBinaryOpens in a new tab, and %Stream.GlobalCharacterOpens in a new tab stream implementations have been optimized for performance by reducing the amount of data copied during certain operations, and by leveraging CACHETEMP-based storage more effectively. In benchmarking heavy stream-based activity, the new stream implementation shows up to a factor of 1.5 improvement over previous versions.

Reliability, Availability, Maintainability, Monitoring

Manage ZEN Report Render Servers

This version introduces a new background process (external to Caché) that will be triggered automatically if you are generating Zen Report PDFs. This process instantiates a Java Virtual Machine (JVM) that will run FOP, the PDF generator from Apache. Caché will launch this process when a request comes in for a PDF based report, and send it information about the material to be processed.

The process will remain running in memory until it is explicitly terminated. More than one server process may be in operation at the same time. Caché will configure the process(es) using the settings defined in the Management Portal for the Zen Report Render Server. An administrator can specify what port each renderer will listen for requests on, what port(s) heartbeat monitor will keep track of, and logging details. If Caché detects a process crash, or a failure in the heartbeat monitor, then it will automatically relaunch this process.

Each server process is configured from the Management Portal parameters available at the time of its launch.

System Monitor

The Caché System Monitor functions as a Multivariate Process Control System for monitoring a Caché system and alerting when it is not running within the statistical boundaries of a “standard” system. The definition of “standard” is defined for each instance based on the application and user workflows in a given Caché environment. Deviations from the norm are measured using the WECO (Western Electric COmpany) statistical probability rules. The System Monitor provides reporting and alerting based on outlier and non-standard events as defined by the WECO rules.

Task Manager Improvements

This release adds a number of improvements to support email notifications, and consistency adjustments. Customers can now specify a port number for the SMTP connection, and use an API to programmatically access task manager information.


CSP Gateway To Caché Over SSL

With this release, applications may now request a secure connection between the CSP Gateway and the Caché instance it connects to. This adds an important security layer for connections where the CSP Gateway does not reside on the same machine as the Caché instance.

Web Services - Secure Conversation

Many Web services applications accommodate frequent communication between the service and client. When this communication needs to be secured end-to-end using WS-Security, the application encounters additional overhead because WS-Security uses public key encryption to secure each message separately.

To mitigate this overhead, the Web services community has introduced WS-Secure Conversation. WS-Secure Conversation moves the overhead from securing each message to a single handshake. Once the secure session is established, the service and client enter a secure conversation until the session’s expiration.

This release provides support for WS-Secure conversations in Caché.


Zen And HTML5

With this release, InterSystems has added logic to allow all Zen pages served from its products to produce HTML5 output. Whether HTML5 output is produced or not is controlled by the setting of a global, ^%ISC.ZEN.cssLevel.

If the value of this global is set to 3, all Zen pages written by InterSystems that are served to browsers that support it will produce HTML5 output (interpreted in strictOpens in a new tab rather than quirksOpens in a new tab mode). If the global is missing or has the value 2, HTML output will be the same as in 2011.1. The default for new installations and upgrades is to retain the previous behavior.

Those applications that wish more fine-grained control over HTML5 production can override the method, %OnDetermineCSSLevel() for a page or subclass to return the value 3. Certain pages in the management portals work in this mode already; and all will beginning in 2012.2.

Generating HTML5 will also automatically invoke the native SVG renderer built into Internet Explorer 9, bypassing the Adobe SVG plugin should it be installed.

Caché 2012.1 Upgrade Checklist


The purpose of this section is to highlight those features of Caché 2012.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 2011.1 and 2012.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 2012.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 releasesOpens in a new tab is now part of the Supported Platforms document.

Management Portal Changes

Numerous changes have been made in the Management Portal for this release both to accommodate new features and to reorganize the existing material to make it easier to use. Among the more prominent changes are those in the pages associated with database mirroring and a major change in the look of the Portal itself to increase the granularity of control and provide the ability to define a per-user “favorites” list.

Operational Changes

This section details changes that have an effect on the way the system operates.

2KB Databases No Longer Supported

Version 2011.1 noted that support for 2KB databases was to be withdrawn in this release. Existing 2KB databases must be converted to 8KB format prior to the upgrade to this release using SYS.Database.Copy().

Default Minimum GMHEAP Size Is Now 22MB for New Installations

Beginning with this release, the minimum size required for the generic memory heap (gmheap) in new installations has been raised from 4MB to 22MB in order to allow loading of the initial iKnow language tables, en (English) and es (Spanish).

Upon upgrade, the installer will examine the value set for the gmheap:

  • If the value set for the gmheap < 21184KB, it will be changed to the greater of the previous value + 16384KB, or to 21184KB, which ever is greater.

  • If the value is > 21184KB, the installer will leave the setting untouched. In this case, administrators are assumed to have other reasons for setting the gmheap value higher, and this new memory demand should also be taken into account in their calculations of a new value.

    Also in this case, if the value does not permit the loading of the basic language tables, Caché will produce a warning in cconsole.log and attempt to degrade gracefully.

If applications wish to take advantage of languages other than English and Spanish, the gmheap size must be further increased per language desired. The following table gives the available language model and the amount of the increase. For those, with gmheap sizes above 21184KB, the sizes of English and Spanish tables are also included.

Language Code Language Name Memory Needed
de German 4.5 MB
en English 3.3 MB
es Spanish 12 MB
fr French 4.4 MB
nl Dutch 3.6 MB

Finally, if a site does not intend to use any of the iKnow capabilities, the gmheap value may be set lower after the upgrade / installation. This will require a restart of Caché to take effect.

Emergency Mode Runs Under the Owner Userid, Not As Root

The emergency mode startup code is now run under the owner userid, not “cacheusr”. This prevents unnecessary failures in attempting to initialize certain resources, such as the CSP portal.

Defragmenting Globals Now Requires %Admin_Manage

Defragmenting the globals in a database now requires the %Admin_Manage role. Previously only write access to the database was required.

^DATABASE Functions Extended to Non-Primary Mirror Members

Beginning with this release, the various ^DATABASE functions related to returning free space, compaction, truncation and defragmentation can now be run on mirrored databases from all mirror members regardless of their current role. Previously, they could only be run on a node when it was the primary mirror member.

^DATABASE Menu Changed

The ^DATABASE menu was changed in this version to add the option

4)* Mirror Set Name:

under the menu item

1)      Create a database

Sites which drive ^DATABASE via scripts should take note.

License Enforcement Tightened

In this release, the management of licenses, including license limit enforcement, has been improved.

  • Licenses Cannot Be Obtained from the CSP Server Process

    Applications that call $SYSTEM.License.Login() from a CSP server process (serving a CSP page request or a SOAP request) will encounter a <FUNCTION> error and must be changed to use the %CSP.Session login API.

  • Use of Management Portal Consumes a License

    The System Management Portal application now consumes a license. There is now no difference, from a license use perspective, whether you log in to Caché through a terminal connection and run character-oriented management/operation utilities, or you access this functionality through the browser based Management Portal.

    Customers who have sites that run with a license key sized to the exact number of users may encounter license limit exceeded issues if the Management Portal is used, consumes the last license unit, and another user attempts to log in to Caché.

  • Remote CSP Connections Not Allowed without a License

    Caché now enforces the rule that a Caché instance that does not have a valid license key installed will not serve CSP applications to a remote host. Without a valid license key, CSP applications are now only accessible from a browser on the local machine.

  • Task Manager Initiated Processes Consume a License with Web Add-On Key

    Processes started by the task manager will now consume a license as web add-ons.

Make LoginCookies Authentication Mode Fully Independent

Beginning with this release, for applications which allow both unauthenticated and login-cookie authentication modes, the login cookie is now checked before the unauthenticated mode. In prior releases, an application could be logged in as UnknownUser even if a login-cookie was available.

Increase Frame Stack Size on 64-Bit Systems

The frame stack size for 64-bit platforms has been increased in this release to account for increased stack usage in recent releases. It may now be larger than 64KB. (The stack size for 32-bit platforms has already been increased in a previous release.) This will prevent <FRAMESTACK> errors when programs are migrated forward.

This change results in an increase in the memory usage for each partition, depending on the 64-bit platform:

  • Unicode: 25,032 bytes

  • 8-bit: 19,817 bytes


If your application (or application set) was close to running out of space in previous versions, this additional consumption of memory may cause <STORE> errors. If this happens, the partition size must be increased.

Changes to %Manager Role

In this release, the %Manager role now has the %Admin_Journal:USE resource added to it.

Managing Tasks Now Requires New Role

Beginning with this release, if a Task is to be created, modified, or run, the resource %Admin_Task:USE is required. This resource is now added to the %Manager role with USE permission so users owning this role can manage tasks.


The %Operator role is not granted this resource by default, so users holding this role cannot manage tasks, unless the %Admin_Task:USE resource is added to the %Operator role.

If an administrator has created roles which were based on the %Operator role and tghey were used to access the Operator menu in the Management Portal, the administrator will need to modify those roles to add the %DB_CACHESYS:RW privilege to it; and, if they wish to manage tasks from this role, must also add %Admin_Task:USE.

DeepSee Resource Additions

This release adds new resources to the system for working with DeepSee, namely:

  • %DeepSee_AnalyzerEdit - Grants full access to DeepSee Analyzer

  • %DeepSee_Analyzer - Grants ReadOnly access to DeepSee Analyzer

  • %DeepSee_PortalEdit - Grants full access to DeepSee User Portal

  • %DeepSee_Portal - Grants ReadOnly access to DeepSee User Portal

  • %DeepSee_ArchitectEdit - Grants full access to DeepSee Architect

  • %DeepSee_Architect - Grants ReadOnly access to DeepSee Architect

  • %DeepSee_Admin - Grants access to DeeepSee configuration and security settings

%Admin_Task Resource Added

In this version, Caché now defines a new resource %Admin_Task. If a task is to be created, modified, or run, the resource %Admin_Task:USE is required.

%Admin_Task:USE is now added to the %Manager role so users owning this role can manage tasks.

The %Operator role is not granted this resource by default; users holding this role cannot manage tasks, unless the %Admin_Task:USE resource is added to that role. If a user has created roles which were based on the %Operator role and used to access the Operator menu in the Management Portal, they will need to modify that role to add the %DB_CACHESYS:RW privilege to it. In addition if they wish to manage tasks, they also need to add %Admin_Task:USE privilege.

Lastly, if when creating a task, the "User to run the task as" is modified to someone other than the logged in user, this operation requires the %Admin_Secure:USE privilege.

BackupScripts No Longer Distributed

The scripts, “cbackup” and “cbackups”have been removed from UNIX® distributions and installations, including RPM and DMG kits.

Dialog Changes for Key Activation at Startup

It is no longer possible to browse for the encryption key file used for database encryption during Caché instance startup. This enforces two-factor security by separating access to the encryption key file from knowledge of the password needed to activate the key.

Changes in the Treatment of the USER Database on Upgrade and Install

Installation processing will no longer modify the USER database and namespace settings on upgrade, nor will it recreate USER database and namespace definitions if they are not present. A new install will create the USER database and namespace by default on all platforms.

The feature “server_user” is no longer visible in custom installs on Windows, but it is possible to disable the USER database installation in new install Windows by disabling the installation of feature “server_user” using command line, creating a transform, or modifying MSI package.

Changes to CSP Gateway Installation for Apache on UNIX®

UNIX® installation scripts will no longer update the external web server configuration if it was already configured for CSP Gateway. If the web server was not previously configured for CSP Gateway, the new configuration will use the shared modules mechanism rather than the CGI-based mechanism used by default in previous versions. This change affects the regular UNIX® installer, the CSPInstall standalone CSP Gateway installation script, and RPM and DMG installations.

The CSP Gateway installation process will not change a web server configuration when it detects that the web server was already configured for CSP Gateway. The current detection mechanism consists of parsing the Apache configuration file for the string “/csp” in any line not started with a comment character(#). If the installer detects that the web server was previously configured for CSP Gateway, it produces a message stating that any required re-configuration should be done manually. Nonetheless, it still upgrades CSP Gateway binary files as needed.

Configuration File Changes
  • STU Parameter Removed

    The STU=1 parameter in the CPF file has been removed. To start the system for maintenance, use the Emergency Startup option.

    Emergency Startup has been enhanced so:

    • Neither TASKMGR, Shadowing, Mirroring, nor (if applicable) Ensemble productions are started.

    • ZSTU,%ZSTART,%ZSTOP,ZSHUTDOW are not run when the system starts or stops.

    • User processes which log in using the emergency id do not run %ZSTART or %ZSTOP.

  • 2KB Buffer Allocation Reassigned

    In the [config], section, if space is allocated for 2KB buffers in the globals= declaration, an amount of memory equal to the same number of 8KB buffers will be added to that allocated for 8KB buffer, and the 2KB allocation will be ignored.

    In the [Startup] sections, if the DBSizesAllowed parameter had an entry for 2KB buffers, this will be removed.

  • MirrorSet Options Expanded

    In the [MirrorSetMembers] section, the new parameters ConnectTo and MemberType have been added. Each parameter allows for the following values: AgentAddress, AgentPort, ConnectsTo, ECPAddress, GUID, InstanceDirectory, MemberType, MirrorAddress, MirrorSSPort, Reserved.

  • Method for Retrieving / Storing Mirror Client Name for SSL Authentication Changed

    The handling of SSL identification fields in mirroring has been revised. Commas no longer need to be converted to slashes, and fields no longer need to be re-ordered for comparison. This change can affect applications trying to use a certificate where the Subject field contains slashes (/) in the data. The DN fields are now base64 encoded when stored in the .cpf file to avoid issues of commas in the data within a comma delimited field.


    This change creates an interoperability problem when there is a mix of failover members, some with and some without this change. The mixed configuration is supported for upgrade purposes and it will function correctly. However, while there is a mixed configuration, it is not possible to re-configure the mirror to use SSL. If the mirror is already configured to use SSL, it will continue to do so. In order to enable SSL, all of the failover members must be running compatible versions.

Add Latin5 And CP1254 Translation Tables to Turkish Locale

This release adds I/O translation tables for Latin5 (ISO-8859-9) and Windows CP1254 to the Turkish Unicode locale (turw).

Stopping Journaling Overrides Freeze on Journal Error

Beginning with this release, stopping journaling overrides the setting that freezes the system in the event of a journal error. That is, on a system set to freeze on journal error (FreezeOnError = 1 in cache.cpf), stopping journaling is allowed and does NOT cause the system to freeze thereafter.


Under this circumstance, by stopping journaling, the site accepts the loss of journal data (and attendant recovery issues in case of failure during this period) as being of less consequence than the loss of the ability to continue processing.

Convert 8-Bit Journals to Unicode Before Using

When upgrading from earlier 8-bit release to a Unicode version of this release, two steps are necessary. First, upgrade the earlier version to an 8-bit version of this release and process any journal files needed. Than, upgrade this 8-bit version to a Unicode version.

Stream Processing Improvements

This version contains significant improvements to how streams are handled by Caché. These include the elimination of unnecessary copying of buffers, better use of CacheTemp, and improvements to the order that stream nodes are saved. The net result of these changes for applications with heavy streams loads is an increase in the number of operations from 1600 streams operations per second to 2400 operations per second.

Web Services Security Speedup

In previous releases, the time needed to generate the security header could represent a sizeable fraction of the time to generate the message as a whole — for the average message, as much as three-quarters of the time. In this version, generation of the header has been cut roughly two-thirds resulting in substantially better throughput.

Changes To ECP Rollback

In previous versions, an ECP rollback would inhibit service until the rollback finished; the time involved depended on the amount of data to be reset. In this version, rollback and normal ECP service can each proceed simultaneously. There is no pause in service.

Change in Form of Generated Queries

In some cases, the DeepSee Analyzer generates MDX queries of a different form than previously. This can affect scorecards based on pivot tables, so that the scorecard is no longer functional and must be reimplemented as described here.

The affected queries are ones for pivot tables that you create as follows:

  • Optionally drag and drop any items to Rows

  • Drag and drop members, levels, or dimensions to Columns

  • Drag and drop one measure to Measures

In the previous release, a pivot table that you created this way had an MDX query like the following example:

SELECT NON EMPTY [Outlet].[H1].[Region].Members ON 0,
       NON EMPTY [Product].%TopMembers ON 1 
FROM [HoleFoods]
WHERE [Measures].[Amount Sold]

A scorecard can display the results of a query of this form.

In this release, a pivot table created in the same way has an MDX query like the following example:

SELECT NON EMPTY NONEMPTYCROSSJOIN([Outlet].[H1].[Region].Members,{[Measures].[Amount Sold]}) ON 0,
       NON EMPTY [Product].%TopMembers ON 1 
FROM [HoleFoods]
WHERE [Measures].[Amount Sold]

Because this query has a crossjoin, it cannot be displayed in a scorecard.

If you have existing scorecards that depend upon a query of the former kind, do the following:

  1. Create a KPI that is based on the desired MDX query.

  2. Use that KPI as the data source for the scorecard instead of the previously saved pivot table.

Rebuild DeepSee Indices

In 2012.1, there is a change to the indices of the generated dimension tables. This change may cause your queries to stop working unless you rebuild the indices for all the dimension tables. To do so, enter the following command in the Terminal, in each namespace that contains DeepSee cubes:

Do ##class(%DeepSee.Utils).%BuildDimensionTableIndices("*")

Platform-specific Items

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

Mac OS X
  • Rename libcache.dylib

    Mac OS X 10.7 (codenamed “Lion”) introduced a new shared library called libcache.dylib. In order to avoid the name conflict, the Caché callin library has been renamed to libisccache.dylib. Existing applications that link with libcache.dylib need to be changed to use libisccache.dylib.

  • Kerberos Authentication Key File

    Kerberos authentication on macOS 10.7 will not work unless a keytab file containing the key for the Caché service principal is present in the file /etc/krb5.keytab. On all other platforms, and on previous versions of macOS, this file should be <installdir>/mgr/cache.keytab. The error returned from the kerberos library that indicates this condition is:

    ERROR #956: Kerberos error: GSS-API error acquiring server credentials; 
    No credentials were supplied, or the credentials were unavailable or inaccessible.
    (00070000); unknown mech-code 0 for mech 1 2 840 113554 1 2 2 (00000000) 
UNIX® — Speed Up Spawning Jobs

When spawning a child process to add a job, files open in the parent need to be closed. In this version, more efficient means are used to do his on Linux, HP-UX and AIX. For situations where many files are open and lots of jobs are spawned, managing the open files can be up to an order of magnitude faster.

OpenVMS — Update Xerces And Xalan For OpenVMS

In this release, the XERCES and XALAN utilities have been upgraded to versions 3.1.1 and 1.11 respectively.

Non-OpenVMS Systems — Large Journal Writes

In this version, the maximum size of a journal write has been increased to 4MB. Measurements indicate this speeds up journaling by a factor of 2 for a streams load on non-SAN disks producing 1.5GB of journal.


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.

Naming Conventions For Globals

Beginning with version 2012.1, InterSystems reserves for itself global names that meet the following criteria:

  • In user databases, all names starting with “^ISC.”.

  • In CACHETEMP, all names beginning with “^CACHETEMP.ISC.”.

  • For process-private globals, all name starting with “^||ISC.”.

Routine Compiler Changes

Check For Too Many Arguments In A Multiple SET

A SET command that sets multiple variables to the same value could overflow the argument stack and cause unpredictable errors. The compiler will now correctly count the number of argument stack entries that the command will use and give a compile error if there are more than 255.

Routine Changes

Error Stack Now Initialized For Each Error

Prior to this release, the error stack information persisted until $ECODE was set to the null string. This means that it could contain levels for an older error that happened at a deeper stack level, mixed with levels of a newer error that happened at a less deep level. This made it difficult to interpret the stack display for the newer error.

Beginning with 2012.1, any existing error stack information will be cleared when a new error happens, and the new error stack will contain only entries that show the state at the time of the current error.

This change should make error analysis code simpler and avoid confusion that could happen with the previous arrangement. Existing code should not have to change unless it has special provisions to try to compensate for the previous behavior.

Charset Is Now In %RO Export And Used On Import

The %RO export utility and Export^%apiRTN will now insert into the routine header the charset the routine was output as. On import, from either %RI or Import^%apiRTN, this charset information will be used to ensure that the routine imported is identical to the one exported. If the importing system does not have the required translate table, it will report a suitable error message stating this.

If the files to be imported does not have the charset information (for example, because it was createdon an earlier release), the behavior will be the same as in prior releases.

Routine Compilation Now Uses Multiple Jobs

A call to ^%RCOMPIL, ##class(%Routine).CompileAll, Compile^%R to compile some routines will now spread the work across multiple CPUs when possible. The behavior of the compilation should be identical except for the improved speed.

The previous behavior, compilation only within the current job, can be restored by executing

Set ^%SYS("Compile","MultiCompile") = 0


When using multicompile, the worker jobs started may run under a different userid than that of the process that initiated the top-level compile. The userid depends on the platform.

  • On Windows, the sub-processes run under the userid set for the Caché server.

  • On UNIX® platforms, the userid of the initiating process is used for the sub-process.

  • OpenVMS, like UNIX®, runs the sub-process under the userid of the process that started it.

This means that if you wish to use multicompile, you must make sure that the files used in the compilation sources and any include files) have permissions that make them accessible to the sub-process doing the lower-level compiles.


If the class compiler is invoked from within a transaction, the multiple-compilation flag will be ignored because the worker jobs would not be in the same transaction as the master process, and if the user tried to roll back the compile it would only roll back whatever the master process had done leaving the classes in an inconsistent state.

Changes To %Routine Read/Write Behavior

In prior releases, if you used %RoutineOpens in a new tab to write n lines of a routine, and then read them back in using the ReadLine method, the AtEnd property would not be set true until you attempted to read line n+1. This is changed in this release to set AtEnd true when the last line is read.

Class Changes

Class Deletions

The following classes were present in version 2011.1 and have been removed in this version:

  • %Compiler.LG — EJBRoot

  • %Library.EIVX

  • %Library.EIVXBench

  • %Library.EIVXBenchNew

  • %Library.EIVXBenchNewNew

  • %Library.EIVXBenchOld

  • %Library.EIVXBrowser

  • %Library.EIVXDemo

  • %Library.EIVXRecreate

  • %Library.EIVXSAXHandler

  • %Library.EIVXUnitTest

  • %Library.EIVXxmlDOM

  • %Projection — EJB, EJBFlexible, EJBJBoss, EJBPramati, EJBWebLogic

  • %template — soapclientwizard, soapclientwizardns, soapclientwizardout, soapclientwizardpreview, xmlschemawizard, xmlschemawizardclasses, xmlschemawizardns, xmlschemawizardout, xmlschemawizardpreview

  • EMS.UI.Component — emsCheckbox, emsDropLabel, emsListBox, emsTagRemoveButton

  • Ens.Enterprise — Portal.LogTablePane, MsgContentsPane, Portal.MsgPane, MsgTablePane, Portal.MsgTraceFilterPane, Portal.MsgTracePane, Portal.MsgTraceSVG

Class Component Deletions

The following class components have been moved or removed in this version from the class where they were previously found.

Class Type Name(s)
%CPT.CalloutCommon Method GetConfig, GetConfigFrom
%CPT.CalloutShell Method ClearConfigScope, ConfigScopes, SetConfigScope, ShowConfigScope
%CPT.HPT.LoadingState Method GetFirstMatchFor
%CPT.HPT.Reader Method GetFirstMatchFor
%CPT.Regen.RegenerateSource Method FirstGloss, Gloss, NextGloss, WriteGloss, WriteLineToOutput, WriteSpaceIfNeeded, WriteToOutput
%CPT.Regen.RegenerateSource Property LastWrittenChar, OutputStream, WriteSpaceNext
%CSP.Daemon Method purgeZombies
%CSP.UI.Portal.Config.SQLDataTypes Method editItem
%CSP.UI.Portal.EnsembleMonitor Parameter APPLICATION
%CSP.UI.Portal.SSLList Method editSetting
%Collection.Super Method oidDataId, orefDataId
%Dictionary.CompiledInstanceVar Property Slot
%IO.LibraryStream Method DeleteAttribute, GetAttribute, IsDefinedAttribute, NextAttribute, SetAttribute
%Library.Storage Method %SQLAfterDeleteTriggers, %SQLAfterInsertTriggers, %SQLAfterUpdateTriggers, %SQLBeforeDeleteTriggers, %SQLBeforeInsertTriggers, %SQLBeforeUpdateTriggers
%Monitor.Health.AbstractSensor Method %OnNew, Log
%Monitor.Health.AbstractSensor Property HealthQueue, Logfile
%Monitor.Health.Control Method BuildChart, Enabled, sendmsg
%Monitor.Health.Control Property MinSampleSize, PeriodDayTime, SavedReading, SavedReadingNo, WaitTime, trace
%Monitor.Health.HealthAlert Property StdDev, ValueList
%Monitor.Health.Period Index IDKEY
%Monitor.Health.Period Property DayMonth, DayWeek, PeriodID
%Monitor.Health.Period Query Periods
%Monitor.Health.SystemSensors Method GetDatabase, GetOldestTx
%Monitor.Health.SystemSensors Property Curtime, DBSizeI, MirrorB
%Monitor.System.Dashboard Property Interval
%SAML.Assertion Method Validate
%SOAP.Security.Header Property WSBodyLength, WSBodyPosition
%SOAP.Security.KeyIdentifier Method Validate
%SOAP.Security.Policy Property encryptedBody
%SOAP.Security.Reference Method Validate
%SOAP.Security.SecurityTokenReference Method Validate
%SYS.Journal.Record Method GetRealPIDSYSinFilter
%SYS.NLS.Record Method InpRelacedGet, InpRelacedSet, OutRelacedGet, OutRelacedSet
%Stream.GblChrCompress Method Flush, OutputToDevice, ReadIntoBuffer, Write
%Stream.GlobalCharacterSearchable Method %SaveData, ReadIntoBuffer
%Stream.GlobalCharacter Property TempNode
%Studio.Project Method ItemCountSet
%Studio.Project Property ItemCount
%XML.Security.EncryptedData Method InitializeForService
%XML.Security.EncryptedData Property ElementId
%XML.Security.EncryptedKey Method IsBodyEncryptedGet, SetEncryptionMethod
%XML.Security.EncryptedKey Property IsBodyEncrypted, X509Credentials
%XML.Security.EncryptedType Property EncryptionOptions
%XML.Security.KeyInfoClause Method Validate
%XML.Security.KeyInfo Method Validate
%XML.Security.KeyValue Method Validate
%XML.Security.RSAKeyValue Method Validate
%XML.Security.ReferenceList Property IsBodyEncrypted
%XML.Security.Signature Method XMLBeforeExport
%XML.Security.Signature Property Length, Position
%XML.Security.X509Certificate Method Validate
%XML.Security.X509DataElement Method Validate
%XML.Security.X509Data Method Validate
%XML.Security.X509IssuerSerial Method Validate
%XML.Security.X509SKI Method Validate
%XML.Security.X509SubjectName Method Validate
%ZEN.Dialog.finderDialog Method ondialogFinish
%ZEN.Portal.selector Method GetDropdownContent
Config.config Property Wdstrategy, WdstrategyPresent
Ens.BPL.UI.BPLDocument Method Delete, GetClassName, GetEditorURL, GetOther, HasExtension, ListClose, ListExecute, ListFetch, Load, TimeStamp
Ens.BPL.UI.BPLDocument Parameter DOMAIN
Ens.BPL.UI.BPLDocument Query List
Ens.Config.Production Method getRoutingRuleDelegates
Ens.Config.Production Method getRoutingRuleTransformations
Ens.DTL.UI.DTLDocument Parameter DOMAIN
Ens.Enterprise.Portal.MonitorStatus Method DrawTitle
Ens.Enterprise.Portal.MonitorStatus Method GetQuickLinks
Ens.Enterprise.Portal.MonitorStatus Parameter APPLICATION
Ens.Enterprise.Portal.MonitorStatus Parameter DOMAIN
Ens.Enterprise.Portal.MsgBankEventLog Method BreakUpDescriptionText, BreakUpStackText, CreateDataSet, DrawLocalType, GetAndUseDefaults, GetWhereClause, GiveAdviceString, SaveDefaults, changeRefresh, countReset, enterKey, expandoState, formReset, onAfterPageChange, onSearchHandler, onSelectItem, showTrace, timeout
Ens.Enterprise.Portal.MsgBankEventLog Property detailsWidth, pageNumberId, pageSizeId, resultsTableId
Ens.Enterprise.Portal.MsgBankViewer Method BreakUpDescriptionText, BreakUpStackText, CreateDataSet, DrawLocalType, GetAndUseDefaults, GetColumnsAndFrom, GetWhereClause, GiveAdviceString, SaveDefaults, changeRefresh, expandoState, formReset, onAfterPageChange, onSearchHandler, onSelectItem, timeout
Ens.Enterprise.Portal.MsgBankViewer Property detailsWidth, pageNumberId, pageSizeId, resultsTableId
Ens.Enterprise.Portal.SystemList Method DrawTitle, GetQuickLinks
Ens.Enterprise.Portal.SystemList Parameter APPLICATION, DOMAIN
Ens.VDoc.SearchTable Method BuildIndex, GetExtentSuperclass, IsASub, RemoveIndex, SearchHeader
Ens.VDoc.SearchTable Parameter DOCCLASS
SYS.Mirror Method ActivatedMirroredDatabase
Method Return Changes

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

  • %IO.LibraryStream — ReadLineIntoStream

  • %Monitor.Health.Control — ClearConfig

  • %Net.POP3 — WalkParts

  • %SOAP.MsgDescriptor — InvokeService

  • %SOAP.Policy — WriteOneAlternative

  • %SOAP.Security.Policy — ApplySendAlternative, ApplySupportingTokens, SignEncryptParts

  • %ZEN.Portal.standardPage — DoLogout

Method Signature Changes

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

Class Name Method Name(s)
%CPT.HPT.ParseNode WriteAnnotation
%CPT.Regen.RegenerateSource %OnNew
%CPT.Tree.Pair RegenSource
%CSP.Session endSession
%CSP.UI.Portal.Config.Devices editItem
%CSP.UI.Portal.Config.ZenReport SaveData
%CSP.UI.Portal.X509Credential SaveData
%DeepSee.Component.pivotTable selectCellRange
%DeepSee.Query.query %RewriteForCurrentMember, setFunction
%DeepSee.ResultSet %GetFiltersForCellRange, %GetOrdinalLabel
%DeepSee.Utils GetMemberTree
%IO.FileStream reopen
%IO.LibraryStream %OnNew
%Installer.Installer CSPApplication
%Library.ClassDefinition ClassInfoExecute
%Library.EnsembleMgr createPortal, createPortalApp, loadMessages
%Library.File NormalizeDirectory, Read
%Library.RegisteredObject %OnValidateObject
%Library.SyntaxColorReader %OnNew, FromCode
%Monitor.Health.Chart %OnNew
%Monitor.Health.Control CheckAllSensors, ClearCharts
%Monitor.Health.Period %OnNew
%Net.SSH.SFTP Get, Put
%SOAP.Addressing.Properties GetDefaultResponseProperties
%SOAP.Security.Header AddToken, Perform
%SOAP.Security.Policy AddSupportingTokens, AnalyzeSamlToken, AnalyzeToken, AnalyzeX509Token, ApplySupportingTokens, GetTokenType, ValidateAsymmetric, ValidateEncryption, ValidateTokenReference, WriteAlternative
%SOAP.WebBase LogOutput, ProcessSOAPEnvelope
%SOAP.WebService InvokeMsgClass, WSAddSignatureConfirmation
%SQL.DynamicStatement referencedObjects
%SYS.Journal.System GetAlternateDirectory, GetPrimaryDirectory
%SYS.PTools.SQLQuery NewQuery
%SYS.ZENReportServer %ServeTransform
%SYSTEM.OBJ GetDependencies
%SYSTEM.Security.Users SSLPeekClientHello
%Standards.AU.eHealth.HI.SignatureContainerType Perform
%Studio.SourceControl.ISC P4Cmd
%XML.Security.EncryptedData ComputeCipherData, Create, CreateFromEncryptedKey, Encrypt
%XML.Security.EncryptedKey AddReference, CreateX509, Perform
%XML.Security.EncryptedType InitializeKey
%XML.Security.ReferenceList InitializeForService, Perform
%XML.Security.Signature AddReference, ComputeSha1Digest, InitializeValue
%XML.Writer CanonicalTree, CanonicalTreeInternal, Canonicalize
%ZEN.Component.abstractPage onServerMethodError
%ZEN.Report.reportPage %PerformTransform
%cspapp.sec.utilsysapplication SaveConfig
Ens.BPL.Transform isProperty
Ens.BPL.UI.BPLDocument SaveBPLClass
Ens.BusinessService CallProcessInputAsync, CheckProcessInputAsyncStatus
Ens.Config.Item GetBusinessType
Ens.Enterprise.MsgBank.TCPService OnProcessInput
Ens.Enterprise.MsgBankOperation exportEvents
Ens.Enterprise.Portal.MonitorStatus GetLocator
Ens.Enterprise.Portal.MsgBankViewer showTrace
Ens.ScheduleHandler ValidateScheduleSpec
Ens.Util.LookupTable %Import
Ens.Util.XML.Reader ChangeXMLStreamEncoding
SYS.Database CreateDatabase, Defragment, PackZU27Error
Security.Events Start
Security.Services StartStopTerminalDaemon
Server-Only Classes

The following classes have been marked in this release as server-only:

  • %MV.Adaptor.xml

  • %MV.EnumClass.xml

  • %MV.File.xml

  • %MV.PropertyParameters.xml

  • %MV.SelectList.xml

  • %MV.StudioRoutines.xml

  • %MV.Verbs.xml

New $SYSTEM.Bit Class

This releases adds a new class, $SYSTEM.Bit with two entry points:

  • StringToBit(str) converts a string of bits into a $BIT format bitstring.

  • ZBitToBit(str) converts a legacy DTM-style $ZBIT* string into a $BIT format bitstring.

These methods will give an <ILLEGAL VALUE> error if the argument cannot be converted into a valid $BIT string.

Changes To Platform Names

The platform names returned by $System.License.KeyPlatform() have been modified to provide consistent format. They are:

Value Old Name New Name
0 XXX Invalid Platform ID
19 HP RISC/32-bit PA-RISC-32(HP UX)
28 Alpha (OpenVMS) Alpha(OpenVMS)
29 Alpha (UNIX) Alpha(UNIX)
30 Solaris/SPARC SPARC-32(Solaris)
32 Intel (Windows NT) X86-32(Windows)
36 Linux/Intel X86-32(Linux)
37 IBM PowerPC/32-bit p-32(AIX)
40 Alpha (Open VMS - DSM) Alpha (Open VMS - DSM)
41 VAX (Open VMS - DSM) VAX (Open VMS - DSM)
44 Cache PC X86-32/64(Linux, OS X, Windows)
45 Solaris (UltraSPARC) UltraSPARC(Solaris)
46 HP RISC/64-bit PA-RISC-64(HP UX)
47 Heterogeneous Heterogeneous
48 IBM PowerPC/64-bit p-64(AIX)
49 HP-UX/Itanium Itanium(HP UX)
52 Linux/x86-64 X86-64(Linux)
53 VMS/Itanium Itanium(OpenVMS)
55 Win64/x86-64 X86-64(Windows)
57 Solaris/x86-64 X86-64(Solaris)
58 Mac OS X/x86-64 X86-64(OS X)
59 (new) ARM(Android)

All other values are either obsolete or unused.

ExportToStream Now Uses Raw File I/O

When an application calls $SYSTEM.OBJ.ExportToStream, Caché exports the items to a file and then construcst a file stream pointing to the file so the caller has the data in a stream. In previous releases, the file stream used was a %FileCharacterStreamOpens in a new tab. This meant the default file character IO table would be in effect when reading the stream back in which, in some circumstances, would corrupt the data in the file. Beginning with this release, Caché uses %FileBinaryStreamOpens in a new tab which will preserve the original format of the data.

%Open OREF Checking Improved

In previous releases, if there were two separate subclasses of %Library.PersistentOpens in a new tab, ClassA and ClassB, with object IDs OIDA and OIDB, respectively, the following statements would execute without error

Set InstanceB = ##class(ClassA).%Open(OIDB)
Set InstanceA = ##class(ClassB).%Open(OIDA)

In this release, %Open now checks that the OID matches the class doing the open. In instances where the exact subclass is unknown, developers should use the closest, common superclass, for example:

Set InstanceB = ##class(%Library.Persistent).%Open(OIDB)
Config.Databases:List Query Changed To Split Out Mirrored Database Info

The Config.Databases:List query has been updated so it no longer generates SYSLOG entries every time it is executed. Config.Databases:List query no longer returns the Mirrored flag nor the MirrorStatus field which indicated whether the database is active or not in the current mirror. A new Config.Databases:MirrorDatabasesList query has been added which returns information about local mirrored databases in the configuration file.

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.

Removed The s System Flag

This release removes the use of the “s” system flag for filtering lists of classes in functions like CompileAll. The functions that return lists of classes that were previously using the “s” system filter will now return classes whether the class has the “system” keyword or not.

This resolves a problem where some customers used the class “system” keyword in order to define the compile order of the classes. Then when they tried to compile their classes, none of the classes with “system” defined were compiled because the compile request did not have the “s” flag. Now all classes will be included regardless of whether the class has the system keyword.

Improvements To Class Dependency Recognition

The class compiler sorts the list of classes to compile into two main types: hard dependencies where one class needs another class to be fully compiled and runnable in order for it to compile (indicated by the keyword DependsOn); and soft dependencies where the other class needs to be compiled as part of the same set, but it does not need to be runnable (such as superclasses).

The dependency resolution code first sorts out the hard dependencies. Then it resolves the soft dependencies in each group. The resolution of these hard dependencies requires that we bring over any soft dependencies into the same group. For example if class A DependsOn class B, then class B must be compiled earlier than class A. However, if class B has superclass C, then C must also go into this earlier group too, otherwise Caché cannot compile B.

The code that resolves the hard dependencies now also recursively checks each item's soft dependencies to ensure that none of these soft dependencies have a hard dependency before it inserts the item into the proper order. Under some rare circumstances, it is possible this change could result in some classes which appeared to compile cleanly in prior releases reporting a compile dependency error. If this occurs, it is because there is a real dependency cycle, but the previous version of the code was not detecting this correctly.

Resolution Of Ambiguous References

In the case where a multidimensional property and a method share the same name, for example,

Class Objects.Test Extends %Persistent
   Property Uncertain As %String [ MultiDimensional ];

   Method Uncertain(a As %String, b As %String) As %String
        Quit "Uncertain Method Return"

the ambiguity of the expression “Uncertain(foo, bar)” will depend on context. When the expression is the receiver of a value (left of the equal sign), it will be treated as a multidimensional value, that is, the statements

Set obj = ##class(Objects.Test).%New()
Set obj.Uncertain("A", "B") = "Some string"
Write obj.Uncertain("A", "B")

will store the value “Some string” in the multidimensional array Uncertain of the instance referenced by obj.

But when it is the supplier of a value (right of the equals), the same reference will be resolved to the method. Thus, in the example given, the value, “Uncertain Method Return”, will be written to the output device.


Though a questionable programming practice because of the ambiguity in usage, the class compiler will not report this as an error.

Re-Enable Checking For Instance References In ClassMethods

If an application makes a reference to a local method, such as,

Write ..Method()

the class compiler checks that this method exists, and that it is invoked from an instance method, not a classmethod. Similar checks are done for properties. Due to an error in version 2011.1, this checking was disabled. It is now operational again, with the effect that some classes that (incorrectly) compiled successfully in 2011.1 will now fail to compile in this version.

Language Binding Changes

Omit Trailing Zeroes In Timestamp Fractional Seconds For Light C++ Binding

The Light C++ Binding no longer stores trailing “0” digits in the fractional seconds component of fields of type, d_timestamp. Furthermore, if the value of the fractional seconds component of a timestamp is zero, then the “.” separating seconds from fractional seconds is also not stored. This corrects a problem in which timestamps stored by the Light C++ Binding could not be correctly compared to timestamp constants in SQL.

Rework MDS API To Use A More Java-Friendly Style

The MDS API has been substantially reworked in preparation for making it visible as a primary API for the Globals product. The primary motivations for this are: to reintroduce visibility of the term and concept "global"; to make the style more in line with the expectations of the Java community; to simplify/clarify the interface; and to add ease-of-use enhancements. The MDS API was released in Cache 2010.1, but was used internally in the implementation of XEP, the interface employed by customers.

Refer to the Javadoc in the com.intersys.globals package for detailed documentation of all classes and methods.

Globals API In Caché

With this release, several related areas of functionality in the Globals API not supported in GlobalsDB are made available when used in Caché:

  • Thread-specific connections; these are in addition to the default non-thread-specific connections which are the only type supported in GlobalsDB.

  • The Globals API and other eXTreme APIs (XDO, eXTreme JDBC) ensure that they do not open incompatible connection types (thread-specific for one API, non-thread-specific for the other) when both APIs are used in the same application in Caché.

  • The underlying JNI code throws the correct exception types based on which API it was called from, even when calls to different APIs are interspersed in the same application.

This means that functionality present in MDS (the deprecated precursor of the Globals API) is provided in a manner that maintains independence of Globals packages from other eXTreme packages. This in turn means that the same Globals code can ship independently of other eXTreme packages in globalsdb.jar in the Globals DB product.

Enterprise Java Bean (EJB) Projection No Longer Supported

With this release, support for the Enterprise Java Bean (EJB) has been removed from Caché.

The Python Binding Now Supports The %Decimal Type

This release corrects a oversight in the Python binding by introducing the %Decimal type. It is support for both Python 2.7 and Python 3.0. A decimal is introduced through the Python class intersys.pythonbind.decimal. The constructor is intersys.pythonbind.decimal(significand, exponent) and the value of the decimal is significand * 10 ** exponent.

Unicode Is The Default Encoding For d_list

In previous releases, the datatype d_list used the thread locale by default. In certain cases, that resulted in loss of information when adding an element to the list. Now the default is Unicode, and no information is lost.

This change may make some $LIST elements become of type 2 (Unicode). this means that binary comparisons for entire lists may now give false negatives since the data is logically the same, but is stored differently, such as comparing $LISTBUILD("1") and $LISTBUILD(1).

Java Extreme XEP Changes

The ability to delete an entire extent via a Java method is a powerful tool, especially during the development and testing stages. It can also be extremely dangerous if used without caution. The three changes introduced by this release improves usability and decreases the possibility of abuse:

  1. OPTION_IMPORT with either of the OPTION_IMPORT_PRESERVE_EXTENT and OPTION_IMPORT_DELETE_EXTENT qualifier has been removed. This means it is no longer possible to delete parts of the schema during the schema import process. Calling get/setOption(OPTION_IMPORT) will result in an exception. Schemas will be preserved by default, as long as the object model has not changed. If necessary, extents should be deleted using the newly added EventPersister.deleteExtent method (see next item).

  2. There is a new method in the EventPersister class that is the preferred way to delete an entire schema. It has the declaration

    void deleteExtent(String eventName) throws XEPException
  3. The Event.deleteExtent method has been deprecated. Applications using it should be altered to call EventPersister.deleteExtent. Event.deleteExtent will be removed in a future release.

All the XEP examples have been changed to use this new approach.

SQL Changes

Support For Includes And Macros In CREATE PROC Statements

This release changes the behavior of the DDL CREATE PROCEDURE, CREATE FUNCTION, CREATE METHOD, CREATE QUERY, and CREATE TRIGGER statements when compiled as embedded SQL statements or prepared as dynamic statements. This change is not fully backward-compatible and may require modifications to applications, especially when code bodies of type ObjectScript are used in the CREATE statement.

Consider the following statement:

        #define Square(%val) %val*%val
        QUIT $$$Square(value)

Prior to this change the #if, #define and $$$Square macro references would be expanded and processed when the CREATE PROCEDURE STATEMENT was compiled. After this change, the processing and expansion will be included in the procedure's method definition, and get processed and expanded when the METHOD is compiled.

Multi-Index Optimization Now Uses Indexes For All Efficient Equality Conditions

If a query has several equality conditions with good indexes on the same table, they will now always be used if that table is chosen as the first to process. Previously, if one or two provided “good enough” selectivity, additional indexes might be ignored.

Some query features may override this behavior. For example, for an ORDER BY, DISTINCT, or GROUP BY query, the benefit of indexes assisting these operations will be compared to the multi-index strategy, and may supersede it. Similarly, since TOP optimizes for time to first row, it may also override this new default behavior. Finally, producing rows in order to improve performance on a later join may also cause a different query strategy to win.

Changes In Storage Methods Associated With SQLStorage

Internal methods generated by the compiler for classes that use Caché SQLStorage were not properly NEWing some %-variables used by SQL code. These methods will now NEW %msg, %ok, and %ROWCOUNT; %ROWID and SQLCODE were being properly NEWed.

Applications that make use of the fact that these variables were getting “left behind” will have to be changed.

Trigger Definition Enhancements

Changes have been made to SQL triggers to make {field} references perform better now that Caché supports trigger events of multiple types. The code generated by a trigger will now only be emitted one time, even if the trigger had more than one event. In order to make this change possible, the rules regarding the behavior of {Field*Flag} references are now as follows:

  • {Field}:

    • For INSERT, resolves to the value inserted for the column.

    • For DELETE, resolves to the on-disk, pre-delete value for the column.

    • For UPDATE, resolves to the new value the column is being updated to.

  • {Field*N}:

    • For INSERT, resolves to the value inserted for the column.

    • For DELETE, resolves to the on-disk value for the column from the row being deleted.

    • For UPDATE, resolves to the new value being updated for the column in this row.

  • {Field*O}:

    • For INSERT, resolves to NULL. This is new behavior.

    • For DELETE, resolves to the on-disk value for the column from the row being deleted.

    • For UPDATE, resolves to the old value for the column being updated.

  • {Field*C}:

    • For INSERT, TRUE if the inserted value is non-NULL, otherwise FALSE. This is new behavior.

    • For DELETE, TRUE if the value being deleted is non-NULL, otherwise FALSE. This is new behavior.

    • For UPDATE, TRUE if the new value differs from the old/on-disk value, otherwise FALSE.

Furthermore, the following also applies to Trigger code: Triggers may contain line labels. However, the trigger code is generated outside the scope of any procedure blocks. This means the label must be unique in the class definition. Any other code compiled into the class must not have the same label defined, including code in other triggers, non-procedureblock methods, SqlCompute code, and so on.


The Caché TSQL compiler now supports the UPDATE STATISTICS statement; it generates a call to $SYSTEM.SQL.TuneTable() for the it. This statement is also supported as a dynamic statement.

Change Processing Of Non-%ObjectSelectMode Select Statements

The result of executing a dynamic SQL statement is a result object. This result object may be a simple result (indicating success or failure), a result set object, or a procedure result object. If the statement was prepared with %ObjectSelectMode = 1, the result set columns can be automatically swizzled when referencing the row type properties if the type of the column corresponding to the property is a swizzleable type. For example,

SELECT Spouse from Sample.Person where Spouse IS NOT NULL

If that statement were prepared as a dynamic SQL statement with %ObjectSelectMode = 1, retrieving the <resultORef>Spouse property will trigger swizzling and an oref will be returned. However, if %ObjectSelectMode is 0 then the property will be returned as a simple ID value.

For streams, SQL will return a fully qualified Stream OID (SOID) value. This is true for embedded SQL and dynamic SQL when %ObjectSelectMode is 0. The fully qualified SOID value can be swizzled manually using ##class(%Stream.Object).%Open(<SOID>). Stream columns selected by executing a dynamic SQL statement prepared with %ObjectSelectMode = 1 will automatically swizzle.

An error in dynamic SQL caused stream columns to automatically swizzle when %ObjectSelectMode was not 1. This has now been fixed. Applications that took advantage of this behavior will have to change their processing to use %OBJECT(streamcol) or to manually swizzle the stream SOID using %StreamObject.%Open.

Dynamic SQL %Print Changes

The %Print utility method implemented for result sets will now quote the output value if the value contains a line feed. Before this, the value would only be quoted if the value contained the delimiter character.

Changes To SQL DECODE Statement

A change has been made to the SQL DECODE function. Prior to this change, DECODE returned the same type as the first return argument in the DECODE function call. It has been changed in this release to return the most compatible type of all the potential return values from the function.

Consider the following function call:

DECODE(999, ' ', 1, 0.7)

Caché considered the return type of this to be INTEGER. When .7 was returned as the value through the xDBC driver, it was truncated to 0 because the type was supposed to be INTEGER. (By contrast, Oracle does not consider the value 1 to be an INTEGER, but rather FLOAT(38) which allows the .7 to be returned to the client intact.)

Now, the possible return values in the function call above are 1 and .7, so in this case the function would return NUMERIC(1,1) The following data types are compatible and are specified in order of precedence (highest to lowest): VARCHAR, DOUBLE, NUMERIC, BIGINT, INTEGER, SMALLINT, TINYINT. A DECODE function call that could return a NUMERIC, INTEGER, or TINYINT; the return type will be NUMERIC because it has the highest precedence of the three types. Due to the type given to literal replaced arguments in xDBC queries, if the above function was included in an xDBC query column, the type reported would be NUMERIC(18,9).

Host Variables Disallowed In The View Of A Query

Host Variables have never been allowed in the query of a view. Their attempted use sometimes caused unexpected and non-descriptive errors like, SQLCODE = -51, when attempting to compile these statements. If you attempt to reference a host variable in a view's query, or in a CREATE VIEW or ALTER VIEW statement, you will now get an SQLCODE = -148 and an appropriate error message in %msg.


A problem has been corrected with the TSQL SET ROWCOUNT feature. If any application relies on the current behavior of ROWCOUNT in Caché TSQL, it will have to be modified.

For TSQL code such as:

ClassMethod RowCountTest() As %Integer [ Language = tsql, 
                                         SqlName = RowCountTest, 
                                         SqlProc ] 
    set ROWCOUNT 1 
    select * from Cinema.Film 
    set ROWCOUNT 0 

In previous releases, the result set returned by executing the procedure would return all the rows. Now it returns only the first one.


The deprecated keyword %IGNOREINDICES now gives a syntax error if the index name given is non-existent. Since %IGNOREINDICES is deprecated, all occurences should be changed to %IGNOREINDEX.

CSP Changes

Improved HyperEvent Error Processing

Developers making use of the OnErrorSetup() method of %CSP.LoginOpens in a new tab to handle issues with hyperevent requests should note that hyperevents error handling is now performed by the CSP server, and they should make use of the client-side error processing if they wish to take action based on these error conditions. Errors which occur during HyperEvents now capture more information about the cause of the error and allow users the ability of making more informed decisions about actions they should take at an application level.

This release introduces a new Javascript object of type cspHyperEventError which has the following properties with the listed values:

  • code: corresponds to an HTTP response code OR a response code from the XMLHttpRequest object in use. XMLHttpRequest codes may be browser-specific.

  • text: a free text field which corresponds to the current text returned to the cspRunServerMethodError() callback function.

  • serverCode: corresponds to the error number on the server, if available. This value may be null.

  • serverText: the error message from the server, if available. This value defaults to the empty string, that is “”.

  • exception: an exception which triggered the error. This value may be null.

  • arguments: the list of arguments to the function where an exception was trapped. This value may be null and will only be populated if exception is defined.

When an error occurs during a HyperEvent call, including server-side exceptions to Zen methods, the new cspHyperEventErrorHandler() function in cspxmlhttp.js will check whether the user has defined the cspRunServerMethodError() callback for handling hyperevent errors. If so, cspRunServerMethodError() will be called with an additional argument containing a cspHyperEventError object. If the cspRunServerMethodError() function has not been defined for the page, the default error handling function will log an alert as it always has.

The behavior for Zen is slightly different. Zen always defines the cspRunServerMethodError() callback. Zen uses the onServerMethodError() callback function inherited from %ZEN.Component.abstractPageOpens in a new tab to allow users the option of handling hyperevent errors. This callback function will also be supplied a second argument containing the enhanced cspHyperEventError object so Zen developers can actively control how hyperevent errors should be handled. Server-side exceptions and errors will now be reported as hyperevent errors and will be reported as HTTP 500 responses. Those being triggered by status errors will include the server-side error code and text. If the onServerMethodError() callback is not implemented, the Zen code will check whether the error indicates the user has been logged out and could not be logged in automatically - this check is based on an HTTP code of 401 and a server code of 864. If this is the case, the Zen framework will trigger a page refresh using the following Javascript:


This will present the user with the login page specified for the current CSP application; the user will not be able to perform any further activities without logging in again. If applications have implemented the onServerMethodError() callback, they should take note that a return value of false from this method will still check for whether the page should be refreshed. An undefined return value or a return value of true will bypass any further Zen processing of the error. Note that many more Zen errors from the server will now be reported through these callbacks, and application developers should be aware of the increase in errors reported this way.

As an extension of these changes, the CSP server will no longer attempt to redirect requests for %CSP.BrokerOpens in a new tab to a login page in situations where

  • previous authentication information (such as for a group-by-id CSP application group or a sticky context) is not available,

  • a username has not been supplied, and

  • unauthenticated access is not permitted for the current application.

This kind of situation is relatively common, and would occur when a session has expired and the hyperevent includes no authentication. If this does occur, then the CSP server will NOT redirect to the login page, but will report an HTTP 401 error to the client and supply a server code of 864 - authentication required. If a login is attempted for the HyperEvent (which is uncommon), the login failure will NOT be directed via the OnErrorSetup() method of the login page, but will be reported directly to the client as an HTTP 401 error with the error code encountered on the server.

Web Services Changes

Allow 200 As Valid Return Value

In prior releases, Caché accepted only 202 as a return from one-way operations. According to WS-I Basic Profile 1.1, it is perfectly OK to return 200 from one-way operations, so this is now allowed.

xDBC Changes

Change Handling Strings Containing NULs

In theory, data returned from Caché and reported as a SQL_VARCHAR and converted to SQL_C_CHAR would be null terminated, and would not contain internal null values. Caché strings, however, can contain NULs and this caused problems for an ODBC application that tries to perform SQLGetData on the value. Previous releases would reported the data truncated when Caché detected the NUL before the full length of the data. The ODBC application usually responded to the truncation error by trying to get the value over and over again, unsuccessfully, in a loop.

With this release, Caché converts and returns all the data to SQL_C_CHAR, even if it contains embedded $CHAR(0). While this is different from what you would expect for a normal null terminated C string, it is now left up to the ODBC application to decide how to deal with this corrupted data.

In the case of SQL_BINARY data, it will be converted to SQL_C_CHAR that contains $CHAR(0) characters and can be fully read and converted to multibyte values since Caché will not return falsely truncation errors that suggest a bigger buffer is needed.


This change affects string output data converted from Caché. Input strings in ODBC are generally null-terminated, and no change has been made to how they are handled.

Return Username On UNIX® And OpenVMS Platforms

In prior versions, Caché returned UID value of the user on UNIX® and OpenVMS for $USER. Beginning with this version, $USER returns the username.

MultiValue Changes

Corrections To SYSTEM(1001), SYSTEM(1051) And SYSTEM(1056) Functions

SYSTEM(1001) is now emulation dependent. For a program compiled with jBASE emulation, it returns the command line as an attribute delimited string. In all other emulations, it will return the emulation number that the program was compiled with (as it currently does).

SYSTEM(1051) continues to returns the emulation number that the program was compiled with as it has in previous releases.

SYSTEM(1056) is new and returns 4 attributes describing the emulation as follows:

  1. The emulation number that the program was compiled with.

  2. The emulation name that the program was compiled with.

  3. The emulation number that currently exists for the MV account.

  4. The emulation name that currently exists for the MV account.

Change R95 emulation name to POWER95

Any references to R95 as an emulation should be replaced with POWER95.

Support Unidata-style Global Catalog Verbs

Now, if the first word of an MV command starts with “*” and the current emulation is “UNIDATA” or “UDPICK”, then the “*” is removed and the global catalog is accessed for that verb.

Can Now Set Port Numbers For Phantom Processes

Starting with this version, phantom processes will now use the custom port number assigned in ^||%MVPortNo.

COPY.FILE Now Updates @ID

The destination of a COPY.FILE command will now have its @ID dict item updated to reflect the new filename.

MV Trigger Wrapper Name Changed

The MV trigger wrapper routine is now named by taking the name of the global that holds the data section of the file and prefixing it with “MVTW”.

Projected Storage Changes

Beginning with this release, an index on a collection in an MVENABLED class will now project as full; previously it had been marked as conditional. Furthermore, the child table projected from a list collection in an MVENABLED class will now include one empty row if the collection (multivalue) is null.

  • MVBasic Defaults For Missing Exponent Term

    The MultiValue BASIC PWRS(A,B) built-in function and the vector ** operator (same as the vector ^ operator) have been modified. If any component of the dynamic array B is missing, or is the empty string, then that component is treated as the value 1.


    This behavior is different from the DIVS(A,B) and MODS(A,B) built-in functions and the vector / operator. These vector operations treat a missing component in the second operand as a 1, but they treat a component containing the empty string as a 0.

  • DIVSZ Function Added To MVBASIC

    There is a new dynamic array function, DIVSZ, in MV BASIC. The DIVSZ function is identical to the DIVS function except that it does not generate an error when an a dynamic array component is divided by zero. If a component of the second operand of DIVSZ has the value 0 then the corresponding component of the result dynamic array will be 0.


    Applications that define a user-written routine or variable using the name DIVSZ will need to rename the routine or identifier.

  • MVB System Variables Not Allowed When Descriptor Is Required

    In MVBASIC, calling $DATA(@ME) or $GET(@ME) would cause the compiler to crash. Applying $DATA() and $GET() to any other system variable (for example, $DATA(@ACCOUNT)) would always return a result as if the system variable were undefined. System variables are not implemented as variables but are instead special cased and are usually implemented as expressions. They cannot used as arguments to functions or statements that require a variable (as opposed to requiring an expressions value.) The compiler now detects these situations and gives appropriate compile-time errors messages.


    It is still legal to write calls such as $DATA(@ME->Property) because a class property can usually be referenced anywhere a variable may be referenced.

  • Disallow Nested Dynamic Array References

    In previous releases, the MVBASIC compiler did not give a syntax error when the program contained a nested dynamic array reference such as VAR<i><k,j>. Trying to compile this illegal syntax would often lead to a crash of the MVBASIC compiler. If the compilation were successful, executing the program would give unpredictable results. This syntax is no longer accepted.

    Where the MVBASIC syntax requires a variable reference (such as a left-hand-side of an assignment, or the first operand of a READ statement), the variable reference can contain at most one dynamic array reference (E.g., A<i,j>) followed by at most one substring reference ( A<i,j>[s,l]). These rules were not enforced previously and variable references containing multiple dynamic array references and/or multiple substring references would often produce erroneous object code.

    It is permissible to use multiple dynamic array references and/or substring references when that variable was being evaluated as part of an expression, for example,

    LET X = A<I><1,J><1,1,K>[s1,l1][s2,l2]

    Previously, a sequence of more than two dynamic array references inside an expression evaluation may have produced a syntax error.

  • IFS() Function Corrected And REUSE() Allowed

    The function IFS(ifarray, array1, array2) takes 3 dynamic arrays as parameters and it returns a dynamic array result. The argument ifarray contains boolean values; the shape of the function result is identical to the shape of ifarray. Where ifarray contains a TRUE component, the corresponding component of the result is the corresponding component of array1. Where ifarray contains a FALSE component, the corresponding component of the result is the corresponding component of array2.

    If the selected component of array1 or array2 does not exist and REUSE() is not used on the selected argument, then the result component is the empty string. If the selected corresponding component of array1 or array2 does not exist but REUSE() is used on that argument, then the result component is the closest, existing array1 or array2 component preceding the missing component position.

    It is an error if REUSE() is applied to the first argument, ifarray.


    If an application calls IFS() using arrays with mismatched shapes, then there is the possibility the results will be different among different MultiValue vendors. The application may need to be altered to require that parameters to IFS() to be reshaped in order to get the desired and consistent behavior.


    The default behavior for short-circuit Boolean evaluation for Ultimate emulation is now


    Previously, it was


    The new behavior will not evaluate the B operand of A & B (A AND B) when the A operand evaluates to FALSE and it will not evaluate the B operand of A ! B (A OR B) when the A operand evaluates to TRUE.

  • MVB OPENSEQ Requires A TO Clause

    The OPENSEQ statement requires that there be a TO clause. This restriction is now correctly enforced.

Zen Changes

Improved HyperEvent Error Processing

Please refer to the changes detailed in the CSP HyperEvent section.

Add Flag To Selectively Enable Toggle Behavior In tablePane Row Select

A previous enhancement enabled the user to unselect the current row by clicking on it, making the row click option effectively a toggle and allowing the user to 'select nothing' without having to reload the page. This was a departure from the prior behavior where subsequent clicks on the selected row were ignored and the only way to clear the current selection was to either select something else or go through the API. This change adds the flag enableToggleSelect to tablePane, effectively making the previous enhancement optional. The default is to mimic the pre-2010.2 behavior in the name of backwards compatibility.

Existing early adopters of the newer behavior will need to add a enableToggleSelect="true" attribute to any tablePane tag where unselecting is desired.

Zen Reports Changes

PageHeaders In PDF Generation

In PDF generation, if a report with multiple sections contains a top-level pageheader, that pageheader will not appear in the output. For a different first page when using multiple sections, specify a masterreference with pagePosition="first". In addition, only a masterreference with pagePosition="any" will be included in the HTML output.

ActiveX Changes

Support For ITypeInfo In CObjInstance Removed

In prior versions, CObjInstance returned the default ATL ITypeInfo for the class. This was incorrect because the actual interface for CObjInstance is much more than what the default implementation returns. Removing it means that CacheActiveX clients will not make decisions based on erroneous meta- information for CObjInstance.

FeedbackOpens in a new tab