Skip to main content

Caché 2010.2

This chapter provides the following information for Caché 2010.2:

New and Enhanced Features for Caché 2010.2

The following major new features have been added to Caché for the 2010.2 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 Upgrade Checklist.

Rapid Application Development

Java Event Processing

This version of Caché introduces several new high performance Java integrations. Each is enabled by the modular in-process Caché kernel. Java can now communicate with Caché on the same computer process-to-process enabling extremely high data access rates.

A standard JNI (Java Native Interface) is used for the Java and Caché integration. In Java JDK 1.6 and beyond, we use the Java NIO features to leverage the evolution of speed and stability in JNI and thus provide:

  • MDS – Multi-dimensional data storage

    This is a raw low-level API to access Caché globals. It is the fastest way to do data access (store / retrieve) between Java and Caché. The API provides support for transactions, locking, iterators, and other features; however, it does not directly enable SQL or object support. The API can be used in multi-threaded environments.

  • XEP – Extreme Event Persistence

    XEP provides a lightweight Object API on top of MDS. It enables an application to use a lightweight restricted SQL dialect for fast queries and also provides traditional full SQL in support of complex queries. XEP makes use of the transaction and multi-threaded support built-in via MDS.

  • In-Process JDBC

    This feature enables JDBC to run over JNI instead of TCP when the Java virtual machine and Caché are running on the same machine.


To complement the Caché implementation of WS-Security, and to support general security requirements, this release now provides the most common elements of the WS-Policy and allows users to easily define policies for existing Web Services.

Soap Configuration Wizard

This wizard assists in the creation of a configuration class that applies to a selected Web Service or Web Service client class. This configuration contains WS-Policy expressions that describe the capabilities and requirements of that service or client. These expressions can refer to WS-Security, WS-Addressing, and MTOM.

MultiValue Indexing Improvements

This version of Caché contains major changes to ensure better coordination between the MV index verbs (for example, CREATE.INDEX) and PROTOCLASS. The core property definition code from PROTOCLASS and CREATE.INDEX has been combined into a common class method, %SYSTEM.MV.createMVProperty to ensure that the same property definition is created by either facility. In addition, all functions, commands and verbs that use the name of an index will now use the real name of the index as a preferred alternative to the mangled name generated from the name of the source attribute. This includes the functions:

and the commands:

Furthermore, errors in any of these should now produce better diagnostic messages.

CREATE.INDEX and PROTOCLASS will both add a new parameter to any properties that they create so that DELETE.INDEX and re-execution of PROTOCLASS know that the property was a generated property and can be modified or deleted by them.

Performance And Scalability

DB Expansion Improvements

Previously, the Expansion Daemon (EXPDMN) would expand a database by allocating new blocks in 64KB chunks. While this algorithm worked well for smaller expansions, InterSystems found that larger expansions (>50 MB) would take longer than expected; in some cases, it could interfere with the read performance on the system.

Now, for expansions larger than 1MB, the EXPDMN has been enhanced to not only issue larger writes, but to use a sliding-scale expansion algorithm. The new algorithm performs writes with the following schedule: two 1MB chunks followed by one 2MB chunk followed by 4MB chunks till the requested expansion is complete.

Large Local Arrays

In previous releases, the performance of operations on local arrays could worsen as the array grew larger. This version of Caché implements a highly optimized algorithm for handling large local arrays that greatly speeds up performance when saving and retrieving values from such large in-memory (local) arrays.

Improved Dejournal Performance

Dejournal performance has been improved in this version of Caché by reducing the amount of contention between dejournal pre-fetcher jobs. This is achieved mainly by providing each pre-fetcher job a larger list of journal entries to process. In addition, each pre-fetcher process now works on approximately 100 chunks of the journal file at a time.

$PIECE/$FIND Performance Improvements

The $PIECE and $FIND functions have been enhanced to speed up the process of finding the delimiter or the search string within a string by utilizing SSE2 instructions present on all x64 processor chips

ZEN Reports Using HotJVM

In this release, the handling of the Java Virtual Machine (JVM) for Zen Reports has changed. In prior versions, Caché would

  • Instantiate an instance of a JVM in the process handling the request

  • Run the rendering application in this JVM

  • Collect the final PDF

  • Terminate the JVM

Beginning with 2010.2, the system starts a dedicated back-end process along with the other CSP server-side daemons. This process instantiates a Java Virtual Machine (JVM) and handles all report generation tasks returning the result PDF. The JVM is never closed. This approach (avoiding the startup and shutdown costs) results in significant reductions in the time needed to produce a report.

Reliability, Availability, Maintainability, Monitoring

Caché Database Mirroring

Traditional availability and replication solutions often require substantial investment in infrastructure, deployment, configuration, and planning. Caché database Mirroring is designed to provide an economical solution for fast, reliable, rapid, robust, automated failover between two systems, making mirroring the ideal automatic failover and high availability solution for the enterprise.

Caché Mirroring not only provides an availability solution for unplanned downtime, but also offers the flexibility to incorporate planned downtimes (for example, Caché configuration changes, hardware or operating system upgrades) on a particular system without impacting the overall SLAs for the organization. Combining ECP application servers with Caché Mirroring provides yet an additional level of availability; application servers simply treat a failover as an ECP server restart, and allow processing to continue on the new system once the failover is complete, thus greatly minimizing workflow and user disruption.

By maintaining independent components on the two failover systems, Caché Database Mirroring also reduces the potential risks associated with physical replication, such as out-of-order updates and carry-forward corruption, which are sometimes present in traditional shared-resource failover technologies.

Caché Mirroring also introduces the mirror shadow which can be configured either as a reporting shadow or a disaster recovery (DR) shadow – a reporting shadow can be used for enterprise-wide reporting and business intelligence (BI) purposes; a DR Shadow, which is an up-to-date read-only copy of the production system, can be used as an integral part of an enterprise disaster recovery and business continuity plan.


