Skip to main content

Release and Upgrade Information for Caché 2013.1

This chapter provides the following information for Caché 2013.1:

New and Enhanced Features for Caché 2013.1

The following new features have been added to Caché for this 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 the “Caché 2013.1 Upgrade Checklist.”

Rapid Application Development

Support for %FIND in WHERE Conditions

With this release we implement a new SQL Condition with the following syntax:

<f> %FIND <x>  [ SIZE <const>]

<x> represents a set of values S used as a filter for <f>, or more precisely, the condition is satisfied if <f> is a member of S.

XEP Enhancements

This version of Caché contains the following improvements and extensions to XEP:

  • It has expanded support for inheritance, references, interfaces, and synchronous indexing.

  • It supports simpler options for persistence modes.

  • XEP now has two types: XEP TCP/IP and XEP JNI.

  • A new @Id annotation for both Java & .NET allows a field to be a database ID.

  • New mechanisms are available for calling Cache Object Script class methods.

  • XEP now has support for calling ObjectScript functions, procedures with multiple arguments, and return types.

  • Performance improvements have been made to array-based data inserts

  • There is a new parallel storage API to maximize multicore machine capabilities, and further increase performance of inserts.

  • InterSystems enhanced JDBC-based queries to replace previous custom query functionality.

  • XEP now has enhancements that reduce the amount of JNI usage across platforms.

JDK 1.7

This release now includes the Java 7 libraries as well as those for Java 6. In addition, Caché now supports JDBC 4.1.

GLOBALS Enhancements

The version of GLOBALS $query is now supported for both Java and .NET APIs. The Globals ValueList now support decimal values. Globals methods can now call Cache Object Script function, procedures with multiple arguments and return types; and Globals methods can now call Cache Object Script class methods. Support for Visual Basic is now available along with a sample that demonstrates its use.

RETURN Statement

The RETURN statement is now available for application developers to optimize code execution and readability. Its definition is analogous to the QUIT statement, but it returns from an enclosing subroutine to its caller.

Support Arguments By Reference With Args...

The args... syntax for receiving and passing a variable number of arguments can now be used when passing an argument by reference.

Websocket Support

The CSP Gateway now includes support for the HTML 5 specification for Web Socket connections between the web server and an HTML 5 compliant browser. This is available for Apache 2.2 and above, and will be available for IIS 8.0 which is part of Windows Server 2012.

There is a base class that must be extended by the user to handle / create WebSockets called %CSP.WebSocket

Improved FrameStack Handling

<FRAMESTACK> errors can now be handled in error traps. Caché will no longer remove items from the execution stack before calling an error trap.

Third-Party Library Upgrades

In this release, ANTLR has been upgraded to version 3.4; Xerces has been updated to version 3.1.1 on UNIX®.

Studio Assist For MVB

Studio assist now recognizes the following syntax elements:

  • Caché Basic: "ClassName".ME.

  • MVBasic: "ClassName"->@ME->

Caché Basic: "ClassName".ME. MV BASIC: "ClassName"->@ME->

XML Support For List of Streams

A list of streams will be projected correctly to XML. A list of streams may be specified by either using 'list Of' syntax or creating class which is a sublcass of %ListOfObjectsOpens in a new tab with ELEMENTTYPE specifying a streamclass.

JSON Improvements

InterSystems made a major enhancements to our public JSON APIs. We now have non-internal function calls that can generate JSON strings from objects, arrays, or SQL statements. These can be subsequently be used to drive a third party client interface that supports JSON as a data transport mechanism. In addition to converting internal structures to JSON, we also support taking JSON sent by the client and converting it into a COS array that can then be consumed within an application.

DeepSee Improvements

DeepSee includes a new editor for creating and editing dashboards. The new dashboard editor takes advantage of improved ZEN charts and other new ZEN components. To edit a dashboard, you click on the bar along the left side of the dashboard. The new dashboard editor provides many more options for controlling the display of charts and tables.

The DeepSee User Portal also includes a new "Covers" view option which displays items on the home page as images. The new covers editor allows you to configure the covers (images, text, colors, etc.). Also, the types of items listed on the User Portal home page now include reports and URL links (in addition to dashboards and pivots).

Performance And Scalability

XML Performance

Performance for XML has been improved by improving the handling of XML between Caché and Xerces. Customers may see improvements of up to 50% for %XML.ReaderOpens in a new tab imports, and up to 25% with SOAP messages.

HTTP 1.1 Keep-Alive

This release of Caché adds support for Keep-Alive with HTTP 1.1. It enables clients to keep the TCP/IP socket to the web server active so that multiple requests can be made via the same socket rather than constantly closing the socket and opening a new one for each request.

Improved ROLLBACK Performance

In this release, ROLLBACK performance is roughly 10%-30% faster than in previous versions. This improvement applies to rolling back single (large) transactions, as well as bulk rollback (as would occur during startup recovery).

AES Encryption On Intel Hardware

Intel support AES-NI with their latest processors, which greatly improves encryption and decryption for AES. Early benchmarks have shown significant performance improvements over software execution of AES, which greatly minimizes the performance overhead for encrypted databases with high a high frequency of physical I/O.

Improved Async I/O Performance

This version includes improvements to asynchronous I/O that benefits sequential workloads. The new algorithm detects multiple sequential updates and performs larger coalesced writes, and has been measured to speed up sequential workload-related writes by a factor of 1.6 to 1.8.

Improved Encryption Performance

Previously, a performance feature called "parallel WIJ encryption" was enabled on the AIX platform. This feature has now been enabled on HP-UX, Linux, and Solaris, and can increase the speed of database encryption during write cycles by up to a factor of 4.

MultiCompile On By Default

Caché now uses MultiCompile for class compilation as a default, which will decrease compile time on multi-core processors.

Optimize Multi-Key Joins

This release removes some older case-specific functions used to optimize multi-column joins in favor of a more generic approach that results in much greater performance across all types of multi-column join statements.

Export/Import TuneTable Statistics

With this release, Caché SQL has added support for exported and importing TuneTable Statistics for a given namespace. This allows one to export TuneTable Data, Selectivity, and ExtentSize details from a given system and reload it without having to ship a class definition and compile it.

Improve Concurrent Update Performance

This version contains an optimization for concurrent updates on very large-scale systems. With this optimization, benchmarks have demonstrated 20% to 30% improvement in overall database access scalability.

Add Indices To A Class With Minimal Downtime

This version introduces a new feature, %Library.IndexBuilderOpens in a new tab. This class and its methods permits one or more indexes to be added to an existing class. It is specially designed to address the circumstances where:

  • the normal %BuildIndices method will take a long time because of the amount of data involved, and

  • the application is running on a system where downtime must be kept to a minimum.

Lock Escalation Improvements

This release introduces a new locking mode, “E”, whose goals are to automate lock management and provide better management of the lock table. In this mode, when the number of existing locks held by a transaction crosses a threshold, and Caché determines it is safe to do so, the lock will be “consolidated” as a higher level lock. The lower level locks will then be released thus freeing space in the lock table.

Reliability, Availability, Maintainability, Monitoring

Support Advanced Format (4K) Disk Drives

This version includes support for native 4KB disk sectors as implemented by Advanced Format (AF) disk drives.

TIFF Output In Zen Reports

Zen Reports now has the capability to create content in TIFF format in addition to our previously released formats such as HTML, XML, PDF, Excel, and so on.

Application Specific Licensing

Some Caché customers wish to license their own applications as a whole or in functional units. Among the challenges they facein doing so is the proper accounting for license units in the face of varying application workflow and abnormal terminations. In addition, some customers desire to link their licenses to the underlying system license provided by InterSystems.

With Application Specific Licensing, InterSystems provides mechanisms to support the customer need to create, deploy and use application licenses. InterSystems itself uses this form of licensing for its products HealthShare and TrakCare.

Very Large Global Buffer Size

This version includes support for a very large global buffer pool. Previously, the limit was around 107 GB; global buffers can now be configured up to 16 TB.

Large Shared Memory Heap

This version includes support for a very large shared memory heap. Previously, the limit was around 4GB; the shared memory heap can now be configured up to 1 TB.

Eliminate Configuration-Related Restarts

The following Caché configuration options can now be updated dynamically, and do not require the system to be restarted for the new setting to take effect:

  • MaxServers: Maximum number of connections to ECP servers from this (client) machine.

  • VMSConsoleTerminal: Name of the console terminal device for logging messages on an OpenVMS system.

  • netjob: Enable/disable remote job requests.

  • wijdir: Write Image Journal file directory.

  • console: Console log file name.

  • LineRecallBuffer: Total size (in bytes) of all input strings to be stored in the command line/read line buffer.

  • LineRecallEntries: Maximum number of entries held in the command line/read line recall buffer, subject to the space limitation in the LineRecallBuffer setting.

  • bbsiz: The maximum memory allocation to permit for a process (in kilobytes).

Autostart Pre-Fetch Daemons As Needed

The block pre-fetching mechanism ($PREFETCHON / $PREFETCHOFF) requires system-wide pre-fetch daemons to be initialized. This version of Caché automatically ensures that the pre-fetch daemons are started as needed, and are stopped when no longer needed, thereby eliminating the need to manually start and stop these daemons.

Improved SQL Performance Tools

With this release Caché contain additional utilities that provide useful functions for analyzing SQL behavior on production data: how many times an Index is used; identify Queries that result in table scans, or that have dependencies on building temporary structures; and identify queries based on Joins and rank how well supported they are by existing indices.

Simpler Disaster Recovery Failover And Failback

In previous releases, Caché Database Mirroring has provided an Asynchronus Mirror configuration for Disaster Recovery purposes. In this release, InterSystems has made it easier to switch over to an Asynchronous DR Mirror node in the event of a disaster (or for testing purposes); and also made it easier to switch back to the main production failover mirror at a later date.


WS Reliable Messaging

With this release Web Services Reliable Messaging can be used to reliably (identify, track and manage) deliver messages between a source and a destination.

Technology Preview

This category is new with this release. It is intended as a way of introducing and providing access to new software capabilities that InterSystems believes will be useful in enhancing the effectiveness of existing and future applications.

The capabilities listed here are ready for use by customers, but they are not yet complete in functionality and design. Customers who take advantage of these capabilities must understand:

  • InterSystems makes no backward compatibility guarantee with future updates;

  • Customers may incorporate these capabilities in deployed applications, but must first check with InterSystems to determine best course of action;

  • Customers who deploy these capabilities in their applications must commit to upgrading to the final released version.

InterSystems stongly encourages those who incorporate these items in their software to provide feedback on their experiences.

Rapid Application Development

iKnow - Customized Summaries

This release of Caché contains the capability to generate custom summaries for sources. Custom summaries are developed for those who desire to tune the content of iKnow generated summaries to their specific needs.

Main parameters for tuning the summaries are the following:

  • The user can indicate the number of the sentences he wants always to be included in the custom summary, e. g. when summarizing a newspaper article it can be beneficial to always include the first two sentences.

  • The user can enumerate a list of words and/or sentence parts he wants to use as absolute triggers, this means that sentences containing one of the elements in the list will always be included in the summary or always be excluded from the summary.

  • The user can give more or less importance to certain words and/or sentence parts. In this case the weight of sentences containing one of the elements in the list will be adapted in accordance with the weight instructions specified by the user. These adaptations will influence the sentence rankings used in the summarization and include or exclude the elements specified by the user if the context of the text allows to do so.

The options for custom summaries can be set by means of an extra parameter in the SourceAPI.GetSummary method.

iKnow Support For Negation

This release of Caché introduces iKnow negation detection. The uniqueness of iKnow negation detection resides in the fact that not only linguistic markers of negation in a sentence such as “not”, “no” and “didn't” are detected, but that iKnow also marks their semantic scope. In the example:

John has no signs of headache but has a fever.

the linguistic negation marker is “no”. iKnow negation detection will not only detect the marker, but also detect the semantic span of the negation. This means it will establish that “John has no signs of headache” is the negative part of the sentence. The span of the negation is indicated by negation attribute markers that can be accessed and used by the following method calls:

  • EntityAPI.GetOccurrenceAttributes(): to see whether an occurrence of an entity contains a negation marker or not.

  • SentenceAPI.GetHighlighted(): to highlight the negative parts in sentences

  • SentenceAPI.GetAttributes(): to get the positions of negation markers and their scope markers at the level of the sentence

  • PathAPI.GetAttributes(): to identify the negative parts of pathway

  • SourceAPI.GetAttributes(): to get all negations for a source.


