Skip to main content

Release and Upgrade Information for Caché 2008.2

This chapter provides the following information for Caché 2008.2:

New and Enhanced Features for Caché 2008.2

This version of Caché has been improved and enhanced in the following areas:

In addition, many more localized improvements and corrections are also included.

Performance and Scalability

Object Performance Improvements

In order to improve performance and reduce contention for method dispatch and property access, Caché now caches the locations of these items upon first reference. Subsequent requests for an item first examine the cache and, if found, avoid the effort involved in locating the requested item. This improves the speed of invocation and access to class members. It also eliminates contention on key class metadata when thousands of processes are running.

Language Performance Improvements

The routine compiler has been enhanced. The tokens marking the beginning of line have been removed and the bookkeeping of statements in the routines has been improved.

The net result of these changes is that compiled object code should be slightly smaller and faster. There is no longer any timing effects for the use of comments in block structures.


This is a significant change to the ObjectScript compiler and therefore increments the compiler minor version number. Code compiled on earlier versions of Caché will run on this version, but the reverse is not true. Code compiled on this version of Caché will NOT execute on earlier versions.

Support For Binary SOAP

This version of Caché enhances the SOAP facilities to allow the binary transmission of SOAP messages between Caché instances. The Web service will then support normal XML-based SOAP or Caché proprietary SOAP format over HTTP. The WSDL produced for a Cache Web service using the binary extension has been enhanced to carry the necessary information for the Cache Web client. This is also a performance improvement since the transmitted data is in a more compact form.

Routine Buffer Management Improvements

In prior versions of Caché, all routine buffers were the same size, configured to hold the largest routine to be executed. This release of Caché implements multiple routine buffer sizes, providing separate pools of 4KB, 16KB and 64KB buffers. In most systems, the size of compiled routines span a range; allocating several buffer pools of differing sizes provides better matching of buffers to routines sizes. This, in turn, provides more efficient use of memory, and allows the administrator to better optimize system resources.

Shadow Latency Improvements

Shadowing latency has been decreased in this version. Caché now pre-scans the journal file for database updates and pre-fetches the data to be applied to the database.

Rapid Application Development

Studio Enhancements


Studio now has an option "Track variables" which switches on a limited form of variable tracking that allows it to identify variables which are used when they don't have a value. This is called READ-UNDEFINED.

Studio Assist