This release adds several Web Service methods to allow monitoring of remote Caché systems via Web Services. The methods are all contained in the SYS.WSMon.Service class, which also includes the details of the implementation.

Database Compaction

This version of Caché includes a Database Compaction utility which compacts a database file by moving free-space from within the file to the end of the file. Once this process is complete, it is possible to run the existing Database Truncation utility to return this free-space to the underlying file system.

Cache Database

In this version, InterSystems adds a new database to support operational storage requirements of the engine itself. The Cache database will be used to store information like cached queries, or session-related information. At startup, this database is mounted as read-write; no customer application should directly interact with it. Please refer to the System Administration information for further details.

Caché Database Blocksize Conversion

This release offers a new class method, SYS.Database.Copy(), that customers can call as part of their application deployment scripts. It allows the specification of the database blocksize of the target database, and is a fast and efficient way to upgrade database files from the now-deprecated 2K block format. For details and options refer to the class documentationOpens in a new tab.


Two-factor Authentication

Starting with this version of Caché, InterSystems provides two-factor authentication as an added security feature during login for client/server applications, console, and terminal. With two-factor authentication, after authentication using the selected mechanism (such as Kerberos or Caché login), Caché sends a security token to the registered mobile phone of the user. To gain access to Caché, the user must then enter the token at a prompt. This adds the possession of the registered mobile phone as a second factor, along with the secrecy of the user's password as the first.

Support for OpenAM

InterSystems has added support to allow Caché to use the OpenAM single-sign on (SSO) component. By using this feature, users that have already successfully authenticated do not have to re-authenticate. InterSystems has demonstrated interoperability with the OpenAM web policy agent, which allows Caché to determine the centrally authenticated ID of a user from the REMOTE_USER environment variable.

Encryption of Shadow Files

This augments the data-at-rest encryption provided by Caché. Journal data on the shadow will now also be encrypted if the shadow system is set up to use journal encryption. The primary server and the shadow server do not need to use the same key to encrypt data-at-rest (for example, database files). Each system will use the local key for this form of protection.

Caché 2010.2 Upgrade Checklist


The purpose of this section is to highlight those features of Caché 2010.2 that, because of their difference in this version, affect the administration, operation, or development activities of existing systems.

Those customers upgrading their applications from earlier releases are strongly urged to read the upgrade checklist for the intervening versions as well. This document addresses only the differences between 2010.1 and 2010.2.

The upgrade instructions listed at the beginning of this document apply to this version.


This section contains information of interest to those who are familiar with administering prior versions of Caché and wish to learn what is new or different in this area for version 2010.2. The items listed here are brief descriptions. In most cases, more complete descriptions are available elsewhere in the documentation.

Version Interoperability

A table showing the interoperability of recent releases is now part of the Supported Platforms document.

Management Portal Changes

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.

Operational Changes

New Database: CACHE

In this version, a new database has been added to the standard set used by Caché. The name of the database is “CACHE” and it holds information such as cached SQL queries or CSP session information. Please refer to the System Administration information for further details.


No customer application should directly interact with the CACHE database.


Those installations that have a pre-existing database with this name must change it, and the applications that reference it, before installing this release. If Caché discovers such a database at startup time, it will note this as an error message to the console log and shut down.

Collation And Resource Required For Database Mount

When mounting a database, Caché now checks to see that its default collation is available. If it is not, the mount fails. If this happens during the system startup and the database is marked as "mount required at startup", Caché will not start. In this case remove this requirement from the configuration and restart. A message is logged to cconsole.log indicating the database that failed to be mounted and its default collation.

Caché will also fail to mount the database if the resource specified for the database is not available. This may be an issue when upgrading older systems.

Automatic Upgrade To 8KB Database

When upgrading to this version, if the CACHESYS database block size is found to be 2KB, it will be automatically converted to 8KB during the upgrade.

Enabling SSL For Secure Communications

Caché can be configured to use SSL for securing its communications with external endpoints. A full administrative interface will be available in a future release. Sites wishing to enable this capability via low-level system settings should contactInterSystems Worldwide Customer SupportOpens in a new tab. Ask for the information on “Client-side SSL settings for Windows”.

Platform-specific Items

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

$ZF For OpenVMS Changed Privileges

An error that caused $ZF calls on OpenVMS systems to execute with more privileges than designed has been corrected. If this affects your application, please contact InterSystems Worldwide Customer SupportOpens in a new tab for assistance.

Java Not Supported On Tru64

In this version, Caché no longer supports version 1.4 of the Java VM. Unfortunately, this is the last supported version of the Java VM on HP Tru64 UNIX®. Customers who must have a working Java virtual machine should contact InterSystems Worldwide Customer SupportOpens in a new tab.

The only way at this time to get support for later versions of the virtual machine on Tru64 involves the customer compiling the OpenJDK sources using the GNU GCC toolset.

Windows Installations No Longer Contain Packet Drivers

Beginning with this version, the packet drivers (ispktd2k.sys) are no longer part of the distribution since DDP is no longer supported. This also removes support for LAT.


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.

General Operational Changes

Error Trapping Now Strictly Nested

In prior releases, when $ZTRAP was set with an asterisk as the first character, or set to %ETN, an error trap set with $ETRAP or TRY/CATCH at a deeper execution level would be ignored. Now the most recent error trap will always have precedence, that is, be invoked first after the error occurs.

Some Cases Of <MAXSTRING> Are Now <SUBSCRIPT> Errors

In this version Caché now correctly returns a <SUBSCRIPT> error when a lock subscript has an encoded string length greater than 256 bytes. Previously, such conditions resulted in an erroneous report of a <MAXSTRING> error.

Default $ZDATE / $ZDATEH Format Changed For Japanese Locale

The default date format for the Japanese locales is now 1 (was 3). This format is used by default with $ZDATE/$ZDATEH functions when locale formats are enabled. The format is changed by setting

New Locales Added For German