Beginning in this release InterSystems has included the first support for the refactoring of code in the Studio. Initially, the available options will be:

  • Change Class Name

  • Change Property Name

  • Change Method Name

Additional options will be incorporated in future releases.

In this release, refactoring is only available on Windows systems.

Caché 2013.1 Upgrade Checklist


The purpose of this section is to highlight those features of Caché 2013.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 2012.2 and 2013.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 2013.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 the addition of pages to assist with database mirroring and the separation of roles.

Operational Changes

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

Check CACHETEMP/CACHE Encryption Status On Upgrade

The installer will check the encryption status of CACHE and CACHETEMP on upgrade and will ask for encryption key file location, username and password if it finds either database is encrypted. This information will be validated before file copying begins and the values will be passed to ^INSTALL.


This behavior is not avauilable for RPM and DMG kinds of installs. In these cases, database encryption should be turned off prior to upgrade with RPM/DMG installers and re-enabled afterward.

Default Answer For ^JRNSTOP Changed To No

The default answer for ^JRNSTOP has been changed from “Yes” to “No”:

Stop journaling now? No => 

This change may affect scripts that assume a default of “Yes”.

Ask User For Confirmation Before Starting Journal Restore

A new prompt is now part of the journal restore utility (^JRNRESTO). The user must confirm the restore request before journal restore actually starts. With the change, the screen output looks like this:

  DEFAULT: Continue despite database-related problems (e.g., a target 
  database is not journaled, cannot be mounted, etc.), skipping affected 
  ALTERNATE: Abort if an update would have to be skipped due to a 
  database-related problem (e.g., a target database is not journaled, 
  cannot be mounted, etc.) 
  DEFAULT: Abort if an update would have to be skipped due to a 
  journal-related problem (e.g., journal corruption, some cases of missing 
  journal files, etc.) 
  ALTERNATE: Continue despite journal-related problems (e.g., journal 
  corruption, some missing journal files, etc.), skipping affected updates 
Would you like to change the default actions? No => No 

Start the restore? Yes => Yes  

This change will affect scripts that are not prepared to respond to the prompt.

Allow Mirror Dejournaling On Reporting Async Members To Be Stopped

All mirror members have a new menu item in ^MIRROR – Pause dejournaling for a database. On a backup member or an async member this allows you to notify the mirror dejournaling system to skip dejournaling to this database. This can be used if maintenance needs to be performed on a database for some reason (for example, it needs to be dismounted so it can be encrypted or decrypted).

On a disaster recovery async member or a backup a mirrored database can simply be dismounted and, if the dejournaling system runs into an error such as a <PROTECT> error, the database will be marked to be skipped and dejournaling to other databases will continue. It is a bit cleaner though to first pause the database because this drains any pending data in the dejournaling system before blocking any future records from being processed.

On a reporting member, however, dismounting a mirrored database can result in the dejournaling system shutting down for all databases in that mirror if there are subsequent records in the journal for that database. This is done because, on reporting members, sites may want to keep all databases in a given mirror in sync with each other so if there is an error in any one, dejournaling should stop there.

If you want dejournaling to continue it can then be restarted using a new ^MIRROR menu item for reporting async members, Manage mirror dejournaling on reporting member, and it will continue without the dismounted database. Alternatively, the database can be paused before it is dismounted and then dejournaling for other databases in the mirror won't shut down if there is data for the paused database in the journal stream.

System Monitor Now Extended To User Databases

Beginning with this release users may create Sensor, Subscriber, and Notification classes to extend System Monitor in non-SYS namespaces. This change requires that all SYS.Monitor.Abstract classes be changed to %SYS.Monitor.Abstract. In particular, users of SYS.Monitor.AbstractSensor must change the declaration to be %SYS.Monitor.AbstractSensorOpens in a new tab.

Use VIRTUALALLOC() and MMAP() For Larger Stack And Error Frames

The frame stack and error stack are no longer allocated as byte arrays in the partition. They are now allocated using VirtualAlloc() on Windows or mmap() for UNIX® and OpenVMS. Using this mechanism, Caché can allocate a larger frame stack with little impact on the system when the memory is not actually used. It can afford to set a larger buffer between the end of the space allowed to be used and the actual end of memory.

Error processing will now recognize that there is still unused buffer space available. So instead of popping existing frame entries to make room for executing an error trap (which risks losing important things like an application error trap), it will now reset the frame size to the actual end of the stack memory, which makes the previously unused stack space available to the error trap.

There are new $SYSTEM methods that can be used for testing the effects of this change:

  • $SYSTEM.Process.FrameStackSize()

    gives the frame stack size for the current process.

  • $SYSTEM.Process.FrameStackExpanded()

    returns 0 or 1 to indicate if the frame stack has been expanded after a <FRAMESTACK> error to allow for an error trap to be run. If this value is 1, then another <FRAMESTACK> error will cause the process to terminate without running an error trap. It will automatically return to 0 after enough stack entries are popped to return to normal operation.

  • $SYSTEM.Util.GetFrameStackSize()

    returns the configured stack size. This is the size that will be used for any new processes that are created.

  • $SYSTEM.Util.SetFrameStackSize(newsize)

    sets the configured stack size to a new value and returns the previous value. This new value will be used as the frame stack size for all newly created processes. If newsize is 0, the system default size is set.


In concert with this new allocation policy, the size of the execution stack, which limits the levels of DO, XECUTE, and so on that are allowed, has been doubled. This does not, in practice, double the memory load on the system unless the full memory is actually used. However, systems with many processes may experience a heavier burden on system memory and/or paging space.

It is possible that for systems where the memory usage was close to the allowed limit, this change may cause memory exhaustion.

New Return Values From System And Memory Status Check

Anew register stored in shared memory and maintained by the System Monitor tracks system health. The values stored here are:

  • 0 – green: all is well

  • 1 – yellow: warnings are present

  • 2 – red: alerts have been posted

All System Monitor subscribers may post notifications. Yellow is set when level 2 alerts are posted. Red is set when 5 alerts have occurred in 10 minutes. The health goes back to green if there are no further alerts for 1 hour.

Users can obtain the status via the following commands:

ccontrol list
ccontrol qlist
cache -cV

or programmatically via $SYSTEM.Monitor.State() which returns the values defined. See also the SetState, Alert , Clear, and ClearAlerts methods.

Third-Party Library Changes

In this release, ANTLR has been upgraded to version 3.4; Xerces has been updated to version 3.1.1 on UNIX®; CacheSSH now uses libssh2-1.4.2.

Make DNS Name Parser RFC1123 Compliant

The DNS name parser grammar that handles TCP endpoint specifications is now properly compliant with RFC1123. Previously, the parser did not allow any portion of a dotted DNS name to begin with a digit. According to RFC1123, it is only the final dotted portion of the DNS name that has this restriction in order to distinguish it from an IPv4 address in dotted quad form.

Recompile Generated Code During Install

During an install, Caché normally recompiles all user Z*, z*, %Z*, and %z* routine and classes. However, prior to this release, it skipped any routines marked as "Generated". Generated routines are routines which are derived or created by compiling other routines or classes.

Beginning with this release, a routine can be marked as generated when there is no source present. This can happen in two cases: (1) the original source is deleted; and (2) a %RO of .INT code generated by a .MAC file is marked in the %RO file as being generated (%RI, it retains the Generated flag), but has no source.

Caché now detects this case during install, and if the generated code is present, with no corresponding source for it, Caché will recompile the generated code.

$VIEW Adds Peak Memory Usage To Output

Beginning withthis release, $VIEW(-1) adds the peak memory usage, in Kb, as the 17th value returned. For example:

Set VSS= $VIEW(-1, $JOB)
Write "Peak memory usage for this process in KB is "_$PIECE(VSS, "^", 17), !

Start Shadow Servers As The User Who Started Caché

The system starts Shadow servers with the same user characteristics regardless when they are started -- whether at Caché startup or after Caché is up and running. Previously, when they were started in the later scenario (Caché is up and running), they could take on the characteristics of a different user. When that happened, process limits and file ownership might differ depending on the circumstances. Now they are always the same

Changes To $ZCONVERT

If a Unicode string ending in a high surrogate character is passed to the 4-argument form of $ZCONVERT() for UTF-8 output translation, for example,

Set S = $ZCONVERT(string, "O", "UTF8" , x)

this function now saves the last character in the local variable (x in this example). The value in x will be prepended to the input string in the next iteration.

If the string in the next iteration starts with a low surrogate character, the prepended x and the leading character are treated as a surrogate pair and translated accordingly. Otherwise, the previous high surrogate character is translated as a 3-byte sequence, and the initial character is treated individually.

The same rules apply to the JSML (Javascript/XML) translation.

Licenses Prompt During Upgrade Changed

Beginning with this release, the installation process will not ask users to enter a license key during the install. Instead, it will ask for the location of the key file. If the location is not known at upgrade time, the file can also be copied to the manager’s directory or entered via the Management Portal after the installation finishes.

Output From Ccontrol Changed

When a mirror member is in the process of transitioning to become the primary, it temporarily blocks users from signing in for part of the transition. An application which is parsing any output from attempting to enter Caché may need to be updated to be sensitive to a new message which says:

Sign-on inhibited: Transitioning to primary mirror member
ECP Recovery Of Open Transactions Across Upgrade

ECP recovery delays handling of the ECP open transactions until the networking subsystem is initialized. During an upgrade, if the system was shut down during the startup recovery, and if there were open transactions that spanned multiple journal files, the second attempt to rollback those open transactions may fail after the system upgrade.


To avoid this circumstance, make sure the system is shutdown gracefully before upgrading.

USE Permission Required For DeepSee Portal

As of this release, to use any DeepSee page, a user must have USE permission for the %DeepSee_Portal resource, in addition to other privileges required for the page. Unless you are using minimal security (which is not recommended for production environments), this change may require you to adjust your role or user definitions.

In particular, if your application includes embedded dashboards, you must provide any applicable users with USE permission for %DeepSee_Portal as well, so that they can use the dashboard viewer. In previous releases, users of embedded dashboards did not require this privilege.

Conversion Of Control Characters Changed

Begining with this release, $ZCONVERT(string, "O", "JS") and $ZCONVERT(string, "O", "JSML") will now translate the $CHAR(1) through $CHAR(7), and "/", to their hexadecimal equivalents: \x01 through \x07 and \x2F equivalently. Previously these characters passed unchanged.

If your application relies on $ZCONVERT for Javascript or Javascript Markup, you must change your application to accommodate this change – most often by using the hexadecimal equivalent of these characters.

Resource Required For Viewing %Monitor Data

In order to view data collected by the %Monitor facility via CSP, the user will need to have %Admin_Manage, %Admin_Operate, and %Developer on the relevant CSP pages and any subclass pages.

Change To Memory Usage And Allocation

In this release, the XML reader now uses local variables for storing its information; previously, it used process-private variables. This results in both a performance improvement and an additional demand on memory. Depending on the sizes of XML files read and the processing mix on the system, the memory allocation may need to be increased to avoid fatal errors. this can be done:

  • permanently by setting the bbsiz parameter in the CPF file.

  • dynamically by having the application adjust the value of the $ZSTORAGE special variable.

