This document contains several sections:

• Important Caché News, Alerts and Advisories
• A change report description
• A list of changes considered critical for this release
• A summary of changes to the documentation 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 - This item indicates whether this change has previously been deployed in an ad hoc release and successfully used by customers in production.

• Enhancement - This notes whether this change provides new features or capabilities.

Make sure that %CSP.SysConnection (which is used to test connectivity from the CSP gateway to the Caché server) can only be called from the gateway. If it is called from somewhere other than the gateway, it returns an HTTP error - Page Not Found.

If a CSP page specifies a 'ContentType' and also a 'CharSet' then Caché always outputs the 'charset=<charset>' header and uses the requested charset to write the page out.

%CSP.Page does not define a CharSet by default. So this change will only effect pages where ContentType and a CharSet are explicitly defined.

Prior to this change, CSP would only write the 'charset' header out if the ContentType contained 'text/'.

This change corrects a situation where state-aware sessions (preserve mode 1) would occasionally lock-up, especially on Linux systems. In extreme cases, the Gateway could become unresponsive to other users. The cause was an internal memory access violation when responding to a session close or timeout event.

The integrity checking for state-aware connections has been improved and the logic for detecting and responding to closed sessions has been reworked.

Since Release 4.1, Caché has allowed the exponent designator for a number in scientific notation to be either upper or lower case, 'E' or 'e'. However, this is not compatible with some programs written in other dialects of the M language, which recognize only upper case 'E'. Those programs use lower case 'e' as a string delimiter. This change provides a switch which restores the behavior of recognizing only upper case 'E' as the exponent designator. The default behavior will continue to allow lower case 'e'.

To change the value of the switch for the current process, issue

SET oldvalue=$ZUTIL(68,63,newvalue)

To change the default value of the switch for all processes which start after this command is executed, issue

SET oldvalue=$ZUTIL(69,63,newvalue)

If newvalue is 1, both uppercase 'E' and lower case 'e' will be recognized as the exponent designator. If newvalue is 0, only uppercase 'E' will be recognized.

During ECP recovery, all ECP sessions should be reset. This change fixes a problem where some of the previous sessions would not be correctly identified and therefore not reset upon recovery.

In prior versions, ECP client shutdown didn't wait for all connections to drop, and it didn't handle free nodes properly. This change causes client shutdown to scan for all allocated slots.

ECP recovery didn't remove ECP sessions info if the session didn't have any open transactions. Because the session slot was not cleared, on the next system restart it would wait unnecessarily for that client to reconnect.

Prior to this change, on slow machines, the write daemon might not join the cluster failover promptly which caused the failover to hang forever.

This was due to intercluster synchronization overwriting the write daemon recovery state, which prevented the new cluster master from resuming the recovery. This now operates properly.

This change corrects a circumstance where unexpected database errors that occured during ECP client recovery could cause the recovery to hang.

This change corrects the way ECP handles connection states. Prior to this, unexpected errors could result in ECP being hung waiting for a re-connect and the only way to clear it was to restart Caché.

If a job exited unexpectedly (for example, with an access violation), ECP did not clear the pending open transactions for that client. The next job that got assigned to the same process slot inherited these transactions, causing confusion between the client and server states. This change correctly handles the cleanup.

%HALT didn't rollback ECP open transactions when the client journaling was disabled. This change corrects the behavior to rollback ECP open transactions.

If you run $SYSTEM.SQL.TuneTable("Schema.Table",1,1) the Selectivity was not getting saved as part of the Class definition. This has been fixed.

In some rare cases, "method does not exist" errors would be reported when compiling classes. This was caused by an error in determining which methods are inherited from the superclasses. It is now fixed.

When importing a class from an XML file into Caché with a very long implementation (over 64k of data), it was possible to get a MAXSTRING error. The import routine tried to concatenate the beginning of the last line from the first 32k block with the next block and this pushed it just over the 32k limit. Now it keeps the beginning of the last line in a separate buffer and only concatenates this with the rest of the first line from the next 32k block rather than the entire block.

When a reference is swizzled, the modbit for that property is not supposed to change. This changes corrects the behavior; the value of the modbit is unchanged for simple swizzling.

The bitmap extent index for a class is automatically built whenever any index is built and the bitmap extent has never been built. When all instances are deleted from an extent there was a situation that caused the system to incorrectly assume that the bitmap extent index was already built.

This has been fixed by assuring that indices are purged whenever extents are removed. If any instances fail to be deleted successfully, the indices remain.