In order to facilitate the migration of sites using the German Latin1-based locale (deu8) to the equivalent Latin9-based one (dei8), the older German1 and German2 collations have been made available in dei8. Although these collations have the exact same binary encoding in dei8 and deu8, users should be aware that:

  1. Latin9 replaces 8 rarely used characters from Latin1 with new definitions: 164, 166, 168, 180, 184, 188, 189 and 190. The most visible one is $C(164) which is now the Euro sign. Subscripts from globals brought from deu8 which contain any of these characters will be displayed with the Latin9 interpretation of their binary values.

  2. German3 is the default collation in dei8. If a site requires German2 or German1 to be the default collation, it should set it during startup or a custom locale should be created with the desired default.

New Locale For Slovenia

A new Unicode locale for Slovenia is now available. It includes the Slovenian1 collation and its internal code is “svnw”.

Source Control Setting Now In ^%SYS

The setting to determine which source control class should be used in a namespace was stored in ^SYS("SourceControlClass") in the users database file, but this means that anyone with write access to this database can modify this setting. The value has been moved into ^%SYS("SourceControlClass", <namespace>); access to the CACHESYS database is needed to change this setting.

The ^%SYS("SourceControlClass", <namespace>) was always in the search path when looking up the source control class, so this will work on older versions of Caché. The change is that the method that updates the class will now set this node and clear the ^SYS("SourceControlClass") node.

Also when looking up the source control path, the locations examined have been changed to this order:

  1. ^%SYS("SourceControlClass", <namespace>)

  2. ^SYS("SourceControlClass")

  3. ^%SYS("SourceControlClass")

Routine Compiler Changes

Macro Preprocessor Return Values Changed

In this version, a change has been made in the macro preprocessor behavior when compiling code that contains SQL statements. Prior to this change if a SQL statement failed to compile, the preprocessor would report the error and stop; no code was produced.

The new behavior is to report the error but continue to compile the code and return the result to the caller of the preprocessor. When a SQL statement fails to compile, the generated code produced is

  X "** SQL Statement Failed to Compile **"

If the method or routine containing the erroneous SQL statement is ever run, the attempt to execute the SQL statement will result in an error message at runtime. This change means when compiling classes with methods that contain embedded SQL statements that fail to compile, the errors will be reported, but the methods will still be generated.


This behavior will not occur for a “&sql(DECLARE CURSOR ...)” statement because DECLARE CURSOR produces no code itself. Furthermore, this new behavior is not in effect when the Caché system compiles cached query routines.

Class Changes

BuildValueArray Now Marked As Final

Subvalue indexes can be defined using property elements and keys. If the property is a collection, the element values correspond to the elements of the collection and key values correspond to the position (for lists) or key (for arrays). For properties that are not collections, elements and keys correspond to subscripts and values as contained in a "value array". The value array is constructed by a property method, BuildValueArray.

If applications had overridden BuildValueArray, the results were ignored when the object was stored, and the index(es) were not updated. This is incorrect.

Beginning with this release BuildValueArray is generated automatically for collection properties and marked as Final; therefore, it cannot be overridden by subclasses.

%Text Parsing Of Hyphens And Negative Numbers Improved

This version of Cache' improves the parsing of hyphen/minus sign so that “–<digits>” is parsed as a negative number, and so that “–<digits>–” is parsed as a positive number (digits). In addition, complex non-numeric sequences such as “Section 3-4.2-2” are now parsed as “Section 3 4.2 2”; the sequence 3-4.2-2 is not treated as a numeric just because it contains all numeric characters.

These parsing differences in %Text.Text could cause the parsing of some numeric text sequences involving “–” to be treated differently; therefore, an index on such a field containing text like this should be rebuilt.

Changes To LogicalToStorage And StorageToLogical

LogicalToStorage and StorageToLogical are methods that can be implemented for properties, either in the datatype class or as an composite method in the class containing the property. (There is no requirement that both methods be implemented for a property, but if the method is defined then it must be executable.) LogicalToStorage method is invoked whenever a logical value is stored (placed in the serialized object in the case of a serial class, written to disk in the case of a persistent class). StorageToLogical is invoked whenever a stored (or serialized) property value is extracted from the stored object and placed into a logical container - usually the property's instance variable.

In previous versions, when applied to a collection, the target method was presented with the entire collection. In this version, the method will be called once for each element of the collection.

Changes To %SQL.StatementMetadata

The %SQL.StatementMetadata class models statement metadata for dynamic SQL statements. The metadata instance has an objects property that is a collection of instances that describe the characteristics of columns whose values are ID values referencing instances of some class. The structure of the StatementObject class has changed to allow for better linking between the StatementColumn and the StatementObject.

Previously, the StatementObject consisted of columnName, extentName and exportCall properties. The definition of StatementObject now includes a new property, column, that is an integer and it corresponds to the element number in the columns collection.

Class Deletions

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

  • Package %JavaScript – Object, Runtime

  • Package %SQL – StatementCache

  • Package %XSQL.DSI – JPAQuery

  • Package %cspapp.mgr – utilconfignethome, utilsysnetworklegacy

  • Package Config – DDP, DDPVolumeAndUCIs, DDPVolumeSets, DTMnetBIOS, ETHServers, LAT, LATServices, Config.MirrorReportingAuthorizedIDs, Config.MirrorReportingSources, Net, Servers, UDPServers

Class Component Reservations

The following class components have been reserved for InterSystems use and should not be invoked by customer applications.

