The release notes are available in the \Docs subdirectory of your installation.

Late-breaking information about this kit can be found in: \relnotes\readme.1st

Release notes from prior kits are combined in the file: prenotes.htm

This document provides a list of the changes between Caché 2008.1.0 and Caché 2008.1.1.

Topics include:

• General Announcements
• Restricted Rights Legend
• InterSystems News, Alerts, and Advisories
• Online Documentation
• Description of a Change Report
• Change Reports for This Maintenance Kit

Customers running on any prior released version of Caché may upgrade to this version of Caché during installation.

InterSystems advises all users to recompile their Applications as part of the upgrade process so as to take advantage of all the performance improvements as well as other changes that may affect them in this release.

After each upgrade step, the following conditions apply:

• Routines
  Unless specified in the upgrade notes for a specific release, routines are upward-compatible and do not need to be recompiled. However, customers may decide to recompile them to take advantage of new features, improvements in generated code and the corresponding efficiencies in runtime support.
• Classes, SQL, Projections, Proxy Classes
  InterSystems requires that all classes be recompiled after an upgrade. This is accomplished by running the following command in each namespace where application classes reside:
     Do $system.OBJ.UpgradeAll("c")
  

  You must regenerate any proxy classes used in the upgraded instance by following the instructions in the appropriate guide(s) in the Caché Language Bindings set.

Customers upgrading from a version of Caché earlier than 5.1 should contact their sales representative to arrange for new license keys. Customers upgrading from Cache 5.1 or later may continue to use their existing keys.

Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013.

When acquired by the Government, commercial computer software and related documentation bearing this legend are subject to the following:

1. Title to and ownership of the software and documentation shall remain with the Contractor.
2. Use of the software and documentation shall be limited to the facility for which it is acquired.
3. The Government shall not provide or otherwise make available the software or documentation, or any portion thereof, in any form, to any third party without the prior written approval of the Contractor. Third parties do not include prime contractors, subcontractors and agents of the Government who have the Government's permission to use the licensed software and documentation at the facility, and who have agreed to use the licensed software and documentation only in accordance with these restrictions. This provision does not limit the right of the Government to use software, documentation, or information therein, which the Government has or may obtain without restrictions.
4. The Government shall have the right to use the computer software and documentation with the computer for which it is acquired at any other facility to which that computer may be transferred; to use the computer software and documentation with a backup computer when the primary computer is inoperative; to copy computer programs for safekeeping (archives) or backup purposes; and to modify the software and documentation or combine it with other software. Provided that the unmodified portions shall remain subject to these restrictions.

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

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 product versions 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 this maintenance kit on your applications, the remaining topics in this document describe each modification in detail.

If you need assistance evaluating the effect on your application(s), system(s), or related plans, please contact the InterSystems Worldwide Support Center:

• Phone:  +1  617  621-0700
• Fax:  +1  617  734-9391
• Email:  support@intersystems.com

This build fixes an occasional memory leak in the Apache modules: CSPa[n][Sys].so/dll. The leak would occur in cases where the Gateway modules chose to forward a request on to the next module in the list (for example, requests for static files).

This build corrects a fault that could lead to CGI environment variables not being removed from the cache when no longer defined. The fault corrected with this change could occasionally result in environment variables left over from previous requests.

This change corrects a situation in the backwards-compatibility code designed to serve Caché v4.1 (and earlier) systems that could result in the premature termination of form request data exceeding 8K in size (as is often the case with forms containing TEXTAREA elements).

The original implementation of ParseString() has been restored to %XML.SAX.Parser to unforseen problems on the OpenVMS platform.

Windows installation will detect when it is running on a Windows 2008 or above cluster and install and register cluster resources.

When stepping through a routine with multi-line comments, the debugger would display the wrong line as the current line.

The arguments in the job command include the specification of an operating system directory to which a child job should switch as part of its startup. However, this is not necessarily the directory the child job will use; it may be overridden by the default directory associated with the namespace for the child job.

Furthermore, errors switching to the directory in the child job were not treated consistently across platforms. On Windows and OpenVMS, errors were ignored. On UNIX systems, the behavior varied depending on the platform and Caché version.

With this change, 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 directory.

This change assumes that references to $SYSTEM classes are correct and do not need to be syntactically checked. All $SYSTEM calls (except for ones of the form $SYSTEM.XXX(...)) are colored as OK.