Platform-specific Items

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

  • Pdfprint Now Requires The PrintServer On Windows

    On Windows platforms, pdfprint now requires the built-in PrintServer. The PrintServer is a Java program which uses the Adobe Acrobat reader to print.

    The user needs to define a file in the PrintServer directory which defines the location of the Adobe Reader, for example, on Windows 7:

    adobe=C:/Program Files (x86)/Adobe/Reader 10.0/Reader/AcroRd32.exe

    A ZEN Report now contains new properties, parameters, and ZEN URLs to pdfprint:




    There is also a PS property, $PS ZENURL and PS parameter to define a printer for GenerateReport. The following URL shows how we put it all together to print a report using Acrobat Reader on Windows. (Line breaks are inserted to improve readability.)


    PS must be the name of the printer in the Printer/General Tabs setting in Devices and Printers/<printer>/Properties.

  • Cterm Option For VT Left-Cursor Command

    The Terminal emulator did not behave like a VT-nnn terminal under the following circumstances:

    • Auto wrap is configured.

    • A character has just been written to the last display column so the terminal is just about to wrap.

    • A sequence of N backspaces, or the cursor left N position escape sequence (CSI n D) issent..

    Under these circumstances, a VT terminal will move the cursor N positions to the left of the last column, while the Terminal would move the cursor N positions from a position just to the right of the last column of the display. This put the cursor in the Terminal one character to the right of where it would be on a VT terminal. The Terminal now behaves like the VT terminal under these circumstances if the following registry entry is defined:

    • On 32–bit Windows:


    • On 64 bit Windows:



    Activating this behavior may create problems editing wrapped lines in programmer mode after command line recall. InterSystems does not recommended that customers enable the behavior unless they require this behavior in their applications.

  • Changes To Address Missing .NET Assemblies

    While it is risky potentially for an application to not have all the components listed in its manifest installed properly, it appears to be a common situation in cases where it is certain the missing code will not be traversed or used. Beginning with this version, Caché will now continue loading all the assemblies it can, listing any that cannot be loaded in the log.

    Users who have problems running code because of deployment issues should use the log to resolve dependency issues.

Windows And UNIX® / Linux

The Caché internal web server has been updated to version 2.4.2 on all Windows, UNIX® and Linux platforms. The installer will automatically update httpd.conf as needed. This behavior applies to Windows install, UNIX® install, standalone CSP Gateway installation script and RPM installation for Linux.

Linux RedHat 32-Bit And 64-Bit


MacOS 64


PowerPC And HP-Itanium

During an upgrade, Caché now modifies the CPF file and increases the amount of memory allocated to the lock table by twice its current amount. It does this by doubling the existing locksiz parameter in the [config] section. This change also adds the same amount of memory to the gmheap parameter which is where the lock table memory is allocated from.

During an initial install, the default locksiz is now increased by twice the default, and the gmheap is also increased by the same amount.

Customers who are configuring new systems should increase the size of the lock table they use by twice the former amount, and add the same amount of size to the gmheap parameter.

OpenVMS Itanium

In this version, the file CACHE.EXE has been separated into two files: CACHE.EXE and CKERNEL.EXE.

If you use the Caché command line, you should be unaffected by this change. Running CACHE.EXE should have the same behavior as before, providing you keep CACHE.EXE and the corresponding CKERNEL.EXE in the same directory.

If you have modified CZF.C or any other source file so that CZF.EXE now does callins (the default CZF.EXE does not do any callins), then changes are necessary. The CZF.EXE image is activated by $ZF("RoutineName",...) calls. If you have built any other image that does callins, changes in how that image is built are also necessary. Previously, these images were LINKed against the CACHE.EXE shareable image. They must now be linked against the CKERNEL.EXE shareable image.

The CLINK.OPT linker options file that is installed into the [InstanceDir.source.cache] directory has been modified so that it refers to CKERNEL.EXE instead of referring to CACHE.EXE. When doing an OpenVMS LINK using CLINK.OPT/OPTIONS, you must either define the CKERNEL logical name to point at the location of the [InstanceDir.bin]CKERNEL.EXE file, or you must have a copy of CKERNEL.EXE in what is the default directory during the execution of the LINK.

If you do not use the CLINK.OPT options file when linking an image that does a Caché kernel callin, you must modify any command file or LINK command that references CACHE.EXE. Most references to CACHE.EXE must be changed to references to CKERNEL.EXE so that your build procedures can use the universal symbols defined by CKERNEL.EXE.

If you have created an executable image that calls in to the Caché kernel, that image must do a LINK as described above. However, when you execute that image, it is also necessary to locate the corresponding copy of CKERNEL.EXE. You do this by defining the logical name CKERNEL before running your image. (You previously had to define the logical name CACHE so that your executable program could find the CACHE.EXE shareable library image.) Defining the CKERNEL local name will look something like:


If the image you built is INSTALLed as a known image with the addition of the /PRIVILEGED qualifier, the logical name CKERNEL must be created with DEFINE/EXECUTIVE_MODE or with ASSIGN/EXECUTIVE_MODE. Privileged executables that activate a shared library image require the shared library image to be a known image that is located by means of an executive mode (or kernel mode) logical name.

If you have an image that dynamically activates CACHE.EXE by calling LIB$FIND_IMAGE_SYMBOL, you must rewrite your call on LIB$FIND_IMAGE_SYMBOL so that it dynamically activates CKERNEL.EXE.


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.

Global Name Reservations

InterSystems reserves to itself all global names in the CACHESYS database except those that start with:

  • “%z” or “%Z”

  • “z” or “Z”

In all other databases, InterSystems reserves all global names starting with “ISC.” and “%ISC.”.

Routine Compiler Changes


Routine Changes

VarArgs May Now Contain References As Well As Values

Beginning in this version, the args... syntax for receiving and passing a variable number of arguments can be used when passing an argument by reference. For example,

   set x=2,y(3)=4 
   do sub1(.x,.y,.z) 
   ; now $DATA(x)=0, y(1,2)=3, z=5 
 set args(2,1,2)=3 
 do sub2(args...) 
 kill a 
 ; b(1,2)=3 and b(3)=4 
 set c=5 

If current programs are passing arguments by reference with this notation, their behavior could change because the actions of the subroutine will now affect the original variables. Before this change, they were actually passed by value so the subroutine could not affect their value.

Z*.inc And z*.inc Include Files Renamed

In this release all Z*.inc include files are renamed to ISC*.inc; and all z*.inc include files are renamed to ISCz*.inc files. This is to avoid having Caché system include file names conflict with user include file names.

Class Changes