Class Type Name(s)
%SYS.Journal.System Method SetPrimaryDirectory
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)
%CSP.Page Method %ClassName, %PackageName
%CSP.UI.DocLocalize Method Net
%CSP.UI.Portal.DatabaseFreespace Method GetSize
%CSP.UI.Portal.SSL Property PeerLevel0, PeerLevel1
%CSP.UI.Portal.SSLList Method DrawTitle
%Debugger.System Property DevOpen
%Dictionary.CompiledClass Property HasJavaScript
%Dictionary.ForeignKeyDefinition Property Origin
%Dictionary.IndexDefinition Property Origin
%Dictionary.MethodDefinition Property Origin
%Dictionary.ParameterDefinition Property Origin
%Dictionary.ProjectionDefinition Property Origin
%Dictionary.PropertyDefinition Property Origin
%Dictionary.QueryDefinition Property Origin
%Dictionary.StorageDefinition Property Origin
%Dictionary.TriggerDefinition Property Origin
%Library.IResultSet Method %GetMetaData
%Library.Persistent Method %OnDetermineClass
%Library.ProcedureContext Method %Display
Property LTT
%Library.RegisteredObject Method %ClassIsLatestVersion, %ClassName, %Extends, %GetParameter, %IsA, %OriginalNamespace, %PackageName
%Library.SerialObject Method %OnDetermineClass
%Library.SwizzleObject Method %AddJrnObjToSyncSet
%Net.Remote.Java.JavaGatewayService Method DefaultClassPath, FindJava, JavaDebugParams, RunJava
%SOAP.WebService Property Action
%SQL.StatementColumn Property propertyId
%Stream.Object Method %OnDetermineClass
%Studio.SourceControl.ItemSet Parameter CCRSrc
%SYSTEM.Process Method EnableCaching
%UnitTest.JDBCSQL Method existJava, getJDK
%UnitTest.Result.TestInstance Method NamespaceGet
Parameter READONLY
%XSQL.DS.IResultSet Method %GetMetaData
%ZEN.Component.tablePane Method onRefreshContents
Config.Cluster Property CommPort, NetworkType
Config.Configuration Method LATSignOnsStatus, NetActivityStatus
Config.Databases Method Mount, SetMIRRORCLI
Config.MirrorMember Method isReportingNode
Property ReportingGUID
Config.MirrorSetMembers Proiperty VirtualAddressInterface
Config.Miscellaneous Property DdpSec, DropRemLocks, EnableCaching, IPV6, MNetSets, NetNullSubs
Config.config Method GetLegacyNetConn, UpdateLegacyNetConn
Property LegacyNetConn, MaxClientsPerPort, UniqueClients, gmaxcache, gnetfrac, netcliconmax, vtabsiz
Security.Users Method SSLGetCipher, SSLGetCipherList, SSLGetLastError, SSLGetPeerName, SSLGetProtocol, SSLPeekClientHello
Method Return Changes

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

  • Package %CSP.UI.Portal.Config.ZenReport – SaveData

  • Package %ResultSet.Result – %Display

  • Package %SYS.Journal.SetKillRecord – ExistsOldValue

  • Package %SYS.TaskSuper – FindId

  • Package %UnitTest.Manager – GetTestStatus

  • Package %XML.Node – GetText

  • Package %ZEN.Template.ObjectGatewayWizard.JavaDone – ImportClasses

Method Signature Changes

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

Class Name Method Name(s)
%BI.WebAnalyzer ExportToExcel
%CPT.COSCallout Compile
%CPT.CalloutTesting ScoopChunk, TestStream
%CPT.ISQLCallout Compile
%CSP.UI.Portal.DatabaseFreespace clearSpace
%CSP.UI.Portal.NLSEdit SaveIODefaults
%CSP.UI.Portal.SSL SaveData
%Compiler.Informix.Flo preparseSQL
%Compiler.Informix.Visitor nearestLoop
%IO.ServerSocket ListenJob
%Library.Boolean DisplayToLogical, LogicalToDisplay
%Library.EnsembleMgr EnableNamespace, InitializeEnsemble, InitializeHealthShare, Upgrade, UpgradeNamespace, check4Install, createPortal, createPortalApp
%Library.File SetReadOnly, SetWriteable
%Library.IResultSet %CreateSnapshot
%Library.PopulateUtils TimeStamp
%Net.Remote.Java.JDBCGateway Test
%Net.Remote.Java.JavaGatewayService StartGateway
%Net.Remote.Service OpenGateway
%Net.SSH.SFTP Test
%Projection.MV genDictitem
%SOAP.Addressing.Properties WriteSOAPHeaders
%SOAP.Security.Header AddElement, GetElementById
%SOAP.Security.UsernameToken Create
%SOAP.WSDL.Reader CreateParameter, GenerateService
%SOAP.WebClient InvokeClient
%SOAP.WebRequest SendSOAPBody
%SOAP.WebService Initialize
%SQL.IResultSet %CreateSnapshot
%SQL.Manager.API AddUser
%SQL.Migration.Import Connect, CopyTableStruct
%SQL.Migration.Util DropTable, DropView
%SQL.StatementMetadata %GenerateMetadata, %OnNew
%SYS.Journal.File CheckIntegrity, GetNext, GetPrev
%SYS.Journal.System GetDefaults, GetHistoryHeader
%SYS.ZENReportServer ServeTransform
%Studio.AbstractDocument CompileDocument
%Studio.Extension.Base OnBeforeCompile
%Studio.General ConstructCSPSession
%Studio.SourceControl.ISC Disconnect
%Studio.SourceControl.ItemSet Import, Load, LoadToOS
%XML.Implementation WSDLMessageSchema
%XML.Node GetText
%XML.Reader Open, OpenURL
%XML.Utils.SchemaReader ProcessSchema
%XML.Writer Canonicalize, WriteAttribute
%XSQL.DSI.Call CompileProcedureContext
%ZEN.Component.dataListBox %DrawItem
%ZEN.Controller InvokeClassMethod, InvokeInstanceMethod
%ZEN.ObjectProjection CreateProjection
%ZEN.Report.Display.Chart.pieChart renderGetLabelText, renderSeriesLabels, renderTrigFunctions %DrawToHTML, %DrawToXSLFO
%ZEN.Report.Display.Chart.chart renderXLabels, renderYLabels
%ZEN.Report.PrintServer %ServePSTransform, %ServeTransformAndPrint %GenerateAggregates, %GenerateCode, %GenerateOpenTag, %SortChildren, %StoreElements %GenerateCode
%ZEN.Report.reportDataClasses CreateParentProperty
%ZEN.Report.reportGenerator CreateReportDefinition, UrGenerate
%ZEN.Report.reportPage %DisplayPDF, %DrawToHTML, %DrawToXSLFO, %DrawXML, %MakeXMLDataFile, %PerformTransform, DeleteTempFiles, GenerateReport
%ZEN.SVGComponent.chart renderYLabels
%ZEN.Utils %GetPhysicalIncludeDi
%cspapp.mgr.utilsysecpcliserv SaveServer
%cspapp.sec.utilsqluseredit Save
Config.Configuration AddDataServer
SYS.Shadowing.Shadow Delete
Security.Users Create, GetUsernameAndPassword, PromptForNewPassword, PromptForUsername

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.