Studio Assist for $SYSTEM calls works as before.

This change corrects a problem where the mapping of sub-packages used uppercase for the names rather than preserving the case of the actual name.

Under rare circumstances, ECP server initialization can fail while partway through leaving a state that may prevent later ECP recovery or clean up. When this happens, a Caché restart is required to recover.

This change prevents the initialization failure from occurring.

In very rare conditions, when the ECP Server fails unexpectedly, and an ECP client connects after dead job cleanup, a race condition can cause confusion about the job identifiers and prevent successful recovery. This correction eliminates that race condition.

When an ECP application server is shutting down, the ECP read daemon may not detect and cleanup the dead process daemon, and may end up waiting for it go away forever. This is now fixed.

This change fixes an error when using the expression $DATA(global, target) over ECP, and the data in the global has Unicode characters in it. Without this fix, the value of <target> could be set to an invalid string.

This change provides a workaround for an issue in the Xerces XML parser that incorrectly reports namespace prefixes. Details of the issue can be found at the Apache website.

In practice, this is most visible in the %XML.TextReader class where the end element node types have the wrong name. This workaround addresses the issue by internally fixing up the name when the node is accessed.

This change

• fixes %IO.FileStream.Clear() by implementing the methods TruncateAt() and ExternalByteTruncateAt()
• implements OutputToDevice() and fixes CopyFrom() to do more accurate global timeout handling when copying from a sluggish stream
• fixes missing error status arguments in some error messages, and some other error reporting issues

This change adds the aliases 'binary' and 'bin' in addition to 'rawbytes' for the RAW translation table.

