This document contains several sections:

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

The following regressions in functionality are known to exist in this release and may adversely affect applications. If you need an immediate correction for any of these defects, please contact the InterSystems Worldwide Response Center.

They will be fixed in a future maintenance release.

• A problem exists in Caché 5.0.16 when calling Stored Procedures. If an application using ODBC or JDBC issues a Close Statement call, Caché incorrectly removes all server side information about the statement. If the application tries to execute the same Stored Procedure a second time, Caché will return an <UNDEFINED> error from the server.

  There is no workaround for this error.
  
  

• A defect has been identified that was introduced in Caché 5.0.11. If you use the follow SQL syntax

  SELECT PatID, Name, SSN
  INTO :array()
  FROM Sample.Patient
  

  where PatID was defined as the IDKey, the node where the value of PatID is stored could change. In releases before 5.0.11, you would have an array that looked like:

  array(2)=12345
  array(3)="Doe,John"
  array(4)="111223333"

  while in Caché 5.0.11 and later the array would look like:

  array(1)=12345
  array(3)="Doe,John"
  array(4)="111223333"

  The value of PatID had moved from array(2) to array(1).

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.

Prior to this change, it was possible for cstat to show a dead process as alive (that is, no "D" indicator in the pid table display) if the process Id had been reused by the operating system for a new process.

Cstat now performs further tests to insure that the process is running cache.exe from the configuration's bin directory before considering it a valid Caché process in the current configuration.

This change corrects a situation where, under certain circumstances, an attempt to send a broadcast message to all mailboxes could result in an access violation error.

A correction has been made for the situation where an object ID based on a simple integer property might be inappropriately detected as modified when set to itself. For example, 'set obj.Prop=6' would report the object as modified when the original value of obj.Prop had previously been 6.

Prior to this change, if you had a class on your system, and then an attempt to import another version of that class failed, Caché would delete the existing class. Now it correctly leaves the existing class present if there during import.

A prior change discarded the value of the EXTENTSIZE parameter when loading a class from XML or CDL. This change reverses that. If you are replacing an existing class with XML or CDL that does NOT contain EXTENTSIZE the EXTENTSIZE of the replaced class will be retained.

A new configuration option now makes it possible to validate system-assigned ID values for new instances of objects. The option is activated by

SET ^%SYS("dbms","validate system-assigned id") = 1

Classes using default storage and system-assigned IDs do not normally check for the existence of an object with the newly assigned ID value. That check is, under normal circumstances, not necessary as the global reference used for the system ID counter is updated each time a new object is inserted into the extent. However, in very rare cases, it is possible for this counter to contain an incorrect value. This can happen if the user modifies the value manually; if objects are inserted into the extent without using the object or SQL filer; or system recovery efforts modify this value and are subject to errors.

By setting the configuration option, the class compiler will generate a uniqueness check on insert for the ID value. If at runtime the uniqueness constraint fails, an error, IDKeyCounterNotValid, will be returned to the caller and a message will be written to the console log. Each failure will also cause the ID counter to be incremented so it is possible that the problem will correct itself over time. It is important to review the console log when this error is reported .

In certain deeply nested object models, it is possible that the underlying error message will not be reported. Rather, a cyclical dependency error could be reported from %Save(). This is not the usual case but, when a cyclical dependency error is reported, one possible cause might be the IDKeyCounterNotValid condition.

When an IDKeyCounterNotValid error message is reported it will be necessary to bring the ID counter back into sync with the data. It is the responsibility of the application developer or administrator to determine how the counter became invalid (manually set by a user or by code not using object encapsulation, bad recovery of a journal file, disk failure, etc.). The correction for the error condition depends on how the data and counter were caused to be out of sync.

During SQL INSERT, if the SQL filer needs to start a transaction, the transaction will now start earlier in the filer than it used to. The transaction will now start before any default values are assigned, including the $Increment(^glo) default value of the RowID field (if applicable). This allows the $Increment of any globals in default values to be recorded in the journal file.

This is the SQL counterpart to DLP1319. Please see that item for details.