SQL Name Of Index Must Be Unique

The SQLNAME of an index must be unique. This constraint was not enforced in earlier releases. It is now checked and an error reported if it is not.

Normalization Required When Using Simple IDs

Simple ID values are no longer normalized in Caché by the various methods that accept an ID as a parameter. ID values passed to the various methods of a class are expected to be in the normalized form, that is, the form returned by the <oref>.%Id() method. If an ID is a simple integer and a value is passed that is not in the integer normal form (for example, it is 01 rather than 1), methods such as %Open() and %Exists() will fail.

Object Binding Changes

Changes To Java Generated Code For Properties

Because of the new object dispatch Java driver in 2010.1 and beyond no longer uses projected values fields ii_<PropertyName>, jj_<PropertyName>, or kk_<PropertyName>. Generated samples will need to have the CacheDB.jar from 2010.1 or later in oprder top work properly.

SQL Changes

SQLCODE And %RowCount Renamed

Certain classes (resultsets, procedure context classes and dynamic statements) contained the property, SQLCODE whose value is set to indicate the result of executing an SQL statement. This property had other, similar names in past versions. Beginning with this version, it will now be called %SQLCODE in all classes but one - %SYSTEM.ErrorOpens in a new tab where it will remain %SQLCode.

Another property, %RowCount is present in some dynamic statement classes and result set classes. This corresponds to the local variable, %ROWCOUNT. Beginning with this version, this property is now named %ROWCOUNT in all classes.

Dynamic dispatch methods are implemented in these classes to reduce the impact on any existing code. Dynamic dispatch will check for %SQLCODE and %ROWCOUNT in various uppercase and lowercase forms and normalize the references to all uppercase. In most situations, this will allow existing code to work without requiring any alteration. However, to achieve better performance it is best to update existing code to use the defined property names of %SQLCODE and %ROWCOUNT.

Qualify Column Names In %ResultSet

If a row type specification received by a %ResultSet instance contains more than one column with the same name, the column name is now changed by qualifying the column name with the column number.

TOP Now Applied By Query

Prior this version, a query of the form

SELECT TOP :a <query1> UNION <query2> ...

would apply TOP to the result of the UNION. Beginning with this version, TOP will be applied only to the query it appears in. To re-instate the behavior of previous release, the query will need to be rewritten as

SELECT TOP :a FROM (<query1> UNION <query2>) ...
SQL Compiler Requires Access To Class Data

When compiling SQL statements, the SQL compiler will now acquire a shared lock on any class definition that corresponds with a table the SQL statement is using. This shared lock will be acquired when the compiler accesses internal metadata; it will be released immediately afterwards. If an SQL compilation is unable to acquire a shared lock on a class it needs for compilation, an error will be returned (%SQLCODE = 150) and the compilation of the SQL statement will fail. The lock attempt uses the current SQLLockTimeout setting.

This avoids a situation present in previous releases where the metadata used by the SQL compiler may not have been complete causing the compiled SQL statement to behave incorrectly.

Cached Query Changes

In this version of Caché, a number of significant changes have been made to the way cached queries are stored and used. The most important are:

  • The global, ^mcq, is no longer used to hold cached queries and is no longer a reserved global name. Cached queries are stored in the CACHE database, and are not visible across namespaces as they had been in the Management Portal.

  • The RS class package is no longer used for some cached queries and is no longer a reserved package name.

  • The “CacheSql” routine prefix is no longer used for cached query routines and is no longer a reserved routine name.

  • When setting server initialization or disconnect code, you can no longer set ^mcq("init code") directly. Instead, you must use the APIs in

    • $SYSTEM.SQL.SetServerInitCode(code): where code contains the initialization code to be executed. Call this function with code="" or missing to delete initialization code for this namespace.

    • $SYSTEM.SQL.SetServerDisconnectCode(code): where code contains the disconnect code to be executed. Call the function with code="" or missing to delete disconnect code for this namespace.

  • There is a new function to purge ALL cached queries in all namespaces on the systems: $SYSTEM.SQL.PurgeAllNamespaces(). $SYSTEM.SQL.Purge() will continue to purge all cached queries in the current namespace only.

  • The %SQL.StatementCache class has been renamed %SYS.SQLStatementCache; %SQL.StatementCache no longer exists.

  • The %XSQL.DSI.JPAQuery class has been renamed to %SYS.SQLObjectQuery; %XSQL.DSI.JPAQuery no longer exists.

Prior to this version, cached queries from one namespace could be visible in another namespace via the System Management Portal. In this version, cached queries are stored in a separate location, and are not visible across namespaces.

Collation Now Applied To Results Of SQL Function

If an SQL function return value has a collation value, and the function is called from an SQL statement, SQL will now use the collation for the return value. It is possible that SQL results for a query that calls such a function might be different than in previous versions.

An example of such a situation follows. Suppose this function is defined:

Class SQLUser.FunctionTest Extends %Persistent
Property myString As %String(COLLATION = "SQLSTRING(100)", MAXLEN = 500);

ClassMethod Reverse(Arg1 As %String) As %String
    (COLLATION="SQLSTRING(100)", MAXLEN=500) [SqlName=Reverse, SqlProc ]
      quit $REVERSE(Arg1)

and it uses the query