Class Deletions

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

  • %BI — Excel, ExcelTry

  • %CSP.UI.Portal — PrintQuery, PrintTable

  • %CSP.UI.Portal.Config — Journal, RemoteDatabase, RemoteDatabases

  • %CSP.UI.Portal.SQL — ExecuteQuery

  • %CSP.UI.SQL — CQInfoPane, ViewInfoPane

  • %CSP.UI.System — AppGroupTablePane

  • %DeepSee — FactView, MetaView

  • %DeepSee.Report.UI — Builder, BuilderCore

  • %DeepSee.UI — SVGWidgetCatalog, WidgetPreview

  • %DeepSee.UI.Dialog — WidgetBuilder

  • %Monitor.System — Dashboard, Dashboard2

  • %Monitor.System.Sample — Dashboard, Dashboard2

  • %Net.Remote.Java — JavaGatewayService

  • %WebStress — HttpRequest

  • %WebStress.Utils — Recorder

  • %WebStress.Utils.Recorder — Port, Recorded, Script, Status, Summary

  • %iKnow.Filters — SimpleMatchFilter

  • SYS.Monitor — AbstractSensor

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)
%BI.CDC method OnPage
%BI.CodeTableCSP method OnPage
%BI.DMG method OnPage
%BI.DatePicker method OnPage
%BI.EdmundPageCSP method OnPage
%BI.ExportImport method OnPage
%BI.ExportList method OnPage
%BI.Generator method OnPage
%BI.GridPivoting method OnPage
%BI.Help method OnPage
%BI.ImportList method OnPage
%BI.KnowledgeCSP method OnPage
%BI.LanguageSVGCSP method OnPage
%BI.LanguageSub method OnPage
%BI.ListFolderData method OnPage
%BI.PerfAlert2 method OnPage
%BI.RulesSetup method OnPage
%BI.Scorecard method OnPage
%BI.SystemVariable method OnPage
%BI.TimeSeries method OnPage
%BI.Trees method OnPage
%BI.UserObjectListWeb method OnPage
%BI.ValueRange method OnPage
%BI.WebADTM method OnPage
%BI.WebAnalyzer method OnPage
%BI.WebAnalyzer2 method OnPage
%BI.WebAnalyzerSetup method OnPage
%BI.WebCMeditor method OnPage
%BI.WebCdnEditor method OnPage
%BI.WebClsCom method OnPage
%BI.WebColorScheme method OnPage
%BI.WebComBank method OnPage
%BI.WebComponentKPI method OnPage
%BI.WebComponentTree method OnPage
%BI.WebCurrency method OnPage
%BI.WebDList method OnPage
%BI.WebDashboard method OnPage
%BI.WebDataCapture method OnPage
%BI.WebDocBrwsr method OnPage
%BI.WebDtAnalysis method OnPage
%BI.WebETL method OnPage
%BI.WebEmail method OnPage
%BI.WebExcelTemplate method OnPage
%BI.WebFile method OnPage
%BI.WebFold method OnPage
%BI.WebGrid method OnPage
%BI.WebKPIClass method OnPage
%BI.WebKnowledge method OnPage
%BI.WebLesenReg method OnPage
%BI.WebListbackup method OnPage
%BI.WebLnkRpt method OnPage
%BI.WebMain method OnPage
%BI.WebMain2 method OnPage
%BI.WebMainTable method OnPage
%BI.WebManEnt method OnPage
%BI.WebMapTable method OnPage
%BI.WebMessaging method OnPage
%BI.WebMessagingExt method OnPage
%BI.WebMultiSites method OnPage
%BI.WebOCR method OnPage
%BI.WebPivTable method OnPage
%BI.WebPrinter method OnPage
%BI.WebPrn method OnPage
%BI.WebSCActions method OnPage
%BI.WebSMS method OnPage
%BI.WebSQLComGen method OnPage
%BI.WebSVG method OnPage
%BI.WebSVGTest method OnPage
%BI.WebSchema method OnPage
%BI.WebSchemaMain method OnPage
%BI.WebSecCorrection method OnPage
%BI.WebShortcut method OnPage
%BI.WebSqlWiz method OnPage
%BI.WebStoredProc method OnPage
%BI.WebSysFn method OnPage
%BI.WebTAClassDialogBox method OnPage
%BI.WebTableList method OnPage
%BI.WebTaskMgmt method OnPage
%BI.WebTransformation method OnPage
%BI.WebTranslationD method OnPage
%BI.WebUsersMtn method OnPage
%BI.WebUtil method OnPage
%BI.WebWorkFlow method OnPage
%BI.WebWorkFlowE method OnPage
%CSP.Login method DrawLogout
%CSP.UI.DocLocalize method DatabaseFreespaceCleanup, DatabaseFreespaceCompact, DatabaseFreespaceList, Journal, RemoteDatabase, RemoteDatabases
%CSP.UI.Portal.ClassList method allowSelectRow
property AllowSelectRow
%CSP.UI.Portal.DatabaseFreespace method clearSpace
%CSP.UI.Portal.DatabaseFreespaceCleanup method DrawTitle1
property msgValidate
%CSP.UI.Portal.DatabaseFreespaceCompact method DrawTitle1
property msgValidate
%CSP.UI.Portal.Dialog.ExportResource property ActionDone
%CSP.UI.Portal.ProcessDetails method doOwnerDrawTabs, drawOneTab, drawTabs, startRefresh, tabClicked
%CSP.UI.Portal.RoutineCompare method getHTML
%CSP.UI.Portal.RoutineList method allowSelectRow
property AllowSelectRow
%CSP.UI.System.SecurityAdvisorPane property readOnly
%DeepSee.Report.UI.ExecuteReport method showFileSelectionWindow
%DeepSee.Report.UI.ExtractDSS property nameSpace
%DeepSee.Report.UI.reportModelServer method ServerCommand
%DeepSee.Report.UI.schemaEditPanel method IsSQLReservedWord, processFieldName
%DeepSee.UI.Dialog.DashboardSave method DrawIcons, selectLayout, updateGridControls
property dashboardDescription, dashboardGridCols, dashboardGridRows, dashboardKeywords, dashboardLayout, dashboardLocked, dashboardModify, dashboardResize
%DeepSee.UI.TermListManager method columnClick
%DeepSee.UI.WorksheetBuilder method CreateDataSet, GetLookupArray, GetWSData, LookupReferences, SaveToServer, SetRecord, applyChange, changeCell, changeColumn, changeGrid, changeRow, clearStyles, deleteItem, editCellHandler, editFormatString, getCellValue, getCurrPageCount, getCurrPageSize, getLogicalValue, gotoGridPage, gridChange, gridEditKeyDown, gridEditKeyUp, gridRender, initEngine, loadDataConnector, loadWorksheet, moveColumnLeft, moveColumnRight, moveRowDown, moveRowUp, nextGridPage, numberToColumn, prevGridPage, printWorksheet, recalc, renderNavBar, resolveFormulaRefs, selectCellHandler, selectColumn, selectGrid, selectRow, setActionTarget, setRecordValue, textEditorKeyup, textOKClicked, toggleSettings, updatePropertyPanel, updateStyleControls
property currPage, dataConnector, gridMode, gridSelected, pageSize, selectedColumn, selectedRow, worksheetDescription, worksheetKeywords, worksheetLocked, worksheetOwner, worksheetPublic, worksheetResource
%DeepSee.UserPortal.DashboardViewer method SaveDashboardToFolder, addWidget, editWidget
%DeepSee.UserPortal.Home method DrawFoldersList
%Library.EnsembleMgr method AddDelegated, CreateFoundationResources, EnableFoundationNamespace, GetHealthShareNamespaceType, InstallFoundationSecurity, IsFoundationInstalled, IsHealthShareInstalled, IsViewerInstalled, ValidateHealthShare, map2hslib, moveHSSiteDefaultFiles, unmaphslib, upgradeUTCIndices
%Library.RoutineMgr method IsServerOnly
%Library.SQLCatalog method GetCachedQueryInfo, MakePat, SQLCODEListClose, SQLCODEListExecute, SQLCODEListFetch, SQLCachedQueryInfoClose, SQLCachedQueryInfoExecute, SQLCachedQueryInfoFetch, SQLCachedQueryTableClose, SQLCachedQueryTableExecute, SQLCachedQueryTableFetch, SQLChildTablesClose, SQLChildTablesExecute, SQLChildTablesFetch, SQLConstraintsClose, SQLConstraintsExecute, SQLConstraintsFetch, SQLFieldsClose, SQLFieldsExecute, SQLFieldsFetch, SQLForeignKeysClose, SQLForeignKeysExecute, SQLForeignKeysFetch, SQLIndicesClose, SQLIndicesExecute, SQLIndicesFetch, SQLParentTableClose, SQLParentTableExecute, SQLParentTableFetch, SQLProcedureInfoClose, SQLProcedureInfoExecute, SQLProcedureInfoFetch, SQLProceduresClose, SQLProceduresExecute, SQLProceduresFetch, SQLRelationshipsClose, SQLRelationshipsExecute, SQLRelationshipsFetch, SQLReservedWordsClose, SQLReservedWordsExecute, SQLReservedWordsFetch, SQLTablesClose, SQLTablesExecute, SQLTablesFetch, SQLTriggersClose, SQLTriggersExecute, SQLTriggersFetch, SQLViewFieldsClose, SQLViewFieldsExecute, SQLViewFieldsFetch, SQLViewInfoClose, SQLViewInfoExecute, SQLViewInfoFetch
%Library.SQLCatalogPriv method SQLRolePrivilegesClose, SQLRolePrivilegesExecute, SQLRolePrivilegesFetch, SQLRoleUserClose, SQLRoleUserExecute, SQLRoleUserFetch, SQLRolesClose, SQLRolesExecute, SQLRolesFetch, SQLUserExistsClose, SQLUserExistsExecute, SQLUserExistsFetch, SQLUserPrivsClose, SQLUserPrivsExecute, SQLUserPrivsFetch, SQLUserRoleClose, SQLUserRoleExecute, SQLUserRoleFetch, SQLUserSysPrivsClose, SQLUserSysPrivsExecute, SQLUserSysPrivsFetch, SQLUsersClose, SQLUsersExecute, SQLUsersFetch
%Library.SysLog method ConfigurePage, DecodeData, OnPage, RenderBanner, ServeStyleSheet, ShowDataPage, ShowLogPage
%MV.Adaptor parameter MVAUTOLOCKED
%SQL.Manager.Catalog method CachedQueryInfoClose, CachedQueryInfoExecute, CachedQueryInfoFetch, CachedQueryTableClose, CachedQueryTableExecute, CachedQueryTableFetch, ConstraintsClose, ConstraintsExecute, ConstraintsFetch, FieldCalcSelectivityClose, FieldCalcSelectivityExecute, FieldCalcSelectivityFetch, FieldCurrentSelectivityClose, FieldCurrentSelectivityExecute, FieldCurrentSelectivityFetch, FieldsClose, FieldsExecute, FieldsFetch, IndicesClose, IndicesExecute, IndicesFetch, MakePat, NamespacesWithXdbcErrorsClose, NamespacesWithXdbcErrorsExecute, NamespacesWithXdbcErrorsFetch, ProcedureInfoClose, ProcedureInfoExecute, ProcedureInfoFetch, ProceduresClose, ProceduresExecute, ProceduresFetch, PropertyInfo, RWListClose, RWListExecute, RWListFetch, SQLCODEListClose, SQLCODEListExecute, SQLCODEListFetch, SchemasClose, SchemasExecute, SchemasFetch, SchemasOnlyClose, SchemasOnlyExecute, SchemasOnlyFetch, TablesClose, TablesExecute, TablesFetch, TablesOnlyClose, TablesOnlyExecute, TablesOnlyFetch, TriggersClose, TriggersExecute, TriggersFetch, ViewFieldsClose, ViewFieldsExecute, ViewFieldsFetch, ViewInfo2Close, ViewInfo2Execute, ViewInfo2Fetch, ViewInfoClose, ViewInfoExecute, ViewInfoFetch, ViewsOnlyClose, ViewsOnlyExecute, ViewsOnlyFetch, XdbcErrorsClose, XdbcErrorsExecute, XdbcErrorsFetch
%SYS.ProcessQuery method PPGClose, PPGExecute, PPGFetch
%SYS.Task.IntegrityCheck method DirectoryIsValid
%SYSTEM.Event method DefinedIP, ListIP, SignalIP
%UnitTest.Report method DeleteSuite, GetTestColor, GetTestState, NoNamespace, ShowAsserts, ShowCases, ShowIndices, ShowMethods, ShowSuites, writeStyle
%XML.Node method AppendChild, InsertChild, ReplaceNode
%ZEN.Portal.assistedText method ghostGotFocus
%ZEN.Report.Display.COSChart.cchart method calculateYAxisWidth
%iKnow.DeepSee.Dimensions.Dictionaries method GetId
%iKnow.DeepSee.UI.Analysis.AbstractAnalysis method GetDomainId, GetFilter
%iKnow.DeepSee.UI.Analysis.Content method SetListing
%iKnow.DeepSee.UI.Analysis.Entities method GetDetailChartData, GetDetailLabelX, GetSelectedItemName, ReBuildEntityList, SetSelectedCell, getDetailChartDataClient, getDetailLabelXClient
%iKnow.Domain property SortField
%iKnow.Matching.DictionaryAPI parameter GetDictionaryElementsRT
%iKnow.Matching.MatchingWSAPI.InvalidateMatchingResults property keepEntUniMatches
%iKnow.Queries.MetadataWSAPI.AddField property buildBitstring
%iKnow.Queries.MetadataWSAPI.UpdateField property buildBitstring
%iKnow.Queries.MetadataWSAPI.UpdateFieldById property buildBitstring
%iKnow.Queries.SourceAPI method GetByEquivalentIds, GetByEquivalents
%iKnow.UI.AbstractPortal method GetDomain, GetTerm
%iKnow.UI.IndexingResults method GetSentFrom, GetSentTo
Ens.Enterprise.Portal.EnterpriseSearch parameter AssistantClass
Ens.Enterprise.Portal.MsgFilter.Filter method DeleteFromTemp, LoadFromTemp, SaveToTemp
Ens.Enterprise.Portal.SystemList method getSSLConfigList, getSoapCredentials
Ens.Rule.Model.ruleDefinition method test
Method Return Changes

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

  • %DeepSee.Report.UI.reportModelServer — ImportXML

  • %DeepSee.Report.UI.reportPreviewer — DeleteTempFile

  • %SQL.Import.Mgr — Import

  • %SYSTEM.iKnow — IndexDirectory, IndexFile

  • %XML.Node — InsertCharacter, InsertElement

Method Signature Changes

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

Class Name Method Name(s)
%CSP.UI.Portal.Config.ZenReport SaveData
%CSP.UI.Portal.DatabaseFreespaceCleanup GetSize
%CSP.UI.Portal.DatabaseFreespaceCompact GetFreeSpace
%CSP.UI.Portal.RoutineList doFullView
%CSP.UI.System.GlobalDrillPane SaveChange
%DeepSee.AbstractKPI %GetFilterLogicalValue
%DeepSee.Component.pivotController showMessage
%DeepSee.Component.pivotTable getDataSourceCaption
%DeepSee.Dashboard.Utils %GetMembersForFilter
%DeepSee.QualityMeasure.Utils %GetQualityMeasureClass
%DeepSee.Report.UI.CreateDCR scanForFieldNames
%DeepSee.Report.UI.reportPreviewer GeneratePresentationReport
%DeepSee.Report.UI.schemaEditPanel autopopulateDBItem, makeNode
%DeepSee.UI.WorksheetBuilder gridKeyDown
%DeepSee.UserLibrary.FolderItem %CheckResource
%DeepSee.UserPortal.DashboardViewer navGetContentForLevel, navSelectItem, widgetSelected
%DeepSee.UserPortal.Home refreshFolders, setFolderCategory
%DeepSee.UserPortal.standardPage navSelectItem
%DeepSee.extensions.iKnow.ClassifierBuilder genCrcTable
%Library.AbstractStream Read
%Library.CacheCollection CollectionToDisplay, DisplayToCollection
%Library.GTWCatalog SQLTablesExecute, SQLTablesJExecute
%Library.GlobalEdit CollationSet, CompactGlobal, Open
%Library.GlobalStreamAdaptor Read, ReadLine
%Library.RegisteredObject %OnValidateObject
%Library.RoutineMgr ImportItemListExecute, getBackupList, getPackageList
%Net.Remote.Service RunStartCmd, StartGateway, StartGatewayObject
%Net.Remote.Utility RunCommandViaCPIPE, RunCommandViaZF
%SOAP.Addressing.Properties GetDefaultRequestProperties
%SQL.Util.Procedures CSV, CSVTOCLASS
%SYS.PTools.SQLStats GetStats, GlobalSave
%SYSTEM.iKnow IndexDirectory, IndexFile
%Stream.Object Read
%Stream.TmpCharacter Read
%Studio.Extension.Base OnAfterAllClassCompile, OnAfterClassCompile
%Studio.SourceControl.ISC BaselineExport, BaselineExportItem
%WebStress.Record Run
%XML.ImportHandler SerializeBase64Node, SerializeNode
%XML.Node AppendCharacter, AppendElement, InsertCharacter, InsertElement
%XML.Security.Signature ComputeSha1Digest
%ZEN.Auxiliary.jsonProvider %WriteJSONFromArray, %WriteJSONFromObject, getDataSourceCaption
%ZEN.Controller InvokeClassMethod, InvokeInstanceMethod
%ZEN.Dialog.fileSelect RebuildLookin
%ZEN.Portal.assistedText doAction
%ZEN.Report.Display.COSChart.cchart createSVGTextNode, getYAxisTitle, renderYAxisTitle, renderYLabels
%ZEN.Report.PrintServer %ServeTransformAndPrint
%ZEN.SVGComponent.chart calculateYAxisWidth, createSVGTextNode, getYAxisTitle, renderYAxisTitle, renderYLabels
%ZEN.SVGComponent.radialNavigator drawNode
%ZEN.SVGComponent.tabBar drawOneTab
%iKnow.Configuration %OnNew
%iKnow.DeepSee.UI.Analysis.Entities GetChartData, GetLabelX, getChartDataClient, getLabelXClient
%iKnow.Domain %OnNew
%iKnow.Filters.Filter GetFilteredCcFrequency, GetFilteredCcSpread
%iKnow.Matching.MatchingAPI GetTopMatchesByDictionaryItemId, InvalidateMatchingResults
%iKnow.Matching.MatchingQAPI InvalidateMatchingResults
%iKnow.Matching.MatchingWSAPI GetTopMatchesByDictionaryItemId, InvalidateMatchingResults
%iKnow.Queries.MetadataAPI AddField, UpdateField, UpdateFieldById
%iKnow.Queries.MetadataI AddField
%iKnow.Queries.MetadataQAPI AddField, UpdateField, UpdateFieldById
%iKnow.Queries.MetadataWSAPI AddField, UpdateField, UpdateFieldById
%iKnow.Source.Lister SetConfig
%iKnow.Source.Processor %OnNew
%iKnow.Utils.MaintenanceAPI AddUserDictionaryEntry
%iKnow.Utils.MaintenanceQAPI AddUserDictionaryEntry
%iKnow.Utils.MaintenanceWSAPI AddUserDictionaryEntry
Backup.General ExternalFreeze
Config.NLS.Locales ImportDir
Config.NLS.SubTables ImportDir
Config.NLS.Tables ImportDir
Ens.Director StartProduction
Ens.Enterprise.Portal.MsgFilter.EnterpriseAssistant EnumerateExecute
Ens.Rule.Generator generateActions, generateOneAction, generateOneRuleSet
Ens.Rule.Model.expression constructCOS, convertToCOS, test
SYS.Database Defragment
SYS.Monitor.Health.Chart %OnNew
JavaGatewayService Class Deprecated