The SAX parser caches the XML parser it uses for performance reasons. During entity resolution, CacheStreams may be created via callbacks to %XML.SAX.EntityResolver and its subclasses. As a side effect of parser caching, the OREFS of these stream objects are also cached. (They are eventually garbage collected, but in a non-deterministic manner). This causes a problem if the user of the parser were to change namespaces before garbage collection of the stream occurs.

This modification corrects the error by reclaiming the streams as soon as the parse is completed.

When the XML Reader NodeType was 'endelement', the LocalName property returned empty string. This correction makes it return the proper value.

An enhancement has been made to the calculation of a Map's estimated block usage to include information about the fields in map subscripts for the map. Now an index of the form:

^glo("index",Field1,Field2,ID)=""

will have a higher "cost" than an index of the form:

^glo("index",Field1,ID)=""

If the query optimizer can use an index on Field1, the second index should now be chosen.

An oversight has been corrected where a table's query optimizer information was not fully updated until the class was recompiled. This was missed when the extentsize of the table was calculated through SQL Manager's tuning facility.

In the situation where the last subscript defined in a storagemap for %CacheSQLStorage was a constant, attempts to execute a runtime query against this table could result in an <UNDEFINED> error. Whether the error occurred or not depended on the details of the global structure for the storage.

The possibility of this error has now been removed.

Prior to this change, a query that JOINs two tables in a WHERE condition and has an ORDER BY <f1> DESC, <f2> ASC might not return the rows in the correct order. This has now been corrected.

In prior versions, Caché might fail to display the text of a cached query when listing the queries of a namespace. This change corrects that error.

This change corrects a situation where a table which uses %CacheSQLStorage and specifies its own Map RowID Specifications might generate improper map definition code. This causes improperly generated query code for queries against the table.

This change corrects an error in constraint checking. Under some circumstances, the checking of a unique constraint or a foreign key referential integrity check by SQL might produce an <UNDEFINED> error. This happened when an SQL query was needed to check the constraint, and the constraint was on the IDKey field.

Under some circumstances, Caché processes could generate a high CPU load after the user has closed them. The symptom was caused by an infinite loop in the process disconnect logic. This change eliminates that circumstance.

A new checkbox has been added to the DSN configuration screen: "Use Locale Decimal Symbol". By default, CacheODBC sets the default decimal separator to "." to provide legacy support for some customers. Unfortunately, this causes some difficulties with applications like PowerBuilder that prefer to use the decimal separator as defined for the current locale.

Checking the checkbox "Use Locale Decimal Symbol" will use the decimal separator in process and leave its value unchanged. Leaving this unchecked will give the old default behavior of setting the decimal separator in the process to "." regardless of the locale.

This setting is defined for all DSNs on a system as it is a property of the driver when it is loaded. On Unix, setting the environment variable CACHEODBCLOCALEDECIMAL = 1 lets the driver use the Locale's decimal separator value.

Under some circumstances, an SQL query might generate code in a single line which is too long (longer than 4095 characters). This can happen when there are many subscript levels (greater than 15) in the map definition and overriding data access expressions are used in the map definition.

This change corrects the problem.

An error has been fixed where conditions (especially JOINs) on single column idkey columns did not behave properly if the SELECT clause were 'SELECT *'. The suspect behavior could be poorly performing plans or SQLCODE= -400 when the query executes.

In prior versions, choosing to execute a query from SQL Manager, but selecting an option from the menu after the query had been typed but not run, would not execute the query. The option choice and query execution would run properly, however, if you used the keyboard shortcuts to execute it instead.

This circumstance has been corrected.

This corrects a problem that would cause an error handler to be skipped when a lower level error handler issued

ZQUIT 1 GOTO @$ZTRAP.

The problem happened when the lower level error handler set $ZT="". This would cause the ZQUIT 1 command to bypass the next error handler.

The code which cleans up after dead jobs in Caché will now check to see if the job has retained a global buffer and if so, it will free it.

The write image restore program will now refuse to run if Caché appears to be running from the manager's directory specified as part of the restore. A message noting this will be logged in the console log.

A bug in timeout handling for TCP read requests under Caché/Unix has been corrected. It could cause the READ to continue waiting past the specified timeout if the process were probed by ^%SS, ^JOBEXAM, or similar interrupting utility programs.

On Windows systems, Caché processes running in a Windows Command Prompt window or running from a local Caché terminal (the title bar will contain Caché TRM:processId) will be improperly terminated when the user who started them logs out of the Windows Workstation. This improper termination also occurs in Caché processes started via the job command from these processes. This problem has existed since Caché 4.0.

This change corrects this problem by establishing a console control handler to catch the Windows Logoff event and exit Caché normally. It also changes the way processes started by the job command are created so they will persist following logout from the Windows Console.

