Skip to main content

Release and Upgrade Information for Caché 2010.1

This chapter provides the following information for Caché 2010.1:

New and Enhanced Features for Caché 2010.1

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

Furthermore, this version of Caché has been improved and enhanced in the following areas:

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

Major New Features

Class Compiler And Routine Dispatch Improvements

Version 2010.1 contains many improvements to the performance and reliability of our object implementation. Many of them are changes to the underlying implementation and therefore invisible to developers. Their effects are evident as much improved compilation times – some early testers report up to twice as fast - and faster run-time performance. The class compiler has been improved to support richer development options, better ease of use and faster compile times. The corresponding object runtime and dispatch mechanisms have also been enhanced for better performance and scalability. Version 2010.1 now supports runtime superclass resolution, system implementations for commonly generated property methods (Get, Set, isModified, setModified), and a shared class cache.

There are new compiler and class dispatch mechanisms that avoid errors associated with compiling a class while instances of the class are in use. The compiler also has improved logic for determining when changes to a superclass require recompilation of subclasses; this avoids unneeded recompilation. Details may be found in “Class Compiler Notes” in Using Cache Objects.

Java Dynamic Object Interface

This version of Caché introduces a new high-performance interface for Java programs that provides the following:

  • Multidimensional Storage (MDS) API

    Java applications may now access and manipulate Caché globals directly via a JNI (Java Native Interface) without requiring a conversion to Java objects. It enables the Java application and Caché to execute in the same process space. Among the advanced features of Caché supported by this interface are:

    • Locking (incremental, non-incremental, exclusive, shared ...)

    • Transactions

    • Iterating over globals represented in the multidimensional data structure

    • Automatic parsing of Java arrays or strings to create or update Caché $LISTs

  • Java Dynamic Object API

    The API provides very fast Java access to objects stored in Caché via an in-process connection based on JNI, the Light C++ Binding, and Caché callin. The API is dynamic; the classes accessed need not be known at Java application compile time, and no separate code generation step is required.

  • In-process JDBC

    This enables JDBC to use a non-TCP/IP connection to Caché like the Dynamic Object API. Applications can execute SQL queries and other SQL statements via JDBC, and in the same transaction context as methods of the Java Dynamic Object API.

Rapid Application Development

Dynamic SQL

This release of Caché includes support for a new interface for dynamic SQL, which allows users to define and execute SQL statements at runtime. Dynamic SQL is now implemented through the %SQL.StatementOpens in a new tab and %SQL.StatementResultOpens in a new tab classes. %SQL.StatementOpens in a new tab includes support for the following methods:

  • %New – for instantiating a new statement object

  • %Prepare – for preparing an SQL statement, including one that supports runtime parameters

  • %Execute – for executing a prepared statement

Execution of a dynamic SQL statement creates a result object, which is an instance of the %SQL.StatementResultOpens in a new tab class. %SQL.StatementResultOpens in a new tab can hold simple data, a single result set, or multiple result sets, depending on the SQL statement that was executed. It includes functionality for iterating through a result set, handling errors, and so on; it also includes functionality for examining statement metadata, manipulating the form of data for display, and related operations.

For more information on dynamic SQL, see the chapter Using Dynamic SQL.

Performance And Scalability

ECP Scalability Improvements

In prior versions, if a request buffer from an ECP application server contained a synchronous request (such as a Set, Kill, $INCREMENT, and so on) that resulted in a disk I/O, subsequent requests in that buffer would wait till the disk I/O for the synchronous request completed. Now, the ECP server process daemon on the database server will continue to service subsequent read (or get) instructions that can be serviced from the buffer, in parallel while the disk I/O is completing, thereby speeding up responses to the application server.

Reliability, Availability, Maintainability, Monitoring


The DataCheck facility provides a mechanism to compare the state of data on two systems to determine whether the two are consistent. It accounts for the situation where the data on each system may be in transition, and includes logic to re-check discrepant ranges. A typical use of this functionality would be to verify that the source and destination of shadowing are consistent.

Compression During Shadowing

Caché version 2010.1 introduces compression of journal data from the primary to the shadow. The source (primary) compresses a source journal block before sending it to the receiver (shadow); the receiver decompresses it upon receipt, prior to saving it to the shadow copy of the source journal file.

ECP Responsiveness Metric

Fast responsiveness of a Data Server is key to good performance on the Application Server. To permit measurement of response times, a new property, ResponseTime, has been added to the SYS.Stats.ECPAppSvrOpens in a new tab class that allows you to measure the responsiveness of the Data Server(s) that this application server is currently connected to. If there are multiple connections, the value is the overall response time for all Data Server connections. To compute the average response time, use the number of connections contained in ResponseConn.


Separate Delegated Authentication and Delegated Authorization

With this release applications can now use different third party technologies for Kerberos and OS authentication using the Delegated Authentication mechanism. This allows customers to use LDAP (Lightweight Directory Access Protocol), for example, to define the Roles of a user, while using Kerberos to authenticate the user.


Removal Of $ZUTIL Documentation

In this release, InterSystems provides class components (methods, or properties) that have the same information and functionality as each of the documented $ZUTIL functions. This has been done to provide a more modern interface to system services available to a wider range of languages used in Caché applications.

In accord with this transition, the documentation for the $ZUTIL functions has been excised from the ObjectScript reference book. It is now part of a separate document stored in the legacy documentation archive. No further updates to it will be made.

The $ZUTIL functions will remain available for applications to use. However, all future functionality updates which would have been done by adding new $ZUTIL functions will use a class paradigm instead.

InterSystems encourages applications to convert to the new usage. To assist in the transition, a table giving the $ZUTIL function identifier and the new equivalent is given in the conversion checklist for this release. The information will also be reproduced temporarily in the ObjectScript reference work as well.


In a few instances, the $ZUTIL functionality is now provided by system variables ($NAMESPACE, and $DEVICE). Also, this information does not include those $ZUTIL functions affected by the removal of support for DDP and DCP.

Change In PDF Page Size

The page size for documentation PDFs has changed in the version. Previously, pages assumed a height of 9 inches and a width of 7 inches. Now they use a height of 11 inches and a width of 8.25 inches. The margins have also been been reduced slightly to 0.75 inches.

This new format permits larger tables and figures, and wider program listings. Waste paper as a result of cropping has been eliminated since the new format will fit on both A4 and U.S. letter-sized paper without need for cutting before binding.

Planned Changes

Database Extents Deprecated

The use of database extents was introduced in early releases to work around the fact that files sizes were severely restricted. Databases of that period often exceeded the limits on the size of an individual file. Database extents allowed a logical database to span multiple physical files.

The limits in the underlying technology are no longer relevant – operating systems, mature filesystems and volume managers currently provide support for extremely large files. Database extents have been rendered obsolete. In the interest of simplifying system management, database extents are no longer supported as of this release.

In a future version, Caché, Ensemble, HealthShare and TrakCare will no longer support database extents. A tool will be provided to assist any customers with extents to aggregate them into appropriate files.

DCP, DDP And LAT Deprecated

InterSystems introduced Enterprise Cache Protocol (ECP) in 2002. Since then, all of our major customers have adopted ECP to deploy scale-out architectures. Usage of DCP and DDP, earlier technologies used to network databases, has diminished considerably and is now almost exclusively used when data is shared between Caché and earlier M technologies.

We intend that, in the latter half of 2010, Caché and Ensemble releases will no longer support DCP and DDP. LAT support on Windows will be deprecated at the same time.

Caché 2010.1 Upgrade Checklist


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

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

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


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

Version Interoperability

A table showing the interoperability of recent releasesOpens in a new tab is now part of the Supported Platforms document.

Management Portal Changes

Numerous changes have been made in the Management Portal for this release both to accommodate new features and to reorganize the existing material to make it easier to use. Among the more prominent changes are:

Operational Changes

Journaling Status Change By Applications Requires Admin Privilege

Setting or clearing the "no journaling" process flag in programmer mode via DISABLE^%SYS.NOJRN or ENABLE^%SYS.NOJRN, respectively, now requires %Admin_Manage:USE privilege. A <PROTECT> error is generated if the privilege requirement is not met.

Journal History Log File Critical To Journal Management

Beginning with this version, journal restore has been improved with an option to locate journal files to be processed via a journal history log. The history file, journal.log, is located in the manager's directory and should not be modified by customers.


No changes to journal.log should be made by any means other than InterSystems-supplied utilities. Failure to observe this rule can result Caché determining that the file has been corrupted. This will result in journaling being disabled.

If journal.log is deleted, Caché will create a new one when creating a new journal file; however, information on previous journal files will be lost.

Changes In Memory Usage

This version introduces several object-related optimizations which involve additional data elements to be cached (both at a system-wide and per-process level). As a result, there are implications for both system and process memory utilization that must be noted.

System-Wide Routine Buffer