In this release the %Net.Remote.Java.JavaGatewayService class has been deprecated. This was an internal class; it was not documented for external use.

If you have developed custom code that relies on this class, you should update the code to instead use the %Net.Remote.ServiceOpens in a new tab class that incorporates the functionality of the deprecated class.

Object Synchronization

If an object is synchronized to a namespace which does not contain the class, the Caché will now catch the <CLASS DOES NOT EXIST> error and log it rather than abandoning the synchronization attempt. This gives the application the ability to more gracefully recover from the error.

If an application expected a failure in this case, it must be modified to check the error reported and handle the error condition.

Change Collation Handling In %Library.GlobalEdit.Create()

Either the external collation name (e.g. "Spanish2") or its internal number (e.g. 32) can now be used as the 3rd argument to %Library.GlobalEdit.Create(). If the specified collation is invalid or is not loaded, an error is generated. Previously, this method would accept only the numerical value, and silently use the database default collation if it were invalid.

Fix To Symbol Binding For Delimited Identifiers

A defect that caused an identity property to not be set when saving a new object has been fixed. If a class defines a property whose name is a delimited identifier as the IDENTITY property, the property was not properly set following an insert.

HTTP Changes

In this release, by default, if you reuse an instance of %Net.HttpRequestOpens in a new tab to send multiple requests, Caché sends all the messages over a single HTTP socket (using a HTTP 1.1 keep-alive connection). Specifically, Caché keeps the TCP/IP socket open so that Caché does not need to close and reopen it. For information on disabling this keep-alive behavior, see “Managing Keep-alive Behavior” in the chapter “Sending HTTP Requests and Reading Responses” in Using Caché Internet Utilities.

Change%Net.Remote.DotNet.Test To Accommodate New Directory Structure

Beginning with this version, Caché has two directories for .NET Gateway: one for Version 2.0, and the other for Version 4.0. The test method ListTypeLibs() of the class %Net.Remote.DotNet.TestOpens in a new tab now references the directory for Version 2.0 by default. Users may change the version by executing:

Do ##class(%Net.Remote.DotNet.Test).ListTypeLibs(port,,"4.0")

where port is a valid port number not in use at the time of the call.

Resource Requirements For Studio Source Control

With this release, the %Developer resource is needed to use the following Studio Source Control classes: %Studio.SourceControl.UIOpens in a new tab, %CSP.StudioTemplateInsertOpens in a new tab, and %CSP.StudioTemplateSuperOpens in a new tab.

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.

IDs Used For Bitmap Index Must be Integers

The class compiler will now report an error if the class uses %CacheSQLStorage and attempts to define a bitmap index map and the ID of the table is not an integer type.

If your tables use SQL Storage, and there is an IDKEY index on the table, and the IDKEY is not defined on a single field that has a datatype with an SqlCategory of INTEGER, the following error will be reported:

Compiling class User.MyTable
ERROR #5485: Bitmap indices are only supported when the IDKEY is based on a single positive integer attribute 
 ERROR #5030: An error occurred while compiling class User.MyTable

Prior to this change, if a bitmap index map was defined, no check was performed for SQL Storage to make sure the ID was compatible.


Any existing applications that have tried to use this probably have bad index data if the ID contains anything but positive integers. In this circumstance, the index should be deleted and rebuilt.

Multicompile Is On By Default

Beginning with this release, the ability to use multiple processes to speed compilation, or loading XML classes from a directory, (“/multicompile”) is enabled by default. To change the default to off for a system you can execute:

  Do $SYSTEM.OBJ.SetQualifiers("/multicompile=0", 1)

Projections Now Utilize Multiple Jobs

When you run a class compile with /multicompile turned on, Caché will now run the class projection calls to CreateProjection using the worker jobs in the same way it compiles classes. This improves the performance of this phase of the compile if class projection code is doing a significant amount of work.

Most projection code will continue to function as it has prior to this change; however, the two areas that should be noted are:

  1. Projections may be run in multiple, simultaneous jobs so if a projection is using $JOB to store information to co-ordinate with other projection code it should change to use %ISCName which will be defined and be the same amongst all multicompile jobs.

  2. It is important to lock data when you need exclusive access to prevent interference. With multiple projections running at the same time, there is a chance another projection may be manipulating the same data structure in another process. This was a potential issue prior to this change when you compiled the two classes at the same time in different jobs, but with multicompile it makes the chance of this occurring higher.

Notice Of Serial Property Change

In prior versions, the REQUIRED constraint was never effectively enforced. It will be in the next version.

Any existing application with properties whose type class is %Library.SerialObject and are defined as REQUIRED will now see that constraint enforced. This can cause objects that once saved to no longer save without error if the referenced serial object is modified or swizzled.

Parameter Properties Format Changed

The stored format of parameter values for compiled programs has been changed to be a $LIST. If your application parses the stored value of a parameter using SQL, it will need to be changed. The new method GetParameterValue has been added with the %Dictionary to assist in this. Also, the query %Dictionary.LegacyQueryOpens in a new tab will return the values in the previous format.

Language Binding Changes

XEP EventPersister Changes

The OPTION_REFERENCES and OPTION_INHERITANCE (and related flags) have been removed. After removal of these two options, no options are left and the EventPersister.setOption and getOption methods have also been removed.

Since these last two options are really generation/import time flags, the following two importSchema flavors have been added in their place:

String[] importSchema(String classOrJarFileName, int options)

String[] importSchema(String[] classes, int options)

where the options are:


    No import options - defaulting to no references and flattened hierarchy


    References are enabled as part of the import


    Do not flatten inheritance

Changes To Enum Handling

This release changes the projection of Java and DotNet enums. Names, and not ordinal positions, are now stored on the Caché side. This change should be completely transparent for new applications.

Old applications, that already have some enums stored, will have to delete and then re-import the data to avoid errors.

SQL Changes

The SQL Filer No Longer Calls IsValid For Reference Properties

The SQL Filer will no longer call the <property>IsValid method for a reference to a persistent class (for example, the Sample.Person.Spouse property). It is rare that a <property>IsValid method would even exist (it must be defined by the developer of the class). The Object %Save method does not call <property>IsValid methods for properties of type persistent or serial either, so now the Object and SQL filers are in sync in this behavior.

If an application depends on this behavior, the reference will have to be validated in another way, perhaps through a trigger.

Correction To StorageToLogical And LogicalToStorage

This release corrects an existing problem storage and retrieval of list or array collections where StorageToLogical and/or LogicalToStorage methods were defined for the property or datatype of the property. Previously, Caché was not properly applying the StorageToLogical or LogicalToStorage to each element of the collection. Now it does with the effect that the returned values for list or array collections may differ from previous releases.

Correct Translation Of Delimited Identifier To Numeric Literal

A Dynamic SQL bug that caused a delimited identifier to be translated into a numeric literal has been fixed. Previously, when a delimited identifier that is also a valid numeric literal was encountered by the statement preparser, it would be translated into a numeric literal. For example, in the query:

SELECT Name FROM Sample.Person WHERE  %ID = "1"

the literal “1” was interpreted as the integer value 1. The correct translation is that the delimited value "1" is retained and the statement will now report an error when prepared.


Previously, “{fn TRUNCATE(value, number)}” where number is greater than 0 and not 2 would display the wrong SCALE for the results when the column was selected in DISPLAY mode; the output of the result in DISPLAY mode would always use a SCALE of 2.

Now the output is properly scaled.

When DDL Compiles A Class, Compile Sub-Classes Too

When an SQL DDL statement is executed and a class definition needs to be compiled, the class now compiled using the “b” flag. This will compile any sub-classes for this class. This behavior is needed for many types of DDL statements, for example, where an index was added to a class with a CREATE INDEX statement, and the class has a subclass. Without this, the building of the index will not work for any rows in the subclass extent until the subclass has been compiled.


It is thought to be rare that customers run DDL against tables where the class has subclasses.

SQLTablePrivileges And SQLColumnPrivileges Changes

In prior versions, the ODBC SQLTablePrivileges and SQLColumnPrivileges catalog queries, along with the JDBC getTablePrivileges and getColumnPrivileges catalog queries, would only return privileges where the current user was the grantee of the privilege or a role held by the user was a grantee of the privilege. Now a row is also returned if the current user is the grantor of the privilege.

DROP TABLE From Management Portal Subject To Checking

In this release, you will no longer be able to drop a table, view, or procedure from the Management Portal if DDLAllowed=False is defined in the class that projected the SQL object.


This does not apply for linked tables. If a class is defined as a linked table, the Drop action will drop the linked table on the local system even if the linked table class is defined as DDLAllowed=0; but it will not drop the table this link references on the server he actual table resides on.

Compiled Names Of Queries Have Changed

In previous versions, if embedded SQL defined a query within a routine or method, and the routine or method was called recursively, the generated name of the cursor would cause the earlier value to be overwritten by the later statement execution. Unpredictable results ensued.

Begining in this release, the SQL Query Processor has changed how cursor variable names are generated and each compile of the statement will generate a different variable name. If application code is relying on SQL to generate certain variable names for an SQL cursor, this code will likely need to be updated to not rely on the variables names generated by SQL. SQL Cursor names must still be unique within a single routine or class method.

Statement-Level AFTER Triggers No Longer Recurse

In this version, the following changes have been made to how statement-level triggers AFTER behave:

  1. In previous versions, an AFTER statement level trigger was only executed if SQLCODE for the statement was 0. Now the trigger will be executed if SQLCODE for the statement is >=0. This means that if the statement does not find any rows to INSERT, UPDATE, or DELETE (SQLCODE = 100), the trigger is now executed.

    This behavior is required for proper behavior of language=TSQL triggers.

  2. Caché now prevents AFTER statement-level triggers from executing recursively.There are a couple of ways triggers can recursively call themselves. Direct recursion is when a table T1 has a trigger which performs the same operation on table T1. Indirect recursion can also occur if table T1 has a trigger that performs an insert into table T2 and table T2 has a trigger that performs an insert into table T1. Another example of indirect recursion is when table T1 has a trigger that calls a routine/procedure and that routine/procedure performs an insert into T1. With this change, when recursion occurs the trigger will not be executed if it detects it has been called previously in the execution stack. No error will be returned when either type of recursion is encountered, the trigger will simply not execute a second time.

    There are a couple of ways triggers can recursively call themselves.

    • Direct recursion is when a table T1 has a trigger which performs the same operation on table T1.

    • Indirect recursion can occur if table T1 has a trigger that performs an insert into table T2 and table T2 has a trigger that performs an insert into table T1. Another example of indirect recursion is when table T1 has a trigger that calls a routine/procedure and that routine/procedure performs an insert into T1.

    With this change, when recursion occurs the trigger will not be executed if it detects it has been called previously in the execution stack. No error will be returned when either type of recursion is encountered, the trigger will simply not execute a second time.


Recursion protection is only performed for AFTER statement-level triggers. If recursion is attempted in a BEFORE statement-level trigger, a runtime <FRAMESTACK> error may occur if the trigger code does not handle the recursion itself.


A statement level trigger with language Caché that attempts to define direct recursion via embedded SQL will fail to compile with a <FRAMESTACK> error. If your application requires recursion for a Caché trigger, indirect recursion must be used. This can be as simple as using Dynamic SQL or Deferred SQL instead of embedded SQL in the trigger code.