Users may encounter one different behavior in processes started by the job command. Since the process is started by the Caché control process at the request of the Caché foreground process, the jobbed process no longer runs in the login session of the user at the console who created the process with the job command. This means that on Windows XP, the process created by the job command will not be able to access network devices using the drive letter mappings defined for the user logged into the Windows console. You should use the UNC naming convention (that is \\server\share...) instead of the local drive mapping (eg. w:\...) in your code to access network shares from processes started by the job command.

This corrects a rarely occurring situation where using JOBEXAM to view a process could cause that process to crash and get an access violation. This happened in the case where the examined process was completely out of process-private memory.

When an MSM job with a large internal job number accesses a remote Caché system using DDP, it may get <DSTDB> error.

This change fixes this problem.

This change corrects a problem with cluster failover failure when the master node is shut down. The source of the issue is that write daemon failed to notify the shutdown requestor when it finished causing a long delay. Also, the ENQ daemon has to be forced down when the cluster node is shutdown.

On a cluster platform, a situation may occur during backup if the procedure to block and quiesce updates/accesses gets an error or fails to quiesce. The problem is that switches set locally but outside the backup program may get cleared during backup.

This change corrects the issue.

This change eliminates a small timing window where a ^LOCKTAB or ^$LOCK SSVN could get an access violations when there is a large volume of lock table activity.

CLU^SWSET, ENQ10^DBACK and ENQ13^DBACK have been enhanced so that timed locks will not time out while switch 10 or 13 is set in a cluster.

This change eliminates potential <SUBSCRIPT> errors during journal restore and transaction rollback.

In interactive mode, journal restore prompts for transaction rollback if some transactions remain incomplete at the end of restore. This happens even if the current journal file is not involved in the restore.

This change addresses a problem with locating the next journal file. In earlier versions, Caché could incorrectly compute the next journal file name. This has now been corrected.

Cluster journal files are logged in cachejrn.log in the pij directory of a Caché cluster. This log, cachejrn.log, is used by cluster journal restore and cluster shadowing to locate every journal file used by any past or present node of a Caché cluster.

This change causes failures in logging the journal file name in cachejrn.log to be reported in cconsole.log.

On VMS, updating cachejrn.log allows read sharing, eliminating a potential cause of update failure in lieu of cluster shadowing.

This change corrects a circumstance where the beginning offset of an open transaction was set to a value smaller than it should be. This did not affect transaction rollback but could affect those applications that assume the return value points to a valid journal record.

This corrects an issue on OpenVMS that may cause a copier on the source side of fast-mode shadowing to get occasional <ENDOFFILE> errors when reading a very small journal file.

This corrects an issue that could result in unnecessarily many small journal files when the amount of free space on the journal disk is less than the expansion size of the journal file.

Fast-mode (aka "block-mode") shadows are now transaction aware and maintain a list of incomplete transactions that are applied on the shadow. To roll back incomplete transactions, stop shadowing and execute

SET rc=$$ROLLBACK^SHDWCBLK(ShadowID)

where ShadowID is the name of the shadow, and "rc" is the result code for the operation: 1 = success and 0 = failure.

This corrects an instance where choosing "this system as source" in control panel may not show any server info (and may get an <UNDEFINED> error) even if there is a running server servicing a shadow.

This change improves the error recovery processing in shadowing by addressing an issue affecting how stack was unwound when errors are passed on to upper level routines.

This change does two things:

1. It prevents occasional <NOTOPEN> errors (generated from updjrninfo^JRNINFO) on the cluster data server ("source") of shadowing.
   
   
2. It allows multiple jobs on the source to open CACHEJRN.LOG file for READ simultaneously, resulting in some degree of performance improvement on journaling and shadowing.

This change corrects a problem where the source of fast-mode shadowing (i.e., data server) on OpenVMS might get occasional <ENDOFFILE> errors.

This change corrects an issue that some component of cluster shadowing might use more process memory than specified in Caché configuration.

Updates to ^%SYS("JRNINFO") by JRNINFO server are no longer journaled.

This addresses an issue of cluster shadowing where the shadow of a source server with no user activity is constantly seen as busy if ^%SYS("JRNINFO") is marked journaled (or "journal all globals" is set in 5.0.x).

This change corrects a performance issue where each cluster shadow request resulted in a JRNINFO server being jobbed off. Now, JRNINFO servers corresponding to a cluster shadow stay around whenever possible.

This change corrects a situation where the control panel could report an <UNDEFINED> error when attempting to manage a cluster shadow, if the system running the shadow was different different in kind from the system running the cluster. An example of this would be a Windows system shadowing a VMS cluster.