SELECT myString, SQLUser.Reverse(myString) gnirtSym 
FROM SQLUser.FunctionTest 

Prior to this change, the execution of the query would result in a <SUBSCRIPT> error when the length of the data in myString approached 500 characters. This is due to a known subscript length restriction in Caché. Beginning with this version, the SQL query processor will recognize the collation of the return value for the function as SQLSTRING(100) and the ORDER BY will be performed on the collated value of the function return value.

Change In Concatenation Operator

There has been a slight change in behavior of the SQL concatenation operator. Prior to this change, if you had “A || B” in an SQL statement, the resulting value would be a string with exact collation. Now, if A and B are both strings and both have the same collation, the result will be of that common collation also. This may cause a change in the results returned for some queries.

New Default DDL Datatype Mappings For Large-Object SQL Datatypes

For new installations, the default DDL Datatype mappings for all large objects have been changed:

Customers with multiple setups that have some new installs and some upgraded systems need to be aware that the newly installed systems may produce different class definitions when executing DDL CREATE TABLE and ALTER TABLE statements to create stream fields. BStream%String and CStream%String and their synonyms (%Library.GlobalBinaryStream and %Library.GlobalCharacterStream) are still fully supported.

Error Returned Instead Of Silent Failure

Now, error messages will be reported for conversions that used to fail without any message. This change returns SQL_ERROR on a row containing conversion errors that are not due to truncation, to match the behavior of SQLServer reporting. The SQL state reported may not be the same as seen with SQLServer when a clearer message is available in Caché.

More Info Now Returned By Error Handlers

Calls to SQLError and the other error handling APIs will return more complete information than in prior releases. These APIs now have the ability to report multiple errors, so that error reporting can now indicate status on more than a single record. This allows Caché to report truncation errors (among other errors) for a particular row and column of a result set through the application calling SQLGetDiagRec and SQLGetFieldRec ODBC 3.5 APIs.

Changes To User-Defined DATE And TIMESTAMP Handling

Prior to this release:

  • if an application had a user-defined DATE datatype, and the Logical value of this datatype was not +$Horolog, it would not accept CURRENT_DATE as input for this field value or in a query as a comparison value for this field. Also, it could not use this field in calls to DATEDIFF, DATEADD, DATENAME, or DATEPART.

  • if the application had a user-defined TIMESTAMP datatype, and the Logical value of this datatype was not 'YYYY-MM-DD HH:MM:SS[.sss]', it could not use CURRENT_TIMESTAMP as input for this field value, in a query as a comparison value for this field, or in calls to DATEDIFF, DATEADD, DATENAME, or DATEPART.

Caché SQL will now support these operations as long as the user-defined datatype class contains methods which convert from the user-defined logical value to the %Library.Date logical value. The methods needed for the user-defined date datatype class are LogicalToDate and DateToLogical.

Owners Of SQL Stored Procedures

A correction has been made to the SQL projection of a stored procedure. If the procedure does not have an owner specifically defined for it (the owner of the class that projects the procedure), the owner will default to “_SYSTEM” and no privileges will be granted to the owner (since _SYSTEM has the %All role). This now matches the behavior followed when compiling classes that project tables and views. Prior to this change, the owner would default to the current user (the user compiling the class).

Class References Projection Changes

For a persistent class with a property that is a reference to another persistent class with a CLASSNAME=1, the property no longer projects to SQL as a reference, but as a simple %List type. This corrects behavior where SQL treated this field was an Integer value that contained the ID of the referenced row. When CLASSNAME=1, the field data is instead an Oid value, which is not an integer.


At this time SQL -> syntax cannot be used on referenced fields that are defined with CLASSNAME=1.


When a linked table is defined through the Link Table Wizard, a new property type parameter will now be defined called EXTERNALSQLTYPE. This will be set to the type number or name returned from the metadata of the external table.

Correction For CAST(x AS NUMERIC(p,s)) Applied

A problem has been corrected where “CAST(value AS NUMERIC(5,2))” would return incorrect results in display mode when using (European-style) comma as the numeric decimal separator.

The expression CAST (value AS NUMERIC(precision, scale)) used to return a logical value that included the full display scale of the cast value. For example, CAST(1 AS NUMERIC(5,2)) used to return 1.00 as the logical value; now it returns just 1. The display value will still be 1.00. Any code that relied on the logical value of the CAST result having being 1.00 will have to be modified.

CSP Changes

Charset Reporting Changed For 8–Bit Systems

When serving up files with the stream server via CSP on 8–bit systems, Caché now reports which charset is used in a different manner. In the past, Caché used the default character file translate table, but on 8–bit systems this is almost always RAW and so does not provide the information required. Beginning with this version, Caché reports the system default locale charset for these files. The logic is now:

  1. If ^%SYS(“CSP”, “MimeFileClassify”, extension) is defined, it is assumed to be of the form “$LISTBUILD(type, binary, charset)” and this will be used to report the type of this file.

  2. If the file is not of a character type, the charset will always be set to “” for binary files.

  3. If ^%SYS(“CSP”, “DefaultFileCharset”) is defined, then this is the charset to use when serving files.

  4. If this is a Unicode installation, Caché will use the default file character translate table.

  5. On 8–bit installations, Caché will use the system default charset.

For background information on character translation in Caché, see “Localization Support” in the Caché Programming Orientation Guide.


The CGI environment variable SERVER_NAME is now in the set of fields that are placed at the beginning of the first request data block dispatched to Caché. This is to enable the CSP server in Caché to identify the application early in the request processing cycle. The order of the first three fields in the data block is now as follows:

  1. Session ID (CSPCHD)

  2. CGI environment variable, SERVER_NAME

  3. Request path/file (CSPLIB)

Properly Handle Session Id Between Secure And Non-Secure Pages

If a page loaded via an http link itself has a link to an https page, Caché will now not include the CSPCHD SessionId. This is true even if token-based session management is in effect, or if this is the initial page of a session and autodetection logic is active.