%sqlcontext No Longer Automatically Created

In Release 2009.1, an embedded SQL CALL statement began to NEW the %sqlcontext variable during its execution and remove it upon return. Beginning with this release, this no longer happens except when the statement contains a USING clause.

iKnow Changes

Proximity Value Format Change

Beginning with this version, the signature of the proximity data value has changed. Previously, it was defined as a decimal value, but this caused problems in conversion when using certain C++ libraries. Now, the decimal proximity value is represented as an integer with a value between 0 and 256. This allows for an appropriate range without suffering loss of precision in using the library.

Access To iKnow UI Classes

Beginning with this release, access to the user interface pages of iKnow (%iKnow.UI.*) as well as the class, %iKnow.Queries.AbstractWSAPI, and any generated subclasses will need %Developer.

XML Changes

%XML.TextReader Use Of Temporary Storage

The development of %XML.TextReaderOpens in a new tab predated the appearance of process-private globals; it used a hard-coded reference to ^CacheTemp for its temporary storage. beginning with this release %XML.TextReaderOpens in a new tabnow uses the process-private global, ^||CacheTemp, and adds an option to change the global name via an additional parameter on the ParseXXX() class methods.

In the rare case where an application has subclassed %XML.TextReader and added its own code, the application will have to fix up the hard-coded global references.

Web Services And SOAP Changes

New Keep-alive Behavior

In this release, by default, if you reuse a Caché web client instance to send multiple request messages, Caché sends all the messages in a single HTTP transmission (using a HTTP 1.1 keep-alive connection). Specifically, Caché keeps the TCP/IP socket open so that Caché does not need to close and reopen it. For information on disabling this keep-alive behavior, see “Disabling Keep-alive for a Web Client” in the chapter “Fine-tuning a Caché Web Client” in Creating Web Services and Web Clients in Caché’.

Change to SOAP Body Available to ProcessBody()

If you have customized a web service by implementing ProcessBody(), you might need to modify that method. In previous releases, ProcessBody() provided access to the SOAP body as is, without all the XML namespace prefix definitions. That is, when you called the Read() method of the requestBody argument of ProcessBody(), Caché returned the body without all namespace prefix definitions. In this release, the returned body includes any prefix definitions which may have been done in the Body or Envelope elements.

XMLNAME Parameter Included in Generated Methods

In some cases, the SOAP wizard now includes the XMLNAME parameter in the web methods in the web service and web client that it generates. This occurs if the WSDL defines the return type of a web method in terms of an element whose name does not follow the form MethodNameResult. For example, in many WSDLs, the return type of a web method is defined like this:

<s:element name="TestResponse">
            <s:element name="TestResult" type="s:string"/>

In some cases, the return type is defined like this instead:

<s:element name="TestResponse">
            <s:element name="MyOutput" type="s:string"/>

In such cases, the SOAP wizard now includes the XMLNAME parameter in the generated web methods as follows:

Method Test(a As %String) As %String(XMLNAME="MyOutput") [ ... ]
Support REQUIRED Keyword For Web Services

The SOAP Wizard is now modified to now add REQUIRED=1 for required arguments. This has no affect on the behavior of the service or client; it affects the WSDL which is created from a service.

The REQUIRED parameter is allowed for web method arguments to influence the generated WSDL. REQUIRED=0 (the default) results in minOccurs=0 in the WSDL. This change also adds support for the REQUIRED parameter in the return type. The default for the return type was REQUIRED=1, however, now REQUIRED=0 is valid and affects the WSDL.

The SOAP Wizard is also modified to now add REQUIRED=1 for required arguments.

XML Prefix Definitions Now In Request Stream Passed To ProcessBody

Previously, when calling ProcessBody call of web service, the body was copied as is. Beginning with this release, the body now includes any prefix definitions which may have been done in the Body or Envelope elements. Any code that depends on the exact form of the request including missing prefix definitions (for example, to add these definitions) must be modified to accommodate the new information.

Correct Processing Of Signed Requests When Using MTOM

When signing and validating signature for MTOM SOAP messages, the attached streams must be substituted for the MTOM reference before before computing the digest of the message body. Previously, the body including the references was incorrectly signed without substituting for the MTOM Include elements.


Caché will no longer interoperate correctly with web services that incorrectly do the signing before the substitution.

WebStress And UnitTest Classes Restricted To Developers

In this release, use of the %WebStress.Portal and %UnitTest.Portal classes requires the user to have the %Developer resource. Customers may also have to manually open up access to these classes by setting the ^SYS("Security","CSP") global as documented in Application Access To %CSP Pages Now Controlled to allow access to these classes via CSP.

MultiValue Changes

Log File Switching

When the mv.log file grows larger than 5MB (or the size limit of cconsole.log) it will be renamed and logging will start with a new file. This action is done by the %SYS.Task.PurgeErrorsAndLogsOpens in a new tab task.

Emulations @(–nn) Correction

For a number of MultiValue emulations, the @(-nn) implementations were wrong. These are all derived from the original Universe emulation and, since Universe doesn't differentiate between @(-nn) codes in its emulations, neither should Caché. For example, Caché doesn't provide a PRIME emulation, it provides a "PRIME as emulated on UNIVERSE" emulation.

The emulations affected are PICK, PRIME, PIOPEN and IN2. Applications will need source code changes if they use any of the following @(-nn) codes:

  • @(-11) to @(-12)

  • @(-17) to @(-53)

  • @(-56) to @(-64)

Changes To Handling Accounts In Root Directory

Beginning with this release:

  • CREATE.ACCOUNT will refuse to create accounts in “/” or “<DriveLetter>:\”.

  • DELETE.ACCOUNT will now prompt for confirmation before clearing and deleting a directory unless the “N” option is used.

Any automated procedure that deletes accounts unattended should be modified to include the “N” option in the command line. If this cannot be done then a lowercase “n” on attribute 5 of the DELETE.ACCOUNT verb will revert to the old behavior as a temporary measure.

Changes To TANDEM Command