A correction to compatible-mode (record-mode) shadowing has been made to prevent the source of shadowing from sending journal records to the shadow destination which have not yet been written to the current journal file

This corrects a problem where the source of shadowing could get transient <FUNCTION> (or other error) while processing the current journal file during a journal switch. It also corrects an issue where, if the source of compatible-mode shadowing crashes, the shadow destination may have more recent completed transactions than what is available on the source after recovery.

Shutting down Caché on a Windows Terminal Server system can leave a cache.exe process attached to the shared memory object if ^SHUTDOWN takes more than about 3 minutes. This residual cache.exe process prevents the configuration shared memory from being destroyed at shutdown. This prevents Caché from being restarted without either rebooting Windows or terminating the residual process with the Windows task manager.

This change properly shuts down all the processes.

Prior to this change, Caché would refuse an attempt to define the shadow for a cluster to be a machine type that did not itself support clustering. This has been corrected.

This fixes a problem in integrity checking of very old ISM databases. Running INTEGRIT would give false errors when global name is not in the top pointer block.

This corrects the issue so that the error is only given when there really are duplicate pointers in the global directory.

In prior versions, when saving MAC/INC from Studio, the data stored in ^rMACSAVE or ^rINCSAVE had the root node incorrectly formatted. This should be the $horolog value of the time this MAC/INC was last changed.

This change sets the proper value in place.

The content of the Caché documentation evolves from release to release in response to editorial improvements, updates to existing material, and addition of new information. The following is a summary of the most noteworthy changes to the Caché documentation since the previous release:

• Caché I/O Device Guide
  • Added further explanation of RMS file open mode parameter restrictions
  
  
  
• Caché ObjectScript Reference
  • OPEN command: removed the RMS file subsection
  • $ZSEARCH function: Windows-specific behavior
  
  
  
• Caché SQL Reference
  • Corrected NULL and empty string usage/representation throughout
    • CAST
    • CHAR_LENGTH
    • CHARACTER_LENGTH
    • LTRIM
    • RTRIM
  • Clarified case-conversion functions functionality and use throughout
  • %ALPHAUP: added Unicode and cautionary examples
  • ALTER TABLE - added 5 restrictions:
    • alter column with streams data
    • add primary key constraints for IDKey and index
    • drop constraints for foreign key and IDKey
  • ALTER VIEW:
    • added WITH READ ONLY and WITH CHECK OPTION to syntax
    • explained privileges requirements
  • CALL: added embedded SQL support
  • CHAR: corrected for Unicode characters, non-numerics
  • COALESCE: clarified string and number handling
  • CONCAT: replaced the prior description with a new one
  • CONVERT:
    • added second syntactical form
    • added description for SQL_DOUBLE data type
  • CREATE INDEX, DROP INDEX: added descriptions of the restrictions when there is existing data
  • CREATE FUNCTION, CREATE METHOD, CREATE PROCEDURE, CREATE QUERY: detailed description of SELECTMODE and RESULTS clauses, when PROCEDURE keyword unnecessary
  • CREATE TABLE: added all 9 collations, more no-op keywords, and security configuration
  • CREATE TRIGGER: updated the description of the ORDER algorithm
  • CREATE VIEW:
    • fixed WITH CHECK OPTION error in syntax
    • added privileges requirements and security configuration
  • DROP TABLE: added privileges requirements and foreign key restriction
  • DROP VIEW: documented the restriction when the view is non-existent
  • GRANT: SQL security configuration options added
  • INSERT: RowID restriction described
  • LENGTH: added second syntactical form
  • ROLLBACK: Cached Query exception explained
  • SELECT: expanded extrinsic functions description; reworded SELECT * note
  • TRUNCATE: documented the handling of numeric literals that represent numbers too large or too small
  • WEEK: fixed the algorithm for calculating the week of the year
  • SQL Concepts:
    • Comments: added the list of variables in .INT code
    • Data Types: added BIGINT and notes on streams
    • Host Variables: added notes on undefined variables, OREF dot syntax, and listings in .INT code comments
    • Identifiers: Added the description of the IsValidRegularIdentifier method and its invocation as procedure call
    • Literals: Completely rewrote the material
    • NULL: added new page on NULL and empty string usage
    • Reserved Words: documented the $SYSTEM.SQL.IsReservedWord method as procedure call
    • Transaction: described the conditions under which cached queries are excluded; described the uniqueness lock
    • Error Codes:
      • added 16 new code values to list and to descriptions of commands
      • added $SYSTEM.SQL.SQLCODE() method and procedure call

  These are in addition to minor enhancements in examples, as well as corrections and improvements to grammar and spelling.