This may be overridden with the CSPSHARE=1 parameter to regain the previous behavior, but is not recommended. Applications should not be sharing a session between secure and insecure pages as this could be a security risk leaking information from the secure pages to the non-secure ones.

XML Changes

Use Caché InitialExpression To Represent XML Schema Fixed Attributes

Caché now represents the fixed attribute for elements and attributes in an XML schema using the InitialExpression keyword in Caché classes created by the XML schema wizard. If an application is depending on being able to determine if a fixed element or attribute has been specified, it will no longer be able to do this.


The ability to determine whether an attribute has been specified violates the spirit and letter of the rules for attribute usage in XML. Also, this is not a complete implementation of fixed attributes since the value may later be changed.

XMLImport Efficiency Changes

XMLImport has been changed to process child elements more efficiently rather than the previous method of recursively processing subtrees. Users who have applications that override XMLImport may be required to redesign some of their application processing.

Web Services Changes

Correct Handling Of MIME Parts

This version corrects an error in the handling of messages with MIME parts present in prior versions. If the WSDL specifies document/literal and MakeMessageStyle=1 (message format which allows multiple parts), Caché now creates the parts which correspond to MIME content if they are called for by the soap:body element of the <binding> <operation>. Prior versions incorrectly ignored all MIME parts, even if they were in the parts list or defaulted to the parts list.

Language Binding Changes

Project %Stream.Object As ICacheObject

In previous versions, if a class used %Stream.ObjectOpens in a new tab in its properties or methods, it couldn't be projected to CacheProvider. Beginning with this release, it will appear as ICacheObject in the generated code (a generic interface for .NET proxy classes). The actual object that is returned to the client at runtime is the projection of the specific server stream object. For example, if the object that is returned at runtime is %Stream.GlobalCharacterOpens in a new tab, the client object will be CacheCharacterStream.

Light C++ Binding Uses Its Own Namespace

Beginning with this version, the Light C++ Binding uses a different namespace ("InterSystemsLCB") than the TCP/IP-based C++ bindings ("InterSystems"). This makes it possible for the same application to use both LCB and TCP/IP-based C++ binding, with each of the bindings using a different shared library (or dll on Windows), and with each library potentially being installed from, and connecting to, a different version of Cache.

Changes To runMethod

The binding server protocol allows nested calls inside output redirection. Before this change, every output redirection call to the client started a nested call to the binding message loop and required a separate message from the client to return to the previous server message.

This change makes the nested call optional. CacheProvider now disallows nested calls to runMethod by default. Applications using nested calls will have to explicitly set AllowNestedCalls to true.

xDBC Changes

Change Formatting For %Numeric Scale 2

In earlier releases, Caché returned “.00” for a zero value as a workaround for an Access 2000 defect where a value of “0.00” would be interpreted as #deleted by Access. This workaround is now withdrawn; sites still using Access 2000 should upgrade their versions.

Concatenation Results No Longer Truncated

In prior versions, if a concatenation expression produced a string whose length was greater than 255 characters, it would be truncated to that length. This no longer happens.

Use WVARCHAR SQLTypes For Version 3.5 ODBC With Unicode SQL Types

ODBC 3.5 fully added WVARCHAR SQLTypes support for strings. While a Unicode Caché installation does not care if a datatype is Unicode or not, DotNet and Access applications sometimes need ODBC to support WVARCHAR. In the past for Access Caché used a DSN defined option called “Unicode SQLTypes”; when set to 1, Caché returned -9 instead of 12 for a string SQLType.

“Unicode SQLTypes” can be used via programatic control or in a DSN setting. By default, it is set to 0, meaning that 12 is returned for VARCHAR types. This change allows Caché to dynamically change the metadata reported back from Catalog queries, based on the switch. The server side still considers these data types as 12.


This change is enabled by the Unicode SQLTypes switch and only affects Unicode clients with Unicode Caché using ODBC 3.5 APIs.

MultiValue Changes

Change Handling Of EQUATE References

In previous versions, any word in the source which corresponded to an EQUATE definition would be replaced by the body of the definition. Beginning with this release, a sequence of words separated by “–>” will be considered as a single entity for the purposes of matching EQUATE definitions. This means that the sequence

AutoCheck->VIN = VIN

would previously have been interpreted as

AutoCheck->CAR(7) = CAR(7) 

whereas now it will be treated as

AutoCheck->Vin = CAR(7)
CREATE.INDEX Key Length Defaults To 150 Characters

The default length of keys created by the CREATE.INDEX command is 150 characters. If an application needs larger keys for the index, the developer must manually edit the index definition in the class.

Secondary Indexes

INDICES(filevar) now returns an array containing the actual index name. Previously, the MultiValue dictionary on which the index was created was returned. This allows the INDICES() function to return indexes created with the MultiValue command CREATE.INDEX as well as those created directly in the class.

Two new attributes have been added to the array returned by INDICES(filevar, indexname). Attribute 7 contains the property name and attribute 8 contains the MVName.

Any MultiValue commands and MVBasic statements and functions can now accept either the actual index name or the MultiValue dictionary name.

Universe Emulation Now Ignores Whitespace In Conversion

Universe ignores leading and trailing white space when converting a string to a numeric value. Now the Caché Universe emulation will do the same.


This change causes the compiler to generated slightly more code for routines compiled for Universe emulation. Very large routines may end up exceeding the maximum space allowed for a routine. In this circumstance, they will have to be refactored into smaller segments.

Extend MVIMPORT To Handle Orphan Directories And Files

MVIMPORT now accepts an optional second parameter on the command line, a path to store any directories and files that are otherwise skipped because they do not directly relate to a VOC. MVIMPORT will examine the backup and determine the lowest point in the tree of directories that includes all these directories and files. MVIMPORT will then import that subtree into the path specified on the command line.

Spooler Now Allows Binary And Text Data In Same Job