The optimizations in this version require additional routine buffers to be available. As a result, the following should be considered:

  • If the default routine buffer pool is in effect, then a 2010.1 Caché installation will consume an additional 8MB system-wide.

  • If, however, a custom routine buffer pool is used (for example, one greater than 17MB), the additional amount of shared memory space to be allocated to routine buffers will depend on the routine buffer usage/utilization:

    • If a rough estimate is desired, increase the routine buffer pool by roughly 20%-30% of the current allocation. For example, if the current allocation is 50MB, increase it to 60MB-65MB.

    • If an accurate estimate is desired, the current system routine buffer utilization will need to be reviewed. This can be done by running the ^GLOSTAT utility and monitoring the "Routine not cached" statistic. The goal is to minimize this value, and this can be achieved by increasing the size of the routine buffer pool.

Per-process Routine Caching

In 2010.1, each process will cache more classes and class info so as to optimize performance. This can result in a 10KB to 30KB memory footprint increase per process.

System-Wide Class Descriptor Caching

In 2010.1, shared class descriptors will be cached. This memory is allocated from the generic memory heap (gmheap). As a result, the following should be considered:

  • The default value for gmheap in 2010.1 has been increased from 3200KB to 6400KB. This is to accommodate the additional memory used due to system-wide class descriptor caching. This can occupy anywhere from 1MB to 1.5MB of the gmheap. The amount occupied depends on the number of classes and objects used.

  • If a non-default gmheap value is used for an object-based application,

    • If the configured gmheap is within 10% of the default (that is, it is between 2880KB and 3520KB), it will be increased automatically by 1600KB when the instance is upgraded.

    • If the configured gmheap is outside of the above range, a warning will be included in the cconsole.log indicating that the gmheap value should be manually increased. If a rough estimate of the increase is sufficient, InterSystems recommends an increase of 1600KB. For a more detailed estimate, thecstat can be utilized to gather system statistics and provide a more accurate estimate. For additional guidance and information, please contact InterSystems Worldwide Customer SupportOpens in a new tab.

GMHEAP Defaults Increased On Upgrade

This version of Caché will increase the gmheap to a minimum value when the system is upgraded. This minimum value is 4800KB for all non-HP platforms; on HP platforms the default is 9600KB.

  • If the size of the gmheap is found to be less than the default, the upgrade installation process will increase it to that value.

  • If the size of the gmheap is more than the default, upgrade writes a message to the cconsole.log file advising that it should be increased by an additional 1600KB.

Licensing Added To CacheProvider

Client licensing is now standardized in this version to provide consistency in license usage between ODBC, and DotNet.

Exporting Classes To XML Omits Generated Classes

When exporting classes to XML format, Caché now removes any classes that are generated by other classes already in the export/compile list. The reason for this is that compiling the class that generates this other item will recreate the omitted class. Often these generated classes are things such as classes for SQL projection which are also marked as deployed. Before this change, an attempt to export a package which contained a persistent class with a collection property would result in an error message about not being able to export deployed classes. Now this deployed class is automatically removed from the export list and no error is reported.

Check For Global Name Errors On Truncation

When a global name is longer than 31 characters, Caché truncates the name to 31 characters for all operations. This can result in the last character of the name being a period which is invalid as the last character. In prior releases, Caché was not detecting this condition and using the invalid global name in the global or LOCK operation which resulted in errors. In this version, Caché will return a <SYNTAX> error when the long name is truncated.

The behavior in previous versions can be restored for the system by setting the GlobalNameTruncated property in the class, Config.MiscellaneousOpens in a new tab.

Counters For SNMP And WMI Changed

This version, eliminates the use of a class of metric counters which had to be specially enabled, and substitutes counters which are always "on" and more closely integrated into the system code. This should noticeably improve the overhead of using either SNMP or WMI for monitoring. The Lines counter is replaced by Commands; GlobalSets becomes GlobalUpdates; GlobalKills has been eliminated. The changes are documented in the MIB and MOF.


^PATROL has been changed to use the new counters. The old behavior and variable names are available by activating $$Light^Patrol(0).

Changes To Temporary File Management

Beginning in this release, Caché has improved the handling of its temporary files to the point that deleting them at startup is no longer necessary. Therefore, Caché startup will no longer delete any files in the Temp directory.


Startup will no longer delete any user files in the Temp directory. If an application uses this directory to store temporary files, it is the responsibility of the application to manage the files it creates across system restarts.

Platform-specific Items

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

$ZF For OpenVMS Changed Privileges

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

Caché Registry Permissions Explicitly Set For Non-Windows Platforms

The Caché registry file, cache.reg, will now have its permissions explicitly set by the installation process. The file will have root as the owner and be writable only by it.

Resource Statistics Gathering Off By Default For Some 64-Bit Platforms

Beginning with this version, the gathering of resource usage statistics is disabled by default on Itanium, POWERPC, and x64 platforms. Enabling and disabling the collection of statistics is done via the Config.MiscellaneousOpens in a new tab class. Set the CollectResourceStats property to true to enable the collection of statistics and false to disable it.

LAT Configuration For Microsoft Windows

The [LAT] section of the cache.cpf file is incomplete in this version of Caché. The System Management Portal does not configure the advertised services: ServiceName, ServiceDescription, and ServiceRating. Therefore, the LAT daemon (lat.exe) now it reads its startup parameters from a lat.ini file in the installation directory instead of from the cache.cpf configuration file. Users employing LAT finctionality should copy the [LAT] section from the existing cache.cpf file into a new lat.ini file or create the information with a text editor.

A sample [LAT] section is shown here. There can be a maximum of eight LAT services advertised. This sample has two. Each service consists of a ServiceName, a ServiceDescription, and a ServiceRating.

ServiceDescription_1=Cache LAT service 
ServiceDescription_2=Second LAT device 

The LAT service will be deprecated in Caché version 2010.2.


This section contains information of interest to those who have designed, developed and maintained applications running on prior versions of Caché.

The items listed here are brief descriptions. In most cases, more complete descriptions are available elsewhere in the documentation.

General Operational Changes

Interactive And Command Invocations Use SHELL Environment Variable

Previously, when invoking an interactive UNIX™ shell via $zf(-1) (or “!” or “$”), Caché used the setting of the SHELL variable if it was defined, otherwise Caché used just sh to start the shell; when a command name was specified, Caché always used /bin/sh.

Now, Caché will check for the SHELL environment variable (and use it if defined) in both cases. This can affect any UNIX™ commands that depend on using /bin/sh.

Changes In Licensing Display

In the output from licensing display functions, under some circumstances fields could run together (leaving no space between columns). When such output was sent to a file and then a program attempted to parse it, the program could fail because it could not distinguish the field boundaries.

Now, field output will break to the following line if this occurs; new types of parser errors are possible. The recommended way to obtain and work with license data is via queries in the %SYSTEM.LicenseOpens in a new tab class.

$SYSTEM.License.Login Now Appends Client IP Address

Applications that call ##class(%System.License).Login(UserId) will find that the license Id has a client IP address appended. This will affect license counting, if the customer previously had users log in to CSP sessions and enabled username-based licensing to cause other types of connections to also use $USERNAME as the license Id. The CSP login will no longer have the same license identifier as other connections.

Also, $System.License.Login() will produce different license Identifiers when called on this version of Caché than on earlier versions. This will cause two license units to be consumed.

Kernel Error Codes Made More Exact

When running out of argument stack space, Cache would sometimes report the condition as a <STORE> error, other times as a <STACK> error, and still others as <ASTACK>. Now detection of insufficient argument stack space always reports the condition as <ASTACK>; running out of heap storage will generate a <STORE> error. The error code, <STACK>, is no longer used.


The argument stack and the string stack share the same block of memory. When a program is using an excessive amount of one kind of stack, it is possible that the error will be detected while attempting to allocate space from the other kind of stack. Therefore, <ASTACK> and <STRINGSTACK> are both possible errors when either of these stacks is being heavily consumed.

Objectscript Changes

$ZOBJ<xxx> Functions Replaced

The $ZOBJ<xxx> functions have been replaced with standard Caché functions. The $ZOBJ<xxx> functions are still available to applications, but they are no longer documented. The calling sequences for the replacement functions remain the same as before; a textual substitution is all that is required to update the application usage. The replacements are given in the following table:

Previous Function New (Replacement) Function

The function, $ZOBJCLASS, was not documented in prior versions.

Remove Descriptions For Obsolete And Deprecated Functionality

In this version of Caché, documentation for legacy networking facilities DDP and DCP has been removed. The functions themselves are classed as deprecated and will be removed in a future release; no replacement functions have been provided. This is also true for several other features because they no longer function as intended. The list of functions that will not have equivalent replacements is:

$ZUTIL Function Description
67, 1, … Returns the activity state of a specified process, and resets.
68, 6, … Enables or disables reliable SET networking mode for the current process.
68, 27, … Sets or clears network hardening for the current process.
68, 28, … Restricts or permits kills of root-level global nodes for the current process.
68, 55, … Selects $X/$Y behavior for TCP devices for the current process.
69, 6, … Sets reliable SET networking mode system-wide.
69, 13, … Sets logging of asynchronous SET/KILL errors.
69, 14, … Sets logging of asynch errors to console.
69, 19, … Sets DDP password security system-wide.
69, 20, … Transfers global nodes with null subscripts with DSM-DDP.
69, 27, … Enables or disables network hardening system-wide.
69, 28, … Controls root-level (unsubscripted) global node kills system-wide.
69, 31, … Sets network locks handling system-wide following a DCP outage.
69, 35, … Sets silent retry for domainspace connection attempts system-wide.
69, 55, … Selects $X/$Y behavior for TCP devices system-wide.
69, 67, … Suppresses or displays the stack and register usage message box system-wide.
90, 4, … Starts up in a specified namespace (UNIX™/OpenVMS.
100 Determines which Windows operating system is running.
113 Reclaims routine and directory blocks.
130, … Sets or returns the domain ID or index.
133, … Maintains a set of metric counters.
Remove $ZUTIL Functions From Documentation

In this version, the Objectscript $ZUTIL functions are no longer documented. The functions remain available for use by applications as in prior releases, but the actions they perform are now also available by other means. The list of functions that have been replaced, their description, and the new means of accomplishing the same objective are given here. Customers should migrate their applications to use the replacement facilities.


The current list of replacements is available in the Caché Objectscript Reference.

Non-Process- & Non-System-Related Functions
Code Description Class Property / Method

4, …

Terminates a Cache process.

SYS.ProcessOpens in a new tab


5, …

Returns current namespace or switches to another namespace.

<Special variable>


9, …

Broadcasts a message to a specified device.

%Library.DeviceOpens in a new tab


12, …

Converts file or directory name to canonical form.

%Library.FileOpens in a new tab


15, …

Converts RMS filename to canonical form.

%Library.FileOpens in a new tab


18, …

Sets undefined variable handling for the current process.

%SYSTEM.ProcessOpens in a new tab


20, …

Specifies the namespace(s) that contains the routine dataset.

Config.MapRoutinesOpens in a new tab


21, …

Returns the location of process-private globals

%SYSTEM.ProcessOpens in a new tab



Deletes all process private globals

%SYSTEM.ProcessOpens in a new tab


22, 0, …

Specifies the form feed or backspace control code sequence.

%Library.DeviceOpens in a new tab


28, …

Performs collation conversion.



39, …

Specifies a search path for percent (%) routines.

Config.MapRoutinesOpens in a new tab


49, …

Obtains database information.

SYS.DatabaseOpens in a new tab

<various class properties>


Passes TCP device name to child process

%SYSTEM.INetInfoOpens in a new tab


53, …

Returns TCP statistics.

%SYSTEM.INetInfoOpens in a new tab


55, …

Returns or changes the current language mode.

SYS.ProcessOpens in a new tab


56, 2

Locates source file and line of code for last ObjectScript error.

%SYSTEM.ProcessOpens in a new tab


56, 6

Returns the operating system error code for a sequential file error.

%SYSTEM.ProcessOpens in a new tab


62, …

Performs a syntax check of command line code.

%Library.RoutineOpens in a new tab


67, 0, …

Returns the activity state of a specified process.

%SYS.ProcessQueryOpens in a new tab


67, 4, …

Returns the process state.

%SYS.ProcessQueryOpens in a new tab


67, 5, …

Returns the routine name of a specified process.

%SYS.ProcessQueryOpens in a new tab


67, 6, …

Returns the namespace name for a specified process.

%SYS.ProcessQueryOpens in a new tab


67, 7, …

Returns the device name for the specified process.

%SYS.ProcessQueryOpens in a new tab


67, 8, …

Returns the number of lines executed by the specified process.

%SYS.ProcessQueryOpens in a new tab


67, 9, …

Returns the number of global references made by the specified process.

%SYS.ProcessQueryOpens in a new tab


67, 10, …

Returns the job type of the specified process.

%SYS.ProcessQueryOpens in a new tab


67, 11, …

Returns the username of the owner of the specified process.

%SYS.ProcessQueryOpens in a new tab


67, 12, …

Returns the name of the system for a client application.

%SYS.ProcessQueryOpens in a new tab


67, 13, …

Returns the name of the executable for a client application.

%SYS.ProcessQueryOpens in a new tab


67, 14, …

Formerly returned the operating system running a client application. Now returns the CSP Session ID

%SYS.ProcessQueryOpens in a new tab


67, 15, …

Returns the IP address of a client application.

%SYS.ProcessQueryOpens in a new tab


71, …

Sets date to a fixed value for the current process.

%SYSTEM.ProcessOpens in a new tab


78, 21

Searches journal file for open transactions.

%SYS.Journal.TransactionOpens in a new tab


78, 22, …

Returns journaling information.

%SYS.Journal.FileOpens in a new tab


78, 23, …

Deletes a journal file.

%SYS.Journal.FileOpens in a new tab


78, 28

Returns journal directory block information.

%SYS.Journal.FileOpens in a new tab


78, 29

Flushes journal buffer.

%SYS.Journal.FileOpens in a new tab


82, 12, …

Redirects I/O operations.

%Library.DeviceOpens in a new tab



Returns configuration file pathname and config name.

%SYS.SystemOpens in a new tab


90, 10, …

Tests whether a namespace is defined.

Config.NamespacesOpens in a new tab


94, …

Broadcasts a message to a specified process.

%SYSTEM.ProcessOpens in a new tab


96, 3, …

Return error number for user-defined command.

SYS.ProcessOpens in a new tab


96, 4, …

Sets $TEST to reflect I/O redirection.

SYS.ProcessOpens in a new tab


96, 5, …

Sets the $DEVICE special variable.

<Special variable>


96, 9

Returns the calling routine name.

SYS.ProcessOpens in a new tab


96, 10

Returns the calling routine database.

SYS.ProcessOpens in a new tab


96, 14

Returns the current device type.

%Library.DeviceOpens in a new tab



Returns the name of the system that is running.

%SYS.SystemOpens in a new tab


114, …

Determines Ethernet address.

%SYSTEM.INetInfoOpens in a new tab


115, 11, …

Specifies whether a value can be inserted into an identity column.

Config.SQLOpens in a new tab


128, 1

Returns location of last single step during debugging.

%SYSTEM.ProcessOpens in a new tab



Makes the last device in use the principal I/O device.

%Library.DeviceOpens in a new tab


140, 1, …

Returns file, directory, and disk information and performs file operations.

%Library.FileOpens in a new tab


140, 7, …

Returns a bitmap of file attributes.

%Library.FileOpens in a new tab


147, …

Handles spaces in pathnames for the host platform.

%Library.FileOpens in a new tab


158, 0

Displays currently installed printers.

%Library.DeviceOpens in a new tab


168, …

Returns location of current working directory, or sets current working directory.

%SYSTEM.ProcessOpens in a new tab


186, …

Sets display in programmer prompt for the current process.

%SYSTEM.ProcessOpens in a new tab



Returns local date and time with fractional seconds system-wide.




Checks if TCP device is disconnected.

%SYSTEM.INetInfoOpens in a new tab


193, …

Converts Coordinated Universal Time (UTC) to local date and time (and vice versa).



Process- & System-Related functions
Code Description Class Property / Method


Sets undefined variable handling for the current process

%SYSTEM.ProcessOpens in a new tab


68, 1, …

Enables or disables use of null subscripts for the current process.

%SYSTEM.ProcessOpens in a new tab


68, 2, …

Sets sequential file open mode for the current process.

%SYSTEM.ProcessOpens in a new tab


68, 3, …

Sets automatic sequential file creation option for the current process.

%SYSTEM.ProcessOpens in a new tab


68, 5, …

Enables or disables processing of argumentless BREAK commands for the current process.

%SYSTEM.ProcessOpens in a new tab


68, 7, …

Retains or strips extended global reference from globals returned to the current process.

%SYSTEM.ProcessOpens in a new tab


68, 11, …

Enables or disables read line recall for the current process.

%SYSTEM.ProcessOpens in a new tab


68, 15, …

Enables or disables I/O device disconnect detection for the current process.

%SYSTEM.ProcessOpens in a new tab


68, 21, …

Sets synchronous commit mode for the current process.

%SYSTEM.ProcessOpens in a new tab


68, 22, …

Sets handling of escape sequences when $X is updated for the current process.

%SYSTEM.ProcessOpens in a new tab


68, 26, …

Sets namespace display in programmer prompt for the current process.

%SYSTEM.ProcessOpens in a new tab


68, 30, …

Sets error handling behavior for the current process.

%SYSTEM.ProcessOpens in a new tab


68, 32, …

Sets date range and invalid date behavior for the current process.

%SYSTEM.ProcessOpens in a new tab


68, 34, …

Sets whether asynchronous errors can interrupt the current process.

%SYSTEM.ProcessOpens in a new tab


68, 39, …

Enables or disables caching for the current process.

%SYSTEM.ProcessOpens in a new tab


68, 40, …

Sets sequential file end-of-file handling for the current process.

%SYSTEM.ProcessOpens in a new tab


68, 42, …

Sets $JOB format for the current process.

%SYSTEM.ProcessOpens in a new tab


68, 43, …

Sets clearing of global vectors for the current process.

%SYSTEM.ProcessOpens in a new tab


68, 45, …

Sets truncation mode for string-to-number conversions for the current process.

%SYSTEM.ProcessOpens in a new tab


68, 51, …

Sets whether or not changing namespaces changes operating system directories for the current process.

%SYSTEM.ProcessOpens in a new tab


68, 60, …

Sets handling of asynchronous Telnet disconnect errors for the current process.

%SYSTEM.ProcessOpens in a new tab


68, 63, …

Enables or disables the use of “e” as scientific notation symbol for the current process.

%SYSTEM.ProcessOpens in a new tab


68, 66, …

Suppress Telnet NUL at end-of-line for the current process.

%SYSTEM.ProcessOpens in a new tab


68, 67, …

Suppresses or displays the stack and register usage message box for the current process.

%SYSTEM.ProcessOpens in a new tab


68, 70, …

Enables or disables $DOUBLE returning INF and NAN values.

%SYSTEM.ProcessOpens in a new tab


68, 71, …

Sets IP address format for the current process.

%SYSTEM.ProcessOpens in a new tab


68, 72, …

Sets MVBasic handling of undefined variables.

%SYSTEM.ProcessOpens in a new tab


69, 0, …

Sets undefined variable default handling system-wide.

Config.MiscellaneousOpens in a new tab


69, 1, …

Sets null subscript mode default system-wide.

Config.MiscellaneousOpens in a new tab


69, 2, …

Sets sequential file open mode default system-wide.

Config.MiscellaneousOpens in a new tab


69, 3, …

Sets automatic sequential file creation system-wide.

Config.MiscellaneousOpens in a new tab


69, 5, …

Enables argumentless BREAK processing system-wide.

Config.MiscellaneousOpens in a new tab


69, 7, …

Retains or strips extended global reference from globals system-wide.

Config.MiscellaneousOpens in a new tab


69, 8, …

Sets ZA and ZD locking modes system-wide.

Config.MiscellaneousOpens in a new tab


69, 10, …

Sets system behavior when journal is full.

Config.JournalOpens in a new tab


69, 11, …

Sets Read Line Recall mode system-wide.

Config.MiscellaneousOpens in a new tab


69, 13, …

Sets logging of asynchronous SET/KILL errors.

Config.MiscellaneousOpens in a new tab


69, 15, …

Sets I/O device disconnect detection system-wide.

Config.MiscellaneousOpens in a new tab


69, 21, …

Sets synchronous commit mode system-wide.

Config.MiscellaneousOpens in a new tab


69, 22, …

Sets $X update mode for escape sequences system-wide.

Config.MiscellaneousOpens in a new tab


69, 24, …

Sets $ZF process deletion behavior for OpenVMS STOP/ID system-wide.

Config.MiscellaneousOpens in a new tab


69, 26, …

Sets namespace display in programmer prompt system-wide.

Config.MiscellaneousOpens in a new tab


69, 30, …

Sets error handling behavior system-wide.

Config.MiscellaneousOpens in a new tab


69, 32, …

Sets date range and invalid date behavior system-wide.

Config.MiscellaneousOpens in a new tab


69, 34, …

Sets interruptability of processes by asynchronous errors system-wide.

Config.MiscellaneousOpens in a new tab


69, 35, …

Sets silent retry for domainspace connection attempts system-wide.


69, 37, …

Sets physical cursor mode system-wide.

Config.NLS.LocalesOpens in a new tab


69, 39, …

Sets caching for future processes system-wide.

Config.MiscellaneousOpens in a new tab


69, 40, …

Sets end-of-file handling for sequential files system-wide.

Config.MiscellaneousOpens in a new tab


69, 42, …

Sets $JOB format default system-wide.

Config.MiscellaneousOpens in a new tab


69, 43, …

Sets clearing of global vectors system-wide.

Config.MiscellaneousOpens in a new tab


69, 44, …

Sets use of the Nagle algorithm for Telnet transmissions system-wide.

Config.MiscellaneousOpens in a new tab


69, 45, …

Truncates numbers during string-to-number conversion system-wide.

Config.MiscellaneousOpens in a new tab


69, 49, …

Sets logging of transaction rollbacks system-wide.

Config.MiscellaneousOpens in a new tab


69, 51, …

Sets namespace default directory assignment behavior system-wide.

Config.MiscellaneousOpens in a new tab


69, 60, …

Sets handling of asynchronous Telnet disconnect errors system-wide.

Config.MiscellaneousOpens in a new tab


69, 63, …

Enables or disables lowercase “e” as scientific notation symbol system-wide.

Config.MiscellaneousOpens in a new tab


69, 66, …

Suppress Telnet NUL at end-of-line system-wide.

Config.MiscellaneousOpens in a new tab


69, 68, …

Enables or disables the encryption of journal files system-wide.

Security.SystemOpens in a new tab


69, 69, …

Enables or disables the use of long strings system-wide.

Config.MiscellaneousOpens in a new tab


69, 70, …

Enables or disables $DOUBLE returning INF and NAN values system-wide.

Config.MiscellaneousOpens in a new tab


69, 71, …

Sets IP address format system-wide.

Config.MiscellaneousOpens in a new tab


69, 72, …

Sets MVBasic handling of undefined variables system-wide.

Config.MiscellaneousOpens in a new tab


69, 73, …

Set global name compatibility checking

Config.MiscellaneousOpens in a new tab


$ZDATEH And $ZDATETIMEH Format 4 Parsing

In version 2008.1, the $ZDATEH and $ZDATETIMEH function were inadvertently changed to accept any nonambiguous date instead of only a European format date. The correct behavior has been restored; $ZDATEH(date,4) and $ZDATETIMEH(datetime,4) will only accept strings using European format dates.

For those applications expecting the post-2008.1 behavior, a new date format code, 15, has been added that uses European date ordering, DD/MM/YYYY, but also accepts any other date input that is nonambiguous.

Number Format Parsing Via $INUMBER And $FNUMBER Now Locale-Independent

Prior to 2008.2, the $INUMBER and $FNUMBER functions worked with European-style numbers: “,” as decimal point, “.” as group separator, “-” as minus sign, and “+” as plus sign. In 2008.2, these functions were changed parsing would use the system default locale to determine the minus sign and plus sign; usually this is “-” and “+”, but not always.

In this version, the behavior has been returned to the way it was before 2008.2, so that is always uses “,” as decimal point, “.” as group separator, “-” as minus sign, and “+” as plus sign.

Improved Detection Of Incorrect $HOROLOG Dates And Times

Some of the routines that accept a $HOROLOG string (and/or a $ZTIMESTAMP string) do not fully validate their input string. Their behavior on illegally formatted string is undefined. In some cases that undefined behavior may change between Cache versions.

A legally formatted $HOROLOG string (or $ZTIMESTAMP) string consists of a <date> followed immediately by a comma (,) and then followed immediately by a <time>. Optionally, the comma and the <time> may both be omitted; this is assumed to implicitly represent 0:00:00, the beginning of the day, or a date without reference to a particular time.

A <date> part consists only of decimal digits. A <date> may not include any fractional part nor an exponent part nor any non-digit characters.

The <time> part is a string of decimal digits optionally followed by a decimal point (.) and some fractional decimal digits. A <time> may not include an exponent.

If a routine accepts just a <time> string that is not preceded by a <date> and a comma, a leading minus sign, (-) is permitted to represent negative time intervals.


Previously, $INCREMENT() of a variable containing a very large number would not change the value of the variable when the increment value is insignificant compared to the original value. Thus, successive calls to $INCREMENT() could all return the same value, which is incorrect. Beginning with this version, this situation will cause the increment operation to throw a <MAXINCREMENT> error instead of returning an incorrect result.

Routine Changes

KillAllObjects Takes No Action

The function, KillAllObjects^%apiOBJ(), used to remove all object memory from the partition has been changed to a no-op. Applications can remove an object by letting the object go out of scope.

Routine Compiler Changes

Routine Compiler Skips Generated Code

The routine compiler, ^%RCOMPIL, will no longer compile code that has been generated. Previously, if you attempted to compile *.mac, and there existed MAC code which was generated by compiling classes, the generated class MAC code would be compiled. This would cause the methods in that class to not be runnable. Other code which is marked as generated will also not be compiled. This includes .INT code which comes from MAC code and classes, and cached query code.


It is possible to compile a "generated" routine, but only if the name of the generated routine is specified exactly as one of the routines to compile.

Class Changes

Namespace Changes And OREFs

Assume you create an OREF to a class instance, and then change the namespace the application runs in. In prior versions, you would normally get a <NOROUTINE> error when you tried to access a method of this OREF in the second namespace because it could not find the code to run. Caché was looking for the code in the current namespace and not in the namespace where the OREF was created.

Beginning with this version, an application can create an OREF and change its namespace; when it attempts to use this OREF and it will run the code from the original namespace. However, any references to global data or locks made during execution will be relative to the current namespace. This means that it the executing code does a %Save(), the data will be saved it will save the data to the current namespace and not the namespace where the code is running. Similarly, a method that does a $GET(^Global) will look up the global in this namespace rather than the original namespace.

When an application changes namespaces, it changes the visibility of data. Cross-namespace access to OREFs does not preserve the global data visible from the original namespace. When an object is opened in Namespace A and it loads data from ^MyGlobal, then ^MyGlobal is expected to be in Namespace A. In changing to Namespace B with an OREF from Namespace A, then any access by that OREF to ^MyGlobal looks for the data in Namespace B.


Caché cannot check for this condition. The use of object references created in other namespace may result in subtle data loss or corruption undetectable at the time of execution.

Class Deletions

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

  • Package %BI – SOAP

  • Package %CPT – RegenerateImpl, RegenerateSource

  • Package %CSP.UI.System – MappingsTablePane, MappingsTitlePane, MenuTree

  • Package %Compiler – JavaScript

  • Package %ISQL – SP

  • Package %Net – Event

  • Package %TSQL – SP, SPContext, SimpleStreamLexer

  • Package %XSQL – CacheMetadata, Convert, Debug, DelimitedReader, Settings, Transaction

  • Package %cspapp.exp – utilexpglobaledit, utilexproutineinfo, utilsysdbglobalinfo

  • Package %cspapp.mgr – utilconfiggblmappings, utilconfigprjmappings, utilconfigrtnmappings, utilsysaccess

Class Reservations

The following classes which were publicly exposed in earlier versions of 2010.1, and/or prior versions of Caché, are being reserved solely for InterSystems use:

  • Package %TSQL – FileBuffer, LineBuffer, ResultSet, StreamLineBuffer, StreamLineBufferWF, SysFunc, Transformer

  • Package %TSQL.sys – cacheMsgXRef, messages, messagesXRef, snf

  • Package %XSQL.DS – Call, ContextStatement, Cursor, DML, IResultSet, Statement, TSQL, TempTable, spexecutesql

  • Package %XSQL.DSI – Call, Cursor, DeferredStatement, GlobalPrivateTable, IteratorFunction, JPAQuery, Statement, TSQL, TempTable, spexecutesql

  • Package %XSQL – Compile, DLLInterfaceUtil, Dictionary, Exception, Format, Reporting, StatementBatch

  • Package %XSQL.Informix – FunctionQuery

  • Package %XSQL.System – CacheMessageXRef, Message, MessageXRef

  • Package SYS.WSMon – Client, EventSink, Service, wsDatabase, wsEvent, wsResource, wsSystem

  • Package SYS.WSMon.wse – Delivery, EndpointReference, Identifier, MyRefProp, ReferenceProperties, Renew, RenewResponse, Subscribe, SubscribeResponse, Unsubscribe, UnsubscribeResponse

  • Package SYS.WSMon.wsen – Enumerate, EnumerateResponse, Items, Pull, PullResponse, Release

  • Package SYS.WSMon.wsman – Client, Locale, MaxEnvelopeSize, OperationTimeout, RequestTotalItemsCountEstimate, ResourceURI, SelectorSet, Service, TotalItemsCountEstimate

Class Component Reservations

The following class components are being reserved for InterSystems use. They will no longer be displayed in the Class Reference and are subject to change without notice. Sites using these components should contact InterSystems Worldwide Customer SupportOpens in a new tab for assistance in replacing these with other published API components.

Class Type Name(s)
%Installer.ClassMapping Method %OnGenerateCode
%Installer.ClassMapping Method %OnGenerateCode
%Installer.Configuration Method %OnAfterGenerateCode, %OnBeforeGenerateCode, generateCode
%Installer.CopyClass Method %OnGenerateCode
%Installer.CopyDir Method %OnGenerateCode
%Installer.CopyFile Method %OnGenerateCode
%Installer.Credential Method %OnGenerateCode
%Installer.CSPApplication Method %OnGenerateCode
%Installer.Database Method %OnGenerateCode
%Installer.Default Method %OnGenerateCode
%Installer.Else Method %OnGenerateCode
%Installer.Error Method %OnBeforeGenerateCode
%Installer.ForEach Method %OnAfterGenerateCode, %OnBeforeGenerateCode
%Installer.GlobalMapping Method %OnGenerateCode
%Installer.If Method %OnAfterGenerateCode, %OnBeforeGenerateCode
%Installer.IfDef Method %OnAfterGenerateCode, %OnBeforeGenerateCode
%Installer.IfNotDef Method %OnAfterGenerateCode, %OnBeforeGenerateCode
%Installer.Import Method %OnGenerateCode
%Installer.Installer Method CopyClass, CopyDir, CopyFile, CreateDatabase, CreateNamespace, CreateResource, CreateRole, CreateUser, CSPApplication, DeleteVariable, EnableEnsemble, eval, Evaluate, GetVariable, GlobalMapping, Import, InstallFromCommandLine, IsLoggable, IsVariableDefined, LoadManifestXML, LoadPage, Log, PopNS, Production, ProductionExists, PushNS, RoutineMapping, SetVariable, special, SystemSetting
Property Logger, LogLevel, NSStack, Variables
%Installer.Invoke Method %OnBeforeGenerateCode
%Installer.LoadPage Method %OnBeforeGenerateCode
%Installer.Log Method %OnBeforeGenerateCode
%Installer.Manifest Method %OnAfterGenerateCode, %OnBeforeGenerateCode
%Installer.Namespace Method %OnAfterGenerateCode, %OnBeforeGenerateCode
%Installer.Production Method %OnAfterGenerateCode, %OnBeforeGenerateCode
%Installer.Resource Method %OnGenerateCode
%Installer.Role Method %OnGenerateCode
%Installer.RoutineMapping Method %OnGenerateCode
%Installer.RunInstall Method %OnGenerateCode
%Installer.Security Method %OnAfterGenerateCode, %OnBeforeGenerateCode
%Installer.Sequence Method findChild
%Installer.Setting Method %OnGenerateCode
%Installer.SystemSetting Method %OnGenerateCode
%Installer.Var Method %OnGenerateCode
%Library.ProcedureContext Property Results
%Net.FtpSession Method endCommand
%Net.POP3 Method GetHeadersArray
%SYSTEM.Config.SharedMemoryHeap Method DisplayUsage
%ZEN.Component.abstractPage Method %IsEmbedded
Class Component Deletions

The following class components have been removed in this version.

Class Type Name(s)
%Activate.UI.Wizard Property lblExit, lblFinish
%CPT.CalloutDump Method DumpParseTreeNodeMap, DumpSourceAndMap
%CSP.UI.Portal.Config.Device Method DrawLocatorExtra, onloadHandler, UpdateDetails
%CSP.UI.Portal.Config.Devices Method DrawLocatorExtra, saveItem, validate
%CSP.UI.Portal.Config.ValueEditor Method DrawLocatorExtra
%CSP.UI.Portal.FileManTemplate Method %OnAfterCreatePage
%CSP.UI.Portal.NLS Method AddLocator
%CSP.UI.Portal.NLSEdit Method AddLocator
%CSP.UI.Portal.ObjectGateway Method doStart, doStop, itemChanged
Property msgConfirmSaveStart, msgConfirmStart, msgConfirmStop
%CSP.UI.Portal.ObjectGateways Method deleteSetting, editSetting, editSettingD
Property PID
%Compiler.Informix.COS Method %OnClose, InformixDT2CacheDT, SeparateName, delimitIdentifier, getTypeCategory, normalizeIdentifier, resolveTableName
Property blockTypeStack, codeStack, contextStack, exceptionDepth, exceptionStack, opStack
%Library.IProcedureContext Property Message, RowCount, SQLCode
%Library.IResultSet Property %RowCount, %SQLCode
%Library.ODBCCatalog Method co25Close, co25Execute, co25Fetch, cr25Close, cr25Execute, cr25Fetch, ek25Close, ek25Execute, ek25Fetch, ik25Close, ik25Execute, ik25Fetch, pc25Close, p25Execute, pc25Fetch, ti25Close, ti25Execute, ti25Fetch
Query co25, cr25, ek25, ik25, pc25, ti25
%Library.ObjectJournalTransaction Method PurgeUpToTxn
%Library.ProcedureContext Property ReturnValues
%Library.qccServer Method OnPage
%MV.File Property %AAA01VarType, %AAA02FileName, %AAA03Namespace, %AAA04DictFlag, %AAA05Global, %AAA06Account, %AAA07TargetAccount, %AAA08TargetFileName, %AAA09IsBinary, %AAA10IsTranslated, %AAA11COSName, %AAA12LockName, %AAA13Class, %AAA14IndexType, %AAA15IndexRoutine, %AAA16IndexName, %AAA17IndexColl, %AAA18BSCAN, %AAA19IndFlag, %AAA20IndNames, %AAA21IndColl, %AAA22IndMV, %AAA23Options, %AAA24TriggerRoutine, %AAA25TriggerOperations, %AAA26FireTriggers, %AAA27CasePreserveName, %AAA28IOTable, %AAA29ClassNamespace, %AAA30SectionName
%MV.PropertyParameters Parameter MVITYPERTN
%MV.SelectList Property %AAA01Type, %AAA02LastReturnedId, %AAA03NextOffset, %AAA04GlobalName, %AAA05Namespace, %AAA06Values, %AAA07Count, %AAA08IndexName, %AAA09IndexFlags, %AAA10IndexColl, %AAA11InReverse, %AAA12LastReturnedMVPos, %AAA13LastReturnedKey, %AAA14CurSub, %AAA15MaxSub, %AAA16ExplodeFlag
%ResultSet.Static Method %RowCountGet
%Studio.Project Method deployToGbl
%SOAP.Security.SecurityTokenReference Property Id
%SYS.PTools.Stats Property CursorName. NameSpace, RoutineName
%SYSTEM.CPU Property nTheadsPerCore
%TSQL.Transformer Method ExecuteStringAsTSQL, ExpandTable
%UnitTest.Manager Method ParseQualifiers, RunOneDirTest, RunTestSuite, SaveLog
%UnitTest.Report Method IsSuccess, NoNameSpace
%UnitTest.Utility Method processError
%ZEN.Auxiliary.dataController Method %GetDataByName, %GetTypeByName, %OnNew, %SetDataByName, autoRefreshHandler, clearAutoRefresh, getData, getDataAsArrays, getDataAsObject, getDataByName, getDimSize, getDimensions, getError, getLabel, getModelId, getPropertyName, getTypeByName, hasData, invokeAction, isModelReadOnly, isPropertyValid, notifyController, onDelete, onloadHandler, raiseDataChange, register, sendEventToViews, setData, setDataByName, setModelId, startAutoRefresh, unregister, update
Property alertOnError, autoRefresh, dataBag, dataLoaded, dataReadOnly, defaultSeries, modelChanged, modelError, modelId, oncreate, ondelete, onerror, onnotifyController, onsave, readOnly, timerid
%ZEN.Component.abstractPage Method %DrawJSTestIncludes
Property %ComponentIncludes, %IncludePackages
%ZEN.Report.Aggregate.StDev Property Sum, SumOfSquares
%ZEN.Report.Display.inline Property field
%ZEN.Report.Display.p Property field
%ZEN.Report.reportPage Method %IsTypeNumeric, OnSVGAttribution
%ZEN.SVGComponent.svgPage Parameter SYSTEMSVGPACKAGES
%ZEN.Utils Method NeedsIncludeFiles, WriteIncludeFiles
Config.CommonMapProperties Parameter SECTIONTYPE
Config.CommonMethods Parameter NAMESPACE
Config.Config.MapPackages Parameter NAMESPACE
Config.Config.MapRoutines Parameter NAMESPACE
Config.MapGlobals Method NameIsValid
Config.Miscellaneous Property NamespacePrompt
Config.Namespaces Method MapPkg, MapSub, MapUserGlobals, MapUserPackages, MapUserRoutines
Config.MapPackages Parameter NAMESPACE
Config.MapRoutines Parameter NAMESPACE
Method Return Changes

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

  • Package %CSP.UI.System.ExportPane – DrawResult

  • Package %CSP.UI.System.ImportPane – DrawResult

  • Package %Library.CacheIndex – Check

  • Package %Monitor.Manager – SystemCountersActive

  • Package %UnitTest.Manager – PurgeLog

  • Package %ZEN.Dialog.fileSelect – GetSubDir

Method Signature Changes

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

Class Name Method Name(s)
%BI.WebScheduler addNewPivotTask
%CPT.COSCallout Compile
%CPT.CalloutCheckTree CheckParseTreeNode, CheckParseTreeNodeAnn, CheckParseTreeNodeChild, CheckParseTreeNodeSource, ReportAnn, ReportChild, ReportNode
%CPT.CalloutDump ExpandAnnIndex, ExpandAnnValue, ExpandChildIndex, ExpandNodeType
%CPT.CalloutIndex BuildNodeIndex, ListEnumIndex, ListNodeIndex, UpdateNodeIndexForEnum, UpdateNodeIndexForNode, UpdateNodeIndexFromLine
%CPT.CalloutTesting TestStream
%CPT.CalloutTypeIndex BuildTypeIndex, IsEqualOrDescendantOf, ListTypeClassHierarchy, ListTypeIndex, UpdateTypeIndexForNode, UpdateTypeIndexForNodeClass, UpdateTypeIndexFromLine
%CPT.ISQLCallout Compile
%CSP.Session Unlock
%CSP.UI.Portal.SSL SaveData
%CSP.UI.System.AutoPageCSP GetLocator
%Collection.ListOfObj GetObjectIdNext
%Compiler.Informix.Flo preparseSQL, parseStream
%Compiler.LG.PropWrapper SetIIJJKK
%Compiler.TSQL.Flo preparseSQL, sqlact
%Compiler.XML.Generator.Adaptor GenArrayCode, GenExportCode, GenListCode, GetSimpleExport
%Debugger.System StackVars
%Installer.Installer CreateDatabase
%Library.ArrayOfObjects %AddToSaveSet
%Library.CacheIndex Check
%Library.Collation FMDLTDate
%Library.GlobalEdit GetGlobalSize, GetSize
%Library.ListOfObjects %AddToSaveSet
%Library.ProcedureContext ResolveTableName
%Library.RegisteredObject %AddToSaveSet
%Library.RelationshipObject %AddToSaveSet
%Library.RoutineMgr UserType
%Library.SyntaxColor Color
%Monitor.Manager SystemCountersActive
%Net.FetchMailProtocol Fetch
%Net.POP3 Fetch
%Net.Remote.Gateway %Connect
%SOAP.Descriptor GetSoapParameters
%SOAP.Security.SecurityTokenReference Validate
%SOAP.WSDL.Reader GetCacheElement
%SOAP.WebRequest GetSoapParameters
%SQL.Manager.Catalog SetFieldSelectivity, SetTableExtentSize
%SYS.PTools.SQLStats Export, Init, Report, Start, Stop
%SYS.PTools.Stats Init, Report, Start, Stop
%SYS.ZENReportServer %ServeTransform
%Studio.Project Deploy, deployToDatabase, NormalizeName
%UnitTest.Manager AutoLoad, DebugLoadTestSuite, DebugRunTestCase, LogStateEnd, RunTest
%UnitTest.ODBCSQL processORSToStream
%XML.Utils.SchemaReader GetCacheElement, ProcessElement, ProcessSequence
%XML.Writer Object, RootObject
%XML.XSLT.Transformer TransformFile, TransformFileWithCompiledXSL, TransformStream, TransformStreamWithCompiledXSL, TransformStringWithCompiledXSL
%ZEN.Component.tabGroup showNextTab, showPreviousTab
%ZEN.Report.Aggregate.StDev ProcessValue
%ZEN.Report.Display.caption %DrawCellFO, %DrawCellToHTML
%ZEN.Report.Display.item %DrawToHTML, %DrawToXSLFO
%ZEN.Report.Display.node %GenerateCode, %StyleXSLFO
%ZEN.Report.Display.tableOutput %DrawCellFO, %DrawCellToHTML, %DrawFooterFO, %DrawFooterToHTML, %DrawHeaderFO, %DrawHeaderToHTML %SortChildren
%ZEN.Utils %GenerateIncludeFiles
Config.CPF MoveToActive, UpdateLines
Config.ComPorts Load
Config.CommonMapMethods Load, MoveToActive
Config.CommonMethods Activate, Load, MoveToActive
Config.CommonSingleMethods MoveToActive
Config.DTMnetBIOS Load
Config.Databases Load
Config.DeviceSubTypes Load
Config.Devices Load
Config.ECP Load
Config.ECPServers Load
Config.ETHServers Load
Config.IO Load
Config.Journal Load
Config.LAT Load
Config.MagTapes Load
Config.Map MoveToActive
Config.Miscellaneous Load
Config.Monitor Load
Config.Namespaces Load
Config.Net Load
Config.SQL Load
Config.SqlSysDatatypes Load
Config.SqlUserDatatypes Load
Config.Startup Load
Config.Telnet Load
Config.UDPServers Load
Method Displacements

The following methods have been removed from one class and added to another:

  • Method: KPI – from %BI.Soap to %BI.Util

  • Method: Pivot –: from %BI.Soap to %BI.Util

DBTIME Implementation Changed

The DBTIME parameter was first introduced in version 2008.2. When set to 1, it caused an index to be defined in the class on a property that was, by default, set to an incremented global on each insert and update; but the index entry for an object was not updated for deletes.

Beginning with this version, DBTIME no longer generates an index definition and property definition. A global, ^OBJ.DBTIME, is set for each insert, update and delete. The first subscript is the incremented global counter - ^OBJ.DBTIME; the second is the class name of the object being filed; and the third is the ID of the object. The value of the global node for each filing event is the type of filing - 0 for update, 1 for insert and 2 for delete. This structure is cumulative. It is used to support various features in Cache and it can be used by user applications for any purpose. Deleting entries from ^OBJ.DBTIME is not automatic and must be done by the user.

Permit Insert Of Trailing Objects In Collections

The SetAt method of a list collection allows the caller to specify an element value and a key. In prior releases, if the element at the key position was not already defined, then the attempt would fail.

This behavior is now changed. The call will still fail if the key is not 1 (the first element position) and the element at the previous position is not defined. Otherwise, the call will succeed and the behavior for calling SetAt(value,key) for a position that is undefined will be the same as Insert. That is, a new element at position “key” will be defined.

Update ID Counter When IDENTITY Set Explicitly On Object Insert

If a value is provided for the IDENTITY property of a new object and the INSERT_IDENTITY option is set TRUE, then the ID of the new object is set to the value of the IDENTITY property.

In previous versions, an error prevented subsequent inserts without the IDENTITY property from succeeding if the ID counter value was the same as a previously inserted object. This has been corrected and an explicit set of an IDENTITY property will update the ID counter as long as the explicit value is greater than the current ID counter value. As part of this correction, another error that prevented a check of the INSERT_IDENTITY option for batch inserts and direct saves has been fixed.

%OnDetermineClass Method Override Blocked

%OnDetermineClass is a class method implemented for persistent, stream and serial objects. It has always been defined to be PRIVATE, but PRIVATE for class methods has never been enforced until this release. Any application class that overrides %OnDetermineClass will now have to update the method definition to remove the PRIVATE keyword.

Indexes Permitted on %Stream.GlobalCharacterSearchable

Several defects that caused corruption in an index based on a property whose type class is %Stream.GlobalCharacterSearchable have been fixed in this version of Caché. These defects caused updates to the stream to be ignored and resulted in index entries based on the old stream value. Also, deleting a container object did not fully remove the index entries from the stream in all cases.

As part of the correction of these defects, indexing streams is only supported for instances of %Stream.GlobalCharacterSearchable. Instances of this class must be processed through the container. It is not legal to extract the stream OID from the container and process updates to the stream without saving the container.


Existing applications should work well with this change as no change to the existing data structures was made. However, the old behavior almost certainly introduced corrupt index structures. Those indices should be purged and rebuilt after installing this version.

Namespace Prompt Property Changed

The property, NamespacePrompt, in the Config.MiscellaneousOpens in a new tab class has been moved to the class, Config.StartupOpens in a new tab, and renamed to be TerminalPrompt.

Class Compiler Changes

This version of Caché continues the work begun in earlier releases of improving the class compiler. The changes that may require changes to applications are detailed in this section.

Class Inheritance Default Order Changed

In version 2009.1, the Inheritance keyword was introduced to specify the order of inheritance from superclasses. In that release, the default for classes that do not specify the order was “right”, as it had been before the keyword was introduced.

In this version, the default inheritance order for classes that do not explicitly specify an order has been changed to “left”.

Superclass Availability Required

In prior versions, subclasses compiled all the method code from their superclasses into themselves. In this version, subclasses contain references to their superclass methods thus avoiding the extra code and saving compilation time. A consequence of this organization is that the first reference to a method in a class requires that all the superclasses be accessible to resolve the reference, that is, either present in the namespace of the calling method or mapped to it.

Flags And Qualifier Removals And Deprecations

In this version of Caché, the following changes made to compiler flags and qualifiers may affect existing operations:

  • Optimization flags ignored

    Due to the more dynamic nature of the class and routine dispatching in this version of Caché, the optimization flags (“o1”, “o2”, ...) are ignored if passed in as arguments. The system code was optimized to make up for any reduction in speed from turning these optimizations off.

  • Force flags

    The force flag, “f”, is now deprecated.

  • SQL compilation deprecated

    The “q” flag that specified SQL-only compilation is now deprecated.

  • Keep-valid deprecated

    The “v” flag previously used to keep the objects valid after compilation finishes is now deprecated.

  • The following qualifiers are no longer allowed:

    • /deletextent – used to delete the extent associated with a class

    • /version4compatible – used to export CDL files that are version 4 compatible

$GET(..<property>) Require <property> To Be Multi-Dimensional

In previous versions, $GET applied to a class property which is not multi-dimensional may not have been caught as an error when certain optimization flags were set. This has been corrected. The expression


is valid only if AClassProperty is marked as Multidimensional.


This restriction also applies to other commands with respect to class properties: KILL, MERGE, $DATA(), and $INCREMENT().

$PIECE References to ..<property> Require <property> To Be Multi-Dimensional

In previous versions, $PIECE treated a reference to ..<property> as a string. Because of changes to the compiler, such references will now result in an <OBJECT DISPATCH> error. Applications using this form should either add the Multidimensional qualifier to the property, or use a temporary string as in:

Set ..MyProperty = "Piece1/Piece2" 

Set temp = ..MyProperty 
Set $PIECE(temp,"/",2) = "Piece3" 
Set ..MyProperty = temp 

Misuse of %this Prohibited

In prior versions of Caché, it was possible to gain access to the private properties of another object with the sequence

New %this
Set %this = OtherOREF
Set Value = ..PrivateProperty

This will not work in the new class compiler due to system changes. Any applications using this questionable practice must be updated.

System code public/private protection has now been changed; from a method of class X access to private members of another instance is possible only as long as the origin of the member is class X or a superclass of class X. This will allow most common use of “Set %this=” to be changed to just access the private properties directly.

InterSystems also found code where a classmethod was executing

Set value=##this.Property

which was implicitly referencing %this on older Caché systems where the value of %this happened to be the last instance method that was called. This is a very risky practice since the last instance is not well-defined; if the classmethod is called as the first thing, then %this will not be defined at all. Applications should be written to pass in the OREF of the object to the classmethod explicitly.

In the new compiler, references to “##this” are converted to $THIS, the current class context.

State Of Serial Object Now Held In %%OID

In prior versions, the serial state of an object was being kept internally. This has now been made visible in a real property called %%OID. It is also updated for serial and stream objects. It is used in %Save to correctly handle the case where a serial object is independently serialized so it reports %IsModified()=0 to the save attempt, but the container does not know the new serial value. Using %%OID, the container can always get the correct version of the serial object.

Setting A Serial Property To "" Causes It To Be Initialized

When a class defines a serial property, constructing a new instance of this class and referencing this serial property will cause it to be created using the NewObject() method. If the application then sets this property to "", the property is now reinitialized and the next reference will create it again using NewObject() just as if theoparent object had been newly created.

NotInheritable Keyword Removed

In previous versions, Caché allowed a user to define a 'not inheritable' property defined with an expression like:

Property A As %String [ NotInheritable ];

This concept breaks object inheritance because the superclass now has interfaces the subclass does not.

Beginning with this version of Caché, this is no longer permitted. Compiling a subclass of a class with a noninheritable property will result in the an error because property “..A” was not present in the subclass.

When upgrading to this version, the upgrade procedeures will automatically remove “NotInheritable” from any property and thus convert any noninheritable properties into inheritable ones. When it does this, it will add the comment [Previously notinheritable] to the property description.

Any new properties marked as “NotInheritable” will cause an error when they are compiled. Studio will be modified to remove the ability to set or display this keyword.

Private Classmethods Now Supported

Caché now supports private class methods. Private classmethods cannot be called from outside of the class (or a subclass). For backward compatibility, all class methods have been marked “public” so customer code will continue to work correctly. The descriptions of these methods have been altered to add the string, “[Previously private]”, to them.

New private classmethods added to classes in the future will be inaccessible from outside the class.

Change In Support For COSEXPRESSION

Prior to this release, the use of COSEXPRESSION in a parameter definition would be treated in the same manner as macro substitution. That is,

parameter P1 as COSEXPRESSION = """Red"",""Green"",""Blue""";

Set X = $LISTBUILD(..#P1)

would be treated as if it were

Set X = $LISTBUILD("Red","Green","Blue")

In this version of Caché, a COSEXPRESSION is constrained to return only a single value. So the parameter definition must be rewritten as

parameter P1 as COSEXPRESSION = "$LISTBUILD(""Red"",""Green"",""Blue"")";

or an error will be reported at the time the class is compiled.

Superclass Reference ##super

The usage ..ClassmethodName() now always calls that classmethod in the current class, not that of the superclass. Classmethod in the superclass are now accessed with the expression ##super.ClassmethodName().

Codemode=Call Cannot Using Variable-Length Argument List

Method marked as “codemode=call” are no longer allowed to use variable length argument lists. Such use will cause an error when they are compiled. They need to be rewritten to specify a fixed list of arguments.

Normalize Results of %Exists And %ExistsId For Subclasses

In prior versions, if an application called %Exists passing a fully-formed OID (one that included the classname in it), then Caché always polymorphically dispatched to the %Exist method of that class. For example, calling %Exists on Sample.Employee passing an OID of a Sample.Person would return true. After analysis, this is considered to be a error since calling %ExistsId on Sample.Employee passing the same OID would return false because this is not an instance of Sample.Employee or one of its subclasses.

In this version, the behavior is changed so %Exists and %ExistsId now both return the correct result in this case. It is possible, but unlikely an application may have been relying on this incorrect behavior.

Limits On Class Descriptor Size

Compilation of a class generates a data structure called a “class descriptor” that contains summary data about the class and its components: properties, methods, parameters, indexes, and so on. Information on each group (such as the methods defined) is stored in its own table and is subject to the maximum limit on Caché strings, 32KB.

In this version of Caché, the table formats have changed. The amount of information stored for each method has increased, while that for a property has decreased. The result is that classes which contain many hundreds of methods or properties may find that the resulting class descriptor exceeds one or more of its table limits resulting in a <CLASS TOO BIG TO SAVE> error.


Classes which encounter this error must be refactored to reduce the number of entries.

The number of methods, properties, indexes and so on includes inherited and generated components not only the ones explicitly visible in the class source. Also, properties may cause the generation of methods, for example, <propertyname>Get and <propertyname>Set.

Names Limited To 180 Characters

Compiled classes are stored in globals indexed by the package name, class name and component name. When each of these is a long string of characters, there is the possibility that the maximum length for a global subscript will be exceeded. To reduce the likelihood of this happening, this version of the compiler imposes a maximum size limit on the names of methods, parameters, and properties declared in a class. That limit is 180 characters.

Stored Procedure Return Parameter Types Checked

Prior to this version, return value type parameters were ignored. Beginning with this version, the return type parameters of a class method are now honored by the stored procedure projection. For example,

classmethod myproc() as %String(MAXLEN=100) [ sqlproc ] {

will now project the xDBC column with a maximum string length of 100. Previously, it would have used the default of 50,

Object Binding Changes

Change In Properties Projected For Jalapeño

Prior to this version, all properties that are defined in Caché class that are not marked as Private or ServerOnly, or otherwise not projectible, are present in Java POJO class. Now, properties with names starting with “%” will not be projected in POJO. This will affect user classes if they have properties whose name begin with “%”.

SQL Changes

Changed Handling Of Procedures Names In Embedded SQL

In this version, Caché now treats unqualified procedures names in the &SQL statement differently from prior versions. The schema name used for unqualified procedure names now takes into account any #import value defined. This means if you have an embedded SQL CALL statement (“&SQL( ... )”) in a class method and the procedure name is unqualified, the default will be the schema that maps to the package of the current class. Previously, the default schema would be the system-defined default schema. The default schema for DDL statements remains the system defined-default schema.

Support For SQL Extension FOR ALL Removed

In this version, support for the FOR ALL statement has been removed. In version 2009.1, it was deprecated. Any application using FOR ALL will need to be modified. If necessary, the FOR ALL statement may be converted into a


statement with a condition carefully constructed to achieve the desired result.

Date And Time Conversion Errors Now Reported In SQL Statements

In an SQL statement that takes a %Date value as input in either DISPLAY mode or ODBC/JDBC mode, if the input value cannot be converted to a valid Logical %DateOpens in a new tab value, the SQL statement will return SQLCODE=-146. For similar errors involving %Time values that cannot be converted, SQLCODE=-147 will be returned. For example,

&sql(select name into :name from sample.person where dob = '02/29/2009')

will return “SQLCODE=-146 Unable to convert Date input to a valid Logical Date value”.

Reserved Word Checking More Comprehensive

In prior versions, a reserved word would be accepted as an identifier, for example:

  • As an alias following AS in a SELECT or FROM clause,

  • As a table reference in a FROM clause

These occurrences will now be reported as errors. This is unlikely to affect many queries since the reserved word could not be used in WHERE, GROUP BY, HAVING, or SELECT clauses, nor as the table qualifying name for a column.

ORDER Is No Longer A Reserved Word

ORDER is no longer a reserved word. It is now a non-reserved keyword. ORDER can be used everywhere a regular identifier is used.

Use Of TOP and ORDER In Subqueries

In prior versions, there were two equivalent ways to apply TOP to a UNION:




Starting with this version, the first syntax form will be required. The second example is considered a defect where TOP always applied to the outermost processing level no matter where it was specified.

CASE Clause Result Type Change

In prior versions, the type reported by a CASE expression would be the same as the first potential return value of the CASE expression. This has been changed to return the best compatible type of all the possible return value types of the CASE expression. Caché will now also use the largest length, precision, and scale of all the potential return values; this applies to numeric return values only.

The precedence of return types (highest to lowest) is:







Thus, if a CASE expression may potentially return TINYINT, INTEGER, or NUMERIC values, the type of the column will be NUMERIC because NUMERIC has the highest precedence.

SQL Gateway Changes

Settin Auto-Commit

In prior releases, it was necessary to call both SetAutoCommit^%apiGTW and SetAutoCommit^%apiSQL to change the auto-commit setting. With this release, the SetAutoCommit^%apiGTW call is the one that will take effect.

XML Changes

Exported xsi:type Now Matches Schema

The xsi:type attribute for datatype classes now reflects the actual type of the value. Previously, the xsi:type attribute was always set as the base predefined type, for example, s:string.

Mixed Content Now Properly Marked In Schema

For all elements identified as “complexType” with an attribute of mixed=”true", generate a CONTENT="MIXED" property as well as properties for each of the elements in the complexType. This change can cause compatibility problems if regenerating a previously existing set of classes from the XML schema because element properties were not previously generated by the Schema Wizard.

%XML.Reader Now Returns SAX Parser Errors

In this version of Caché, %XML.ReaderOpens in a new tab now returns SAX parser validation errors. Previously, the SAX parser was reporting the error, but there was a defect that prevented the error from being properly reported.

SAX Namespaces Change

In Xerces 3.0 (the version used in this release), there is a change to the way namespaces are processed. The flag to recognize namespaces is on by default. Turning it off will now cause the localname of the returned startElement callback data to be the empty string; previosly, it was a copy of the qname (fully-qualified name).

Zen Changes

Client-Side JavaScript Change

Zen applications that use client-side JavaScript methods will need to change the declarations of these methods. Where the method signature formerly began with the “Method” keyword, such as

Method test() [Language = javascript] 

the declaration must be changed to

ClientMethod test() [Language = javascript] 

Without this change, Zen classes will not compile or run on this version of Caché.

Changes To Include File Handling

The way that JavaScript and CSS files are generated for Zen components and the way that these files are used at run-time has changed with this release, namely:

  • Modules

    Prior to this change, Zen would create a single JavaScript (.js) and stylesheet (.css) file for each class package containing Zen components. With this version, there is a mechanism for greater granularity – within a package, one or more Zen components can be placed into collections called modules.

  • Reorganization of JavaScript on pages

    Zen pages are changed so that JavaScript includes and inline JavaScript are placed at the bottom of a page, after the HTML content is served. This should result in faster display of pages.

  • Dynamic loading of component JavaScript and stylesheets

    When a component is created, the browser must have its JavaScript and stylesheet definitions on hand. This is accomplished by including the entire library within one large include file. This, in turn, allows dynamic creation of Zen components after a page has been loaded.

  • Use of include files for *all* non-page components

    Prior to this, it was possible for a non-page component to have its JavaScript and stylsheet inline within a page. With this change, all non-page components will use include files.

  • Removal of Zen background file generation

    The generation of JavaScript and stylesheet files now takes place as part of the compilation; the background file generation mechanism is no longer needed.

Zen dynaTree NodeCount Changed

ZEN dynaTree has a property that counts the nodes in the tree. With this version of Caché, the count now includes all the nodes in the tree, not just those at the top level.

Java Binding Changes

Caché Version 2010.1 Is Compatibility Break

Because of internal changes to the way the Java binding manages memory for objects, version 2010.1 represents a break in cross-version compatibility. Java clients on any version of Caché from version 5.0.13 to 2009.1 are compatible with Caché servers in that same range of releases. Those clients will receive an exception if they attempt to access a Caché server running 2010.1.

Java clients attempting to access a Caché server running version 2010.1 must also be running on 2010.1.

xDBC Changes

Make Catalog Queries Independent Of Version

For ODBC Catalog queries there are differences between ODBC 3.5 and 2.5. In version 2009.1, this was addressed by increasing the protocol number. This will not continue to work because SQL Server can dynamically switch between returning data for version 3.5 or version 2.5 by calling SQLSetEnvAttr. This sets the SQL_ATTR_ODBC_VERSION option to either 2 or 3 depending on which type of ODBC error messages or catalog information it wishes to present.

In this version, ODBC allows an application to dynamically switch between the two environment settings. Calling SQLAllocEnv sets the environment to version 2.5 by default. If you want to get the version 3.5 catalog information, you need to call SQLSetEnvAttr. If you use SQLAllocHandle (3.5) the driver manager will force you to call SQLSetEnvAttr before making a connection by giving you an out of sequence error.

Preserve Scale For %Numeric Values

In this version of Caché, the JDBC driver no longer ignores the scaling for %Numeric 0 values; it did in previous releases.

Callin And Callout Changes

Compatibility Between Caché And External Routines

When using Callin or Callout, the Caché instance and the external program exchanging data must have the same view of the characters exchanged. That is, they must both use a Unicode representation for strings, or both use an 8–bit representation. Mismatched exchanges where one side is Unicode and the other are not permitted. Failure to conform to this requirement may result in segmentation or access violations.

MultiValue Changes

Interpretation Of Sleep Value Changed

In prior versions, the MV shell SLEEP command would interpret 2:14 as sleeping for 2 hours and 14 minutes. Now it will be interpreted as a time of day. Beginning with this version the value will be interpreted in one of two ways:

  • If the value is of the form, HH:MM[:SS][AM|PM], it will be interpreted as a time of day. The system will sleep until the next occurrence of that time (which may be tomorrow if that time today is past).

  • Otherwise the value will be interpreted as the number of seconds to wait from the current time.


This interpretation also applies to the MVBasic SLEEP and RQM statements.

Platform-specific Items

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


System Management Portal

There have been a number of changes and improvements to the system management portal. These are detailed in the administrator section.

FeedbackOpens in a new tab