This document contains several sections:

• Important Caché News, Alerts, and Advisories
• Online Documentation
• Description of a Change Report
• A list of changes considered critical for this release

From time to time, InterSystems publishes items of immediate importance to users of our software. These include alerts, mission critical issues, important updates, fixes, and releases of Caché.

The most current list can be obtained from the InterSystems Website.

Users should check this list periodically to obtain the latest information on issues that may have an effect on the operation of their site.

As a convenience to our users, InterSystems provides online access to documentation for recent versions of Caché at the InterSystems Website.

From the home page choose the "Caché" tab, and on the "Downloads" menu, select "Documentation and Help Updates" or follow this link.

To help you assess the impact of these changes on your applications, each change description contains a more detailed explanation of the modification.

All changes include a table giving pertinent information on the issue's likelihood, impact of the change, and whether this has already been used successfully in production by other customers. In order to make the information easy to assimilate visually, the tabular information has been simplified to a keyword or two and a value. The full explanation of the keyword meanings are:

• Likelihood - The probability that a user on the affected platform will encounter this issue.

• Risks - An assessment of how likely this change is to introduce additional issues into the application environment.

• Ad Hoc - Whether this change has previously been deployed in an ad hoc release and successfully used by customers in production.

• Enhancement - Whether this change provides new features or capabilities.

When you set '%response.Timeout' in the OnPreHTTP method, the server was not flushing the buffer. Thus, this timeout value did not get to the CSP gateway until the whole page was flushed. At that point, it was too late.

The change flushes the buffer when Timeout is set.

This change provides a way to reclaim a lost CSP license. This happens rarely with Preserve=1 CSP session where the session was being unlocked. However, in case of any future occurrence Caché now has a way to count CSP licenses and CSP sessions and reclaim any lost licenses.

This change ensures that extended URL syntax (with PATH_INFO) is fully supported. For example:

http://<ip address>/csp/samples/page.csp/testdir

In this example the PATH_INFO environment variable will be set to 'testdir'.

This change corrects a timing problem that could occur in the garbage collection of timed-out CSP requests.

When a CSP request to Caché times-out (in accordance with the value of 'Server Response Timeout'), the corresponding connection to Caché is closed and its associated memory and other resources are released.

In prior versions, there was a problem in which a connection handle (i.e. number) could be reused by the Gateway before the resources associated with the previously timed-out request were fully released. Under these circumstances a memory violation could occur resulting in the CSP request using the new connection failing and a message being recorded in the Event Log.

This change generates the code needed to call OnPreHyperEvent within <formname>_save and <formname>_new JavaScript methods that are generated by CSPBIND.

In very rare situations, the ECP client may send a request for an invalid (dismounted) DB. With this change, the request is checked for validity and rejected if it does not pass.

When closing a persistent object, an error would be encountered if the object has not been assigned an ID, and the concurrency setting indicates that retained locks should be used. This change corrects that error.

When exporting a class to XML format, Caché now skips writing the UDLText 'name' attribute; these were automatically generated and have no significance themselves. Caché will still import XML files with UDLText names in them, but this attribute is now optional in the schema.

The reason for this change is because the names of these UDLText were generated automatically they would often get renumbered and this would cause problems using source control as it would show conflicts on these names when there really was not difference between these items.

The %Activate.GenericObject methods that return streams have now been supplemented with methods to return BinaryStreams.

This change fixes the following problems in output redirection inside language bindings:

