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: \relnotes\cache\relnotes.htm

This document provides a list of the changes between Caché 2007.1.3 and Caché 2007.1.4.

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 upgrading from a previous version of Caché 2007.1 may continue to use their existing license keys. Customers upgrading from earlier releases should contact their sales representative to arrange for new license 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 evaulating 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 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.

The hash function used to manage global mappings might cause data validation errors in worst case scenarios due to a high number of collisions.

This change installs an improved hashing function and increases the size of the hash buckets.

Previously, the %IsModified method was available only on the server. This correction changes %IsModified() to be available on client-side systems too.

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 alters the permissions on the shared library, /usr/lib/hpux64/dld.so, to allow Caché to access it at startup time.

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.

The ECP server guarantees that database changes are durable before granting a lock. In rare conditions, the validation did not ignore dead ECP server sessions properly.

This change corrects that behavior. Now, in the worst case, a database server with dead ECP server sessions may end up in an unexpectedly long wait.

Remote de-locks originated by the cleanup of failed jobs may itself fail and leave the ECP client in an unexpected state. This has been corrected.

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 fixes an error that occurs when ECP clients execute $DATA() with 2 arguments to get value of the global node. If the global contains a string longer than 4000 characters, the system internal argument stack could become misaligned causing various error afterwards.

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 endelement node types have the wrong name. This workaround addresses the issue by internally fixing up the name when the node is accessed.

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 corrects a problem where the Light C++ Binding incorrectly stored 0 rather than null for null properties of types %Double, %Float, and %Currency.

This corrects a problem where the use of blocking io on some UNIX platforms would cause problems when the Xerces parser tried to access data over a network (such as trying to get the document DTD).

This corrects an issue where a UNIX user could bypass privilege checking and become a member of the "cacheusr" group. The permissions on Caché have been changed to -rwx--x---.

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.

A change has been made to the SQL filer to help reduce the number of locks acquired for large updates on tables 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 previously locked all the rows referenced by foreign keys, if the foreign key field values did not change.

Now the system will only lock referenced rows where the foreign key 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.

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.

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

This change fixes a <NOLINE> error that occurred when a label with Unicode characters was used.

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 corrects a rare error where, if a journal switch occurred with no pending journal data to write, the journal synchronization position could be set to the wrong value.

This change fixes an error in the 4 argument version of $PIECE() on Itanium platforms. The problem would manifest itself only when:

• the delimiter (2nd argument) was a single character literal,
• the initial and ending pieces (3rd and 4th arguments) were not literals,
• the initial piece evaluated to zero.

Before this fix, on Itanium platforms the following would return the null string:

USER>Set data="ABC^XYZ^123",x=0,y=1
USER>Write $P(data,"^",x,y)
ABC

This changes corrects a situation where, if the write daemon could not process a directory or a database lock request within its preset timeout, the operation was treated as a success. It will now be considered a failure.

Attempts to create a database when the write daemon is unable to respond to lock requests for 60 seconds or longer will now fail. Previously they would succeed but this would cause errors if two systems tried to create a database in the same directory at the same time.

A situation which could lead to priority inversion hangs on AIX platforms has been resolved. This appeared on systems which use ^%PRIO (or other mechanism) to adjust the process priority. A symptom of the error is that the system would appear to be hung yet consuming lots of CPU time and cstat would show several (20 or more) jobs in the LOCK module, not in a WAIT state.

The following changes have been made to improve cluster recovery:

• The maximum path length for Caché databases and other files has been decreased from the prior limit of 232 characters to 227. For a database, this refers to just the directory portion of the path. For other files, it can include the final file name. As a general rule, the path name of the root (or home) directory for a Caché instance should be approximately 195 characters to allow for the subdirectories and databases within its structure.
• A long standing cluster failover problem has been resolved where the journal restore was not correctly synchronized across the cluster members. If a cluster member failed while it was in the process of writing to the WIJ file, its journal would be restored from an earlier point in time (one write cycle) than the other cluster members. If, during the prior write cycle, the other cluster members have sets or kills which came after the items restored from the failed system, these would be missing from the database after cluster recovery completed.

This change fixes the formatting of ":D" flag for dead jobs in the cstat PIDTAB display by placing the marker in its proper column.

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=

The cstat problem analysis program should be run as administrator on Windows Vista when the Caché Service is running as SYSTEM. If it is not, the status of processes in the PID table cannot be determined.

With this change, Caché will print a warning to the user when this situation occurs.

A problem is corrected that caused job servers to exit with an access violation in Caché.

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 situation where Caché shutdown on OpenVMS could hang because a job's terminal output was suspended by Control-S.

This change extends the allowed length of an OpenVMS terminal device name from 7 to 10 characters.

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

During an upgrade, Caché would erroneously enable some services that would have been disabled during the initial install. This has been fixed; Caché only updates the capability properties of these services (i.e. types of authentication allowed for the service.)

This change makes Backup.General.ExternalThaw() return OK, if no prior Backup.General.ExternalFreeze() has been called.