The following improvements have been made to Studio Assist as aids in program development:

  • When the indicator sequence for macros is typed, “$$$”, Studio now displays the list of commonly-used system macro names. User-defined macros are also added to this list. Previously, Studio had displayed all defined macros in the system.

  • When Studio Assist recognizes the beginning of a reference to a class parameter, (..#), it will allow a selection from among the currently defined parameters for the class.

  • Studio will now also provide a list of available local variables for name completion when appropriate. It will also specially color variables used only once in the bounds of a routine or method since these may be typographic errors.

Zen Enhancements

In this version Zen has been enhanced. There are new menu formats and desktop components:

  • Zen now supports a drag-and-drop API.

  • Active groups may now be dynamically resized.

  • Zen provides a “lazy” tree control that only loads the data for a sub-tree when it is expanded tree.

  • A new tab control has been added.

Text Search Enhancements

Text Search in Long Streams

Previous versions of Caché provided the ability to search text represented as streams. However, searching streams longer than 32 KB required that long-string support be enabled. In this version of Caché that restriction has largely been lifted except for usage of %CONTAINS and %SIMILARITY.

Query Optimizations For Text Searches

The SQL optimizer has been improved for searches involving text queries. It now takes account of the fact that text strings are made of individual words that themselves can be indexed as collections.

Improved SQL Support for Streams

This version of Caché has improved the handling of streams as fields in SQL tables, namely:

  • It is now possible to open the stream returned via a simple function that returns of OID value of the stream. This is true for stream fields which are NULL as well, though attempting to read them will result in an immediate EOF.

  • The INSERT and UPDATE clauses now accept such an OID as the new value for a stream field in a table.

  • The SUBSTRING function now accepts a stream as its first argument.

  • The ODBC and JDBC gateways now provide this support as well.

Light C++ Binding

Caché has changed the semantics of the Light C++ Binding object references. In prior releases, each “open” of an object created a new reference to a copy of the instance. Now the semantics for “open” match the semantics of regular C++ binding object references; all references to the same object point to the same local storage.

This version also provides support for embedded objects and inheritance.

JIS2004 Support

This version extends Caché Unicode support to include characters known as surrogate pairsOpens in a new tab. These are pairs of 16-bit characters that, taken as a unit, represent more than a million Unicode characters outside the Basic Multilingual Plane (BMP). To allow applications to deal with the characters properly, this version of Caché also introduces specialized versions of the regular string functions that correctly handle surrogate pairs.

Subroutine-level Profiler

Caché now permits profiling at the level of individual subroutines, procedures, and functions. This feature allows the user to easily see the “busiest” routines, and then drill down to the subroutine line level to analyze and improve performance of any “hot spots.” The facility extends the existing ^%SYS.MONLBL profiler (and coverage analysis).


A number of improvements to numeric computation have been made in this version of Caché. These include:

  • Improved support for $DOUBLE values.

  • Better handling of conversions between $DOUBLE values and Caché numbers and strings.

  • User control over conversion to Caché floating-point using the $DECIMAL function.

Updates To Third-party Software

This version of Caché contains updates to third-party software packages. The following are the version changes from 2008.1 to 2008.2 for all platforms except for OpenVMS:

Package Version in 2008.1 Version in 2008.2
ICU 3.2 3.6
Xerces 2.6 2.7
Xalan 1.9 1.10+ (contains fixes not in the Apache release 1.10)

For OpenVMS, there are no version changes for these packages in 2008.2. The versions remain as: ICU 3.2, Xerces 2.1, and Xalan 1.5.

Reliability, Availability, Maintainability

CSP Enhancements

This version of Caché has several important, new features for CSP and the CSP Gateway:

  • It is now possible to enable HTTP authentication programmatically from within Caché.

  • This version supports the new native module interface to Microsoft Internet Information Services (IIS) version 7.

  • The CSP Gateway now supports connection pooling when using Apache.

  • CSP now supports communication using HTTP version 1.1

  • The CSP Gateway now supports transmission of messages greater than 32 KB in length via “chunks.”

  • Updating the CSP password via the System Management Portal now automatically updates the password value in the CSP.ini file.

  • In prior versions, requests longer than 32 KB were converted to streams. In this version, they are converted only if the length exceeds the maximum string length. That is, if long strings are enabled, the conversion to a stream will only happen if the request exceeds the maximum long string length.

Improved National Language Support

The administration of NLS has been extensively reworked in this version of Caché. A new page has been added to the Management Portal to provide a convenient means of administration, and the %SYS.NLS.TableOpens in a new tab, %SYS.NLS.FormatOpens in a new tab, %SYS.NLS.LocaleOpens in a new tab and %SYS.NLS.DeviceOpens in a new tab classes now contains the functionality of the previous NLS utilities. See the Windows installation documentation for an example. One can also use the line-oriented routine, ^NLS, from a terminal connection.

The Visual Basic-based NLS management application has been removed. The corresponding replacement page is now part of the Management Portal at Home,Configuration,NLS Settings.

Improved UNIX® Installation

The cinstall installer for UNIX® has been updated. It is now possible to embed a Caché UNIX® installation within a partner product and to provide the responses needed by the Caché sub-installation in a script file. This allows a seamless installation of Caché as part of a containing product.

Per Socket Keep Alive

This version of Caché refines the TCP keep-alive timeout for Windows and Linux down to individual processes (rather than relying on the machine-wide setting). This makes it possible to detect lost connections due to network failures, VPN trouble, and so on in a more reliable fashion.

Improved Protection Against Starting Multiple Copies of Caché

Under some circumstances, Caché database locking proved insufficient to prevent multiple instances of Caché from being started against the same databases. This version has added safeguards on UNIX® systems against that happening.

New Archive Interface Classes

This version of Caché now contains a package, %Archive, that permits connection to an external service for long-term document retention. The package contains classes that allow for the definition of content, %Archive.ContentOpens in a new tab, as well as the management of the initiation of the data transfer, %Archive.SessionOpens in a new tab.

In this first release, the archive interface has been tested for use with the EMC Centera™ servers.


Superserver Can Accept SSL Connections

The Caché superserver has been enhanced to allow communications using either the Secure Sockets Layer (SSL, version 3) or Transport Layer Security (TLS, version 1). Ports can be configured to require the use of SSL or TLS by requesting clients.

The clients that have been upgraded to use this communications capability are:

  • Shadowing (configured and enabled via a command-line utility)

  • JDBC and Java binding

See the notes in the Upgrade Checklist for further details.

Telnet Over SSL for Windows

Caché will now accept Telnet connections if the superserver is configured to use SSL and the %TELNET/SSL configuration has been defined. This is done via the Management Portal.

SQL Column-level Security

Caché now permits access control to be applied to SQL table columns. The privileges control the ability of a user to select, insert, and update column values. This allows one to limit access by designated users to only specified columns in a table. See the SQL verbs GRANT, REVOKE, INSERT, UPDATE, and other related verbs for an explanation.

WS-Security 1.1

Caché now gives applications the ability to use WS-Security 1.1 to protect web services messages. This capability permits the canonicalization of XML, and the generation and verification of digital signatures for message content according to the X.509 standard (X.509 addresses public key and privilege management infrastructure).

WS-Security is unrelated to HTTP basic access authentication which Caché already supports in this area. The WS-Security support is for UsernameToken Profile with clear text password, as described in the following document:

oasis-200401-wss-username-token-profile-1.0.pdfOpens in a new tab

Online at the Organization for the Advancement of Structured Information Standards (OASIS) site: in a new tab

InterSystems recommends that you use SSL with this profile because the password is transmitted in clear text. Support for SSL is documented in the “Using SSL/TLS with Caché” chapter of the Caché Security Administration Guide. InterSystems also recommends using a SOAP/XML gateway for security purposes; for further details, see Securing Caché Web Services.

Caché 2008.2 Upgrade Checklist


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

General upgrade issues are mentioned in the chapter General Upgrade Information in the Caché Release Notes and Upgrade Checklist. Those customers upgrading their applications from releases earlier than 2008.1 are strongly urged to read the upgrade checklist for earlier versions first. This document addresses only the differences between 2008.1 and 2008.2.


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 2008.2. The items listed here are brief descriptions. In most cases, more complete descriptions are available elsewhere in the documentation.

Journal Restore UI Changed

The journal restore utility, ^JRNRESTO, asks a sequence of questions of the operator to determine what part of the journal to restore. The questions and their order are different in this release from previous releases.


Those sites that use a script to supply the answers to questions presented by ^JRNRESTO must be reviewed to ensure they still accomplish their intended task.

Prevent Login As UnknownUser

This version of Caché no longer allows “UnknownUser” as the user name for login. The UnknownUser is now reserved for use to identify users who gain access as unauthenticated users. Any application using “UnknownUser” as a login name will need to be changed to use some other userid.

Support Variable-Sized Routine Buffers

In prior versions, Caché allowed the administrator to specify in the CPF file the amount of memory to be used for routine buffers (routines) and the size of each buffer (rbufsiz). Assuming sufficient memory, Caché allocated a single pool of fixed size buffers; each buffer holding one executing routine.

In this version of Caché, rbufsiz is ignored in the configuration file. Caché instead allocates half the space specified by routines to a pool of 64KB buffers, three-eighths of the space for a pool of 16KB buffers, and one-eighth of the space for a pool of 4KB buffers.


The maximum number of buffers allocated to any pool is limited to 65,529. Caché also will never allocate less than 205 buffers to any sized pool. This means the actual memory used for routine buffers can be larger than specified in the configuration file.


The format for Caché routines does not allow more than 32K characters for literal strings regardless of the setting for the maximum routine size.

Superserver Support For Secure Communications

The Caché superserver has been enhanced to allow communications using either the Secure Sockets Layer (SSL, version 3) or Transport Layer Security (TLS, version 1). Individual ports can be configured via the Management Portal to have SSL required, enabled or disabled. For each setting, the following action takes place:

  • Required: If the initial attempt to connect does not present a valid SSL or TLS certificate, the superserver will drop the connection.

  • Enabled: If the initial attempt to connect presents a valid SSL or TLS certificate, the superserver will mark the connection as secure. Otherwise, the connection will be marked as not secure.

  • Disabled: If the initial attempt to connect presents a valid SSL or TLS certificate, the superserver will drop the connection.

Configuration of the ports with respect to communications security is done via the Management Portal: Home,Configuration,Shadow Server Settings. Both the “Add Shadow Server” and “Edit Shadow Server” pages now have an Advanced options, SSL Configuration.

A Caution Regarding Requiring SSL on the Superserver for 2008.2

If an administrator creates an SSL configuration called %SuperServer, enables this configuration, and then specifies in the Superserver SSL/TLS Support field that the SSL/TLS is required (clicking the Required radio button), then the System Management Portal will no longer be able to communicate with the instance.

The administrator can correct this problem at the Terminal (which still connects) using ^SECURITY as follows:

  1. Start ^SECURITY in a terminal session.

  2. Select option 9 (Systems parameter setup).

  3. Select option 1 (Edit system options).

  4. In answer to the question, “What type of SSL/TLS connections are allowed for the superserver?,” change the setting to Accept or None (equivalent, respectively, to Enabled and Disabled in the Management Portal).

System Scan On New Install or Upgrade

Beginning with this version of Caché, upon completion of a successful install or upgrade, Caché will automatically scan the related files and directories compiling an inventory of the instance. This data will be stored in the database, %SYS.

National Language Support

The administration of NLS has been extensively reworked in this version of Caché. A new page has been added to the Management Portal to provide a convenient means of administration and the %SYS.NLS class now contains the functionality of the previous NLS utilities.

The program previously used for NLS management on Windows, “cnls.exe”, has been removed and replaced by the line-oriented routine, ^NLS. The routines ^NLSMGR, ^%Wsnls, ^%Wsnls2, and LOCGEN have also been removed and new system classes, %SYS.NLS.TableOpens in a new tab, %SYS.NLS.FormatOpens in a new tab, %SYS.NLS.LocaleOpens in a new tab and %SYS.NLS.DeviceOpens in a new tab, have been added.

^NLS is a line-oriented utility that provides basically the same functionality of CNLS.EXE in previous releases. Its main options are:

  1. Locale definitions

  2. Table definitions

  3. Current system settings

The first two options manipulate static definitions of the main NLS entities: locales and tables. The third option allows the user to see currently active settings on a system-wide basis or just for the current process.

Security-Related Changes

New Resource Required For Secure Login

A new resource is now created during installation called, %Service_Login. This resource is now used by the $SYSTEM.Security.Login() function. The $SYSTEM.Security.Login function will now only succeed if the application calling that function runs as a user who has USE access to this resource.

Before this change, any application could call $SYSTEM.Security.Login(), and if presenting a valid userid and password, then login as that userid. Now, they must also be able to USE the resource.


This resource is not required if the calling process has Write permission on the resource that protects the CACHESYS database, or the calling routine is stored in the CACHESYS database.

Adding Roles Prohibited From Command Line

The function, $SYSTEM.Security.AddRoles() can no longer be called from the command line, or from within the debugger. Doing so could allow a user to inadvertently leave their process with elevated roles when the call returns. Calling the method in this way will fail to elevate the roles, and the error

ERROR #940: Insufficient privilege for operation 

will be returned as the value of the function. Moreover, if

  • there is a routine which calls $SYSTEM.Security.AddRoles(), and

  • it encounters an unhandled ObjectScript error in this routine while in programmer mode, and

  • the routine breaks at the debug prompt,

the programmer can no longer call $SYSTEM.Security.AddRoles() from the debug prompt and escalate roles outside of the scope of the application.


It is recommended that any routine or class use error handling in the procedures which call $SYSTEM.Security.AddRoles().

Privileges For Changing Database Properties Modified

To edit the properties of a database, the privilege %Admin_Secure:USE is now required. If a user without this privilege attempts this action, the following error will occur:

ERROR #921: Operation requires %Admin_Secure:USE privilege 

Parameter File Name Always Defaults to cache.cpf

The default for the optional configuration argument used when starting Caché from the command line has changed. Previously, when a command line such as

ccontrol start an_instance_name a_config_file

was issued to start Caché, a_config_file.cpf would become the default configuration file used to start later instances.

Beginning with this version, the configuration file will be used only for the current startup. Subsequent start commands which do not explicitly specify a configuration file will cause the Caché instance to be started using the cache.cpf configuration file.

Platform-Specific Items

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

UNIX®: Improved Installation

The “cinstall” package now offers three setup types to replace "Standard" and "Custom".

  • Development: (the default) install server and all client components.

  • Server: Install the components for Caché server; but do not install client components, nor anything normally found in the /dev area.

  • Custom: Install server components; present a dialog for all client components, allowing them to be individually selected.

Furthermore, the install will use a parameters.isc file created from a previous installation to parameterize the install rather than by prompting the user.


Automatic install scripts may need to be reworked because the order of some of the Caché installation prompts has changed.

UNIX®: Protection Against Starting Multiple Copies of Caché

In prior versions, the use of .lck files for Caché databases to control failover proved insufficient to prevent multiple instances of Caché from being started against the same databases under all circumstances. Caché now takes out additional locks for the control process, write daemon and journal daemon to provide better isolation.

As part of this change, information has been removed from the cache.ids file, and is placed in a system-internal file. The existence of the cache.ids is all that is used as a marker.

Macintosh: CShell Effective Id Anomaly

The setregid call used by csh to establish the real and effective group id for executing commands ignores the effective group id (presumably as a security issue). Administrators should use alternatives such as sh, ksh, or bash when administering Caché from other accounts than the one Caché runs as.

This issue appears on all Macintosh supported platforms.

Windows: License Acceptance Dialog

The Windows installer now requires explicit acceptance of the InterSystems license terms as the first step in the installation process. This applies to both upgrade and new instance installations. The Next button for the license acceptance dialog is not enabled until user selects the I accept the license terms choice. The only other action available is to cancel the installation.

Windows 64–Bit: Studio Activate Wizard Unavailable

The Activate Wizard is currently supported only on 32–bit windows platforms. It is greyed out on the Studio Tools menu for 64–bit systems.


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.

Compatibility Notices

ObjectScript Compiler Version

The ObjectScript compiler has been modified to improve code generation. This change is significant and internally the minor version of the compiler has been incremented to mark this. Code for routines or methods compiled in this version of Caché will not run on previous versions.

Class Component Signatures

This version of Caché corrects a deficiency in the class compiler in versions 2007.1 and 2008.1. Existing classes that compiled without error in those releases may now be recognized as having signature errors in some overridden inherited components.

Property References

This version of Caché corrects a deficiency in the class compiler that existed in earlier versions. References to properties must have an instance context; you cannot GET a property without giving the OREF for it.

This change also affects cases where an applications called propertyGet() methods as class methods. For example, applications using ##class(name).property to call the propertyGet() will have to change to call a proper class method. Such calls will now result in an error. These method calls should be rewritten as class methods instead of calculated property.

Preservation Of $TEST Value Across Calls

It is documented that the value of $TEST is preserved across calls to any procedure. In prior versions, however, this was true only for calls to procedures defined in the same routine as the caller. Caché has been changed in this version so that the value of $TEST is restored regardless of where the called procedure is defined.

Change To Storage Global Name Generator

The name of the global used to hold the storage for instances of a class is derived from the fully-qualified name of the class; that is, package name and class name. If the length of the resulting name exceeds the maximum global name length, the class compiler may truncate either the package name, class name or both to generate a global name that fits within the defined limits.

When one of the name parts is truncated, the truncated portion is encrypted to help create a unique name. In previous versions, this encryption produced a three-character string. Beginning with this version of Caché, the algorithm produces a four-character string.


If an application has external class definitions that do not include storage definitions, it is possible that recompilation of the class will produce a storage structure incompatible with existing data.

$SYSTEM.Task To Be Removed

Caché version 5.2 moved the task manager classes from %SYSTEM.TaskOpens in a new tab to %SYS.TaskOpens in a new tab. The documentation for the class were changed to indicate that the %SYSTEM.TaskOpens in a new tab class was deprecated. Users were advised to change their applications to use %SYS.TaskOpens in a new tab.


InterSystems intends to remove the %SYSTEM.TaskOpens in a new tab and the corresponding $SYSTEM.Task classes in the next version of the product.

Character Set Changes

Support For Unicode-16 And JIS2004 Added

Caché introduced support for Unicode in version 3.0. In this first implementation, only characters in the Basic Multilingual Plane (BMP), that is, those in the range U+0000 to U+FFFF, were supported. Version 2007.1 introduced support for GB18030 in one- and two-byte values.

This version extends that support to codepoints that result in Unicode surrogate pairsOpens in a new tab. These are pairs of 16-bit characters that, taken as a unit, represent Unicode characters outside the BMP. A surrogate pair consists of a high-order and a low-order code. The high word ranges from U+D800 to U+DBFF and the low word from U+DC00 to U+DFFF. When interpreted as a UTF-16 character, these pairs map from U+10000 to U+10FFFF and cover one million code points. Unicode strings that contain surrogate pairs are said to be encoded in UTF-16.

Existing ObjectScript string functions such as $Extract, $Find, and so on are not aware of surrogate pairs and thus can provide inconsistent results when supplied with strings that may contain such pairs. This version of Caché introduces specialized versions of the regular string functions that correctly handle surrogate pairs. These functions are:

  • $WAscii

  • $WChar

  • $WExtract

  • $WFind

  • $WIswide

  • $WLength

  • $WReverse

These new functions must scan the string in order to determine the boundaries between the characters because some may be represented by a single 16-bit value and others by surrogate pairs. For example, the 4 word sequence 0x41, 0xD800, 0xDC00, 0x42 is a 3-character string if surrogate pairs are taken into account because the two middle words correspond to a single character, U+10000.


The new W functions work as expected when supplied with regular 16-bit Unicode characters but are generally slower than their non-W versions due to the overhead of having to scan the target strings. Therefore, one should preferably use the existing non-W functions and resort to the new W ones only when there is a real possibility that the strings will contain surrogate pairs.

On 8-bit systems the $W* functions work as their non-W equivalents. In this case $WIswide() always returns zero.

New Collation Defaults For Some Unicode Locales

Some Unicode locales have had their default collations replaced with a new collation that allows any Unicode character to be encoded in a subscript. Their previous default collations were restricted to the 256 characters in their 8-bit base character set.

Locale Prior Default Collation New Default Collation
danw Danish1 Danish2
deuw German2 German3
ellw Greek1 Greek2
espw Spanish1 Spanish2
finw Finnish2 Finnish3
plkw Polish2 Polish3

The new collations were available in prior versions, but they were not the default. The older collations will remain available.


The new default is compatible with the old one in that alphabetic characters collate the same way. However, punctuation and control characters may collate differently since they are ordered as they are in Caché Standard.

Default For Simplified Chinese Changed

The Simplified Chinese locale (chsw) now uses GB18030 as the translation default where GB was previously used (Magtape, Printer, Terminal, Sequential files, $ZCONVERT). The GB table has been removed from the list of available tables.

Routine Changes

^NLSMGR, ^%Wsnls, ^%Wsnls2, and LOCGEN

These routines have been deleted as a result of the re-implementation of national language support.

Permissions For %ERN and %SS

We now allow a user with the %Development:USE permission to run %ERN and %SS. Previously we would only allow someone with %Admin_Operate:USE permission to run it. Write access to CACHESYS is still required to run %SS.

ObjectScript Changes

Explicit Conversion To $DOUBLE Now Required

Programs that depend on the automatic conversion of large decimals numbers to IEEE double precision numbers will now require an explicit call to $DOUBLE() to make that conversion.

Whenever a numeric literal is larger than 9223372036854775807E127 (or smaller than -9223372036854775808E127), a <MAXNUMBER> error will be generated. The error will also be generated whenever an arithmetic calculation involving decimal numbers exceeds this range. This reverts to the Caché behavior before version 5.2.

In version 5.2, IEEE double precision numbers were introduced. In that release, IEEE double precision numbers were generated by the $DOUBLE function and by decimal operations that exceeded the range for these numbers. Starting with version 2008.2, only the $DOUBLE function can be used to initially create IEEE double precision values. Out-of-range decimal literals and decimal calculations will generate the <MAXNUMBER> error. Some undefined computations involving decimal functions (example: $ZLOG(0)) will now return the <ILLEGAL VALUE> error rather than returning the IEEE infinity or NaN value.

Any operation with operands that are a mix of decimal numbers and IEEE double precision numbers will continue to have an IEEE double precision result. The newly defined $DECIMAL function will be available to convert IEEE double precision numbers to decimal numbers.

The reasoning behind this change is this. The mixing of decimal floating point with binary floating point caused some problems since their introduction. The Caché decimal type has almost 19 digits of accuracy; the IEEE binary floating-point type has less than 16 digits of accuracy. The IEEE binary double precison floating-point type has a much greater range (about 1.7976931348623158E308) than the Cache' decimal type (9223372036854775807E127 or 9.223372036854775807E145). Thus, a conversion in either direction will lose either range or precision. Also, most decimal fractions do not have an exact representation in binary floating point. Therefore, most conversions of fractional decimal numbers to IEEE binary floating-point numbers will involve a small change in value.

To reduce the impact of these incompatibilities between decimal floating-point values and binary floating-point values, InterSystems has decided to not automatically convert between these values. A conversion directly between these numeric values will require a direct call on the $DOUBLE or $DECIMAL functions.

New $ISVALIDDOUBLE Function Added

This version of Caché adds new function calls $ISVALIDDOUBLE(num) and $ISVALIDDOUBLE(num,scale,min,max). These functions are identical to $ISVALIDNUM except they always test validity for the $DOUBLE type.

The value of min, and max are always converted to the IEEE 64-bit binary floating-point type. If the num argument has a valid format, it is convert to the IEEE 64-bit binary, floating-point type. The min/max range is tested using binary floating point comparisons. If min is not supplied then $DOUBLE("-INF") is used. If max is not supplied then $DOUBLE("INF") is used. The value $DOUBLE("NAN") is always considered valid regardless of the values of min/max.

New $DECIMAL Function Added

This version of Caché implements $DECIMAL(X, N) which converts the IEEE double-precision value X to a decimal string with N significant digits. Rounding is done according to the IEEE Floating Point standard. Currently, values of N larger than 40 are unsupported.

If N has the value 0, then the result is a string with 20 significant digits and with special rounding. The result of $DECIMAL(X, 0) is also the default conversion of the IEEE double-precision value X to a string.

When $decimal(X,0) is evaluated the following rounding is done:

  • No rounding is needed if the result can be represented exactly in 20 or fewer significant digits.

  • If the result has more than 20 significant digits, and if the 20th decimal digit is a 0 or a 5, then it is rounded up to a 1 or a 6. All other digits in the 20th position will be left unchanged. Digits beyond the 20th position will be discarded or replaced with zeros as is necessary to put the string into numeric canonical form.


If a value with this special rounding is later converted to 19 or fewer decimal digits, then this second conversion will be the correctly rounded result of the original value, without a double-rounding error.

Also, the string value that results from $DECIMAL(X, 0) will collate in the correct order with the string values that result from converting a Cache decimal number to a string.


The function $ISVALIDNUM() has been changed. In this version of Caché, $ISVALIDNUM will return 1 only for syntactically correct strings. All others will return 0.

$DOUBLE Changes

The $DOUBLE() function now accepts “INF” and “NAN” as arguments resulting in the IEEE values infinity and not-a-number, respectively.

In keeping with normal Caché practice, strings beginning with “INF” and “NAN” produce the proper value even if these strings are followed by extraneous material. Thus, $DOUBLE(“INFRACTION”) produces a positive infinity, and $DOUBLE(“NANTUCKET”) a NaN. Also, an optional number of arithmetic signs may proceed the string value as in $DOUBLE(“-+-inf”). The case of the string is not relevant.

Infinity and NaN

A new draft standard for IEEE binary floating-point is under development. Under this standard, the valid strings for $DOUBLE will be restricted to “INF”, “INFINITY”, “NAN”, and “SNAN” (a signalling NaN is not distinguished by Caché from a non-signalling NaN). Developers are urged to restrict themselves to these proposed strings with a single optional sign character.

Controlling Overflow On Conversions

This version of Caché now allows the developer to control the behavior of programs in the presence of numeric conversion errors. This is done via the function, $ZUTIL(68,70,x).

  • If the value of “x” is 1, when $DOUBLE or $ZDCHAR encounter a numeric string with an absolute value too large to be a finite value of the IEEE 64-bit binary floating-point type, a <MAXNUMBER> error is reported.

  • If the value of “x” is 0, no error will be reported. Caché will replace the value with the appropriate value of infinity, “INF” or “-INF”.

For example, executing:

Write $ZUTIL(68,70,0) 
Write $DOUBLE("1e309")

does not result in a <MAXNUMBER> error; instead the string "INF" is written as the value.


The default value for overflow control when a process starts is 1.

Conversion Of Numeric Literals

During compilation when parsing a numeric literal, or at runtime when converting a string to a numeric value, Caché will convert the numeric value to a $DOUBLE (IEEE 64-bit binary floating-point type) if the value exceeds the range of the Caché decimal floating-point type. Note that this extends the numeric range, but it also reduces the numeric precision by about 3 decimal digits.

In this is not the desired behavior, the function, $ZUTIL(68,45), can be used to have these conversions from numeric string to decimal return the most-positive/most-negative decimal floating-point value when the range of decimal floating point is exceeded. Also, the function, $ZUTIL(68,70), which can be used to control error reporting when the range of $DOUBLE (IEEE 64-bit binary floating point) is exceeded.

Exponentiation to the Zero Power

In prior versions, Caché defined zero raised to the zero power as zero. This was true regardless of the numeric representation. Thus, X**Y always evaluated to zero when X and Y were both zero, regardless of representation – 0, $DECIMAL()), or $DOUBLE(0).