The condition will be reported as an error code of -119.

The default file parameters when sending the output of %r to a file are now "WNS".

A problem has been corrected where under certain rare circumstances the same cached query routine could be associated with and invoked by two different SQL statements.

An error has been fixed where certain queries could return the wrong answer. The type of query affected contains these phrases:

• col1 IN (?,?,...)
• col2 IN (?,?,...)

and also the condition, col1 = col2, is true.

The problem may occur whether col1 and col2 come from the same table or different tables. Also, the IN condition could also be "(col1=? or col1=? or ...)" and similarly for col2.

Other conditions can occur before or after these, or in between them. However, if the join condition occurs before at least one of the IN conditions, the problem doesn't happen.

The Studio COS parser now colors legacy list functions: $ZLENGTH, $ZLIST, $ZELEMENT, and $ZSUBLIST.

Added Tools->Source Control->Add to the Source Control menu item which will cause to add the active document to source control.

A previous change introduced support for the new #[]# syntax, which allows ObjectScript commands to be embedded. This adds it to the &html(...) processor.

In prior versions, importing a routine from Studio was not working correctly because Studio lost the extension type of the item it had imported. The item would be imported correctly but it would not get compiled. This is now fixed.

When an attempt to lock an item calls the studio hook in the 'GetStatus' method, Caché now uses more information in returning an error code to the caller.

Prior to this, Caché would always report that the item was not checked out of source control. Now it only reports this is if the 'isinsourcecontrol' argument is true; otherwise it just reports that this item is not editable.

Also if a username is returned from the GetStatus call, this is displayed as part of the error text.

This change fixes a problem importing and compiling a BAS routine. It also improves support for importing large numbers of items into Studio.

The Studio Open dialog displays items sorted case insensitively. When a user opens up a namespace with a huge number of routines, Studio must scan the whole list to find the correct order to place these routines in. This can cause delays when there are hundreds of thousands of routines in a namespace. In order to allow these namespaces to be usable you can now set a flag:

Set ^SYS("Studio","CaseInsensitive")=1

This will force Studio in this namespace to work in a case insensitive manner which allows it to list the items as they are found rather than having to sort them all first. The routines are all listed at the root level rather than the standard approach which is the list routines from a class compile along with that class.

This change modifies the import/export functions so that they will also call the source control hooks when a user imports items. This permits the source control hooks to export them to a source control system.

When a process has set $HALT, it should be effective only for normal process termination. This fix corrects a problem that caused the system to attempt to locate and run the $HALT routine in situations such as RESJOB and system errors when the process should be halted immediately without attempting the $HALT.

The %STACK debugger utility could display unprintable characters if the routine object code is modified while the routine is being debugged. This is no longer the case.

If a routine sets $HALT to an entry point in a different routine, and the halt trap returns back to the original routine because of a QUIT command or a trapped error, the original routine context is not restored correctly. Prior to this change, this situation could cause invalid execution results or memory access violations.

A memory access violation could occur during error processing if there was an unexpected additional error while trying to read the routine source. With this fix, the system will continue without providing source information about the original error.

This changes corrects a rare problem where Caché may get suspended in a system function while holding database blocks under a lock.

A problem which could cause an exception (core file, dump file, etc) where an <EDITED> error should have been generated has been resolved. This involved cases where the program is returning after evaluating the result of an indirection that involved invoking another routine and the routine it is returning to has been recompiled. An example of where this could occur is a reference of the form:

 Set str="name($$ent(123))"
 Set x=@str

where $$ent goes off to another routine which causes the calling routine to be recompiled.

This fixes possible access violations during shutdown in situations where the process table has been expanding. This is on Windows only.

This correct a problem in $zobjexport with exporting long strings in a Unicode encoding.

New $System.Device class methods have been implemented. Descriptions are available in the %SYSTEM package class documentation. In summary:

• GetRightMargin() - returns the right margin setting for the current device. This only applies to terminals.
  
  
• GetReadTerminators() - returns the read terminator string for the current device. Does not apply to some devices.
  
  
• GetMnemonicRoutine() - returns the write mnemonic space routine name for the current device.
  
  
• GetMnemonicDirectory() - returns the write mnemonic space routine directory for the current device.
  
  
• GetClearScreen() - returns the Clear Screen (Form Feed) string for the process principal device.
  
  
• GetBackSpace() returns the Back Space string for the process principal device.<.LI>

A problem with the Caché node name recognition has been fixed. This only affected UNIX/Linux systems which connect to a DHCP name server. After an abnormal system shutdown, Caché startup could believe the instance was still in use by another node.

Correct utilization of the unique node name mechanism requires that the 'ccontrol nodename <name>' command be used to assign a unique name to the local node/machine, and that no instance of Caché should be active when the node name is assigned or modified.

Allow users to select "0" process count for less overhead in collection.

This change corrects issues with interactions between ^PATROL and ^PERFMON (MONITOR), and also removes unnecessary overhead (STATISTICS resource locking) when running PATROL.

This change adds ECP operations to the MONITOR (i.e. ^PERFMON and $System.Monitor) network statistics.

This change displays the correct client name for server statistics in MONITOR. ECP shows the name of client, as opposed to the address for DCP statistics.

This change corrects network MONITOR statistics, including proper display of ECP and DCP node names.

This change adds all network related counters (total requests, cache hits/misses for client, etc.) to the ECP MONITOR metrics. They now parallel DCP metrics.

This corrects a situation where, on Windows XP after the Control Process has crashed, the system can not be cleanly halted, even by cforce.

A process performing %SS or any mailbox send may hang forever if the destination process has gotten in a state where the mailbox lock is permanently held. With this change, the calling process will exit the mailbox code after trying and failing to get the mailbox lock 10 times (total wait of 1 second).

This corrects a situation where, if you change the priority of one process other than the current one, using $SYSTEM.Util.SetPrio(prio, processid), then all process priorities may be changed by the same amount. This will not happen if the current process priority is changed, using ^PRIO or $system.Util.SetPrio(n).

This corrects a problem where a fault could occur during use of the $VIEW function to view data in the process partition.

This change adds a new daemon called the 'Clean Daemon' (CLNDMN). This daemon wakes up every 10 minutes to scan the system pid table to see if any dead jobs are pending. It will reclaim any dead job pid slot it finds. This daemon takes over the duty used to be done by Control Daemon.

This change fixes a potential problem on 64-bit platforms where trying to load a user DLL or shared library via $ZF(-4)/$ZF(-5) might result in an error depending on previous memory allocations.

This change adds an option to remove default directories (for searching for journal files to dejournal) when setting up noncluster journal restore. (The mechanism/interface for locating journal files in cluster journal restore is different.)

Prior to this change, the prompt for specifying journal directories along its help text looked like this:

Files to dejournal will be looked for in:
d:\Cache51\mgr\journal\

Specify other directories to search: <return when done>

There was no way to remove "d:\cache51\mgr\journal\" from the list of directories to search for journal files.

With this change, the prompt looks like this:

Files to dejournal will be looked for in:
     d:\cache51\mgr\journal\
in addition to any directories you are going to specify below, UNLESS
you enter a minus sign ('-' without quotes) at the prompt below,
in which case ONLY directories given subsequently will be searched

Directory to search: <return when done> -
     [Directory search list is emptied]
Directory to search: <return when done> d:\cache51\mgr\journal\
Directory to search: <return when done>
Here is a list of directories in the order they will be searched for files:
     d:\cache51\mgr\journal\

Note that there must be at least one entry on the directory search list or Caché will issue a warning:

** WARNING ** Directory search list must NOT be empty

and the setup will keep prompting.

Directory to search: <return when done>

unless one hits Ctrl-C to abort journal restore.

A new sequential file OPEN option has been added, to provide exclusive write access to a file. This provides a way of blocking simultaneous updates of a given file by various processes. The "L" option may be combined with "R" and "W" options as follows:

• "WL" - exclusive/write mode
• "RL" - shared/read mode
• "WRL" - exclusive read and write mode

Under Caché/Windows, shared access for read and write is the default, so "RL" does not alter the behavior. Exclusive mode interacts with file accesses by non-Caché applications on the system.

Under Caché/UNIX, the share mode mechanism employs file locks, so "RL" is necessary to coordinate with "WL" usages. If the "L" option is not specified on OPEN, file locking neither affects nor is affected by processes that do not employ it.

Under Caché/OpenVMS, files opened for write access use exclusive mode (no sharing), and those opened for read use shared GET mode. This behavior is not affected by the current change, hence the "L" option is not used.

To avoid accidental deletion of a sequential file due to incorrect keyword syntax specification in the OPEN command, this change nows causes a syntax error to be reported if there is a "/" (slash) anywhere in the mode parameter string (the first positional device parameter).

In previous releases, if one of the extensions after the first volume of a multi-volume DB fails to mount during startup, then those extensions that successfully mounted before the failure are not cleared, and are assigned instead to the next DB in the list of databases in the config file.

For example, suppose there are two databases, "Multi" and "Single". Multi has primary and 3 extensions stored in these files:

• c:\cache5012\mgr\
• c:\cache5012\mgr\v2
• c:\cache5012\mgr\v3
• c:\v4

Further suppose that the cache.ext in c:\v4 is deleted and Caché is started.

In this case, the DB Multi is not mounted because extension v4 fails to mount. But the DB Single will be started as a multi-volume DB, with extensions in

• c:\cache5012\mgr\v2
  
  and
  
  
• c:\cache5012\mgr\v3

An error was corrected in %Buttons where the cstat output and/or cconsole.log files were being deleted even if they were not copied to the HTML output file.

%Buttons does not include these two files if they are larger than 5MB or if appending either one of them will make the HTML output file larger than 5MB. In this case, a pointer to the original location of the cstat and/or cconsole.log is written to the HTML file.

In calculating free space, this change causes Caché to examine secondary map blocks first to determine which maps are full maps. This avoids the need to read in those blocks for maps that are known to be full.

This change allows $$RebuildIndex^%R(impliednamespacereference) to work correctly. Prior to this, it would return an error.

This changes corrects errors in looking at the bitmaps on big-endian databases.

With this change, WebLink is now fully compliant with HTTP v1.1 response headers.

In particular it is possible to take advantage of v1.1 KeepAlive connectivity in WebLink applications. Unlike HTTP v1.0, KeepAlive connectivity is 'on' by default in v1.1. If KeepAlive connectivity is not required the 'Connection: close' header directive must be added. For example:

HTTP/1.1 200 OK
Content-type: text/html
Connection: close

If KeepAlive is used, a 'content length' header field must be supplied. If the response header generated by the application indicates that KeepAlive should be used but does not contain a 'content length', WebLink will automatically buffer the response content, determine its size, and insert the length header before dispatching the whole response to the client.

This change allows HTTP 'Keep-Alive' connectivity to be used in WebLink applications, for example,

Minimal HTTP/1.0 response header without keep-alive:

HTTP/1.0 200 OK
Content-Type: text/html

Minimal HTTP/1.0 response header with keep-alive:

HTTP/1.0 200 OK
Content-Type: text/html
Connection: keep-alive

Minimal HTTP/1.1 response header without keep-alive:

HTTP/1.1 200 OK
Content-Type: text/html
Connection: close

Minimal HTTP/1.1 response header with keep-alive:

HTTP/1.1 200 OK
Content-Type: text/html

Note that the default behavior is for keep-alive to be 'off' in HTTP v 1.0 but 'on' for HTTP v1.1.

When Keep-Alive connectivity is used it is necessary to include a 'Content-Length' response header. If the application does not include this field in a response for which keep-alive is required (as is the case in the examples above), WebLink will cache the response data to determine its size and add the length field before dispatching the final response headers. However, better performance will be achieved if the application is able to add this field. For example:

HTTP/1.1 200 OK
Content-Type: text/html
Content-Length: 123