Caché Release Notes and Upgrade Checklist Archive
Caché 2008.2 Upgrade Checklist
[Back] [Next]
Go to:

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 at the start of this document. 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:
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.Table, %SYS.NLS.Format, %SYS.NLS.Locale and %SYS.NLS.Device, 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
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".
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.Task to %SYS.Task. The documentation for the class were changed to indicate that the %SYSTEM.Task class was deprecated. Users were advised to change their applications to use %SYS.Task.
InterSystems intends to remove the %SYSTEM.Task 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 pairs. 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:
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, Caché 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:
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).
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:
The operation of the function, $LISTSAME, has changed slightly. When comparing items from each list argument:
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.SystemException. This class is reserved for use by Caché. Applications that wish to provide their own exception data should define subclasses of %Exception.AbstractException 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.SystemException will be processed by the nearest enclosing CATCH, $ZTRAP, or $ETRAP statement.
User-defined subclasses of %Exception.AbstractException 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.
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 %Collate.
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:
More information on qualifiers is displayed by the method call, $SYSTEM.OBJ.ShowQualifiers().
%SYNC.Transporter Class Added For Moving Objects
The %SYNC.Transporter 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,
On the receiving side,
%Studio.SourceControl.File Class Added
This version of Caché adds a new class %Studio.SourceControl.File 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.File, the following methods will use the value of $ZUTIL(168) (the current default directory), if no value is specified for the directory argument:
%Stream.FileBinary And %Stream.FileCharacter Classes Added
This version of Caché introduces two new classes that correspond to %Stream.GlobalBinary and %Stream.GlobalCharacter. 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.FileBinaryStream and %Library.FileCharacterStream, 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.EnumString. This class is identical to %Library.String except that the string values are restricted to those specified in the VALUELIST parameter of the class:
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.SlidingWindow 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.SlidingWindow 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.SlidingWindow 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.SlidingWindow.
The following functions of %DATE are not implemented in %SYS.Date.SlidingWindow 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.RelationshipObject 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:
It is important to not that while %Library.RelationshipObject 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:
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.Alert 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.Content, as well as the management of the initiation of the data transfer, %Archive.Session. 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.Document 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.Reader for Correlate'd objects as there is no instantiated containing object in this case.
See the documentation for the class, %XML.Adaptor, for further details.
Translation List For Portuguese Updated
Uppercase accented characters of the Portuguese language were added to the character set of the %Text.Portuguese 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.Service 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.Service. The default for the parameter is SOAPSESSION = 0.
If your subclass of EnsLib.SOAP.Service 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:
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:
$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, Caché 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:
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:
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:
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.Date or %Library.TimeStamp 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.Request 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.Request 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:
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:
To support these changes, new configuration options specified with the CSP application settings have been added:
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.Adaptor.
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.0 (except for the InclusiveNamespaces PrefixList feature of Exclusive Canonicalization). This means the Canonicalize method of %XML.Writer writes the XML document represented by the subtree at a %XML.Node 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.Writer and %XML.Namespaces 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.Writer 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.Writer 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.
Caché Terminal Changes
Cache Terminal Local Network Encoding Changed
The Caché 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 Caché 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.