This change allows a MultiValue application to have binary data and non-binary data inside the same print job. In prior versions, there were problems with the form-feed character being translated to another sequence (if defined by SP-CONTROL); the translation would be performed on both textual data which did require the translation and binary data that did not. This change also fixes an anomaly earlier versions that might result in fewer form feeds being output at the start of a job.

Use Default Precision Of 4 For SQL Formatting

Users of the MV formatting operations in SQL introduced in 2010.1 ($MVFMT, $MVOCONV, and others) will find that the MultiValue precision now defaults to 4, the same as it does from the MV Shell, rather than zero. In prior versions, the value was not initialized until an MV command was issued.

Logical Operators Now Emulation Dependent

The MVBasic logical operators “AND” and “OR” will now behave properly according to the emulation under which they are compiled. Emulations such as Universe and jBase will stop evaluating arguments as soon as a result for the expression is known.

A new $OPTIONS is provided to control this behavior if the emulation default is not desired:

  • $OPTIONS FULL.LOGICAL.EVALUATION means that all the operands will always be evaluated.

  • $OPTIONS -FULL.LOGICAL.EVALUATION means that if the result is known after evaluating the first operand, other operands will not be evaluated.

VAR.SELECT Now Default For Ultimate

$OPTIONS VAR.SELECT is now the default for the Ultimate emulation.

Comparison Of Non-Numeric Strings Fixed

Non-numeric strings in the arguments for the comparison functions EQS, NES, GTS, GES, LTS, and LES will now be converted properly according to the emulation under which the program is compiled. This was not the case in prior versions.

Positioning Of READPREV Corrected

In prior versions, the first READPREV after a SELECT ATKEY to a key that does not exist would skip one record. Now, the record position is properly managed and the record is not skipped.

Suppress Newline At End Of Print Job

Normally, when printing in MultiValue, at the end of printing a line of data a newline sequence will be printed. This is normally CR + LF (but can be amended with SP-CONTROL). There are now 3 scenarios when we do NOT print this newline sequence at the end of a line of data:

  1. When outputting binary data on a line, as specified with the CHAR(255):"BINARY": sequence.

  2. When a line of data is immediately followed by a form-feed on the next line. In this case the new line sequence is not only superfluous,but might also create an unintended blank page.

  3. At the end of a print job. Again, this might create a blank page if the page was full when the newline is printed. It is up to the form feed specification using the SP-SKIP setting to decide trailing form feeds.

There is a small chance that print job might have been relying on the previous behavior to throw a page at the end of a print job. If this is the case, then the form queue setting needs to be amended with SP-SKIP to carefully define the end-of-job form feeds.

Named Common Match Checking

If two programs have the same named COMMON area with a different number of variables in the COMMON, there will now be a <COMMON MISMATCH> error thrown when the second program is entered, except in UNIDATA emulation where no error will occur.

Named Common Initialization

Named COMMON variables will now be initialized according to the emulation or $OPTIONS specified. CLEAR COMMON /name/ will now clear all variables in the named COMMON.

Allow TANDEM Usage From Any Account

The use of TANDEM as the master controlling terminal no longer requires SYSPROG account privileges. You can now, by default, TANDEM to a running terminal from any MV account. Before you can become a TANDEM master, the client terminal must enable itself with the following:


This has been enhanced to support:


which is the same as TANDEM ON, but it now enforces the SYSPROG security i.e. any terminal that wants to be a master controlling terminal must run from the SYSPROG account.

Change MV Login To Use The Caché User Name

When the MV shell starts up, it will now look for a Proc or Paragraph with the same name as the Caché user rather than the OS user. This change means that it is now looking for the @AUTHORIZATION value rather than @LOGNAME value. This change should not affect Windows users; UNIX® MV users may have to change the name of the login proc if they have used the OSUserName rather than the Username.

Zen Changes

Add USECOMMONDIRECTORY Parameter To Zen Components

By default Zen classes write out generated js and css files to the CSP directory corresponding to the namespace they are defined in. For packages that are mapped to other namespaces this can be very inconvenient. This change provides a way to change the default behavior: if a Zen Component class sets its USECOMMONDIRECTORY class parameter to 1, then any files generated for it will be placed within the common /csp/broker directory and thus be visible to all namespaces.

This is a somewhat advanced feature and has some important caveats:

  • ALL Zen classes within the same class package must define (or inherit) the same value for USECOMMONDIRECTORY. If not, the application will get an error when it is compiled.

  • If USECOMMONDIRECTORY is enabled for classes that had previously been compiled without it, priously generated .js and .css files must be deleted from the local CSP directory. If this is not done, they will continue to be used.

  • This mechanism is designed for cases where a package is mapped across the entire system. There is no mechanism for avoiding collisions between two packages with the same name in different namespaces that use USECOMMONDIRECTORY. If this is the case, DO NOT USE this feature.

Platform-specific Items

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

Changes To Spawned Child Process File Descriptors On UNIX®

External programs started with $zf(-2, <path>) on UNIX® platforms now run with file descriptors 0, 1 and 2 redirected to /dev/null. In prior versions, these descriptors were closed before starting the program.

$FNUMBER Parsing Corrected On AIX

In prior versions, on the AIX platform, illegal format strings passed to $FNUMBER(n,format) were not always detected. The illegal format strings that were not detected consisted of a "P", (parenthesis format) combined with any of "+-TL" (plus, minus, trailing, or leading format). Now these will generate a <SYNTAX> error.


Symantec Backup Exec

Symantec Backup Exec solution seems to install an additional driver file (tpfilter.sys) for magnetic tape devices.esence of this driver make it impossible to back up to a magnetic tape from within Caché (first observed for HP Ultrium 920 SAS streamers).

Symptoms that indicate the problem include:

  • The "Tape Symbolic Name" tab disappears from device properties in Windows Device Manager.

  • The “\\.\Tape0” device becomes unavailable, making 'o 47:("auv":0:2048)' hang forever and never return.

The only effective remedy is to uninstall the driver (by uninstalling the Backup Exec).

FeedbackOpens in a new tab