Caché 2008.2

Studio

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

Studio Assist

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

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

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

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

Text Search in Long Streams

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

Query Optimizations For Text Searches

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

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.

Adding Roles Prohibited From Command Line

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

ERROR #940: Insufficient privilege for operation 

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

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

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

• the routine breaks at the debug prompt,

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

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 

UNIX®: Improved Installation

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

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

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

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

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

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.

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.

$SYSTEM.Task To Be Removed

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

Support For Unicode-16 And JIS2004 Added

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

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

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

• $WAscii

• $WChar

• $WExtract

• $WFind

• $WIswide

• $WLength

• $WReverse

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

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.

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

Default For Simplified Chinese Changed

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

^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.

Explicit Conversion To $DOUBLE Now Required

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

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

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

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

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

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

New $ISVALIDDOUBLE Function Added

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

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

New $DECIMAL Function Added

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

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

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

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

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

$ISVALIDNUM Changes

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

Controlling Overflow On Conversions

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

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

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

For example, executing:

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

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

Conversion Of Numeric Literals

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

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

Exponentiation to the Zero Power

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

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

$FACTOR Improvements

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

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

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

$LISTSAME Changes

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

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

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

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
        …
        THROW
    }

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

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

InterSystems recommends that the code be rewritten as

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

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

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

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 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'.

Class Compiler — Query Compilation

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

Class Compiler — Keeping Query Intermediate Code

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

NLS Changed To Use Object Interface

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

New Argument Added to $SYSTEM.SQL.TuneTable

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

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

$SYSTEM.OBJ.ShowMacros() Method Added

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

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

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

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

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

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

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

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

%SYNC.Transporter Class Added For Moving Objects

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

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

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

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

On the receiving side,

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

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

%Studio.SourceControl.File Class Added

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

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

%Library.File Default Directory

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

• GetDirectory()

• GetDirectoryLength()

• GetDirectoryPiece()

• GetDirectorySpace()

%Stream.FileBinary And %Stream.FileCharacter Classes Added

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

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

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

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

Class %Library.EnumString Added

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

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

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

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

Class %SYS.Date.SlidingWindow Added

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

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

Navigating %Library.RelationshipObject

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

• GetObjectIdAt()

• GetObjectIdNext()

• GetObjectIdPrevious()

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.

TSQL Implies PROCEDUREBLOCK

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.

Wider Recognition of LogicalToStorage and StorageToLogical Methods

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

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

%IO.FileStream Changes

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

Preserve Stream Content Across Restarts

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

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

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

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

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

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

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

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

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

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

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

Handling Of Time On Import Has Changed

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

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

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

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

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

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

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

%Monitor.Alert.External() Method Added

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

File Archiving Classes

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

Row ID Flag Added to ResultSet Metadata

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

%BuildIndices and %PurgeIndices Now Validate Names

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

FreezeOnError Removed From System Classes

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

• SYS.DatabaseOpens in a new tab: the FreezeOnError property has been removed. It is also no longer returned by the Detail query.

• SYS.MetricsOpens in a new tab: the FreezeOnError property has been removed from the database metrics display.

It has also been removed from the Management Portal.

XMLNew Method Argument Changes

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

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

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

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

Translation List For Portuguese Updated

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

TCP Broadcast Logic Changed

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

AllowSessions Property Removed from EnsLib.SOAP.Service

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

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

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

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.

MVIMPORT For Universe Backups

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

• The O option has been removed.

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

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

MVIMPORT Change To Contents Of IMPORTED.VOC

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

Reference To Undefined Variables Returns <UNDEFINED> Error By Default

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

To change the default behavior:

• For the current process –

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

• For the entire system –

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

$GET Function Added

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

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.

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

#PRAGMA Added

By default, when an MVBasic routine is compiled, the system generates a routine name MVB.xxx. 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:

#PRAGMA ROUTINENAME=rrr

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:

#PRAGMA ROUTINENAME=

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.

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.

Support For XPICKCOLORS Added To PICKMON TERMDEF File

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.

XPICKCOLORS,

Improved SQL Support for Streams

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

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

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

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

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

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

Support For SQL Column-Level Privileges Added

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

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

for example,

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

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

The syntax for granting UPDATE and SELECT privileges is similar.

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

REVOKE INSERT (SSN) ON Sample.Person FROM John

Other items of note:

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

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

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

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

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

Text Search In Long Streams

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

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

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

Computed Property Self-Reference

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

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

Duplicate Fields In Update or Insert Statements No Longer Allowed

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

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

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

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

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

SQL COALESCE Function Requires Compatible Types

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

• DOUBLE

• NUMERIC

• BIGINT

• INTEGER

• SMALLINT

• TINYINT

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.

SQL UNION Enforces Type Compatibility

In previous versions an SQL query such as

    SELECT 0 AS var1 FROM Table1 
    UNION ALL 
    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:

• VARCHAR

• DOUBLE

• NUMERIC

• BIGINT

• INTEGER

• SMALLINT

• TINYINT

Thus, the query

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

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

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 
    UNION ALL 
    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:

UPDATE SQLUser.MyTable 
     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:

UPDATE SQLUser.MyTable 
     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

LAST_DAY(<expr>)

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

Support Field Collation Names Without Leading %

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

CREATE TABLE MyTable (NAME VARCHAR(50) COLLATE EXACT) 

as being identical to

CREATE TABLE MyTable (NAME VARCHAR(50) COLLATE %EXACT) 

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..

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.

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.

Change To Conversion Of SQLBINARY, SQLVARBINARY And SQLLONGVARBINARY

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.

Properties Of %request Marked Read-Only

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

Added %request Properties

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

Hyperevents Now Changed To Use xmlHttpRequest

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

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

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

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

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

  now always return the empty string.

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

  now always return the empty string.

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

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

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

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

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.

Serve Static Files From Caché Instead Of WebServer

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

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

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

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

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

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

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

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

  • No: Never server files from this application path

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

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

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

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

Password Change From Empty Detected

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

Support for Binary SOAP Messages

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

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

Support XML Exclusive Canonicalization Version 1.0

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

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

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

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

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

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

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

Terminal Local Network Encoding Changed

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

Changes To Terminal Connection Display When Invoked From Scripts

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

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

csession cache -U%SYS ALL^%FREECNT

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

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.