OpenVMS could close a Caché terminal session because of inactivity/timeout. This change now properly handles that situation.

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.

This change fixes a cluster journal sequence number out of synch with ECP cluster connection.

This change addresses an issue where a manually initiated journal switch could block journal daemon from rolling to a new journal file.

When a Caché system is configured to freeze on journal errors, the system could be unfrozen by a subsequent successful journal switch. This is usually a desirable behavior unless the journal error resulted in the loss of journal data, in which case, user intervention is necessary to bring the system back to an appropriate state. Until then, the system should remain in the frozen state despite journal switch attempts.

This change enforces the above behavior in the event of possible loss of journal data resulting from a fatal error in journal switch. If such an error occurs, the operator should see a message like the following in cconsole.log:

An irreversible error occurred in writing <xxx> to journal file.
Any pending journal data is lost.
You should restart the system and back up databases immediately.

Prior to this change, journal switch would get a <SYSTEM> error.

This change addresses a performance issue in scanning a journal file for open transactions in journal recovery (at Caché startup, cluster failover, and so on). With this change, the time spent in the scanning operation has been cut by half.

The phrases "primary/secondary journal directory" and "current/alternate journal directory" are not interchangeable; there are subtle difference between them.

Primary and secondary journal directories are persistent journal properties that are created and modified by the user only; current and alternate journal directories are transient journal properties that are used by journal daemon. The current journal directory, by definition, is where current (i.e., the latest) journal file is located. The alternate journal directory is "the other" directory that journal files should go to when a problem with current directory arises.

Journaling always starts in the primary directory. The primary directory is the current directory and the secondary, the alternate. That remains the case until journaling encounters an error (for example, disk full) in current (primary) directory and fails over to the alternate (secondary) directory. At this point the secondary directory becomes current directory and the primary, the alternate.

Journaling will alternate between primary and secondary directories upon an I/O error in current journal directory.

cstat -j1 shows the current and alternate journal directories. When the user creates or edits journal directory properties (via ^JRNOPTS or MgtPortal), any default values given for these properties affect the primary and secondary directories.

Prior to this change, after the journal failover, a journal switch performed by the user (via GUI or CHUI or API such as ^JRNSWTCH) or task manager (at midnight by default) caused the alternate directory to be set to the current directory and, as a result, there would be no alternate directory for journaling to fail back to if there should be a problem with the current directory.

All journal switches are still logged in cconsole.log.

This change corrects an issue that occurs when a system is set to freeze on journal error and journaling fails to start at startup. Prior to this change startup continued; with the change it now aborts.

This correction addresses an issue where, in certain circumstances, a $BITSET occurring in a transaction would be journaled with incorrect old value and old bit length. A rollback of this $BITSET would restore incorrect data to the database.

This change corrects an issue with shadowing a Windows source that could cause shadowing to stall if the source journal file path contains upper-cased characters. On the Windows source side, one may see errors like the following in cconsole.log (and shadow source error log):

NEXTJRN: -98,'D:\CacheSys\Mgr\Journal\20071221.003' appears to be
the next file of 'D:\CacheSys\Mgr\Journal\20071221.002' but
contains a pointer to a different previous file from
'D:\CacheSys\Mgr\Journal\20071221.002' and thus couldn't be the next file

This change corrects a potential journal performance issue on AIX 6 systems where Caché was unable to determine the type of the filesystem hosting the journal files. As a result, Caché was unable to use the optimal settings for journal I/O performance, even if the underlying filesystem was mounted with the recommended optionns (for example, cio for JFS2).

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 fixes an error in Caché cluster shutdown when there are three or more cluster nodes in operation. In some cases, when the cluster master shut down, the new master node could get a corrupted lock table.

When a multi-item LOCK command contains duplicate items, for example,

L (^a,^b,^c,^b))

and those locks are mapped to remote ECP server, there is a possibility that the ECP daemon on the client side could get an access violation error, < ACCVIO>.

This change fixes a problem on an ECP/DCP network which could leave a shared mode lock on the ECP/DCP server while there is no lock entry in client node.

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 corrects an issue that caused a spurious error to be logged in cconsole.log in place of a real error (or warning) message from shadow or source server.

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

On OpenVMS, sometimes the process that shuts down Caché (executing cforce()) hangs forever.

This change prevents that situation.

In a TCP server process whose current (TCP) device has disconnect detection (the "D mode") turned on, TROLLBACK might fail after the TCP client disconnects, leaving databases in an uncertain state. This change allows TROLLBACK to finish regardless of the state of client connection.

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.

This change disables the quick integrity checking on globals restored from the WIJ. This could take a long time when the global happened to contain large amounts of data.

This change fixes a problem in Backup.General.ExternalThaw for OpenVMS. When it was called from a command line, the process would hang. This is not a problem on Windows or UNIX.

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

This change correctly associates the "wdphase" column in mgstat with the underlying data value. It also adds columns for "wdpass", "ijucnt" and "ijulock".