It also adds 'default' in addition to 'native' as an alias for the natively active NLS translation table for the current device (as determined currently by

This fix corrects a concurrency error caused by multiple Java threads attempting to validate the cached data for a class while fetching the class definition metadata.

This change implements uptodate class checking in Java Metadata. Java projection and EJB operations now conform to how the class compiler interprets uptodate.

This corrects a problem where the Light C++ Binding incorrectly stored 0 rather than null for null properties of types %Double, %Float, and %Currency.

This change allows a %IO.DeviceStream to properly initialize its LineTerminators shadow variable using $System.Device.GetReadTerminators() rather than just using defaults as it formerly did.

Add OnPreSOAP and OnPostSOAP callbacks to %SOAP.WebService for use by Ensemble. These callbacks are internal and thus do not need to have customer documentation.

More detail may be found in the class documentation.

Change %SOAP.WebService to output %SOAP.Fault properties whose value is $c(0) as an empty string.

Any output written by a web service WebMethod will currently end up between the HTTP headers and the SOAP envelope resulting in a badly formed SOAP message. This change corrects the problem by redirecting any output from the WebMethod to the null device.

A defect has been fixed that caused locks on existing rows to be taken out when enforcing foreign key constraints when the constraint properties have not been modified. Locks are now only taken out if any of the constraint properties is modified.

With this change, after cleanup XMLNew is now supported for customer override.

• The first argument is changed from tree which is the index of the DOM in the global to document which is a %XML.Document instance. The tree may be obtained by
     set tree=document.DocumentId.
• The second argument is renamed from node to nodeId for clarity.
• This change also adds an optional third argument (containerOref) to XMLNew which is the oref of the already instantiated containing object. This allows seeing the object context when overriding XMLNew. The containerOref argument is passed by XMLImport when importing referenced objects as the containing object. The containerOref argument is "" when passed by %XML.Reader for Correlate'd objects as there is no instantiated containing object in this case.
• internal cleanup is done to use %XML.Document instead of %XML.ImportHandler so that a document may always be passed to XMLNew

A %XML.Node instance for navigating the DOM may be obtained by calling the new method of %XML.Document
   set node=document.GetNode(nodeId)

For further information, see documentation included in the method definition in %XML.Adaptor.

During an upgrade, Caché erroneously enabled some services which would have been disabled during the initial install. This has been fixed. Caché only updates the capability properties of these services (That is, types of authentications allowed for the service.)

A permission issue prevented a Caché Terminal console login from writing messages to cconsole.log on Windows Server 2008. The problem was caused by a change in the default ACL on the \intersystems\cachesys\mgr\cconsole.log file on Windows Server 2008. This is now fixed.

This change prevents a user from entering a "" (null) username and password when logging into a Visual Basic Cache Direct application, thereby authenticating as the UnknownUser when Unauthenticated access is not enabled for Cache Direct applications.

This change corrects a defect that incorrectly converted the socket number for a TCP connection when interacting with the OpenVMS socket library. The incorrect conversion resulted adding a delay of 4 seconds to each connection attempt. Attempts to use SSL for the connection would fail.

A change has been made to the SQL filer to help reduce the number of locks acquired for large updates on a table with foreign key constraints.

When a table is updated, a lock is acquired on the referenced table row for every foreign key. In the event the update is rolled back this insures old referenced rows are still valid. This logic used to lock all the rows referenced by foreign keys kicked in even if the foreign key field values did not change.

Now the system will only lock referenced rows where the fkey field(s) have actually changed. This will reduce the number of locks required for this situation in large transactions involving updates where not all fields are updated with new values.

When an outer join is removed, a parse-time structure that refers to it was not cleaned up. This caused an <UNDEFINED> reference when an outer join was removed. It has been corrected.

Uppercase accented characters of the Portuguese language were added to the character set of the %Text.Portuguese class, enabling Portuguese text containing uppercase accented characters to match with unaccented variations of the same word. The characters are: "ÀÁÂÃÇÉÊÍÓÕÔÚÜ".

During the processing of an outer join, new query blocks may be created. While most internal structures are maintained, a few that are initialized earlier by the DISTINCT optimization were not maintained. A code reorganization caused an internal structure to be uninitialized, resulting in an <UNDEFINED> error.

This is now fixed.

A query optimization that flattens a correlated SQL subquery into the containing query block produced incorrect results when the body of the subquery had unique rows, and when the correlated join condition was on a non-unique column.

This is now fixed.

This change corrects a defect where a query sent through the SQL Gateway might not return to the Caché application all the results sets selected by the query.

This corrects a problem where a Macintosh ODBC application that called SQLDriverConnect without using a DSN experienced random core dumps when connecting.

The problem was caused by accessing the ODBC.INI file via SQLGetPrivateProfileString which does not need to be used when not using a DSN to connect to the database.

When calling SQLDriverConnect without specifying a DSN, users were unable to set UNICODE SQLTYPES, STATIC CURSORS, or QUERY TIMEOUT values using the connection string key/value pairs. These values could still be specified via a DSN and its settings.

This is now fixed.

This change corrects an issue with multibyte character streams when characters containing more than one byte occur exactly at the end of an internal buffer byte location that splits the character. This caused a conversion error on character sets like those used in Japan, China, Korea.

In Japanese version (only), when a class is compiled, the output window goes into a recursive loop resizing slightly, which causes continuous repaints. This has been corrected.

When closing multiple objects (for example, via $SYSTEM.OBJ.CloseObjects), under some circumstances the system could get an access violation error.

This has been fixed.

This change corrects a situation where Studio failed while editing DTL (Data Transformation Language) documents.

This change corrects a problem where a MERGE of array nodes into a local variable, V, followed by KILL of all the array nodes, would result in $DATA(V) having a value of 10 or 11 when it should have been 0 or 1.

If a routine is running with breakpoints set, available process memory was gradually lost until unrecoverable <STORE> errors occurred. This change corrects the memory leak.

When changing namespaces, the routine target cache is cleaned up, since it is namespace-specific. This modifies the order of the target cleanup to avoid process routines encountering cache corruption and/or access violations.

If a routine switches its namespace and invokes some other routine(s) and a later invocation finds the original routine in the cache, the references to the routine source may fail (i.e. errors, debugger, or $text). This change preserves the invoking namespace when the routine is invoked from the routine cache.

This change corrects a problem in the algorithm that counts the number of CPUs and cores on Solaris. In particular, when running on some Sun Fire T1000 and T2000 configurations, counting an incorrect number of cores could result in license restrictions.

This change fixes a problem in the UnicodeLittle and UnicodeBig NLS translations that, when used with fixed length READs in TCP devices, could lead to some bytes being dropped in the connection if the translation type were changed on the fly between records.

A problem has been resolved where killing a global inside a transaction could result in a <TOO MANY LONG STRINGS> error even on systems which do not have long strings enabled.

The problem occurs on Unicode installations where the global tree being killed has more than 512 big string data values that consume more than 32767 bytes when stored in the database. Generally in order to consume more than 32767 bytes a data value needs to be fairly long to start with and it needs to contain a mix of characters from different 16-bit character sets. Users can check whether strings take up this much space by examining the # of data blocks used to store the big string values as reported by ^REPAIR. If ^REPAIR reports a length larger than 32767, then this would count as one of the 512 strings that would cause a problem.

A problem was resolved on UNIX systems where CACHETEMP fills the disk and subsequently space is made available so that the delayed writes can complete.

If Caché became idle for 5 minute the control process might incorrectly decide that the write daemon was stuck because the internal counts of how many blocks needed to be written had gotten out of sync with the number of blocks which actually needed to be written.

A longstanding defect affecting AlphaVMS and Alpha/Tru64 platforms has been resolved. It bug involved an internal stack discipline problem which rarely caused problems.

The symptoms of this defect that have been see range from spurious <STRINGSTACK> errors in extrinsic function calls to seemingly-random access violations. The issue was that a post conditional expression which was evaluated as a boolean not would leave an extra argument on the operand stack in the case where it executed the "skip" case.

The WMI server code in Caché was not recognizing SNMP Trap IDs for LicenseExceeded or DCP errors, which could possibly cause events to get stuck in the system queue.

This has been corrected.

cstat has been enhanced to allow it to perform self-diagnostics for many types of system hangs.

When the -S option is selected, cstat first attempts to determine if the system is hung in a way that can be self-diagnosed. If it is hung in that way, then it examines the system state in effort to identify the cause of the hang.

Informational messages are output reporting the progress of the self-diagnosis and any relevant recommendations to the user. Finally, a list of processes is reported which are suspected of causing the hang at that Caché system level. Each process reported may be in one of several possible states. The states reported and their meanings are as follows:

• SUSPECT
  Processes in this state are suspected of causing the hang. These processes should be investigated with debugging tools native to the operating system or dumped with user-mode process dumping tools in order to determine their state.
• EXONERATED
  Processes in this state were suspected of causing the hang, but were determined to be waiting for another process, thus are not likely to be the cause of the hang. Processes in this state typically do not need to be investigated further.
• DEAD
  Processes in this state are suspected of causing the hang and additionally are believed to have exited at the operating system level. Typically no further investigation of these processes can be done.
• LOSTWAKE
  Processes in this state are suspected of causing the hang. Additionally, they are believed to be hibernating and have failed to be awoken by another process. These processes should be investigated with native operating system debugging tools like jobs in the SUSPECT state. It may be possible to resume the system by sending a wakeup to these processes using cstat -P<job#>

As an example a hang with IJULOCK set and an updater waiting for a global buffer would produce self diagnostic output like this:

Beginning hang self-diagnosis
Updates are blocked because ijulock is set
System is waiting for the WD (job 2)
  WD (job 2) has set ijulock and is waiting for updaters to finish
    Updater job 27:
     Job 27 is waiting for bdb #9411
     bdb #9411 is in use by job 13
     Job 13 is suspect
     Job 27 is exonerated
     Job 2 is exonerated

Summary of Job States: {state: [job#:pid[|tid] [...]]}
SUSPECT: 13:5353
EXONERATED: 2:5298 27:5357
DEAD:
LOSTWAKE:

Note that not all types of hangs necessarily result in having any processes requiring further investigation.

In a Caché cluster, the cstat self-diagnostics should be run on all cluster members. It is possible that one cluster member may appear to be hung before the others. Typically, within 10 minutes, the other members become hung because the write daemons time out while trying to synchronize with the other nodes. For this reason, the self-diagnosis may not detect the hang on one or more nodes of the cluster until this timeout has expired.

Additionally, this change adds a new bit 2048 to the cstat -p option. When the 2048 bit is on, the file number and block number of each process's retained buffer is displayed.

There are two general types of tools native to the operating system that can be used to investigate the suspect processes: user-mode process dumping tools and user-mode debuggers. To gather comprehensive information about a suspect process, use a user-mode process dumping tool. The resulting dump file can be very large, but contains the entire state of the suspect process. Other debugging tools can gather key information without needing to produce a large output file. Often using multiple tools in conjunction is desired.

User-mode process dumps by platform:

• Windows:
  The Userdump utility is provided and documented by Microsoft http://support.microsoft.com/kb/241215
• UNIX:
  For Solaris, Linux,and HPUX: use gcore
  For AIX: use gencore
  kill -11 may be used to cause the process to terminate and core (invasive)
• OpenVMS:
  SET PROCESS /DUMP=NOW /ID=

When a job is terminated abnormally, there is a chance that the job could get into a CPU loop. This change prevents that possibility.

This change corrects an error that occurred when a job exhausts its heap memory space while trying to set up its cache of recently-used global subscripts.

This change fixes an access violation that can occur on Caché when using a MERGE command with two local arrays.

This change fixes a possible <STRINGSTACK> error when exporting an object that contains large arrays.

If a cluster slave crashes or is forced down when the master has one or more active ECP connection, cluster recovery may leave the cluster in a partially recovered state and prevent the slaves from restarting and joining the cluster. Slave restart may assume the master is middle of ECP recovery, and wait forever for the master to finish the recovery.

This change corrects the issue.

This affects systems which support clusters (for example, all OpenVMS versions and the Tru64 version with cluster support) regardless of whether the Caché instance is part of a Caché cluster or not.

An error has been fixed where, in very rare circumstances, an attempt to expand the database could get an access violation or could enter an infinite loop syslogging errors during the expansion of a non-cluster mounted database. The error code syslogged is 8484 (0x2124) in module #16.

When system is set to freeze on journal error and journaling fails to start at startup, startup aborts rather than continues on.

The problem present in 5.1 and later releases; it is corrected by this change.

This corrects a situation where a process (synchronous TCOMMIT, ECP daemon, write daemon, etc.) waiting for the journal daemon to commit the journal up to a certain offset could get stuck indefinitely (depending on the journal activity volume on the system).

This occurred in rare circumstance that involved a journal switch before the wait. The problem affected only Caché systems that saw very little journal activity and used small-sized journal files (as a result of either journal file max size being set to very small or journal files being switched frequently by the user).

This change addressed an issue that could cause rollback of a SET whose new and old values are strings of significant lengths (that is, close to 32KB), to fail.

This change corrects the following limitations regarding the affect of TROLLBACK on TCP devices:

• TROLLBACK could clear the user-specified line terminators of current TCP device
• It would suppress the <DISCONNECT> error during rollback only if current device is TCP and has the D mode turned on. It would not suppress the <DISCONNECT> error during rollback
  • if the current device is NOT TCP, or
  • the current device is TCP but doesn't have the D mode turned on

This correction addresses an issue where a change to JournalFilePrefix property made in the configuration parameter file (.cpf) did not take effect even after Caché restart and might get overwritten by subsequent journal switch.

This only involves changes made to the file; changes made via ^JRNOPTS or MgtPortal took affect as expected.

The defect was present in releases 5.2.4 and later.

This corrects a problem that prevented creating the permitted number of databases with an Entree license.

This correction changes the license accounting algorithm so the built-in databases of an Ensemble installation are no longer counted as part of the database limit for E2 (Entree) and E4 (Elite) license keys.

This change fixes a network lock problem where a ECP/DCP client job could hang when it has a node locked and another job locked the parent node of the one it had locked.

This change reworks the prefetching algorithm to improve performance of shadow dejournaling.

This change fixes a transaction error that can occur when a pending transaction does SET or KILL over multiple remote ECP systems. Under these circumstances, the ECP daemon on a remote ECP remote system may fail, or cause the transactions to be out of synch on the ECP server.

This problem only occurred when set/kill is done on two different ECP remote system.

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.

This change makes the MGR directory the assumed default directory in cstat. It is no longer necessary to add "-s." on the command line.

This change modifies the NLS setting in WebLink so that it will always read multipart MIME content (such as uploaded files) in "RAW" mode.

This change was made because it was found that binary data would not upload correctly if the WebLink base NLS setting (as set in the 'NLS_Translation' parameter) was set to a multi-byte character set (e.g. SJIS).

The visible symptom of this was fault was file uploads stalling and timing-out.

The Zen Page class defines a parameter, RESOURCE. This is the name of a resource on which the user must hold USE privilege in order to use the page.

With this change, the RESOURCE parameter can contain a comma-delimited list of resource names. The user must hold USE on at least one of the given resources to use the page.