This interpretation is at odds with the proposed IEEE Floating-Point Standard which defines any IEEE value (including NaNs and infinity) raised to the zero power as 1. Accordingly, this version of Caché changes the definition of $DOUBLE(0) raised to the zero power to conform to the standard.

$FACTOR Improvements

In prior versions of Caché, calls to $FACTOR on negative numbers, INF and NAN did not give consistent results. This has been corrected by the following changes:

  • $FACTOR no longer computes approximate results and it no longer limits the number of significant bits to 64. $FACTOR now computes all the bits in the integer part of its arguments and returns the appropriate bit string.

  • When $FACTOR is applied to a negative argument, it returns the bit string corresponding to the absolute value of that argument. When $FACTOR is applied to $DOUBLE("NAN") or $DOUBLE("INF"), it returns an empty bit string.


The operation of the function, $LISTSAME, has changed slightly. When comparing items from each list argument:

  • elements with the value $DOUBLE(+0), $DOUBLE(-0) and 0 are treated as being identical.

  • element with the value $DOUBLE("NAN") to be the same as any other list element containing $DOUBLE("NAN").


Caché does not distinguish between different NAN representations even though the hardware underlying different platforms may generate different representations. Also, some NANs are considered to be signaling and others are considered to be quiet. Caché behavior does not depend on these differences.