1. the output is not redirected outside running methods (but this change doesn't address output redirection in stored procedures)
   
   
2. output redirection does not preserve the last referenced global which is important when using naked references
   
   
3. if the server code does an explicit new before output redirection, the context becomes lost, and the output is not redirected correctly.

The routines $system.OBJ.ExportJava and ##class(%Compiler.LG).ExportJava now take a final flag in which one can specify the use of new collections.

Also there is a projection parameter, NEWCOLLECTIONS. The flag is "/newcollections"

• /newcollections and /newcollections=1 turn on new collections
  
  
• /newcollections=0 turns off new collections

Here is an example of calling ExportJava with the newcollections flag:

zn "USER"
s Status=$system.OBJ.ExportJava("ISC.TestCollections",
                                "c:\perforce\users\levinson\TestCollections",
                                "/newcollections")

i 'Status d DecomposeStatus^%apiOBJ(Status,.Err) w !,Err(Err) ;'
w !,"Status="_Status

When "newcollections" is set, a property with collection type list has a return type java.util.List, and a property with collection type array has return type java.util.Map. Each of these may be overridden by specifying a return type viaJAVATYPE.

When NEWCOLLECTIONS is set collection properties project as java.util.Map (for arrays) and Java.util.List (for lists). When NEWCOLLECTIONS is zero (the default), collection properties project as follows:

• ArrayOfDataTypes for array of a datatype
• ArrayOfObjects for array of an object
• ListOfDataTypes for list of a datatype
• ListOfObjects for list of an object

There are different coding paradigms for utilizing these from the Java code.

Here is an example of accessing a list of strings with NEWCOLLECTIONS set to 1.

/* Iterate over the FavoriteColors collection */
colors = person.getFavoriteColors();
for (r = 0; r < colors.size(); r++) {
   System.out.println("   Element #" + r + " -> " + colors.get(r));
}

System.out.println( "Modifying 'FavoriteColors' ..." );

/* Remove the first element */
if (colors.size() > 0)
    colors.remove(0);

/* Insert a new element */
colors.add("Red");

/* Show the changes to the collection */
colors = person.getFavoriteColors();
for (r = 0; r < colors.size(); r++) {
    System.out.println("   Element #" + r + " -> " + colors.get(r));
}

System.out.println("Dumping favorite colors should be red");
i = person.getFavoriteColors().iterator();
while (i.hasNext()) {
    System.out.println(i.next());
}

In 5.0.X, the default behavior of the projection is old collections.

%XML.DataSet had a bug that caused it to report an all whitespace string field as an error. It now correctly returns the all whitespace value.

Customers have expressed the desire to control the retention of whitespace for element content. Currently the TextReader removes leading and trailing whitespace by default. A parameter (KeepWhiteSpace) has been added to the ParseXXX method of %XML.TextReader which allows the user to specify a boolean 1 to keep whitespace. The default is 0, meaning strip whitespace so that backwards compatibility is maintained

%TextReader provides a means to parse XML source and navigate through a list of Nodes much like a cursor is used in SQL. There is a property on the reader object called Path which contains a string representing the hierarchical nesting of the current node. For example, in this XML:

<a>
   <b>
       <c/>
   </b>
</a>

When the cursor is at the <c/> node, the path would be the string "/a/b/c".

The Rewind() method returns the cursor to the first node in the list. The error was that the Path property was not cleared upon Rewind so on the second navigation to the <c/> node the Path would look like this /a/b/c/a/b/c. The fix clears the Path property to "" when Rewind is done.

When importing a XML file that contains a large (>32k) binary file, the base64 decode logic could fail resulting in an invalid file being created. The import of these files is now correctly handled.

An error prevented XML export of a global that contained a $c(0) character. With this change if Caché encounters this character it will base64 encode the data.

The SOAP Client Wizard combines the name attributes of the wsdl:service element and the wsdl:port element to form the name of the web client class. This changes makes that combination a class name valid in cases where it would not otherwise be valid such as when a part of the name bracketed by periods (.) is numeric.

This change causes Caché to escape enumeration value attributes that correspond to %String VALUELIST when writing out a schema for element of type xs:string.

This correction allows the application to rewind to the beginning of an %XML.DataSet if the %XML.DataSet was created by importing XML or is input to a SOAP web service. A new method of %XML.DataSet can be called to do the rewind, ResetXML.

If the %XML.DataSet was populated by a query, no rewind is possible since we cannot return to the beginning of result set created from a query.

Have XMLExport method (also when it is called internally by %XML.Writer) call ResetXML after export is complete.

The namespace associated with an element will always be as specified by the NAMESPACE parameter of the class in which the element is defined. The element keeps the same XML namespace even when it is projected by a class that inherits the property and has a different NAMESPACE parameter.

If the superclass has no NAMESPACE parameter defined and a subclass does, then the properties in the subclass that were inherited from the super class are deemed to have the NAMESPACE specified by the subclass. This is a sort of reverse inheritance just for the property's XML namespace.

Inheritance of the NAMESPACE parameter follows normal inheritance rules, so that a subclass without a NAMESPACE parameter is deemed to be defined with the inherited XML namespace.

The above rules for the NAMESPACE parameter also apply to the ELEMENTQUALIFIED parameter.

If you have a class that has CacheSQLStorage and no subscripts, Caché would generate an incorrect line of code in the gunlock2 procedure of the Table routine. This has been fixed.

A bug has been fixed where the following query would erroneously get an SQLCODE=8 error during compilation:

SET x=$ZTIMESTAMP
&sql(SELECT DISTINCT DATEADD('ms',10,:x)
     INTO :a
     FROM Sample.Person)
WRITE a

A problem has been corrected where a sub-query in a SELECT clause returned a value that should have LogicalToOdbc or LogicalToDisplay applied. Instead, the Logical value was output.

There is a new Property Parameter called CALCSELECTIVITY. The default value for this parameter is 1 (TRUE).

When a table is tuned via TuneTable, the selectivity for a field will only be calculated if the corresponding property parameter value for CALCSELECTIVITY is 1.

If you do not want TuneTable to calculate the SELECTIVITY for a property/field, set the property parameter CALCSELECTIVITY to 0.

A change has been made to Caché so that modifications to cached queries are not journaled. This prevents some changes to cached queries that happen during a transaction to not appear in the journal; shadowing will not apply cached query changes across systems.

A problem has been corrected where the INSERT or UPDATE of a row in a table with a self-referencing Foreign Key would fail with an error if the row referenced the same row being inserted or updated, and the foreign key field was required.

This change corrects a problem where queries such as the following:

String sSQL3 = "SELECT {fn CONVERT (i1 + (i2 * 10), SQL_INTEGER)}
    AS myval
    FROM test1
    WHERE (i1 IN (?, (30)+1, ?))";

got preparser errors, because the production rule for a numeric operation appearing within an "option list" did not allow the numeric operation expression to contain parenthesized subexpressions. This occurred where numeric operations appeared as function arguments, or within an "IN(...)" predicate.

The parser production rule for a numeric operand has been changed to allow a parenthesized expression.

JDBC Preparser now handles aggregates as FN arguments like

{fn CONVERT(AVG(fINT2) ,SQL_INTEGER)}.

Caché incorrectly preserved cached queries associated with a connection after that connection had been disconnected. This has been corrected.

Nested parenthesis caused an exception when used in the IN construct during JDBC preparsing. This change corrects that error.

This change correctly calculates the buffer length needed for sending Unicode Streams > 32K in length.

This change corrects an error present when using S-JIS text with several third party tools. The symptom was the inability to insert binary data via an SQL statement. This fix is an alternate way to prevent the problem seen with S-JIS that will also allow inserting null values without prematurely terminating the SQL Statement.

When using SQLGetData to fetch data, the CacheODBC driver automatically will fetch more data from the server when needed. When this happens, several columns of data are in the original message, and the remainder of the row are in the newly fetched message. The mechanism works correctly as long as the application does not call SQLGetData to fetch a column of data that is earlier than the last call to SQLGetData. DOing so would cause a processing exception.

This change fixes this condition.

This change causes a UNION between 2 subqueries with different SELECT-list lengths to report

SQL error #9:  Incompatible SELECT lists used in UNION

A bug has been fixed where error 94 (unsupported use of outer join) was erroneously returned when using ODBC, JDBC, or dynamic SQL. The query would work using embedded SQL. The circumstances are:

<view or FROM clause subquery> L
LEFT JOIN <something> R
ON L.y = R.a
LEFT JOIN <something else> S
ON L.x = S.b

when L.x referred to a view or subquery column that was an expression or aggregate. Note, the view or subquery must have aggregates, GROUP BY, or DISTINCT.

If there was a routine, test.MAC, open for editing in Studio, it was possible for a second person to open test.MAC. As long as they did not attempt to change the routine, they could compile it.

However because another user is actively working on this routine (as they hold the lock on it), this is wrong and Caché now prevents the second person from compiling this routine by attempting to obtain a lock on this before compiling it.

When a user undoes a checkout on a class from Studio, it did not mark the document as read only. Thus the user could continue to make edits to the class even though it was not checked out. This is now fixed.

XML import could import a class but then fail to lock the class if, for example, it was already instantiated in another process. In this circumstance, XML was not removing the temporary global structure it had created. This meant that the next global import merged its data into this existing global thus creating a class that was a combination of methods/properties of both classes.

This is now fixed.

When a user subscript maps a global in Caché and then locks one of the subscript mapped nodes, the lock does not follow the same mapping as the global data.

In the case of a routine mapped from another namespace, Studio was locking this routine in the namespace where it was accessed. Thus, it was possible to get a lock on the same routine from more than one namespace.

Now Studio determines where the data lives for this subscript node before taking out the lock, so if a routine is mapped from USER to SAMPLES, then the lock will be taken out in USER no matter which namespace Studio was running in.

During symbol table operations, the system would sometimes read an extra byte beyond the end of the table. If that next byte happened to be in a block of memory that had never been allocated, a memory access violation would result. This fix corrects the system so it does not read the extra byte.

This change addresses a problem introduced by the optimization phase of the C compiler on Alpha OpenVMS systems that might, under certain circumstances, result in an access violation when trying to JOB a new process.

This change addresses an issue in Caché for UltraSPARC 64-bit that might cause the Write Daemon to hang in certain circumstances.

$SYSTEM.Backup.ExternalFreeze() and $SYSTEM.Backup.ExternalThaw() have been enhanced to correctly manage suspending/enabling lock timeouts in a clustered environment.

In a cluster while the cluster is suspended to perform a backup, timeouts on the lock command are suspended. When the cluster is resumed, the timeouts start counting down again.

Previously there was a problem where timeouts would be suspended by $SYSTEM.Backup.ExternalFreeze() but not re-enabled by $SYSTEM.Backup.ExternalThaw()

A problem that on rare occasions could cause Caché process hangs during HALT on Windows systems, has been fixed.

Sporadic hangs or failures with sending a broadcast message to another process have been fixed.

This change allows for a process to have more different classes active at any one time, and more efficiently deals with classes that are not in active use by the process.

With this change, the cache.dmp on older version could not be analyzed by the cstat of the 5.1 version. And the cstat of older version of Caché could not analyze the dump from Caché 5.1. This changes makes the analysis possible for both systems.

A new set of methods have been added for suspending the system in order to perform a backup external to Caché. These are designed to be used with a technique such as splitting a disk mirror or creating a snapshot which allows the system to back up an open file as of a specific point of time.

The methods are $SYSTEM.Backup.ExternalFreeze() and $SYSTEM.Backup.ExternalThaw() and replace the existing technique of calling ENQ13^DBACK and DEQ13^DBACK.

These methods must be used on a cluster as they generate the journal information required to restore the journal in conjunction with restoring one of these external backup. For non-clustered systems these are preferable to using the entry points in ^DBACK as they do not suspend the system using switch 13. Rather they use a new technique which stops the write daemon from writing to disk. User jobs continue to run as long as there are enough free global buffers for them to complete their work.

The Caché Class Reference documentation contains details on the arguments to these methods.

Caché backup restore will no longer allow a full backup to be restored other than as the first backup to be restored. Previously multiple full backups could be restored in a single DBREST session. This caused problems during the subsequent journal restore.

The Caché BACKUP/RESTORE mechanism has been enhanced to permit simultaneous restore of the same backup archive file by multiple configurations under OpenVMS.

The ^BACKUP utility now warns if the user adds an invalid directory to the backup list.

This change Addresses an issue where an access violation (or coredump) might result from the user's specifying a journal file path longer than the Caché limit (64 characters).

This change addresses an issue that could cause the cluster sequence of journal records on a slave node to become out of order (i.e., an earlier record has a higher sequence than a later record does).

The problem can occur where a slave issues a $increment() on a global in a cluster-mounted database and the $increment() is not journaled on the master for some reason. One example is when the network type of the cluster is ECP and journaling is turned off in the process issuing the $increment() on the slave. As a consequence of the problem, the affected journal files may not get dejournaled properly in cluster journal restore or shadowing.

With this change, $INCRs involving cluster-mounted databases (redirected from slaves or initiated on the master) always result in bumping the master copy of cluster journal sequence, whether they are journaled on the master or not. Previously, the master copy of cluster journal sequence was NOT bumped unless $INCRs were journaled on the master.

This change fixes a possible lock memory corruption on OpenVMS.

This change corrects a situation where an ECP client on OpenVMS could stall waiting for a lock timeout to occur.

Caché started in single user, read-only mode (cache -cd) will now not overwrite startup.last.

A job could be hang in tight CPU loop if it uses TCP device with different translation table than the other side. This has been corrected.

Silent^Integrity doesn't handle the case where the log file cannot be accessed. This has been fixed.

This fixes a case where Silent^Integrity could leave a file open if an error occurs.

This enhances ^Integrity to check for inconsistencies in the map block that will cause database errors. This does not apply to legacy databases.