The TANDEM command includes several new changes in this release.

  1. Input handling

    In previous releases, if the tandem slave was sleeping at an INPUT statement, then the tandem master could not interrupt the INPUT statement. This could often render the use of TANDEM less useful.

    With this change, once a tandem slave allows a future session (see below), then all INPUTs will have a maximum of 60 second timeout allowing a tandem master to interrupt with a maximum of a 60 second wait. Although the tandem slave process is continually doing timed out inputs, the application will not see this and will behave as normal.

  2. Future TANDEM Sessions

    A slave terminal can allow a future TANDEM session by executing one of the following commands: TANDEM ON; TANDEM SYSPROG; or TANDEM (N).

    All these 3 variants allow an optional numeric parameter to determine the timeout to apply during INPUT statement processing. The default is 60 seconds, as noted earlier. For example, to change the INPUT timeout to 10 seconds, you can do one of the following: TANDEM ON 10, TANDEM SYSPROG 10 or TANDEM 10 (N).

    By choosing a lower timeout value, it means that when a tandem master is initiated, if the slave is processing an INPUT statement then the master has to wait less time for an initial response. The downside of a lower timeout value is a marginal increase in CPU overhead during INPUT processing.

    Note that once the master has initiated a sequence with the slave, this timeout value no longer applies -it is purely for the initial connection.

  3. “(A)” Option

    The (A) option allows you to use <CTRL-A>as a sequence identifier instead of the ESCAPE key. For example, normally when you start a master sequence you do this SYSPROG:TANDEM 6 TANDEM to port 6 in VIEW ONLY mode. To exit TANDEM, enter ESC + “X”

    With the (A) option, the ESCAPE is replaced with <CTRL-A> so to TANDEM enter <CTRL-A> “X”.

  4. Input History Buffer

    A Tandem slave now keeps the last 20 INPUT statements in a circular buffer. The master can now see this history using the ESCAPE + “H” sequence (or <CTRL>A + “H”if the “(A)” option is in use). This will allow an operator to get some idea of what the slave process has recently been doing.

  5. Terminal independence in MultiValue is obtained using calls to CommandInit() and CommandNext(). These allow an application to easily interpret characters from keyboards. For example if you press an arrow key on some keyboards, instead of returning 3 characters (CHAR(27):“[A”) it would return an identifier saying "CURSOR UP". These functions did notwork very well when using TANDEM and the program would instead see 3 characters. This has been fixed now. The MultiValue editor JED uses these commands, and so now you can JED edit an item using TANDEM.

  6. Double Echoed Characters

    Due to an error, when a tandem master was in FEED mode (that is, sending keystrokes to the slave terminal), then these keystrokes would double-echo on the master terminal. This has now been fixed.

SP-ASSIGN Command Line Syntax Changes

This release makes slight changes to the syntax of the SP-ASSIGN command make it more compatible and remove anomolies:

  • The method of specifying the channel and associated form queue name can no longer have spaces. For example,


    must now be represented as

  • Any numeric on its own in the statement will define the number of copies. For example,


    is now interpreted as assigning channel 0 (as it is not defined) to STANDARD and requesting 3 copies of the output.

  • A standard form queue name format is supported across all emulations.


    now means for channel 5, assign form queue 3 with options H (Hold) and S (Skip).

  • The options on the command line can now be passed in parenthesis, for example,


    is the same as

Rebuilding Indices From Prior Releases

Multivalue users who upgrade their applications from a release prior to 2012.1 to 2012.1 or later may experience a slowdown in CMQL queries that had previously made use of an index. Previously, CMQL assumed the collation for left-justified strings was SPACE. It is now SQLSTRING(150). This will not match an existing index that was created with the previous default of SPACE collation.

To correct this issue, use studio to edit the class associated with the multivalue file and change the COLLATION parameter to SQLSTRING(150) on all properties that are used as index keys. Then rebuild the affected indexes.

Changes To Transaction Lock Handling

In previous releases, committing a transaction would release all locks held on the records involved. Beginning with this release, that behavior has changed. It now follows these rules:

  1. Any operation that creates or frees a lock during a nest of transactions will have any release of the lock delayed until execution of the COMMIT or ROLLBACK that exits the outermost transaction in the nest. Furthermore, any lock that is promoted from SHARED lock type to EXCLUSIVE lock type during a nest of transactions will have any demotion of that lock delayed until the exit from the outermost transaction in the nest.

    This behavior will be followed without exception, even in preference to subsequent rules.

  2. Numbered or named locks that are created and freed by the MVBasic LOCK and UNLOCK statements are not incremented. You can do any number of “LOCK 2” statements, but a single “UNLOCK 2” statement will free lock number 2.

    None of the file locks or the record locks are incremented.

  3. If a FILE or RECORD is locked with either the SHARED or EXCLUSIVE lock type on entry to an outermost transaction, then on exit from the outermost transaction (with either a COMMIT or a ROLLBACK) that FILE or RECORD will still be locked with the same lock type.Locks promoted from SHARED to EXCLUSIVE inside the transaction nest will be demoted when the nest exits. Locks newly created inside the transaction nest will be freed when the nest exits.

    Nonetheless, the following exceptions apply to this rule:

    1. If a FILE was CLOSEd during the transaction, then all FILE and RECORD locks on the closed file are released on exit from the outermost transaction.

    2. Executing either “FILEUNLOCK fvar” or “RELEASE fvar” (but not “RELEASE fvar, recid”) will free the file lock AND all record locks on the file referenced by fvar. If this occurs during a transaction, the locks will be released when the outermost transaction exits.


Delaying unlocking until the outermost transaction is a feature of the Caché implementation. Most legacy MultiValue implementations only delay the release or demotion of a newly created or promoted lock to the exit of the nested transaction level where the creation or promotion took place.

MV Spooler Changes To Named Queue Form Numbers

The Caché MultiValue spooler attempts to serve emulations where the spooler form queue is usually numeric as well as platforms where the spooler form queue is a name. For example we support “F23” (interpreted as form queue number 22) and “CANONLAB” (interpreted as a form queue name CANONLAB and internally represented by a form queue number assigned automatically and starting at 2 — STANDARD is always form queue 1).

The result of this practice is that there are cases when this automatically generated form queue number clashes with form queues that have explicit numbers.

Starting with this release, all named form queues created will default to a form queue number from 1000 upwards. That is,


    creates a new form queue table.


    will create a named form queue whose number is allocated starting at 1000 (in this case it will be 1000) .

  • SYSPROG: SP-CREATE F20 LPTR /dev/lp20

    will create a numbered form queue whose number is 20 but is also allocated a form queue name of F20.

If you wish to change the starting point from the default 1000, then you can add this as an option to the SP-NEWTAB command line with the (Qnnnn) option. For example, to start allocation of named form queues at number 400, do this


Any MultiValue application that creates named form queues and expects these form queues to have exact form queue numbers will fail; the default form queue number for new named form queues is now 1000 instead of 2. To resolve this, the developer must either remove that association from the application or use "SP-NEWTAB (S1)" to give results compatible with prior to this change.

Terminating A Process Now Runs Normal Wrapup Tasks

In this version, terminating a MultiValue process from the Management Portal now forces the process to perform the normal MultiValue wrapup tasks before halting.

Studio Will Not Overwrite Catalog Pointers In VOC That Point To A Different File

The MultiValue compile and catalog operation in Studio will no longer overwrite the catalog pointer if the existing catalog pointer refers to a program from a different file.

Correct MVR collation Generation For Long Embedded Numbers

In prior versions, MultiValue right-justified collation (MVR) generated incorrect keys for mixed alphanumeric values containing more than eight digits in a row and where the digit string followed a non-numeric character. This release correctly generates the keys.


All indexes based on right-justified fields with collation MVR that may contain mixed alpha numeric fields with an embedded sequence of more than eight digits should be rebuilt. This does not affect fields that are purely numeric or numeric with a non numeric suffix.

DATA Statement Changes

Prior to this release, the input stack would only contain the line from the last DATA statement. Multiple DATA statements will now stack multiple lines in PARAGRAPHS

Directory Copy Uses Binary Mode

The MuliValue COPY command will now copy items in binary mode when both the source and destination are directories. Previously the items were processed to convert between AMs and newlines. The current behavior now copies directories unmodified to the destination.


Only “–>” Allowed For Object Component Access

The MV BASIC compiler would sometimes accept the dot, “.”, character in places where an right-arrow token, “–>”, should have been used for access to the property or method of an object instance. This was true even though the MVBASIC language definition permits dot, “.”, to be used only as an identifier character.

Beginning with this release, the MVBASIC compiler always interprets the “.” as part of a name. Those developers who incorrectly copied COS or Cache BASIC examples of object references using “.” into their MVBASIC programs will have to recode those examples to use “–>” instead.

Correct Processing Of @XXX–>Component

In prior versions, macro substitution was improperly done on names following a system variable and “–>”. In this release, the component name is properly associated with the system variable. This means that in the sequence

EQU UserId Lit "X->UserId" 
X = "MV.TestClass"->%New() 
X->UserId = 2 

the last two lines would previously have been interpreted as

X->UserId = 2 

but now are processed as

X->UserId = 2 
Change Handling Of Substitution With –>

Previously, names which were part of a “A–>B–>C...” sequence were not expanded if they were defined using EQU. This was only true if no whitespace separated “–>” from a name (before or after). Now only names which follow “–>” are not expanded; the sequence, “–>”, coming after a name no longer inhibits EQU definition expansion. Whitespace between “–>” and a following name does not affect the inhibition of EQU definition expansion.

This means that the lines

EQU UserId Lit "X->UserId"
CRT UserId
CRT UserId->UserId
CRT UserId->UserId->UserId
CRT UserId -> UserId -> UserId
X->UserId = 2

used to result in

CRT X->UserId
CRT UserId->UserId
CRT UserId->UserId->UserId
CRT X->UserId -> X->UserId -> X->UserId
X->UserId = 2

but starting with this version they become

CRT X->UserId
CRT X->UserId->UserId
CRT X->UserId->UserId->UserId
CRT X->UserId -> UserId -> UserId
X->UserId = 2
Identifiers Can Start With $

Previously, MVBASIC identifiers starting with a dollar sign, “$” could only use letters as the remaining characters of the identifier. This restriction has now been lifted and any legal identifier character can be used after the dollar sign that starts such an identifier.

However, InterSystems reserves MVBASIC identifiers of the form $SYSTEM.XxX, where the letters “SYSTEM” in the identifier prefix may appear in any combination of upper and lower case, but the identifier characters following the “$System.” prefix are case-sensitive. An MVBASIC identifier of the form “$System.XxX” is treated as the name of the system package, and the $System.XxX identifier may be followed by a right-arrow token, '->', then a method name and then a method argument list in order to call the appropriate method in the system package.


Package names using the $System.Xxx identifier syntax cannot have a blank before or after the dot characters that are part of the identifier. Previously,it was possible to put white space following the package name prefix. Programs that previously contained such white space must now be modified to remove the white space that follows any dot characters used in package names.

Change Triggers On WRITEV

Previously, when a WRITEV statement was executed on a file with WRITE, INSERT or UPDATE triggers, the record passed to the trigger routine consisted of just the attribute value to be modified rather than the entire record to be modified. This has been fixed and now these triggers get the entire record when a WRITEV modifies an attribute in that record.

Trigger routines executed because of a WRITEV statement that depended on being the passed record containing only the attribute to be modified must be rewritten. The passed record contains the entire record that will be modified and the attribute number so it can extract and/or modify the particular attribute value that will be modified.


Trigger routines that do additional I/O on the file containing the trigger must now be prepared for recursive calls on the trigger routines and must protect against infinite recursion.


Previously in MVBASIC, when a READV statement was executed on a file with a POSTREAD trigger just the attribute being read was passed to the trigger routine rather than the entire record containing that attribute. This has been fixed and now POSTREAD trigger routines always get the entire contents of the file record being read.

Also previously, any active trigger routine on a file disabled calling any additional triggers on that file while that trigger routine remained active. This prevented trigger routines from being called recursively. Now none of the triggers will disable additional trigger calls during the execution of trigger routine.


The trigger routine is not passed the attribute number as an argument so the attribute number must be passed by other means if the trigger routine needs to extract and/or modify the particular attribute value that will be read by the READV statement.


Trigger routines that do additional I/O on the file containing the trigger must now be prepared for recursive calls on the trigger routines and must protect against infinite recursion.

SETTING Clause Processing Changes

Before this release, an MVBASIC I/O statement which included a variable in a SETTING clause was setting that variable to the I/O error status after executing any THEN, ELSE or ON ERROR clauses.

This had two bad effects. First, the variable in the SETTING clause could not be tested in the THEN, ELSE or ON ERROR clauses. Second, any I/O operation executed by the THEN, ELSE or ON ERROR clauses of the current I/O statement would override the status that would be stored into the variable specified by the SETTING clause of the current I/O statement.

The MVBASIC compiler now generates code to store the I/O status into the variable specified by a SETTING clause before executing any THEN, ELSE or ON ERROR clauses.

I/O Statements Now Clear $MVSYSRETCODE On Success

Previously, most I/O statements did not zero @SYSTEM.RETURN.CODE when starting a new I/O operation. This meant that any I/O statement with a SETTING clause that executed without any I/O error would leave behind the previous error code that was still left over in the system variable @SYSTEM.RETURN.CODE. Now, @SYSTEM.RETURN.CODE is reset to zero just before executing any I/O statement.

More Emulations Have HEADING Statement

In this version, for the emulations jBASE, Reality, Unidata, Udpick, Information, and Piopen, when a second or subsequent HEADING statement for terminal output is executed, it takes effect immediately.

For the other emulations, the second or subsequent HEADING statement will not have any immediate effects until the terminal executes a page break; this is when the HEADING statement is used.

Duplicate Names Not Allowed In DIM Statement

Previously, the MV BASIC compiler allowed a name to be defined more than once in the same DIM statement. For example,

DIM X(), X();

was permitted. Under some circumstances this results in a corrupted symbol table that could crash the process doing the compilation.

Now such statement will generate a compile-time error message and the redundant symbol definition must be removed from the DIM statement. The compiler does allow a name to be redefined multiple times in separate DIM statements providing the name as not been defined as a COMMON name.

xDBC Changes

Automatic Conversion Of Long Strings To Streams Removed

It previous versions, applications could ask that literal strings longer than 16K to be automatically converted to character streams. While this supported INSERTs and UPDATEs, queries never supported streams in this way for literal values.

Now that Caché supports long strings in ODBC, the previous functionality is no longer needed. Applications that need to support huge literal string values in SQL statements should make sure that Caché has long strings turned on.

Change To Null Parameter Handling

Beginning in this release, Caché conforms to the Microsoft documentationOpens in a new tab regarding null parameter values, namely, when you send a null parameter value to the server, you must specify DBNull, not null. The null value in the system is an empty object that has no value. DBNull is used to represent null values.

Prior to this, Caché had been treating null and DBNull the same,, but the mapping for parameter values are as follows in terms of the $list values sent to Caché. The only change is for a null to specify a default value.

null 01 default value
DBNull 02 01 null value
“” 03 01 00 empty string

This changes makes the behavior of Caché consistent with the ODBC native provider, and all other ADO providers in terms of null Parameters representing default values.

Accomodate New SQL Server Mappings

This version changes the JBDC mappings for varbinary and nvarchar (BLOB and CLOB, respectively) to use streams in accord with changes in Microsoft SQL Server version 2008.

SQLBindParam API Removed From ODBC

SQLBindParam is an older 2.x API that Caché added with Version 3.5 release. However, it conflicts with SQLBindParameter which was present then as well and its presence ended up causing problems with iODBC driver manager. It has been removed from this versionof Caché to allow iODBC to function correctly by calling SQLBindParameter with the proper arguments.

Support Binary In %SQL.Gatway.ODCResultSet

In previous releases, binary values returned by queries were converted to the corresponding ASCII values (visible in linked stored procedures). Beginning with this release, binary values are returned as is.

DeepSee Changes

Changes To Filter Handling In Pivots

In prior versions,

  • Multiple valued filters – If you added 2 filters from the same hierarchy and level (for example, DateOfSale.Actual.YearSold.Members), both filters would display on the filter bar, but only one value was used in the query.

  • Single valued filter – Multiple single valued filter from the same hierarchy and level (DateOfSale.Actual.YearSold.2009 and DateOfSale.Actual.YearSold.2010) were logically ORd together.

Now, in both cases, they are logically ANDed together. This is an improvement in several ways:

  1. It makes all filters consistent – all filters in the filter bar are now ANDed together with no exceptions.

  2. For list-type levels, it lets you filter on combinations (such as allergy on mites AND dessert toppings).

  3. It removes a lot of "Why do I get multiple counts when I add more filters" questions.

DeepSee Key Values Now Checked For Illegal Characters

KEY values for DeepSee members may not contain the characters “|”, “&”, “~”, or “:”. In previous releaqses this was not explicitly checked. Beginning with this release, attempting to build a cube with illegal KEY values will result in a validation error.

Improved Expression Checking

An expression or scalar function on a SET, such as,


does not make sense. In previous version, executing the expression would give a nonsense answer. Now, it will return an error.

Add %DeepSee.ReportBuilder Resource For Access Control

In this release, a new resource has been added which grants access to the DeepSee Visual Reporting Report Builder. Users and applications that wish to access this functionality must now have %DeepSee_ReportBuilder and a valid license for the feature, or they will be denied access.

CSP Changes

Define Logout Handling

Beginning with this release, the recommended way to logout of a CSP session is to link to the application home page passing a URL that contains the string, “CacheLogout=end”. This will end the current session – release any license acquired, delete existing session data, remove the security context of the session – before it attempts to run the home page.

If this CSP application requires authentication, there will be no session and no authenticated user. In this case, Caché will not run the home page logic but will display the login page instead. When the user submits a valid login, this will start this new session and then display the home page.


In this release, the class %CSP.PageOpens in a new tab now has an additional class parameter, SECURITYRESOURCE which controls access to the page. The value of the parameter is a comma-delimited list of system resources and associated permissions. A user must hold the specified permissions on the specified resources in order to view this page or invoke any of its server-side methods from the client.

The format of each item in the list should be as follows:


Resource is a registered system resource. Permission is optional, and defaults to USE if not supplied. If it is supplied, it must be one of USE, READ, or WRITE.

You can also specify OR grouping using the “|” character, so


means you must have resource ResA, and one of ResB or ResC, and one of ResC or ResD. So if you have ResA and ResC, you will have access. If you have ResA1 and ResD, you will not since the ResB or ResC condition is not met.


The “|” binds more tightly than “,”.

Application Access To %CSP Pages Now Controlled

Beginning in this release, application access to arbitrary %CSP pages (and their subclasses) can now be better controlled. By default, the new rules allow a user application to access:

  • All non-% classes

  • Pages of the /csp/sys/ application and all its subapplications.

  • Pages of the isc/studio/templates/ and /isc/studio/usertemplates/ applications.

and also explicitly to the following classes:

  • %CSP — Broker, StreamServer, Login, PasswordChange, PageLookup

  • %ZEN — SVGComponent.svgPage, Dialog.*

  • %Z* and %z* — all are allowed except for the %ZEN.* pattern other than the specific exceptions allowed for %ZEN already mentioned

This checking is performed in addition to any “Permitted Classes” checking defined for this CSP application. So a class reference must pass both sets of tests in order to be allowed.

An administrator can permit access to additional classes by configuring the global, ^SYS(“Security”, “CSP”, <category>) in the %SYS namespace by using the AllowClass, AllowPrefix, and AllowPercent keywords. The following sections describe these keywords.


Checking is done by applying the default rules first, then the categories in the order listed. This permits making an entire package accessible, except for one class in the package whose access is restricted.

Category: AllowClass

If your application relies on invoking a particular class, the AllowClass keyword creates an exception for that class and makes it available.


If your application relies on invoking any class other than those listed above, it could potentially be unsafe to use. InterSystems recommends that you determine if calling this class is required, and have performed a risk assessment for your deployment, so that you understand the implications of making the class available.

To create an exception for a particular class, set the ^SYS global subscript to a value of 1 as follows:

Set ^SYS("Security", "CSP", "AllowClass", "<web-app-name>", "<package.class>") = 1

where entire body of the command – except <web-app-name> and <package.class> – is used in the exact form as it appears here. For the variable content of the command:

  • <web-app-name> is the web application’s name as it appears on the Management Portal’s Web Applications page in the Name column.

  • <package.class> is the name of the class being allowed.

Setting the data value of the global to 0 specifies explicitly that Caché does not permit access to the class.

For example, to allow a specific classname (in this case, %User.Page) to be called from a /csp/webapps/ application, the command is:

Set ^SYS("Security", "CSP", "AllowClass", "/csp/webapps/", "%User.Page") = 1

To allow, for example, the %User.Page class in all CSP applications, the command is:

Set ^SYS("Security", "CSP", "AllowClass", 0, "%User.Page") = 1 
Category: AllowPrefix

If your application relies on invoking one or more classes or packages that begin with the same set of characters, the AllowPrefix keyword creates an exception for those packages or classes and makes them available.


If your application relies on invoking any class other than those listed above, it could potentially be unsafe to use. InterSystems recommends that you determine if calling this class is required, and have performed a risk assessment for your deployment, so that you understand the implications of making the class available.

To create an exception using the AllowPrefix keyword, set the ^SYS global subscript as follows:

Set ^SYS("Security", "CSP", "AllowPrefix", "<web-app-name>", "<prefix>") = 1

where the entire body of the command – except <web-app-name> and <prefix> – is used in the exact form as it appears here. For the variable content of the command:

  • <web-app-name> is the web application’s name as it appears on the Management Portal’s Web Applications page in the Name column.

  • <prefix> is the beginning of the package or class names being allowed.

Setting the data value of the global to 0 specifies explicitly that Caché does not permit access to the relevant packages or classes.

For example, to allow the entire %MyApp package to be called from a /csp/webapps/ application, the command is:

Set ^SYS("Security", "CSP", "AllowPrefix", "/csp/webapps/", "%MyApp.") = 1

In this case, adding the dot prevents access to any packages whose names begin with and are longer than “%MyApp”.

To allow, for example, all packages that begin with “%My”, the command is:

Set ^SYS("Security", "CSP", "AllowPrefix", 0, "%My") = 1 

As a further example, you can allow %MyPkg.*, but disallow %MyPkg.Class1 in the /csp/samples/ application by setting:

Set ^SYS("Security", "CSP", "AllowClass", "/csp/webapp/", "%MyPkg.Class1") = 0 
Set ^SYS("Security", "CSP", "AllowPrefix", "/csp/webapp/", "%MyPkg.") = 1

Category: AllowPercent

If your application relies on invoking the packages that begin with the % character generally, the AllowPercent keyword creates an exception for those packages and makes them available.


If your application relies on invoking any class other than those listed above, it could potentially be unsafe to use. InterSystems recommends that you determine if calling this class is required, and have performed a risk assessment for your deployment, so that you understand the implications of making the class available.

To disable %-page checking totally in all CSP applications:

Set ^SYS("Security", "CSP", "AllowPercent") = 1

Setting the data value of the global to 0 specifies explicitly that Caché does not permit access to the percent packages.

Special Case: DeepSee

For a web application to use DeepSee, it needs access to all the classes in the %DeepSee package. By default, only the “/csp/samples” web app is set to allow Deep See access. If you want to use Deep See in any other web app, you must explicitly allow it.

For example, to enable the /csp/webapp web application to use DeepSee, the syntax is:

Do EnableDeepSee^%SYS.cspServer("/csp/webapp/")

which is the same as

Set ^SYS("Security", "CSP", "AllowPrefix", "/csp/webapp/",  "%DeepSee.") = 1
Set ^SYS("Security", "CSP", "AllowClass", "/csp/webapp/",  "%CSP.UI.Portal.About") = 1

To allow all web applications to use DeepSee:

Do EnableDeepSee^%SYS.cspServer(0)

which is equivalent to:

Set ^SYS("Security", "CSP", "AllowPrefix", "",  "%DeepSee.") = 1

If you have enabled Deep See access for all web apps and you want to disable it for a specific web app, you should set the global to a 0 value as shown in this syntax:

Set ^SYS("Security", "CSP", "AllowPrefix", <web-app-name>, "%DeepSee.") = 0

This is only for DeepSee versions released with Caché version 2011.1 or later – that is, only for what was previously known as “DeepSee II”. If you are using a version of DeepSee released prior to Caché 2011.1 even on a version of Caché that is more recent, there is no issue.

Special Case: iKnow

For a web application to use the sample UI pages for consulting or managing iKnow data, access also needs to be granted explicitly as follows:

Do EnableIKnow^%SYS.cspServer("<web-app-name>")

To disallow an application from using iKnow, the syntax is:

Set ^SYS("Security", "CSP", "AllowPrefix", <web-app-name>, "%iKnow.") = 0

Granting or disallowing access for all web applications works analogously the way it is done for DeepSee.

Translation For JS and JSML Changed

The EscapeURL(url) function of %CSP.PageOpens in a new tab first encodes a URL using the current device charset; then it escapes this using the standard encoding for URLs.

If the current device is set to the JS or JSML translate table, this function converts “/” characters into '%5Cx2F' with the result that the URL no longer functions correctly.

Zen Changes

Improve Parsing Of #(...)# Expressions

Zen allows for expressions in values of the form #(<object>.<propname>)#. In this release, the Zen compiler will only allow the names of properties to be used in place of <propname>.

ZenMethod Keyword Now Enforced

In the very early versions of ZEN, there was no ZenMethod keyword; Zen overloaded the WebMethod keyword for this purpose. Beginning with this release, support for the WebMethod keyword is now removed. Applications that use WebMethod must be changed to use ZenMethod instead.

ZenMethods Can Only Be Called From The Current Page

If a Zen class defines a ZenMethod, this method can now only be called from the client/browser.

You can define a security resource (using a class parameter) for a given Zen page. This prevents any methods on this page from being invoked unless the user has Use permission on the resource. Hence, any Zen methods defined on that page can only be called from methods on that page.


Zen methods of Zen components can be called from any page. Thisis due to the dynamic nature of Zen – pages can create instances of any compnent as needed at runtime. This means that care must be taken when creating new Zen components containing server-side methods.

Fix Parsing Of Escaped Data In Zen jsonProvider

The Zen jsonProvider component was correctly escaping data on output, but was not unescaping the same data on input. This change updates the parser to correctly handle the following escape sequences defined in RFC 4627:

 \/   \r   \n   \f   \b   \t

Furthermore, the escape sequences for Unicode values are also converted into the raw Unicode characters on input. The jsonProvider parser will now automatically convert escape sequences of the form \uXXXX to the character representation of the specified Unicode code point.


This may cause problems for 8-bit Caché systems where incoming data containing code points beyond \u00FF, as the conversion process will now produce wide characters.


This version of Zen significantly updates the chart functionality in the following areas:

  • Use of real coordinate space – new render logic computes the scaling factor in the x and y dimensions and saves these in local properties so that other rendering methods can see them.

  • Label positioning – You can now place x-axis labels on the top or bottom.

    You can now place y-axis labels on the right OR left.

  • Time-based x-axis – It is possible to use a time line as the x axis for certain chart types (namely line, bar, and combo). This draws a set of calendar markings for the x axis between a start time and an end time.

  • Subtitles – Chart may now have a subtitle.

  • New zoom buttons and styles


Applications that subclass charts will need to be changed to use the new superclasses. Applications that do not use the default setttings may need to modify their styles for existing charts to achieve the desired visual effects.

Zen Reports Changes

Zen Report Must Use %SQL.Statement For Result Sets

As of this release, %ZEN.Report.ResultSet has been deleted. Zen report data generators and collectors should use %SQL.Statement instead for proper results. To define the method as an SQL stored procedure, use the method keyword, “sqlproc”.

Change To Multiple Line-Feed Handling

In prior releases, a sequence of multiple line-feeds sent to the output would ignore any after the first. To have multiple line-feeds appear in the PDF output, one must do the following:

  • On the table set preserveLineFeed=“true”, or

  • If the items are not in a table, put them in a block with linefeedTreatment=“preserve” as an attribute setting.

On the item set the following attribute as follows: breakOnLineFeed="true"

Automatically Provide Unique Sheet-Names For Excel

Zen Reports no longer takes the sheet name from the group name. Instead, it now automatically provides unique sheet-names for Excel.

When generating multisheet output for Excel, each sheet must have a unique name. This may be done by specifying an expression in “excelSheetName”. By default (that is, when excelSheetName is not specified), each sheet in a multi-sheet report be given a unique sheet name using the same default names Excel uses for sheets: "Sheet1", "Sheet2", etc.

If any application is depending on our taking the sheet name from the group name they can use excelSheetName to set the sheet name equal to the group name.

Changes To ongetXXX Method Handling

Beginning with this release, the ongetXXX methods now pass a chart object as the final argument of the method. This allows the callback methods to access properties of the chart such as id.

A ZEN Report chart on a chart callback method that worked in prior releases will now get a parameter error. There are two ways to work around this situation:

You can work-around this parameter error two ways:

  • You specify passChartObject=“false” on the chart. This tells the code not to pass the chart object.

  • You can modify the callback method to accept a final parameter which will be the chart object when ZEN Reports calls back the call back.

%ZEN.Report.ResultSet Removed

In this release, %ZEN.Report.ResultSet has been removed. Applications using %ZEN.Report.ResultSet must define their own ResultSet class to emulate its functionality, for example,

Class MyResultSet Extends %Library.ResultSet {

    Method %Get(name As %String) As %String [ ProcedureBlock = 1 ] {
        if (name '= "") && ($Data(i%Data(name))) { 
            set rReturnValue = $get(i%Data(name)) 
    else  {
        s rReturnValue=""
    quit rReturnValue

Two-Dimenional Arrays In CallbackTables Are Now Zero-Based

Beginning with this release, callback tables will now be zero-based to make them consistent with callback charts. For example,

<table callBackMethod="NamesAndAddresses">
    <item fieldnum="1" suppressDuplicates="true">
         <caption value="Name"/>
     <item fieldnum="2">
         <caption value="Address"/>

will be interpreted as

Method NamesAndAddresses(ByRef var As %String) 
    // record of names
    // record 1
    Set var(0,0)="Santa Claus"
    Set var(0,1)="North Pole"
    // record 2
    Set var(1,0)="Zeus"
    Set var(1,1)="Olympus"
    // record 3
    Set var(2,0)="Robin Hood"
    Set var(2,1)="Sherwood Forest"
    // record 4
    Set var(3,0)="Robin Hood"
    Set var(3,1)="Nottingham"

FeedbackOpens in a new tab