THROW Without Argument Deprecated

This version of Caché deprecates the use of THROW without an argument. In its place InterSystems strongly recommends explicitly passing the exception as an argument to THROW. To understand the reasoning, consider the code fragment:

    TRY {
        Some statements
    CATCH {
        Error correction statements

If the execution of “Some statements” raises an error, the code for the CATCH block is executed. If “Error correction statements” do not themselves cause an error, the THROW will cause the error that occurred when “Some statements” were executed to be passed to an enclosing error handler.

If, however, the execution of “Error correction statements” causes an error, then the error from “Some statements” will be overidden and the enclosing error handler will receive this latter error information. The error that occurred in the TRY block will not be reported.

InterSystems recommends that the code be rewritten as

    TRY {
        Some statements
    CATCH ErrorData{
        Error correction statements
        THROW ErrorData

This ensures that, if the THROW is reached, the error information will be passed to the enclosing error handler. If the execution of “Error correction statements” causes a failure, this will be reported to the enclosing error handler, but the exception data from the TRY block will still be available for debugging.

In the rewritten example, if the error is detected by Caché, ErrorData will be an instance of %Exception.SystemExceptionOpens in a new tab. This class is reserved for use by Caché. Applications that wish to provide their own exception data should define subclasses of %Exception.AbstractExceptionOpens in a new tab and use instances of these subclasses as arguments for the THROW.


The main distinction between system exceptions and user exceptions is how they are processed. Instances of %Exception.SystemExceptionOpens in a new tab will be processed by the nearest enclosing CATCH, $ZTRAP, or $ETRAP statement.

User-defined subclasses of %Exception.AbstractExceptionOpens in a new tab will only be processed by enclosing CATCH statements. If there is no enclosing CATCH, a <NOCATCH> error will be thrown.

Thus, the reason for deprecating the use of THROW without an argument is the difference in the way system-generated versus application-generated exceptions are handled. The use of an argument allows precise control over the kind of exception process executed.

Supported Macros

This version of Caché defines the initial set of officially supported ObjectScript macros. These macros will be the only ones displayed by StudioAssist when the sequence, “$$$”, is recognized during program input. The full set of macros and their definition can be displayed via the $SYSTEM.OBJ.ShowMacros method.

Changes To Compiled Code

This version of Caché eliminates the tokens that were previously generated to mark the beginning of each line source line. The system now keeps track of the number of CacheObjectScript (or CacheBasic, CacheMVBasic, or CacheMV PQ/PQN PROC) statements that have been executed in a manner more efficient than previously.

This gives a much more accurate picture of how much work is going on in a routine. In previous versions, blank lines, comment lines, and lines with executable statements on them were all marked with these tokens. This change also frees programmers from worrying about the performance effects of writing in a much more readable, modern style, with each statement on a separate line, and with ample comments.

JOB Command Requires Startup Directory

Among the “process-params” given to the JOB command is os-directory, a directory the child job should switch to as part of starting up. This is not necessarily the directory the job will use as it may be overridden by the default directory associated with the namespace for the child job.

In prior versions, errors that occurred in the child job while attempting to switch to the os-directory were not treated consistently across platforms. On Windows and OpenVMS, errors were ignored. On UNIX®, the behavior varied by platform.

All platforms have now been changed to return a <DIRECTORY> error to the original job command if the child fails to switch to the specified o/s directory.

Class Changes

Class Compiler Correction — Signatures

In Caché 2007.1 and 2008.1, there is a deficiency in the class compiler mechanism for inheritance. This affected all inherited components except methods; methods are processed correctly. Specifically, the compiler failed to properly reconcile the attributes of the inherited component with the values possibly overriding them in the subclass.

This deficiency has been corrected in this version and those occasions where a subclass improperly overrides attributes of an inherited component will now be reported as signature errors in the component.

Class Compiler Correction — Properties

Prior to this version of Caché, it was possible to attempt a property “Get” on a class without supplying an instance context. However, Caché does not permit properties to be associated with classes similar to Java class constants; properties are associated only with class instances. The generated code for this case in prior versions was unpredictable as to what it would return.

This version of the class compiler reports an error that the result of the attempted operation is undefined.

Class Compiler — Journaling

When the journal switch was changed from being set individually for globals to being a database property, one effect was that class compiles were then journaled. However, if a class compile fails, the database it applies to will be in an inconsistent state until it is successfully recompiled. This means that there is no need to journal the class compile itself.

In this version, journaling of class compiles is off by default. It can be enabled using the qualifier '/journal=1'.


Systems using journaling to maintain a shadow system, relying on a compile on the main system being picked up on the shadow, should change the default qualifiers so that updates made as part of the compile will be reflected on the shadow system.

In Caché 2011.1, this change was reversed and journaling of class compiles is on by default in Caché 2011.1 and later versions.

Class Compiler — Query Compilation

In prior versions of Caché, all queries defined in a class were callable as stored procedures, even though only the ones marked as SQLPROC appeared in catalog queries. In this version, a query that is not explicitly defined as SQLPROC is no longer callable as a stored procedure. Any applications taking advantage of the older behavior will need to be updated.

Class Compiler — Keeping Query Intermediate Code

Beginning with this version, Caché no longer generates MAC code for the generated table routines; it now generates .INT routines and these are retained only if the "k" flag or /keepsource qualifier is specified. This behavior now matches that of the generated class routines.

NLS Changed To Use Object Interface

The ^%nls routines have been rewritten for this release using Caché object technology. Applications that used ^%nls directly in prior releases must be modified to use one of the methods found in the classes %SYS.NLS or %CollateOpens in a new tab.

New Argument Added to $SYSTEM.SQL.TuneTable

A new (sixth) optional argument has been added to the method, $SYSTEM.SQL.TuneTable. This argument expects a boolean value indicating whether to clear the SELECTIVITY and EXTENTSIZE values from the specified table.

If this argument is true, and the second argument (which indicates whether to update the table values) is also true, the SELECTIVITY and EXTENTSIZE will be reset.


If the class is deployed, the class definition will not be updated.

$SYSTEM.OBJ.ShowMacros() Method Added

The ShowMacros() method has been added to the $SYSTEM.OBJ class in this version of Caché. Invoking the method displays the documentation and definition of the supported Objectscript macros.

$SYSTEM.OBJ.GetClassList(.() Method Added

The GetClassList() method has been added to the $SYSTEM.OBJ class in this version of Caché. Invoking the method returns all classes in the current namespace as a local array subscripted by the class name. Class selection can be controlled by the following qualifiers, each of which is assigned a value of 0 or 1:

  • /application=<N> - Include application classes (<N> = 1)

  • /system=<N> - Include system classes, that is, ones with class attribute 'system' set to something other than zero (<N> = 1)

  • percent=<N> - Include percent classes (<N> = 1)

  • /mapped=<N> - Include classes mapped from other databases (<N> = 1). or just classes in default databases passed to the method (<N> = 0)

More information on qualifiers is displayed by the method call, $SYSTEM.OBJ.ShowQualifiers().

%SYNC.Transporter Class Added For Moving Objects

The %SYNC.TransporterOpens in a new tab is new in this version of Caché and is intended for copying persistent objects from one namespace to another. The class provides facilities for both sending and receiving objects. On the sending side,

  • An instance, T, of the Transporter class is created.

  • The Import of T is called to get the objects to be copied. The import operation automatically creates new objects or updates existing objects as required.

  • When all objects in this exchange have been registered, the ExportFile method is called to save the registered objects in a system file.

On the receiving side,

  • An instance, T, of the Transporter class is created.

  • The OIDs of the objects to be sent are registered with T.

%Studio.SourceControl.File Class Added

This version of Caché adds a new class %Studio.SourceControl.FileOpens in a new tab that just imports/exports classes, routines, and so on to a file in the filesystem. The item is determined to be editable if the user has write permission on the file.

This is an elementary source control class that can easily be enhanced to actually talk to a source control system. It is intended to be used as a base class for customer source control classes, or as a code example.

%Library.File Default Directory

In the class, %Library.FileOpens in a new tab, the following methods will use the value of $ZUTIL(168) (the current default directory), if no value is specified for the directory argument:

  • GetDirectory()

  • GetDirectoryLength()

  • GetDirectoryPiece()

  • GetDirectorySpace()

%Stream.FileBinary And %Stream.FileCharacter Classes Added

This version of Caché introduces two new classes that correspond to %Stream.GlobalBinaryOpens in a new tab and %Stream.GlobalCharacterOpens in a new tab. These use the new stream formats but store their data in files rather than globals.

The directory where the data is stored can be specified at the property level, for example,

property FileStream As %Stream.FileBinary(LOCATION="c:\temp");

The older classes, %Library.FileBinaryStreamOpens in a new tab and %Library.FileCharacterStreamOpens in a new tab, are unchanged; they will continue to work as before. However, if writing a new class it is suggested you use these new file stream classes.

Class %Library.EnumString Added

A new system datatype class has been implemented in this version of Caché, %Library.EnumStringOpens in a new tab. This class is identical to %Library.StringOpens in a new tab except that the string values are restricted to those specified in the VALUELIST parameter of the class:

  • The LogicalToOdbc method will look up the value of the string in the VALUELIST parameter and display the corresponding value in DISPLAYLIST.

  • The OdbcToLogical method will do the opposite; it looks up the value in DISPLAYLIST and returns the corresponding value from VALUELIST.

with the addition that VALUELIST->DISPLAY list transformation is done for LogicalToOdbc conversion, and DISPLAYLIST->VALUELIST transformation is done for OdbcToLogical conversion.

Class %SYS.Date.SlidingWindow Added

This class defines the commonly used entry points of the %DATE utility. The %SYS.Date.SlidingWindowOpens in a new tab class supports entry points for inspecting, setting and modifying the system-wide or process-specific sliding window definitions. Each class method with the exception of GetSystem() and GetProcess() returns a status indicating success or failure.

The %SYS.Date.SlidingWindowOpens in a new tab class implements almost all entry points of the %DATE utility and with this change makes this mechanism available to all Caché scripting languages. The functions of %DATE are implemented with slightly different names in %SYS.Date.SlidingWindowOpens in a new tab to make them more readable.


The %DATE utility is now deprecated. It will be removed from Caché distributions in some future version. Existing applications should convert to using the methods of %SYS.Date.SlidingWindowOpens in a new tab.

The following functions of %DATE are not implemented in %SYS.Date.SlidingWindowOpens in a new tab and will no longer be available once %DATE is removed from Caché distributions: CvtAbsStart, CvtAbsEnd, CvtRelStart, CvtRelEnd and LEAP.

Navigating %Library.RelationshipObject

Several methods have been added to the %Library.RelationshipObjectOpens in a new tab class to make it similar to a collection object. These methods can be called on a relationship whose cardinality is either MANY or CHILDREN. The following methods are now implemented:

  • GetObjectIdAt()

  • GetObjectIdNext()

  • GetObjectIdPrevious()


It is important to not that while %Library.RelationshipObjectOpens in a new tab implements a collection-like interface, it is not a collection class and is not required to implement the entire collection interface. Relationships are different from collections even though they implement many similar behaviors.

Inventory Scan Task Added To %SYS.Task

A new on–demand task has been added to the task manager. The “Inventory Scan” task (%SYS.Task.InventoryScan) runs the Inventory.Scanner.RunScan() method and saves the resulting inventory scan.

Inventory scans start from the instance install directory and perform a recursive examination of all directories, files, databases and routines within databases, recording their name, size, date last modified and a hash identifier. This data is stored into the %SYS database.

The Inventory Scan task is set to run automatically after the install or upgrade finishes. Users may start it manually thereafter, if they make changes to the system.


Starting with this version, defining a method whose language is set as TSQL automatically assumes PROCEDUREBLOCK equal to 1 overriding any explicit setting for the class or method.

CDL Qualifiers Removed

Object flags and qualifiers (“4” and “version4compatible”, respectively) referring to the ability to export data in CDL have been removed.

FetchODBC Method Removed From Default Query Interface

Prior to this release, the FetchODBC method was introduced to provide an interface to send query data to an xDBC client. Now, Caché has added a SendODBC method that much more efficiently sends the query data to the xDBC client and removes the need for the FetchODBC method. Therefore, FetchODBC code that just calls the Fetch query method and reformats the data is no longer generated. If a user had written a FetchODBC method, the SendODBC method will still user the users code as it would do before.


The FetchODBC method is unlikely to have been used by user code as it was previously only used by Caché to send data to xDBC. If an existring appl;ication relies on this FetchODBC method being generated, it will need to change to call the Fetch method instead.

Wider Recognition of LogicalToStorage and StorageToLogical Methods

The LogicalToStorage and StorageToLogical methods convert logical values to and from storage values respectively. Prior to this version, only methods inherited from the property type class (or property class) were recognized. This limitation was due to the way SQL recognized property methods.

In this version, inherited methods as well as locally overridden methods are recognized. It is now possible to implement LogicalToStorage and StorageToLogical methods for a property, and both SQL and Object actions will invoke them at the appropriate times.

%IO.FileStream Changes

The functionality of the method, Clear(), as been augmented by the methods, TruncateAt() and ExternalByteTruncateAt(). In addition, methods OutputToDevice() and CopyFrom() have been improved to do more accurate global timeout handling when copying from a sluggish stream.

Preserve Stream Content Across Restarts

Previously, when an application created a file stream where the LOCATION was not specified, Caché created it in the system wide temp stream location. If the application then saves the file stream, Caché marked it as permanent in the database, but did not move the stream from the directory.

The system wide temp stream location was automatically cleaned up on a Caché restart, so all such file streams were being deleted.

To address this issue, Caché now does the following:

  1. Caché will now allow a default stream directory configuration parameter for each namespace. If not specified, it will be assumed to be the stream subdirectory of the location of the CACHE.DAT file.

  2. When a stream file property is first initialized, if there is no LOCATION property parameter, Caché sets the directory to the default stream directory for this namespace.

  3. If an application writes to a stream where the directory has never been set, it will create a temporary file in the system wide temp directory. Saving this stream will move the file from the temp directory to the default stream directory for this namespace.

This will minimize change to existing stream behavior while ensuring that we do not lose any file. The current behavior of streams is:

  1. An application that opens an existing file stream or links to an existing file and then writes to the stream will create a new temporary file in the same directory as the existing file. If this is saved then the existing file is deleted and the temp file renamed so it has the same name as the linked file.

  2. An application that links to a filename that does not exist, and writes to the stream,will create a new file with the filename specified. Saving this stream marks it as permanent.

  3. For a class that defines a file stream as a property of a persistent object, creating a new instance and writing to trhe stream will create a new file in the default stream directory. Saving this object will mark the stream as permanent.

  4. An application that creates a new file stream object outside of a property, and does not specify a directory in the %New command, will create a new temporary file in the system wide temp directory when the stream is written. When the stream is saved, it will be moved to the namespace specific default stream directory.

Handling Of Time On Import Has Changed

The way Caché handles the last-modified time specified in files imported by XML and %apiRTN changes in this release to make it more consistent. The current rules are:

  • For classes, Caché allows the TimeChanged class attribute to be exported during XML export of a class definition. This may be suppressed by the /diffexport qualifier.

  • On import, if there is no last-modified time in the file, Caché will use the following algorithm:

    • If the class already exists and is identical to the previous copy, Caché uses the previous copy timechanged value.

    • If the class already exists and the timechanged is the same as the file time modified, then Caché uses the current time. This is because it must make sure this node is modified since the class is different from the previous one.

    • Otherwise, Caché sets the timechanged to the file time modified.

  • When an routine or class is imported, if the last-modified in the file differs from the last-modified time of the file, Caché assumes that the file has been modified by some external tool, but the timestamp in the file has not been updated; it uses the last-modified time of the file. This ensures the timestamp of the item in Caché changes so it can detect that this item has changed.


This change has also been made to time-modified handling by %R code.

%Monitor.Alert.External() Method Added

The %Monitor.Alert.External() method has been added to provide way for user applications to send alerts via SNMP or WMI. The method takes parameters that describe the alert and uses a generic Cache SNMP Trap (cacheAppAlert) or the WMI Cache_Event to send the information. See the %Monitor.AlertOpens in a new tab class documentation for more details.

File Archiving Classes

This version of Caché adds classes that permits connection to an external document retention service. The classes allow for the definition of content, %Archive.ContentOpens in a new tab, as well as the management of the initiation of the data transfer, %Archive.SessionOpens in a new tab. In this first release, the archive interface has been tested for use with the EMC Centera™ servers.

Row ID Flag Added to ResultSet Metadata

In the column metadata returned for queries and result sets, bit 12 is used to indicate that the column is part of the RowId..

%BuildIndices and %PurgeIndices Now Validate Names

The methods%BuildIndices and %PurgeIndices accept a $LIST of index names to use for their operation. Starting with this version, that list is now validated. If it contains a name that is not the name of an index that can be built in the current class, then the method returns an error status.

FreezeOnError Removed From System Classes

The FreezeOnError property for a Database is now always set to on. Therefore, all the FreezeOnError references have been removed from the system classes that define, manipulate or display this property. Specifically,

It has also been removed from the Management Portal.

XMLNew Method Argument Changes

The first argument is changed from type, “tree”, which is the index of the DOM in the global to type, “document”, which is a %XML.DocumentOpens in a new tab instance.

The second argument is renamed from node to nodeId for clarity.

There is now an optional third argument to XMLNew which is the oref of the already instantiated containing object. This allows seeing the object context when overriding XMLNew. The containerOref argument is passed by XMLImport when importing referenced objects as the containing object. The containerOref argument is “” when passed by %XML.ReaderOpens in a new tab for Correlate'd objects as there is no instantiated containing object in this case.

See the documentation for the class, %XML.AdaptorOpens in a new tab, for further details.

Translation List For Portuguese Updated

Uppercase accented characters of the Portuguese language were added to the character set of the %Text.PortugueseOpens in a new tab class. This allows Portuguese text containing uppercase accented characters to match with unaccented variations of the same word. The complete list of accented characters for the Portuguese language that are treated in this fashion is: “ÀÁÂÃÇÉÊÍÓÕÔÚÜ”.

TCP Broadcast Logic Changed

In prior releases, when the target process of a broadcast using the $zu(94) function has a TCP device as $Principal, the output data was buffered for the device. It was not transmitted until either the buffer became full or the process issues a subsequent "write !" to the device. In this version of Caché, the broadcast message will be transmitted immediately.

AllowSessions Property Removed from EnsLib.SOAP.Service

In the 2008.1 Ensemble release, the AllowSessions property was removed from the EnsLib.SOAP.ServiceOpens in a new tab class settings. It is no longer configurable; instead, you must choose whether the service should use CSP/SOAP sessions at compile time using the SOAPSESSION class parameter of EnsLib.SOAP.ServiceOpens in a new tab. The default for the parameter is SOAPSESSION = 0.

If your subclass of EnsLib.SOAP.ServiceOpens in a new tab relied on the AllowSessions setting to control session behavior, you must rewrite it to use the SOAPSESSION class parameter. If you are using sessions you must override it to SOAPSESSION = 1. If you do not use sessions, you can rely on the default setting.

See the Enabling SOAP Sessions section of the “Creating an Ensemble Web Service” chapter of Creating Web Services and Web Clients with Ensemble for details.

MultiValue Changes

Account Emulation Setting Affects MVBasic Command Line

Before this change the command was compiled with the options set by the most recent BASIC routine compile, or by entering a $OPTIONS setting on the command line.

Starting with this version, when a BASIC command is entered at the command prompt on the terminal, it will now be compiled using the account emulation settings. If a non-default option is required (one which is not the CEMU default), the $OPTIONS and the command must both be entered as one command line, separated by a semi-colon.

Debugging Display

While debugging an MVBasic routine at a terminal, the <BREAK> message will now include a line showing the name of the MVBasic source routine and the source line number.


Many lines of executed code may map to the same source line if that line is a $INCLUDE statement.

MVIMPORT For Universe Backups

This version of Caché changes the way Universe backups are imported, namely:

  • The O option has been removed.

  • If an account already exists, then MVIMPORT will not import the backup over it. The user must import to a non-existent account.

  • If MVIMPORT can locate a namespace of the same name as the account would use by default, then MVIMPORT will restore to that namespace if it is currently empty.


InterSystems recommend that users specify the “W” option when importing from Universe so that MVIMPORT will display its plan, then pause and ask for confirmation.

To have fine control over the location of databases, the “W” option will ask the user to confirm the accounts on the backup and the namespaces that MVIMPORT would use for them. Then quit out of MVIMPORT at the prompt and use the SMP to create the databases and namespaces in the desired locations. Rerun MVIMPORT and, if the plan is correct, continue with the restore.


In prior versions, the file, IMPORTED.VOC, contained the MVIMPORT exceptions, that is, all the items that were NOT written to the VOC. It now contains all the original VOC, regardless of whether or not the items were restored to the VOC. This allows a customer to see what the VOC looked like on their original system before MVIMPORT made decisions on whether or not to apply the items to the VOC.

Reference To Undefined Variables Returns <UNDEFINED> Error By Default

MVBasic routines will now be subject to the switch that controls all references to undefined variables in Caché. By default, MVBasic routines that attempt to reference an undefined variable will now get an <UNDEFINED> error. Before this change, an empty string was silently substituted for the undefined variable.

To change the default behavior:

  • For the current process –

    The process can invoke the either $ZUTIL(18, 2) or $ZUTIL(68, 72, 1) to restore the previous behavior.

  • For the entire system –

    Invoke $ZU(69, 72, 1) during system startup, such as in a ZSTU routine. Any new processes started after that point will have the previous behavior.

$GET Function Added

The function, $GET, has been added to MVBasic. This is a MultiValue analog of the Caché function, $GET, except that it does not have the Caché abbreviation of $G.


Prior to this change, $GET was a valid variable name. This is no longer allowed. Applications using $GET as a variable will have to be changed to use a different name.

Collation Changed

In prior versions, right justified fields that contain zero or null would sort into the same place in an index. Starting with this version, nulll fields will sort before fields containing zeros.


Any indexes on right justified fields should be deleted and re-built.

ED Changes

It is now possible to enter value marks or sub-value marks in ED the same way as other MV platforms. CTRL+\ will enter a sub-value mark $CHAR(252) and CTRL+] will enter a value mark $CHAR(253).

The TB command now works inside ED. For example,

TB 3,6,9

means set tab stops at 3, 6 and 9. If the user enters a tab at any point in the ED editor, the tab gets replaced with a number of spaces to satisfy the TB setting.

The delimiter between tab stops can be spaces or commas. The TB setting persists until the user logs off and on again.

TCL Changes

Caché now supports the TABS command. This is a TCL command and the format and usage is identical to the TB in the ED editor, for example:

USER: TABS 3,6, 9


By default, when an MVBasic routine is compiled, the system generates a routine name This name applies to the intermediate MVI source code and to the object code. If you want to specify a specific routine name for a source file, add a #PRAGMA statement to the file:


where “rrr” is the routine name and where “rrr” satisfies the syntax for Cache routines: first character is % or alphabetic, and subsequent characters are alphabetic, digit or period. If the name supplied is not in this format, an “invalid routine name”compiler error results.

Once a routine name has been associated with a source file, that name will continue to be used even if the #PRAGMA is removed. To stop using the associated name and have the system generate a new name, specify an empty routine name:



The empty name should be specified only once (for one compile). Then the #PRAGMA should be removed. Otherwise the system will continue to generate a new name each time the routine is compiled, instead of replacing the existing routine.

SYSTEM(31) Now Returns A Unique Value

SYSTEM(31) has been changed; it now returns a unique id for each Universe-related emulation. Prior to this, it did not distinguish among these.

SYSTEM(30) and SYSTEM(40) Now Return Port Ids

The SYSTEM() function which reports the owner of a lock after a failed lock operation will now return the port number instead of the process id of the owner. For D3 emulation, it is SYSTEM(30); for all other emulations, it is SYSTEM(43).

The process id continues to be available in STATUS() after the failed operation.

SYSTEM(0) In D3 Emulation Changed

In prior versions, for D3 emulation, SYSTEM(0) returned the lock owner. Now it will return the current STATUS() value, which will vary depending on the last operation that set a status value.

$CHAIN Support Removed

This directive was originally introduced in PICK to compensate for restrictions on the size of programs. In Caché, this issue does not arise. Applications attempting to use this directive will receive a syntax error and must be upgraded to use a more modern program linking mechanism, for example, subroutine calls.

Handling Breaks On INPUT

The Ctrl-C (break) sequence, if entered while executing the INPUT statement, will now go to the COS debugger. In prior versions, the application would return to the command line.


This assumes the application has not disabled this by executing BREAK OFF.

Log File Collects Erroneous Usage

When a MultiValue program uses a non-numeric string in a numeric operation, a value of zero is used. When this happens, Caché now writes an entry in the mv.log file when this action is taken., Developers can review this file and take action to correct the program or data. The file, mv.log, is an operating system file in the Caché installation Mgr directory. The entry will indicate the program line that used the incorrect value.

Support For MVBASE Dimmed Foreground Colors Added

The MVBASE emulation now supports the sequences @(-57) through @(-64) to produce the dimmed foreground colors white, yellow, magenta, red, cyan, green, blue, and black, respectively.

Terminal Type Additions

New terminal types vt100-color, vt220-color and vt330-color have been added in this version. They were added rather than modifying existing definitions to conform to common practice of creating "-color" definitions in cases where color schemes are optional.


The PICKMON terminal definition has a new boolean value added, XPICKCOLOR. This is a non-standard terminfo value (hence the name beginning with “X”). It allows the color definitions 'setab' and 'setaf' from PICK-style color sequences rather than ANSI style color sequences.


Customers using PICKMON terminal definitions with a terminal client such as Accuterm that use the color sequences may need to manually upgrade their TERMINFO definition for PICKMON when they upgrade from earlier versions. New installations are not affected. This involves adding the following line to the PICKMON item in the TERMDEFS file


and then running the program "COMPILE.TERM". Restarting the MV shell will activate the new definition.

SQL Changes

Improved SQL Support for Streams

This version of Caché has improved the handling of streams as fields in SQL tables, namely:

  • It is now possible to open the stream returned via a simple function that returns of OID value of the stream. This is true for stream fields which are NULL as well, though attempting to read them will result in an immediate EOF.

  • The INSERT and UPDATE clauses now accept such an OID as the new value for a stream field in a table.

  • The SUBSTRING function now accepts a stream as its first argument.

  • The INSERT and UPDATE clauses now accept such an OID as the new value for a stream field in a table. The SUBSTRING function now accepts a stream as its first argument.

  • The ODBC and JDBC gateways now provide this support as well.

Support For SQL Column-Level Privileges Added

Caché SQL now supports column level privileges for SQL INSERT, UPDATE, SELECT, and REFERENCE privileges. The syntax for granting privileges at the column level for INSERT is:

GRANT INSERT ( FieldName1 [,FieldNameN ...] ) ...

for example,

GRANT INSERT ( Name, SSN ) ON Sample.Person TO John

will give John permission to insert into the Sample.Person table but only specify values for the Name and SSN fields. All other columns would be set to their default values (if they have one) or to NULL (if they have no default and are nullable).

The syntax for granting UPDATE and SELECT privileges is similar.

Caché SQL now also supports the ability to REVOKE privileges on columns. The syntax for REVOKE is the same as previously except that a user must specify the optional column list after the privilege. For example:


Other items of note:

  • Although Caché allows granting and revoking column level privileges for the REFERENCE privilege also, the REFERENCE privilege is not currently fully supported in Caché SQL. Full Support for REFERENCES is planned for the future.

  • Column-level security does not invalidate tabel level privileges; these are still fully supported in a backward compatible manner. If an application uses only table level privileges, and has no need for column level privileges, everything will work as before.

  • If a user grants a privilege at the table level, the SQL standard says the grantee will have privileges on all columns of the table as it is currently defined, and all privileges on any columns added to the table in the future. This is supported. However, Caché SQL does have the following limitation: You cannot grant a privilege at the table level, and then revoke the privilege from a set of columns of the table. Instead, the user should grant permissions only on the columns needed, leaving the remainder of the table inaccessible.

  • The %CHECKPRIV statement has been enhanced to support checking for privileges at the column level.

  • Users will now need SELECT privilege on any field names specified in an INSERT or UPDATE statement that are not part of the INSERT or UPDATE field list. In addition, If arrow syntax is involved, the user also needs SELECT privilege on the ID of the referenced table in addition to the referenced field.

Text Search In Long Streams

Previous versions of Caché provided the ability to search text represented as streams. However, searching streams longer than 32K required that long-string support be enabled. In this version of Caché that restriction has largely been lifted except for:

  • Use of the %CONTAINS predicate requires that the stemmed, noiseword-filtered text be converted to a string. To avoid the possibility of that text being to long, applications should use the %CONTAINSTERM predicate instead.

  • If the %SIMILARITY operator is used on a non-indexed field, the document will be broken up into chunks of 32K or less characters. In this case, terms that span boundaries may not be properly referenced. TO avoid this issue, %SIMILARITY should only be used on indexed fields.

Computed Property Self-Reference

Beginning with this version, computed properties can use {*} to refer to the current property in the compute code. This allows for more easily transportable compute code. For example, the following would be displayed in Studio

Property FOO As %String [ Calculated, SqlComputeCode = { s {*}="bar"}, SqlComputed];

Duplicate Fields In Update or Insert Statements No Longer Allowed

Starting with this release, an SQL INSERT or UPDATE statement that contains duplicate fields will now be reported as being in error when the statement is prepared or compiled. For example, the following statement will result in an SQL error code:

insert into sample.person (name, Name) values ('Dave','tom')

 insert into sample.person set name = 'Dave', Name = 'Tom'
 update sample.person (name, Name) values ('Dave','tom')

update sample.person set name = 'Dave', Name = 'Tom'

The new error code value is -377; its message is “Field name '%1' appears more than once in assignment list of insert or update statement”.

SQL COALESCE Function Requires Compatible Types

In SQL,when preparing or compiling a query that contains the COALESCE function, Caché will now return an error (SQLCODE = -378) if the datatypes of arguments are not compatible with each other. Compatibility is judged according to the ODBC type of the data. If the type are compatible, but different, the COALESCE function will return a value of the type with the highest precedence. All the numeric types are compatible and have the following precedence:







For example, in a COALESCE function call with arguments of type TINYINT, INTEGER, and NUMERIC, the type of the column will be NUMERIC because NUMERIC has the highest precedence.

All of the other ODBC types are currently not compatible with other types, so they must be explicitly CAST in the function argument in order to mix types.


Normalizing the type to the one with the highest common precedence may change the way numbers are displayed. Changing the apparent type from INTEGER to NUMERIC, for example, will display the results with decimal points.

SQL UNION Enforces Type Compatibility

In previous versions an SQL query such as

    SELECT 0 AS var1 FROM Table1 
    SELECT 0.1 AS var1 FROM table2

report INTEGER as the column type of var1 to ODBC and JDBC. The 0.1 value would be sent to the client as an integer and the data truncated as a consequence.

In this version the SQL processor will examine all parts of the union and return the type of the highest precedence for each column. The order of precedence for Caché types is:








Thus, the query

    SELECT MyTinyIntField AS var1 FROM Table1 
    SELECT MyIntegerField AS var1 FROM Table2 
    SELECT MyNumericField AS var1 FROM Table3 

will return type NUMERIC for the column since it has a higher precedence than TINYINT and INTEGER.


Normalizing the type to the one with the highest common precedence may change the way values are displayed. Changing the apparent type from INTEGER to NUMERIC, for example, will display the results with decimal points.

At this time Caché will only use the type precedence in UNIONs as listed above. If other types are involved, no automatic type detection will be done. The type of the union fields with the highest precedence will be returned. Other types will be ignored. If a specific type is desired for the column, an explicit CAST statement must be used, for example,

    SELECT CAST(MyStringField AS DATE) AS var1 FROM Table1 
    SELECT MyDateField AS var1 FROM Table2 

SQL Query Collation Results Now Depend On All UNIONs

Beginning wit the version of Caché, if a FROM view or subquery consists of a UNION, then the collation of a resulting field will depend on the collations of the corresponding field/expression in all the UNION legs, using EXACT (no collation) if they do not match. In previous versions, the collation was determined by the first UNION found.

Stream Coercion Not Allowed In SQL UPDATE

Starting with this version, an attempt to Prepare or Compile an UPDATE statement that sets a non-stream field equal to the contents of a stream field will now receive an error. There is no implicit datatype conversion supported for this case. For example:

     SET MyStringField = MyStreamField ... 

will fail with SQLCODE = –303: No implicit conversion of Stream value to non-Stream field 'MyStringField' in UPDATE assignment is supported.

The proper way to perform this assignment is to convert the fields from Stream to String using the SUBSTRING function. Suppose the length of MyStringField is 2000 characters. The statement:

     SET MyStringField = SUBSTRING(MyStreamField, 1, 2000) ... 

will set the MyStringField to the first 2000 characters of the MyStreamField.

Support For LAST_DAY Function Added

Caché SQL now supports the LAST_DAY() scalar expression function. The syntax is


where <expr> is a %Library.DateOpens in a new tab or %Library.TimeStampOpens in a new tab value. The return value of the function is the number of the final day of the month that contains the date or timestamp supplied.

Support Field Collation Names Without Leading %

When specifying a columns collation function in SQL DDL, Caché now supports the name of the collation without the leading “%”. For example Caché now supports:


as being identical to

TCP Keep Alive Interval

This version introduces a new SQL Configuration setting that controls the TCP keep-alive timeout for individual processes (rather than relying on the machine-wide setting). This makes it possible to detect lost connections due to network failures, VPN trouble, and so on in a more reliable fashion. If there is a network failure, Caché will throw a <DISCONNECT> error within the timeout period specified rather than the machine default (which is something like 60 minutes).

The interval value is accessed via the Management Portal at Home,Configuration,SQL Settings as the field, “TCP Keep Alive interval”. It can be set programmatically via the method, SetTCPKeepAlive in the $SYSTEM.SQL class..


This feature is available only on Windows and Linux platforms.

Static Cursors May Return More Rows

The limit on the number of rows that can be return by static cursors has been expanded. In prior releases, it was 32K rows. Beginning with this version, it is 4GB.

Unamed SAVEPOINT Support Removed

The SAVEPOINT capability was introduced in Caché version 5.1. This change removes support for unnamed savepoints to enhance compatibility with the savepoint implementations of other vendors. Unamed savepoints are not widely used among Caché applications. Applications that do use the feature will need to be modified to specify savepoint names.

ORDER BY Not Allowed In View

In previous versions, if an ORDER BY clause was used with a view in an SQL expression, Caché would ignore the ORDER BY clause. Beginning in this version, use of the ORDER BY in that situation will generate SQL error -143: ORDER BY not valid in a view's query.

Compilation Checks Field Names In Maps

In prior versions, the class compiler did not complain about references to nonexistent properties in the CacheSQLStorage map. Now, a non-existent field that is part of an expression in a map subscript will be reported as an error during class compilation.

The compiler now also checks that all field references are of the form schema.fieldname and that the schema is correct.

Privilege Checking Extended To Functions Called From Queries

Beginning in this version, Caché SQL now checks to see if the user executing a query has the privilege to execute any procedures called as user-defined SQL functions in that query. The user must have EXECUTE privilege on the functions procedure in order to execute the SQL statement that calls it. For example, to execute the query:

SELECT A, B, MyFunction() from SQLUser.MyTable

the user will need SELECT privilege on the SQLUser.MyTable table and EXECUTE privilege on the SQLUser.MyFunction procedure.


As with all other SQL privilege checking, this only applies to SQL prepared and executed via ODBC, JDBC, or any flavor of Dynamic SQL. It does not pertain to Objectscript embedded SQL, “&sql( ... )”.

Long Fields In xDBC Queries

If a class defines a property of type %Library.String, and the MAXLEN for this property is greater than 16374, when this field is selected in a query over ODBC or JDBC, only the first 16374 characters of the field will be returned. To support data in a single field longer than 16374 characters, use a stream datatype in place of the string.


Current ODBC and JDBC drivers have differing limits on the maximum length of returned columns. For those used with Caché, customers should assume that the maximum length returned by a query is 4096 characters.


The behavior for conversions of SQLBINARY, SQLVARBINARY, and SQLLONGVARBINARY has changed. It now returns two character hex values for each byte of data returned as SQL_C_CHAR and SQL_C_WCHAR.

The algorithm used in prior releases could result in erroneous conversions and/or incorrect string lengths. This caused problems for WinSQL when displaying SQLLONGVARBINARY columns. This change alters the behavior when using SQLFetch and SQLGetData for columns using these datatypes. The behavior now matches what is seen with SQLServer data.

CSP Changes

Properties Of %request Marked Read-Only

Modifying some properties of the %request object that are provided by the CSP gateway would cause the next request in the same process to also show this modified value. This could result in subtle errors in the application. To ensure this problem does not occur, this version of Caché now marks the following %CSP.RequestOpens in a new tab properties as read only: UserAgent, ContentType, CharSet, Method, Protocol, Secure, GatewayApplication, GatewayConnectionName, GatewayBuild, GatewaySessionCookie, GatewayInstanceName, and CSPGatewayRequest.

Added %request Properties

This version of Caché adds the following properties to the %CSP.RequestOpens in a new tab object: GatewaySessionCookie and GatewayInstanceName.

Hyperevents Now Changed To Use xmlHttpRequest

In prior releases, CSP supported hyperevents in Java via CSP Java Event Broker and the JavaScript framework using iframes to invoke server methods. This was because not all browsers provided the xmlHttpRequest object for this purpose. This is no longer true. All supported browsers provide this functionality; it has been the default mechanism for CSP for several releases.

Beginning with this release, support for the older mechanism has been removed and all server requests will use the xmlHttpRequest for hyper-event processing. Specifically, this means:

  • The methods used to include code for iframe and Java applet support are deprecated.

  • The Java Event Broker and iframes have been removed from the product.

  • The method calls HyperEventFrame and HyperEventBody of class %CSP.PageOpens in a new tab

    now always return the empty string.

  • The method call HyperEventBody of class %CSP.ResponseOpens in a new tab

    now always return the empty string.

  • The attributes InsertBrokerIframe and InsertBrokerApplet of the CSP:CLASS tag are deprecated. When present, the javascript (.js) files for XMLHttpRequest hyperevent will be included instead.

  • To avoid requiring changes to existing applications, the %CSP.PageOpens in a new tab) methods, HyperEventBody, and HyperEventFrame, will be retained and always return the empty string.

  • The “HyperEvent Implementation” choice has been removed from the Management Portal.

  • The property, HyperEvent, in the Security.ApplicationsOpens in a new tab class has been deprecated. Applications using the security API to manipulate CSP pages should be changed since this code no longer has any effect. This property will be removed in a future release.


InterSystems expects this change to have no impact on existing applications. The documented APIs for using hyperevent calls in CSP shield applications from the internals of the mechanism used to execute such calls so this change will be transparent to applications.

CSP Gateway Changes

The CSP Gateway consists of two modules: A Management Module, CSPmsSys.dll, and a Runtime, CSPms.dll. The runtime is responsible for processing requests for CSP files and the Management module provides the Gateway’s Management interface.

In older versions of the Gateway, these two modules were configured separately in the web server configuration. In this version, the runtime assumes responsibility for loading and routing management requests to the management module; it is no longer necessary to configure the Management module in the web server. This greatly simplifies the overall web server configuration for the Gateway.


To find the build of the CSP Gateway that you are running, in the System Management Portal, go to Home,Configuration,CSP Gateway Management and choose “About CSP”. The build number is the last four digits of the Gateway Build field, after the dot, such as 1020.

Serve Static Files From Caché Instead Of WebServer

In earlier versions, only files of type .csp, .cls and .zen were processed in Caché by the CSP engine. All other (such as static) files were served by the web server. With this version, the CSP engine is capable of serving any type of file that is placed in the CSP applications path (including static files). Among the advantages of this approach are these:

  • The application is simpler to administer and deploy since all the files are on the Cache server. There is no need to copy static files to the web server machine; all files now come from the same place.

  • This provides the ability to remap file locations so common files may appear to be in every path when there is a single copy in a central location in the /csp/broker application.

  • Caché security rules can now be applied consistently both dynamic and static files.

  • The web server configuration for CSP applications to be further simplified because it is no longer necessary to create aliases in the web server configuration to represent the locations where the static files for an application reside. This resolves issues of contention when a single (i.e. common) web server serves two different versions of Caché, each requiring different versions of certain static files (for example, hyperevent broker components).

To support these changes, new configuration options specified with the CSP application settings have been added:

  • Time to cache static files: This defaults to 1 hour if not specified. This is both the time the browser will cache this file and also the time the CSP gateway will cache this file if this caching is turned on.

  • Modify the “Server Files” question to change the choices to:

    • No: Never server files from this application path

    • Always: Always server files from this application path, ignoring CSP security settings for this path for static files. This is the default for new applications; it is backward compatible with previous behavior serving files from the web server.

    • Always and cached: Always server files from this application path and allow the CSP gateway to cache these files to avoid having to request them from Caché. This is the mode most deployed application should use.

    • Use CSP security: If the user has permissions to view a .csp or .cls page in this application, allow them to view tatic files, If they do not have permissions to view a .csp or .cls page then return an error code of 404 (page not found) page. This is not cached in the gateway as only the server can decide if the user has the correct security permissions.

Any files placed in /csp/broker will effectively appear in all directories as the server will first look to see if the file, /csp/user/file.txt, is present. If not, it will look in /csp/broker/file.txt and, if there is a file with this name there, then it will serve this file up. This will allow applications to remove hard links to /csp/broker files which makes having a single server that serves up applications from multiple versions of Caché possible.

Password Change From Empty Detected

In previous versions, an attempt to change passwords using the CSP password change page where the old password was “” did not succeed. The code acted as if no old password had been passed to it. Now, it does detect that the old password was passed, was just “” and calls the password change code.

XML Changes

Support for Binary SOAP Messages

If the parameter SOAPBINARY is set to 1 for a web service, then binary transmission of SOAP messages between Caché instances will be enabled. The web service will then support normal XML based SOAP or Caché proprietary SOAP format over HTTP. The SOAP binary transport will be implemented using a custom object serialization mechanism. Any class used by the web service must be a subclass of %XML.AdaptorOpens in a new tab.

The WSDL produced for a Cache web service with SOAPBINARY parameter specified as 1 has been enhanced to carry the necessary information for the Cache web client. These WSDL extensions are valid according to the XML Schema, WSDL and WS-I Basic Profile specifications and are expected to be ignored by all conforming web client toolkits.


Web Client toolkits which do not support the WS-I Basic Profile may experience problems with a WSDL that is generated for a Cache web service with SOAPBINARY = 1. This should be quite rare and found only with older toolkits.

Support XML Exclusive Canonicalization Version 1.0

Caché now supports XML Exclusive Canonicalization Version 1.0Opens in a new tab (except for the InclusiveNamespaces PrefixList feature of Exclusive Canonicalization). This means the Canonicalize method of %XML.WriterOpens in a new tab writes the XML document represented by the subtree at a %XML.NodeOpens in a new tab class instance in canonicalized form as mandated by the specification. As part of this implementation the order of output of attributes by the Tree, Document and DocumentNode methods is changed to be in the canonical order. This change will mostly be noticed in the output of schemas and WSDLs.


This reordering will have no effect on any standards-conformant XML processor.

As part of this implementation the SuppressAutoPrefix property is added to %XML.WriterOpens in a new tab and %XML.NamespacesOpens in a new tab which allows optional suppression of the prefix that is created for the default XML namespace even if it is not needed for the current element.

Most methods in %XML.WriterOpens in a new tab now escape characters as specified by the XML Canonicalization standard. The following table describes how methods in this class escape specific characters, when found in attributes and in elements:

Original Value How Value Is Escaped When Found in Attribute* How Value is Escaped When Found in Element
& &amp; &amp;
< &lt; &lt;
" &quot; no escaping
$CHAR(9) (tab) &#x9; no escaping
$CHAR(10) (line feed) &#xA; no escaping
$CHAR(13) (carriage return) &#xD; &#xD;
> no escaping &gt;

*This column applies to the method WriteAttribute() and to the methods that use WriteAttribute(): Document(), DocumentNode(), Tree(), Canonicalize(), CanonicalTree(), Element(), and RootElement().

This column applies to the method WriteChars() and to the methods that use WriteChars(): Document(), DocumentNode(), Tree(), Canonicalize(), and CanonicalTree().

Note that Object() and RootObject() do not use WriteAttribute() or WriteChars().

The change of escaping of text and attributes could be noticed, but should make no difference in any XML processing. The most noticeable change is that the WriteChars method of %XML.WriterOpens in a new tab will now escape $CHAR(13) characters and thus $CHAR(13,10) will have the $CHAR(13) escaped as &#xD; which means that the $CHAR(13) will be in the data when it is later imported. Previously, it was lost.

Terminal Changes

Terminal Local Network Encoding Changed

The Terminal local connection default network encoding has been changed to UTF8 in 8-bit installs to be consistent with the default Caché server default value.

Changes To Terminal Connection Display When Invoked From Scripts

Beginning with version 5.1, a Terminal session would begin by displaying the Node and Instance name that was the endpoint of the connection. It was done so a customer connecting to a machine via telnet would get a confirmation indication that they connected to the correct instance. However, this caused some existing customer scripts to fail because the display of the node and instance could throw off the parsing of the output.

In this version, the terminal will not display the node and instance if a routine is passed in on the command line, for example,

csession cache -U%SYS ALL^%FREECNT

since the process entering Caché is already on the correct node, and specifies the correct instance on the command line. In all other circumstances, the node and instance names will be displayed.

Standardize UNIX® Names For ODBC

InterSystems is standardizing on iODBC for building our narrow and wide ODBC dependent projects. Cgate is already using an "i" or "u" suffix to designate iODBC and unixODBC respectively. A "w" suffix will designate a wide or Unicode version of the library.

The file, libcacheodbc, will continue to be the narrow version of the InterSystems ODBC driver using iODBC headers, but libcacheodbciw will be the Unicode version of the InterSystems ODBC driver supporting iODBC.

Currently the narrow version of cgate and libcacheodbc will remain the default working executables in shipped examples. It is up the user to configure to use the Unicode versions of cgateiw or libcacheodbciw if needed.


Mac platforms require a special link operation on libcacheodbciw to support the cppbinding and that will be called libcacheodbcmiw.

Language Binding Changes

Light C++ Binding Reference Count Behavior Changed

Prior to this change, if openid() was called twice for the same class and id, and the results assigned to two different lc_d_ref's, those lc_d_ref's pointed to two separate projection objects in memory, each initialized with property values from the same database object. Setting new property values using one would not affect the other. If changes made to one were saved, and then changes made to the other were saved, the property values from the last-saved projection object would overwrite those from the previously-saved projection object.

Similarly, if a projection object returned by create_new() was assigned to an lc_d_ref and saved to the database, and openid() was then called for that class with the id of the newly-saved object, and the result assigned to a second lc_d_ref, the two lc_d_ref's would point to two separate projection objects in memory.

This version changes the semantics of the Light C++ Binding object references (lc_d_ref's) to match the semantics of regular C++ binding object references (d_ref's), for cases in which multiple lc_d_ref's refer to an object of the same class with the same id.


Well-designed applications should not experience any problem or notice any change in behavior. However, if an application was coded to use multiple references to the same object, and counted on the ability to modify the object through one of the references without affecting the in-memory values seen through the other references, the application's behavior will change. All of the references to the same class/id now point to the same object in memory.


System Management Portal

There have been no incompatible changes to the operator interface. Operators are advised to review the administrator section.

Default Configuration File Named Handling Changed

The default configuration file name used when Caché is started has changed. Please refer to the administrator section for the details.

FeedbackOpens in a new tab