There is no section for 5.0.6.

This section provides a listing of changes between Caché 5.0.10 and Caché 5.0.11.

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.

A new CSP parameter, Hyperevent Implementation, has been added.

New CSP Applications will be created with the Hyperevent Implementation parameter equal to "Select on server". On upgrade, existing CSP Applications whose Hyperevent Implementation parameter is missing will have it created with the value "Use Java applet".

This change introduces the optional use of the XMLHttpRequest Javascript object to implement #server. The actual method used to implement #server is determined by a new Configuration Manager parameter for CSP applications, called "Hyperevent Implementation". "Hyperevent Implementation" has four possible values that determine how #server is implemented:

• Use Java applet for #server
• Use XMLHttpRequest Javascript object for #server
• Select implementation using browser Javascript
• Select implemetation using HTTP_USER_AGENT on server

where:

• "Select on server" means CSP pages that use #server will include either an applet tag OR Javascript to use the XMLHttpRequest object; the selection will depend on the server HTTP_USER_AGENT CGI variable. This option, "Select on server", is the default.
  
  
• "Use Java applet" states CSP pages using #server will always supply an applet tag identifying the CSP Java broker applet; #server will always use this applet.
  
  
• "Use XMLHttpRequest object" indicates CSP pages that use #server will always include Javascript that uses the XMLHttpRequest object to implement #server.
  
  
• "Select in browser" means CSP pages that use #server will include BOTH an applet tag and Javascript to use XMLHttpRequest. The method used will be chosen based on the availability of the XMLHttpRequest object to the Javascript code in the browser.

In &html 3.2 compatibility mode, CSP will ignore < or > within <% ... %>. This is meant to handle constructs like

&html< <% w "first->last" %> >

which are encountered in Cache 3.2 WebLink applications.

This change improves the validation of the session token's fields after a failover (or web server/NSD restart) situation.

Previously, a request could be directed to an incorrect (or unexpected) Caché server after a web server/NSD restart. This issue could also result in requests in Virtual Host configurations being directed to incorrect (or unexpected) Caché servers. The term, 'unexpected' Caché servers, means a Caché server configured as an alternative to the main (or default) server).

Editing the Gateway's server and/or application configuration on web server/NSD startup would make problems of this nature more likely to occur.

This change corrects an issue in the transmission of form data in which CSP* variables (e.g. CSPToken) were placed at the end of a form posting more than 8K of data. The problem manifested itself as such forms failing validation checks on submission ('Illegal CSP Request' errors).

This change ensures that Gateway error messages sent in response to SOAP-based requests are formatted as SOAP fault messages (as opposed to HTML).

For example, if the Gateway is unable to connect to the Caché server for the purpose of servicing a SOAP request, the following SOAP fault will be returned:

HTTP/1.1 200 OK
Content-type: text/xml
Connection: close
Expires: Thu, 29 Oct 1998 17:04:19 GMT
Cache-Control: no-cache
Pragma: no-cache

<?xml version='1.0' encoding='UTF-8' standalone='no' ?>
<SOAP-ENV:Envelope
   xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
   xmlns:s='http://www.w3.org/2001/XMLSchema'
   SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'>
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>CSP Gateway Error (version:5.1.0.423.0 build:663.775)</faultstring>
<detail>
<error xmlns='http://tempuri.org' >
<special>
Server Availability Error
</special>
<text>
Server is currently unavailable
</text>
</error>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

It should be noted that this facility can only work if the Gateway can identify the incoming HTTP request as a SOAP-based request for information. This may not be possible if a request for a SOAP-based response is made via the HTTP GET method. It is, however, recommended that requests for SOAP-based services be made through HTTP POST (or related) methods. If the HTTP POST method is used, the Gateway can identify SOAP-based requests by the associated content type.

A message is displayed when a HyperEvent method's argument length is > 32000 characters. With this change, the argument will not be displayed since it detracts from the clarity of the error message.

This changes corrects a situation where the packet-driver for Windows 2000/XP and 2003 Server did not properly report all the network cards it had bound to.

When $ORDER didn't find an answer across ECP, it sometimes left the global vector naked reference invalid. This caused a subsequent $ZREFERENCE to fail with wide character error.

This change prevents that from happening.

Prior to this change, the Caché packet driver would cause a fatal Windows error when invoked on systems containing more the two processors. This no longer happens.

This change corrects a problem where attempting to define an index involving the %ID token would fail.

The maximum routine size has been changed from 40k to 32k. This will result in smaller OBJ routines and, for large source files, more routines generated. This adjustment was necessary in order to load files with methods with more than 32k of source code.

This corrects an oversight where the status code from the compile was only being returned if the compiler flag to display errors was set. Now the status code is always returned.

If you write a generator method the compiler was not making sure that any variables you create in this generator do not end up in the partition. Now an exclusive new is done before running generators for a class to prevent this possibility.

If you open an existing file stream stored in a directory other than the current default directory (the one with the CACHE.DAT file in it for this namespace) then the MoveToEnd method would fail to work correctly. This change corrects the problem.

The default global name generator used by the default storage class has been improved.

• First, the package definition 'package prefix' is retrieved. If it is empty then the package name is used for the package prefix. A default global name is generated by taking the package prefix, class name and adding a suffix character.

  If the resulting string is less than the maximum global name length then it is used.
  
  

• Otherwise, the class name is hashed into a string that is one half the maximum global name length. The package prefix is hashed into a string that is one character shorter (to allow for a '.') than the remaining maximum global name length.

This change corrects an issue in the class compiler. In constructing the initial expression for stream properties, it did not properly handle values that contained quote characters. This has been corrected.

This change corrects a problem in the FindAt method in %Stream.Object. The method would not calculate the correct position when it had read in two or more 20,000-byte chunks of data.

If the global ^%SYS("TempDir") is defined, this is now used as the temporary location for stream data.

If this is not defined, then Caché will use "" as the directory. This puts the stream data in the current directory which is normally the location of the CACHE.DAT file.

This change introduces a new class %GTWConnection. Its %OnClose method disconnects an active connection if the gateway is terminated.

The Caché ODBC driver has been externally thread-safe for quite some time now. For example, if two threads were simultaneously operating on the same statement object, Caché ODBC driver guarantees there will be no conflicts.

This change fixes the instances internally where there were thread-related issues that could result in "message sequence errors".

This change improves error handling in cases where ODBC terminates abnormally and error recovery actions by the application override the default actions taken by the operating system.

A problem has been fixed in ODBC/JDBC. The first time a query is Prepared, if

• a Cached Query exists for the statement, and
  
  
• the user is privileged for the statement,

an <UNKNOWN ERR> would get passed back to the client under some conditions.

This changes corrects a situation where a decimal literal in the first column of a SELECT statement, for example,

SELECT 0.1, F1  FROM TESTCASE1234

would prevent parameter replacements from being made.

This change corrects an error that caused compile-time <UNDEFINED> errors in SELECT statements with OUTER JOINs when certain CacheSqlStorage "general mapping" features were used.

This change optimizes streamless (sub)expressions (i.e. expressions without any fields) in SELECTs and a few other places by evaluating them only once at the beginning of the query.

This change corrects an error in optimization where certain query conditions were "pushed down" and applied within the evaluation of a view that has a GROUP BY clause. This occurred in cases where the condition included a unary operator or a {d ...} date expression.

This change remedies a situation which caused incorrect processing or a likely run-time <UNDEFINED> error when

• there were a large (more than 250) number of expressions, and
  
  
• these expressions had to be evaluated at the beginning of the query.

An example of this is an IN condition on a collated field with more than 250 constants.

Caché SQL now supports a datepart of "ms" or "milliseconds" for the DATEADD and DATEDIFF functions.

We also now support SQL_TSI_FRAC_SECOND for the ODBC Scalar functions

• {fn TIMESTAMPADD()},
  
  
• {fn TIMESTAMPDIFF()}.

This corrects an instance where a query can return incorrect results when

• there is a WHERE clause condition selecting attribute values less than a negative value, for example, f < -5,
  
  
• there is an index on that column, and
  
  
• some of the rows are null in that column.

An error has been corrected where a field value that used the SPACE collation compared against NULL was not returning the correct results. For example, a query like:

SELECT count(*) FROM SQLUser.MyTable WHERE MyField IS NULL

return the incorrect results if MyField's collation was SPACE.

This change adds a new feature. Previously, you could never use <viewcolumn>->x syntax. Now, if view column maps to a base table column that supports arrow syntax, the view column will support it as well. Note that arrow syntax referring to a child table from a parent table is still not supported for views because there is no way to specify whether the child table pseudo column is 'selected' by the view. In addition, this new feature will not work for views defined by SELECT DISTINCT, or aggregated views, or UNION views.

Another new feature is that special columns %ID, %CLASSNAME, %TABLENAME now work with arrow syntax. Thus ref->%CLASSNAME will return the name of the referenced class.

Addressed a problem where $SORTEND may generate a <STRINGSTACK> error when there are many SETs (hundreds of thousands of, or even millions) to sort.

Under some circumstances $SORTEND would generate an access violation or <SYSTEM> error.

A problem has been resolved which could cause access violations on OpenVMS from certain block split operations in 8KB databases when more than 2GB of global buffers have been allocated.

A small problem in the internal mailbox code on VMS systems has been corrected. This could have caused corruption of data being returned on Caché's internal string stack in certain rare circumstances, particularly during reads from TCP/IP devices.

Under some circumstances, when a sufficient number of KILLs have been done to reduce the number of global directory blocks needed by 1, the consolidation of directory blocks can cause a <DATABASE> error during dismount.

ECP is more likely to provoke this rare problem but it can occur without any ECP.

This change rectifies that possibility.

This change addresses a situation with journal restore when using a journal filter where SETs may not get applied to the destination databases.

the wait time in Caché backup, and other places where the system waits for quiescence, has been extended. If, after the timeout period has expired, the system is quiet except for the write daemon, the timeout is extended for up to 2 minutes to wait for the write daemon to finish its current pass.

Previously on systems where the write daemon routinely took more than the allowed timeout, a backup might never succeed.

This change corrects a situation where Wndows startup would take a long time whenever

• the Caché configuration was marked as automatically starting service in the system, and
  
  
• a recent (i.e. after TTS031) packet-driver had been installed.

^%GCMP didn't work across ECP. It was looking for a legacy net connection id

NET(1,"ACTIVE","CPNU",<connection name>)

which wasn't set.

This change corrects a problem where globals in the ISM pre-6.2 collation that had a particular data pattern (final subscript of any global node ending with $C(1)) could cause problems. The particular symptom that was reported is a failure to convert the node properly when using GBLOCKCOPY.

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:

• High Availability Guide
  • Reorganized the material and added a chapter called "Cluster Journaling" which covers cluster restore, recovery, and shadowing
  • Reorganized ECP information by removing a large amount of material from the GHA ECP chapter and moving it to the Distributed Data Management book, including a new appendix of guarantees and limitations
  
  
• Supported Platforms and Windows Installation
  • Added SP2 for XP
  
  
• Cache ObjectScript Reference
  • Added time formats 5, 6, 7, & 8 to $ZDATETIME, $ZDATETIMEH
  • Rewrote $ZTIMESTAMP special variable for local time variants (Daylight Savings, etc.) and Time/Date interactions.
  • Added class info section to $JOB special variable
  
  
• Cache SQL Reference
  • Rewrote and expanded CREATE TRIGGER, DROP TRIGGER, Triggered Action pages
  • Rewrote and expanded UNION page
  • Rewrote Identifiers page, with updated character & length restrictions
  • Added naming conventions/name conversions sections to CREATE TABLE (table name & field name), CREATE VIEW, CREATE INDEX, CREATE TRIGGER
  • In SELECT specified naming conventions for AS clause values
  • Added features to GRANT command
  • Added note to SELECT on use of asterisk option
  • Expanded the material on the UPDATE command, the Symbols table, and the SQLCODE error code list
  • Documented schema names, package names, and Configuration Manager schema default in CREATE TABLE and CREATE VIEW.
  • Completely rewrote Table page, renamed as Table Reference with new syntax and description.
  • Improved the clarity of the examples illustrating the difference between the HAVING and WHERE clauses.
  
  
• Cache Class Reference
  • Corrected EXTENTQUERYSIZE and EXTENTSIZE
  
  
• Organizational Changes
  • Re-ordered the sequence of book collections on the documentation home page and also re-ordered the sequence of books with each group. Prior to this, they had been sorted alphabetically; now they appear with the more important topics first.
  • Changed the title of the short articles section from "Caché Knowledge Base" to "Technical Articles" to make it more explanatory.
  • Reworded the page headers to say "InterSystems Online Documentation" instead of "Caché Online Documentation".
  • Added a new home page item called "Documentation List" which provides a list of the titles for all the books and all technical articles sorted alphabetically.

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

This section provides a listing of changes between Caché 5.0.9 and Caché 5.0.10.

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

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.

ECP can survive server restarts and crashes without any client application involvement. During startup, if there were any ECP client open transactions, the open transaction journal offset got stored in the ^%SYS("ECPDELAYTR") global in case the system crashed again. The global was never killed after successful ECP recovery.

So after many hours or days, if the system is restarted (for any reason) it scanned from that remembered journal offset, which could be many journal records. This would cause the next system restart to take a long time, and some of the journal files may possibly have been deleted, which will abort the rollback because of missing journal file.

With this change, the information will be maintained in the WIJ file.

An XML file such as this example

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE note [
 <!ELEMENT note (to, from, heading, body)>
 <!ELEMENT to (#PCDATA)>
 <!ELEMENT from (#PCDATA)>
 <!ELEMENT heading (#PCDATA)>
 <!ELEMENT body (#PCDATA)>
]>
<note>
 <to>Tova</to>
 <from>Bill</from>
 <heading>Reminder</heading>
 <body>Don't forget the party this weekend!</body>
</note>

containing a DOCTYPE but no SYSTEM or PUBLICID caused

ERROR #6301: SAX XMLParser Error: Unknown Error.

This change accommodates the missing information.

An error has been fixed which prevented the creation of a view against a table linked via the SQL Gateway. With this change, SQL can now create such a VIEW. Previously, this operation would report that the table had no Master Map definition.

A deficiency has been fixed in which the insert/update of a serial field's values through SQL might not be stored properly in the database. The error occurred when the serial field was stored in a global node by itself (without any other fields stored in the same node).

In previous versions of Caché, fields using a Space collation in a CacheSQLStorage subscript expression of the form " "_{FieldName} were treated as expressions rather than collated field values. This made the SQL Query Optimizer less likely to use the index.

This is now corrected.

A problem was fixed where an OUTER JOIN could sometimes behave like an INNER JOIN. This occurred when the join column of the left side of the left join is an IDKEY, while the join column from the right side is an indexed column that has a collation different from EXACT.

This change corrects a problem in SQL Manager's export and import class methods, %SQL.Export.Mgr.DeleteExportRoutine and SQL.Import.Mgr.DeleteImportRoutine, that prevented generated routines from being later deleted.

This change resolves a problem that could cause access violations in OpenVMS during certain block split operations in 8KB databases. The problem occurred when more than 2GB of global buffers had been allocated.

This fixes an error in $BITLOGIC where empty strings would not get negated correctly if there were a length present and only one argument, i.e. $BITLOGIC(~x,len).

This fixes a problem with $BITLOGIC(X) for certain values of X. A spurious error would be reported when the following conditions were met:

• X was stored as a bitmap whose last byte was 1
  
  
• (($BITCOUNT(X)-1)/8+5)=$LENGTH(X)

This change corrects a condition that resulted in the generation of an invalid bit string from $BITLOGIC(u ^ v) (i.e. XOR operation). The error occurred on Unicode databases when one of the operands was compressed and the other was not.

This change corrects an error where, under circumstances requiring conversion from bitlist to bitmap, an incorrect result could occur using the & (AND) $BITLOGIC operator. This only occurred on Unicode installations.

When the DCP daemon is shut down, it will roll back all opened transactions by remote client jobs. However, it intermittently failed to record the restored globals into journal file. This caused the globals set be back to the pre-rollback value when the server is restarted.

This change corrects that occurrence.

This change addresses a problem with journal restore involving a CACHETEMP database of specified max size (i.e., max explicitly set to a value greater than zero). Under some circumstances, users could experience a <SUBSCRIPT> or <UNDEFINED> error during journal restore.

This change corrects the following problems with cluster failover (after a node crash) or cluster recovery at startup (after cluster crash):

• <NOTOPEN>main+1^JRNCLFOR, an error that would result in cluster hanging (in the case of cluster failover) or startup aborting (in the case of cluster recovery);
  
  
• incorrect data, as the result of journal records being restored in the wrong order.

A problem which could cause a pause in the write daemon cycle on a Tru64 cluster system has been resolved. Since global updates are locked out during this phase of the write daemon cycle, this appeared to an application as a global module pause.

A problem with clusters where the write daemon would get stuck in an infinite loop if it encountered a problem completing its portion of cluster startup has been resolved.

This was found during internal testing, it has never been seen in the field.

A problem has been fixed that could lead to file handle and memory leaks with JOB servers, mostly on Windows platforms.

Journal start used to abort when the name for the new journal file was taken by an existing file other than a valid journal file. The new behavior of is to skip the non-journal file and use the next available name for the new journal file.

A warning message is also displayed in cconsole.log.

In previous versions, some settings affecting globals may not have taken immediate effect in existing processes. This was due to the fact that global vectors were cached locally in the process.

The system setting that dictates whether all or selected globals are journaled fell into this category.

This change enables the change of the system setting of journaling to take immediate effect, even in existing processes.

This change corrects a problem where incomplete transactions involving databases redirected elsewhere in the journal restore were not rolled back properly.

The problem is present in all Caché releases.

There was a problem introduced by a change to version 5.0.5.

If a clustered system crashes shortly after journaling switches/rolls-over to a new file, open transactions may not be properly rolled back during the subsequent cluster recovery or failover.

This change corrects that circumstance.

This changes corrects a problem in 5.0 where the descendants of a KILL of a global node are journaled if the global is marked for journaling, even though the KILL is NOT part of a transaction. It would be the correct behavior if the KILL is part of a transaction, but in this case it is not.

Cstat has been enhanced with the “-j16” option to display jobs, if any, queued for synchronous journal I/O. For example,

Sync I/O queue (job:iowake:nextjob): 16
   15:0:   13,   16:0:   15

The job # at the end of the line "Sync I/O queue" is the head of the queue. It is followed by a list of jobs on the queue (not necessarily in their order on the queue) that are NOT the last entry on the queue. The nextjob field is the job # following this entry. In the example above, the actual queue is:

head = job #16 -> job #15 -> job #13 = tail

Job #13 is not shown in cstat because it is the last entry on the queue.

This addresses a potential problem that might cause jobs to hang while waiting for journal I/O to complete.

This correction prevents the journal daemon from hanging in an infinite loop in some situations involving a job (or jobs) waiting in a synchronous journal operation (e.g., synchronous TCOMMIT).

Under some circumstances an attempt to manually switch the journal file via ^JRNSWTCH or the GUI equivalent could hang indefinitely. This has been corrected.

In previous versions, the journal info in the wij was not updated when there was no database update. This could become a problem in some situations where the journal grew indefinitely (e.g., with TS/TC or NN records) without any database update, resulting in stale journal info in the wij. If Caché aborted while in this state, users would see a time-consuming journal restore and transaction rollback at startup.

With this change, the journal info is updated in the wij as long as journal has grown, even if there is no database update.

Under some conditions, jobs in synchronous journal operations (e.g., synchronous TCOMMIT) could hang if killed while the journal daemon is retrying a failed I/O operation.

This change prevents that from happening.

This change eliminates a sporadic access violation error in dejournaling.

If for some reason journaling failed to start at Caché startup, the journal info in the wij would remain stale even if databases are subsequently updated (without journaling). At the next startup, the stale journal info in the wij could cause the previous database updates (when journaling was off) to be overwritten by the stale data from the journal.

This has been corrected.

In an NWDS configuration, some globals were not properly mapped. This resulted in the SourceControl class being unaccessible from the client.

In Caché version 5, fast mode shadowing may suffer a performance degradation if journal file grows substantially. This change addresses this issue.

When the packet-driver service is configured to start automatically, Caché could take a long time to start. This has been corrected.

This change corrects a problem where the DCP server may fail to roll back open transactions under certain circumstances. One such situation, for example, occurs when a DCP server terminated involuntarily at OS level. In this case, it left some incomplete transactions behind, which the succeeding DCP server would failed to roll back.

When error occurs in TROLLBACK, <ROLLFAIL> is now generated and an error message is logged in the cconsole.log.

GBLOCKCOPY was using a subdirectory called "old" for saving temporary data. This changes that to be called "pre-gbcopy", so that it will not duplicate a commonly used name like "old".

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:

• ObjectScript
  • Added the description of the "*variable" usage to the $ZTRAP special variable.
  • Rewrote descriptions of HALT and ZTRAP commands, $HALT special variable.
  • Rewrote LOCK command description for multiple locks and subscripted arrays and updated ^$LOCK and ^$ROUTINE structured system variables.
  • Added TROLLBACK 1 option and other changes to TROLLBACK and TSTART commands.
  • Made a number of corrections to the $ISOBJECT and $ZCONVERT functions,
    and to the special variables: $HOROLOG, $STACK, $ESTACK, $ZTRAP, $X, $Y, and $ZA.
  • Revised the logical operators section, & and &%amp;, precedence and nesting, and '= operator for the “Operators and Expressions” chapter of Using Caché ObjectScript.
  
  
  
• IO Device Guide
  • Rewrote Open command mode options for Interprocess Communication.
  • Added material describing the differences in printer handling on UNIX and Windows.
  
  
  
• High Availability Guide
  • Updated the material on Backup, Failover, and Journaling.

These are in addition to numerous, minor enhancements in examples, and corrections to grammar and spelling.

This section provides a listing of changes between Caché 5.0.8 and Caché 5.0.9.

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

As necessary, 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.

This Cache version adds support for the following new platform:

• Windows Server 2003 for 64-Bit Itanium-Based Systems

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

Once there, choose the "Caché" tab, and on the "Downloads" menu, select "Documentation and Help Updates".

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.

This change corrects a circumstance where the Config Manager would set the wrong value for the JournalZGlob parameter. This would cause globals beginning with "Z" or "z" not to be journaled when the user intent was the opposite.

For a CSP page logged in with a new named user license and '%session.EndSession=1', the license associated with the most recent CSP session was not released. This has been corrected; the named user license for a CSP session is decremented correctly if its session ends immediately.

Under some circumstances, the ObjectScript compiler generated incorrect object code at the end of a procedure. This could result in various errors at the end of the procedure, such as <SYSTEM> or <NO CURRENT OBJECT>.

This only happened if all the following conditions were met:

• the procedure ends with an IF statement;
  
  
• the last command of the IF statement is QUIT;
  
  
• the last line of the procedure contains all of -
  • the QUIT,
  • the closing brace for the IF,
  • and the closing brace for the procedure.

If the FTP connection times out, the Connected property of the %Net.FtpSession object was still true. With this correction, it is now correctly reset to false.

Delphi has Edit/Text box windows with a 'Text' property. The windows do not support OLE Automation, so the SetOutput() method of CacheObject.Factory is unable to access them.

DelphiCallback is a new component. It is an ActiveX control that can be placed on a visual programming environment form. To use it, call the CacheObject.Factory.SetOutput() method, passing in the name of the DelphiCallback control. At runtime, the control is invisible but will trigger a 'TextChanged' event when its Text property is set. This event receives the Text written out by Cache.

1. Create a Delphi 7 Windows Forms Project
2. From the Project menu, select Import Type Library. Scroll through the list and select CacheObject, select the Install button, and follow the prompts.
3. From the Components menu, select Import ActiveX Control. Scroll through the list and select DelphiCallback. Then, select the Install button and follow the prompts.
4. Add a TEdit box, a TButton , a TCallback, and any other components to the form.
5. Doubleclick the form to enter code for the form's creation, button press, etc.
6. Click the TCallback. From the Object Inspector window, select events, and create an event for OnTextChange. This will tie the callback to the TEdit box.

Here is sample code assuming a TextBox called Edit1 on a Form called TForm1 with the OnTextChange event called TextChanged. Text shown in boldface was added to the code generated by Delphi.

unit Unit1;

interface

uses
  Windows, Messages, SysUtils, Variants, Classes, Graphics,
  Controls, Forms, Dialogs, OleCtrls, DELPHICALLBACKLib_TLB,
  StdCtrls, CacheObject_TLB;

type
  TForm1 = class(TForm)
    Edit1: TEdit;
    Button1: TButton;
    Callback1: TCallback;
    procedure FormCreate(Sender: TObject);
    procedure Button1Click(Sender: TObject);
    procedure TextChanged(ASender: TObject; const p_bstrText: WideString);
  private
    { Private declarations }
  public
    { Public declarations }
  end;

var
  Form1: TForm1;
  Factory : IFactory;
  Connected : Boolean;
  ConnectString : string;

implementation

{$R *.dfm}

procedure TForm1.FormCreate(Sender: TObject);
var
  Dispatch: IDispatch;
begin

  Factory := CoFactory.Create;
  ConnectString := Factory.ConnectDlg('Connect to Cache');
  Connected := Factory.Connect(ConnectString);

  If Connected = False Then
    Begin
      ShowMessage('Could Not Connect');
    End
  else
    Begin
      Dispatch := Callback1.DefaultInterface;
      Factory.SetOutput(Dispatch);
  End
end;

procedure TForm1.Button1Click(Sender: TObject);
var Person: Variant;
begin

  Person := Factory.New('Sample.Person', 1);
  If VarIsNull(Person) or VarIsClear(Person) then
    Begin
      ShowMessage('Could not create person');
    End
  Else
    Begin
    Person.Name := 'Test Person';
    Person.PrintPerson;
  End

end;

procedure TForm1.TextChanged(ASender: TObject; const p_bstrText:
WideString);
begin
  Edit1.Text := Edit1.Text + p_bstrText;
end;

end.

1. Create a new VB standard executable.
2. From the Project Menu, select Components. Scroll through the list and select a checkmark next to "DelphiCallback 1.0 Type Library." This will add a Component on the Components Tab.
3. From the Project Menu, select References. Scroll through the list and select a checkmark next to "CacheObject".
4. Add a TextBox, Callback (added from above), and other controls to the form.
5. Hook up the text of the Textbox to the Callback. Double-click the Callback object. In this TextChanged method, set the text to the desired text. The output from the Factory's SetOutput() method is contained in the string passed to this method.

This is sample code assuming a Textbox called Text1 and CommandButton Command1:

Private Sub Callback1_TextChanged(ByVal p_bstrText As String)
Text1.Text = Text1.Text & p_bstrText ' Add the Text to the TextBox
End Sub

Private Sub Command1_Click()
Dim F As New CacheObject.Factory
Dim C As String
Dim P As Object

C = F.ConnectDlg("Connect Me to the Samples Namespace Please")
If F.Connect(C) = False Then
    Exit Sub
End If

F.SetOutput Callback1 ' Hook up the Callback Control to CacheObject Factory

Set P = F.New("Sample.Person")
P.Name = "Jamie"
P.PrintPerson ' Output should appear in the TextBox
End Sub

The %String MAXLEN parameter must be a positive integer. Prior versions of Caché did not check MAXLEN for validity. This corrects the oversight in this class.

The ftp client provided by %Net.FtpSession now supports both PASV and non-PASV mode for transferring data. Change the default PASV mode by setting the property UsePASV to 0.

Use the ChangeUser method to modify the current user logged in.

Sending LIST plus a space character even when there was no pattern caused a problem. This has been corrected.

If you removed an item from a relationship with the Remove method, and then you inserted the same item back into the relationship, the insertion operation was not restoring the connection between the two objects properly. The referred-to object was thus not being saved when its referrer was saved.

This is now fixed.

When an application calls the NameList method in %Net.FtpSession, that method issued a read without a timeout on it. The lack of the timeout could cause a hang in the presence of a bad network connection. The read has been changed to honor the same timeout as all the other reads.

As an enhancement to Cache 5.0.5, URL parsing was removed from Caché code. Instead, Caché used the facilities of the underlying Xerces parser to process URLs.

On OpenVMS, this caused an opcode fault. The change rebuilds the Xerces parser properly for OpenVMS.

Saving the object instance of a parent in a parent-child relationship now succeeds when the reference to the child is removed from the relationship.

In some more complex transactions, a child object could both be modified (requiring it to be saved), and removed from its relationship to its parent. This would result in validation failures when the save of the (previous) parent object was attempted.

This correction changes the behavior. Any objects deleted from relationships are removed from the save set so that they do not cause validation errors in saving the parent. These objects are examined after the save set is constructed.

When a relationship is severed between two objects, a record of that is kept in the relationship object. Prior to this change, under some circumstances Caché might miss this fact and not save the new relationship state. With this change, the new state is properly saved.

The XML parser used by %XML.TextReader uses a length value to indicate how much data it has room for in its buffer. Due to an oversight, one part of the routine was treating it as bytes and another as characters. This caused buffer overrun conditions when Unicode characters were read and could result in fatal errors on some systems.

This change makes the length interpretation uniform, and eliminates the error.

Prior to this change, when TuneTable had been run, all classes were marked as modified and requiring recompilation. This happened regardless of the setting of the "KeepClassUpToDate" argument to TuneTable. Now, only the tuned tables are marked as being updated.

The number of properties in a class has been increased from 430 to about 800 mapped to a single node.

The lock escalation is now performed on a per-table basis.

Caché has had the concept of lock escalation for some time. This is when "X" number of INSERT/UPDATE/DELETE/Saves occur within a single transaction, the next lock acquired for the table is a table-level lock. This prevents the Caché system lock table from filing up too quickly.

But, if an application inserted 1000 rows into table A and then 1 row into table B, table B would acquire a table-level lock. This is because the lock escalation threshold counter was incremented for each save in all tables.

With this change, there is a separate counter for each table. Therefore, the lock escalation only occurs on a table when that table reaches the lock escalation limit within a transaction (the default limit is 1000).

This change corrects an instance where an <UNDEFINED> error may occur during the table compilation phase of the class compiler. Caché reports the error

• if a property in the class uses a datatype with StorageToLogical and LogicalToStorage methods,
  
  
• and the property is in the IDKEY index,
  
  
• and the table is a child table.

When Caché detected a stored procedure parameter mismatch error, it immediately raised an exception. In some instances, this leaves the input buffer with data that was supposed to be consumed. The subsequent call would then fail with a message sequencing error.

This change clears the buffer so sequencing errors do not result from the exception being reported.

This change improves the speed of certain queries with GROUP BY or DISTINCT, especially when these operations can be assisted by an index. If a query has DISTINCT or GROUP BY and no aggregates need to be processed by the query, execution terminates as soon as all the DISTINCT field values become known.

Note: the optimization will not be evident in Show Plan.

This correction changes the SQL CASE statement to return its result as the datatype of the result of the first CASE condition.

All the values returned by CASE are supposed to be of the same datatype, but Caché does not enforce this. So if the first condition returns a DATE, the column will be of datatype DATE. If a later condition returns an INTEGER, the value will be treated as a DATE value.

A query such as

SELECT a.spouse->name FROM sample.person a,
       (SELECT contact FROM sample.vendor) b

containing a sub-query of an unrelated table would fail with an SQL erroe code of -29.

This change allows Caché to properly handle this case.

This change corrects an error where Caché would report a <MAXSTRING> error during the table compilation phase of the class compiler if %CacheSQLStorage is used, and more than 200 fields are stored in a single node using a delimited string storage structure.

Delimited String storage simply means:

^glo(id)=field1^field2^field3^...^fieldN

where each field in this example is delimited by "^".

The performance of the Studio New Query Wizard could be poor in a namespace that contained many classes with many relationships among the classes. The performance has been improved. The Query Wizard is initializes only the data for the levels the user actually explores.

The class syntax checker has been fixed to correctly report an error when the final closing brace of a class definition is missing. In previous versions, this invalid syntax was unreported.

In previous versions, Caché failed to set UTF8 mode for devices used in debugging. This resulted in non-Latin characters (for example, Japanese) being displayed incorrectly.

This change rectifies that situation.

This change addresses a issue with sorting (started and ended via $SortBegin and $SortEnd, resp.) on 64-bit platforms. Global nodes that are set to values of double type may attain incorrect values after sorting. Since sorting is enabled in journal restore in 5.0.5 and later, journal restore was affected by the problem too.

This change corrects an error that caused an <INVALID TYPE> error when comparing an OREF to a non-null string. Now this comparison returns 0 (false).

This change corrects the calculation for $NORMALIZE(<number>,-1) that could incorrectly return zero in some circumstances. For example, prior to this change, the sequence

Set x = 3.5
Write $NORMALIZE(x, -1)

would correctly return the value 3. However, the sequence

Set x = 7 / 2
Write $NORMALIZE(x, -1)

would return the value 0. Now it returns 3 as it should.

There is a small chance that ^LOCKTAB or ^$LOCK SSVN could get an access violation when there is heavy lock table activity. This change prevents that from occurring.

Under certain circumstances, an attempt to restore a saved database file into a bigger existing database can cause data corruption resulting in <DATABASES MAP LABEL> errors and system hangs.

With this change, the data corruption no longer occurs.

An error in the non-interactive API for restoring backups, $$EXTSELCT^DBREST, has been fixed. The result of the error is that the manager's database could be inadvertently restored. This would happen even if it was not specified in the restore list. If it were present in the backup archive and the file containing the restore list contained a blank line, the manager's database would be overwritten.

This could also happen if the calling process had enabled $ZEOF handling.

In previous versions, a process would crash if it attempted to open a Windows printer device with a name longer than 69 characters (including the "|PRN|" prefix). Now, length of up to 256 characters is supported with a <NOTOPEN> error occurring for a length greater than 256.

If a lock is held by a remote DTM client, the LOCKTAB and Control Panel display will now append a "/" followed by the process ID of the owner on the remote DTM system to the lock display as a monitoring aid.

On earlier versions of Caché, it was possible for the statement

For i=1:1 ZA ^a(i)

to get a <COMMAND> error when $ZU(69, 8) is set. When it is not set, it should not get this error because ZA works like the LOCK command. This change fixes this issue.

Prior to this change, the %CSP.Daemon process was getting started in the implied namespace because this is the namespace the startup code is in before it calls the function to start the daemon. Now the daemon swaps to %SYS namespace.

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:

• In the Caché I/O device guide:
  
  • Added the OPEN and USE options (positional and keyword) for the COM port
  • Fixed and updated the UNC section for printer names
  
  
  
• In the Caché SQL Reference book:
  
  • Added new pages for
    
    • %CHECKPRIV,
    • GROUP BY,
    • HAVING,
    • the new date and time constructs {d ...}, {t ...}, and {ts ...},
    • and variables includiing %msql, %ROWCOUNT, and SQLCODE
  • Added %msql information to the material on CREATE TABLE, CREATE VIEW, GRANT, and REVOKE
  • Updated the information on CREATE TABLE %Description adding explanations of the %FILE, %NUMROWS, and %ROUTINE options
  • Reworked and expanded the material on dates and time including: CURRENT_TIME, CURTIME, HOUR, MINUTE, SECOND, CURRENT_TIMESTAMP, GETDATE, NOW, TO_DATE and TO_CHAR
  • Added descriptions of the %DELDATA and %NODELDATA options for DROP TABLE
  • Clarified the explanations of %DB_OBJECT_DEFINITON and added cross-references to %CHECKPRIV for GRANT and REVOKE.
  • Improved and expanded the examples showing SELECT usage with more varied option combinations and more explanatory information on each example.

• Changed the browser stylesheets to remove excess leading spaces from lists appearing inside table cells
  
  
• Added the lead items from the Glossary of Terms to the word index
  
  
• Added Itanium as a supported platform for Windows

These are in addition to numerous, minor enhancements in examples, and corrections to grammar and spelling.

This section provides a listing of changes between Caché 5.0.7 and Caché 5.0.8.

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

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.

If you have a form in a CSP page with a textarea, and the submitted data in the textarea is longer than 32K characters, the CSP server now automatically creates a stream to hold the data and returns the stream OREF as the result of %request.Data("txt",1).

This means that for any fields that could be larger than 32k you should code something like:

Set value=%request.Data("fieldname",1)
If $isobject(value) {
  ; Treat this as a stream
} Else {
  ; Treat this as a regular string
}

Under some circumstances, closing the status window of a GUI backup could result in the system hanging. This change corrects that.

If a request for a new CSP page comes in which causes a new session to be created, and a serious error occurs before the request is complete, there are situations where the %cspServer process may HALT after allocating a license but before storing the session information in ^%cspSession.

Should this occur, the license will never get released because the %CSP.Daemon process will never detect this session timeout (there is no entry in ^%cspSession).

With this change, the %cspServer process inserts an entry in ^%cspSession before allocating a license. Should the new process terminate abnormally, this license will still get released by the %CSP.Daemon process.

This change removes support for URL and FILE query parameters of %XML.Utils.SchemaServer so that arbitrary file viewing is no longer possible.

This change closes a %CSP.DwxUtils security hole that allows running of an arbitrary classmethod.

Dreamweaver MX2004 changed the mechanism needed for installing plugins. This change contains the modifications to the Caché plugin necessary for it to work with MX2004 as it has with earlier Dreamweaver versions. Corrections were made to fix uninstall problems uncovered in earlier releases.

This change corrects a problem where attempting to post small binary files as multi-part MIME attachments could result in an error return. This issue was particularly relevant to files containing the NULL (ASCII 0) character in the first few bytes. This location, for example, is usually reserved for header information in image and zip files.

This change corrects an error in the Caché Version 5 communications protocol between the Gateway and Caché. Prior to this, 'textarea' submissions greater than 32K could fail.

Hyperevents may fail in non-cookie, session-management mode if the session token (CSPCHD) was not passed as the first hidden field in the form's posted data. This could also happen in regular CSP forms, but more rarely. This changes corrects this situation.

This change corrects an issue involving a POST of a textarea element containing more than 32K characters. Under some circumstances, the textarea content could be silently truncated.

Sun has changed the default behavior of the Sun ONE (formerly iPlanet) v6.1 server. The change mainly involves requests processed through NSAPI extensions.

The effect of the change is that the server now assumes responsibility for formulating and dispatching HTTP response headers. Previous versions would allow NSAPI extensions to stream their own headers back to the client and wouldn't intervene in this process unless the module explicitly called the NSAPI header formulation and dispatch functions.

This change includes essential modifications to ensure that the Gateway works with the latest iPlanet/Sun ONE web servers under Linux.

The I/O keyword table was inadvertently truncated in Release 5.0.5. The keywords /WRI, /WRITE, /XYT, and /XYTABLE were not recognized as valid and attempts to use them resulted in <SYNTAX> errors on Windows systems.

On UNIX and VMS systems, only the last entry, /XYTABLE, was truncated with similar effect.

This change corrects both errors.

This change updates the InterSystems packet driver to correct issues with Windows "Plug-n-Play". Prior to this change problems during install or uninstall could sometimes cause a Windows system failure.

The driver also now processes properly many dynamic operations via packet-driver handles allowing the system to proceed more gracefully.

The internal version number of the driver has been updated to reflect the change.

Under some circumstances, class instances were being marked as modified when Count() or %GetNext() were invoked, and more than one instance of the object was stored in the database. An example is a "parent" object instance with multiple "children". This change properly preserves the modification state of the object.

Under some circumstances, upgrading could result in the discard of privileges for SQL tables. This changes preserves the privileges across an upgrade.

The ReturnFault() method of web services was not properly preventing creation of the SOAP body after a fault was generated. This has been corrected.

Prior to this change, the XML Schema wizard could not properly handle an XML document that was encoded in a character set other than UTF-8. Now the Schema Wizard uses the character set encoding specified in the <?xml ...> directive.

Prior to this change, if a linked table (for example, to data residing in Microsoft SQL Server) contained a class query with a parameter, and that parameter was referenced in the WHERE clause, an attempt to compile the class would result in a <SYNTAX> error. This change corrects the problem and the class now compiles properly.

This change enables the generation of the HAVING clause for tables linked from other databases. In prior versions, the HAVING clause was wrongly omitted when the SQL was sent to the other database.

Under some circumstances, a user could receive a <MAXSTRING> error if a large number of streams were used in a bulk insert or update operation. The streams were not properly being closed when the operation completed.

Since there is no reason to keep the streams open in this circumstance, Caché now automatically cleans up all such structures after a(n) (bulk) insert/update has completed.

The internal use of the ISDIGIT ANSI function resulted in undefined behavior on integer values larger than 255. This failure was present in version 5.0.5 and 5.0.7. This has been corrected.

Allow the constant, host varible, or "?" that follows TOP to be enclosed in parenthesis. (Currently, Caché does not allow a general expression there, not even a constant expression.) This is needed for external tables, since other vendors support only constants after TOP, and thus the parenthesis are required to prevent literal-replacement of that constant.

Before this, Caché would report an error when it attempted to compile queries with IN conditions on parent reference fields, and those conditions had more than one "||" component.

For example:

SELECT * FROM grandchild WHERE parentref IN ('1||2', '3||4')

This change allows the compilation to proceed correctly.

A query that uses linked tables now succeeds when the query includes more than one OUTER JOIN.

The existence of certain WHERE conditions can cause an OUTER JOIN to be converted to a regular join without affecting the query semantics. (Regular joins can be more efficient to process than outer joins.)

In prior versions, the analysis of the conditions under which this conversion could be performed was incorrect for some usages of ISNULL, NVL, COALESCE, NULLIF, IFNULL, DECODE, and CASE, as well as for fields in an extrinsic or a user-defined function. This change corrects the analysis.

It also extends the analysis to correctly convert queries involving OR conditions.

Finally, it corrects the regular 3-value logic NULL analysis in situations where there were NULL arguments in a call to an extrinsic or a user-defined function contained in a WHERE clause.

Under certain circumstances, an attempt to copy and paste a program fragment would cause Studio to crash with an internal buffer overflow. This is more likely when the program fragment has a large number of short, syntactic elements because the internal representation of the fragment required more space than was allocated. This change allocates sufficient additional space to contain the copied section.

When a process is using $System.Event.Wait() to do a timed wait, and it receives a signal from another process, such as from JOBEXAM or to update internal tables after mounting a database, the timing mechanism was lost and the process would never return from the Wait(). This change makes it work properly.

This change corrects a error affecting non-Unicode Caché systems. The error happens during the translation of the internal encoding of subscripts from ISM versions 6.2 through 6.4 to Caché Standard collation. Such translations occur, for example, when using %GIF.

Subscripts starting with a ÿ (lower-case "y" with an umlautl HTML = &yuml; or &#255;) might not get translated properly and end up in the database with the wrong encoding. This would generate a <WIDECHAR> error when those nodes were later accessed via $ORDER or $QUERY.

A defect has been corrected that could cause the write demon to hang. The problem only occurs when a database on a Unix system is not readable by all Caché jobs, and the database is included in a Caché incremental or concurrent incremental backup. Under these circumstances, the system may hang following the backup.

This hang can be identified by examining the wdwake value displayed by cstat. It has a value of 2, the problem resolved by this change has occurred.

This change corrects a problem which could cause processes to skip resetting their global vectors after a database has been dismounted and re-mounted.

From the Caché alert issued 22 April 2004:

InterSystems has corrected a defect that can cause Caché processes to be incorrectly deleted from Caché. This defect is present on Windows platforms only and applies to currently released Caché 5.0.x versions.

Only processes that call out of Caché using $ZF() and modify their Windows security profile are at risk of encountering this defect. The likelihood of encountering this problem is low, but the effects could be severe including causing Caché to hang. To determine if your system has encountered this defect check the cconsole.log file for a message indicating that a dead process has been "cleaned", for example:

04/20-17:28:33:734 ( 4184) cleaned dead job, pid: 4224

If the PID that has been cleaned still exists as a Windows process, then the problem may have occurred.

See the earlier section on alerts for related information.

From the Caché alert issued 27 April 2004:

InterSystems has corrected a defect in Caché backup that could result in inability to restore from a backup archive. This defect exists in all Caché 4.1.x and later versions and for all platforms and operating systems.

This problem can only occur in backup archives with 16 or more databases. The likelihood of encountering this problem is low but increases with the number of databases in an archive. Existing backup archives can be checked with the following procedure without actually restoring any databases.

To check whether existing archives are subject to this error, user should

• invoke ^BACKUP;
• choose option 3, "Restore Selected or Named Directories";
• mark every database listed with an "X", so they will be read but NOT restored.

If the restore reads through the entire archive without a "missing blocks" error the archive is not affected by the condition. No database restore should occur because none has been selected - that is what the "X" means.

This change eliminates the error. See the earlier section on alerts for related information.

Prior to this change, a call to NORMAL^%PRIO after a call to LOW^%PRIO would leave the process in priority 0 (zero). This only happened on Windows NT.

A workaround for the problem was to set the priority by doing HIGH^%PRIO, then NORMAL^%PRIO.

With this fix, it no longer happens on any platform and the workaround is no longer needed.

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:

• Supplied additional program examples in the SQL reference manual
  
  
• Added additional cross-references between the Caché ObjectStript and the SQL references
• Updated the table of symbols for SQL
  
  
• Updated the documentation on installing and configuring the CSP Gateway
  
  
• Added additional active links to related material in cross-references

These are in addition to numerous, minor enhancements in examples, and corrections to grammar and spelling.

This section provides a listing of changes between Caché 5.0.5 and Caché 5.0.7.

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.

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.

A bug has been fixed where all the VMS-created backup versions of the .cpf file were deleted when the configuration was edited via Config Manager.

DSM systems cannot handle the full range of Caché double-precision numeric subscripts. The subscripts are now reduced in precision to that which a DSM system can accept.

This change corrects an illegal internal reference in the named method which caused an <UNDEFINED> error.

Prior to this change, when a child object attempted to reference its parent, all the objects contained in relationships of the parent would be instantiated. This resulted in an unexpected and unnecessary large overhead in making the reference. This change removes the automatic loading in favor of loading only those objects actually referenced.

With this change, related objects are now loaded when calls are made to the Next() and Previous() methods. Previously, these methods could return errors.

The modified bit for an object was incorrectly being set when other objects it referenced were brought into memory. This has been corrected and the modified bit is now set only if the object is actually modified.

When an applilcation called Insert(oref) to insert an object reference into a relationship collection, or called the deprecated method SetAt(oref,key), instead of the oid being stored in the relationship, just the id was stored. This could cause problems when searching for an oid in the collection. Now both methods correctly insert the oid.

In correcting this, some changes were made to improve the performance of the internal storage for the relationship and to reduce the memory footprint required.

The %ConstructClone method failed to load all the ID's of a relationship before performing its work. Prior to this change, it would clone only the ID's that had been loaded by other reference attempts.

An incorrect method call in the SAX content handler resulted in an attempt to reach a non-existent method. This is now corrected.

A problem has been corrected with the SQL code generator. If you selected against a UNION subquery containing an OR clause, under some circumstances the columns would display the wrong value in the results.

Under some circumstances, the conversion of a date/time to display format would result in an <ACCVIO> error if the fractional seconds portion of the date/time was zero.

Under some circumstances, $SortEnd() may apply SETs to the same global node in a different order from the one in which they were issued, resulting in incorrect value of the global node. This change applies them in the correct order.

This change corrects a performance degradation in the HPUX implementation of Caché that eventually results in a <STORE> error.

This change corrects several errors in exporting objects whose size approaches 32K in length, and involve undefined variables. It also improves the handling of object tokens during export.

This changes adds error handling for the condition where a Caché system running on Windows runs out of handles.

This change corrects a problem where SETs using the $BIT (bitmap indexing) function in a 2K (old format) database could cause database integrity errors. Prior to this change, when a $BITSET created bigstring data, it failed to update the bottom pointer node to reflect the addition of the bigstring node in the data block. This problem affects all prior Caché releases.

HIGH^%PRIO sets an incorrect priority on OpenVMS. This has been corrected.

Under some circumstances, attempts to access globals on a remote DSM/MSM system using $DATA or $ORDER could result in a <SUBSCRIPT> error or the wrong data being returned.

This has been corrected.

When there is no network configured, an attempt to use ^LOCKTAB or Control Panel to delete a lock entry would result in a <NETWORK> error. This change corrects that condition.

The very first ECP access to remote server took about 5 seconds for Windows platform. This change corrects this issue.

This changes corrects a situation where internal state flags were not being properly reset when errors were reported by DBACK* in the case where it was invoked by an application.

This change addresses an issue on an ECP-based Caché cluster where a corrupted backup may results because the cluster was not quiesced before backup started.

A non-privileged user is not allowed to stop journaling. As far as journaling is concerned, a non-privileged user is one who doesn't have the write access to the journal file.

When a non-privileged user tries to stop journaling, one of the following errors is reported:

Access to journal file [journal name] denied

or

Unable to open journal file [journal name] for write access

When upgrading a license key on a running Cache version 5.0 configuration, either by copying the cache.key file into the system manager directory and running $$UPGRADE^%LICENSE, or by installing it using the Configuration Manager License Wizard, communication with the License Manager would be lost because the internal License Manager address field was overwritten.

This change prevents this from happening. The License Manager will receive the new key capacity values and update its internal tables within a minute or so. The new capacity values are immediately available on the local system.

An error has been fixed where mappings defined for the %SYS namespace would be lost upon Cache restart.

If there is a file in the Cachesys directory such as:

cache.cpf.<config>

where <config> is the Configuration name, ccontrol will start the Configuration using the cache.cpf.<config> (even if you put nothing in the command line, or use 'cache'). During the startup it tells the user that it is using just the "cache.cpf" file.

With this change, it correctly reports the file name.

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:

• An article on using Caché with a Network Appliance Filer was added to the Knowledge Base section.
  
  
• The article on calculating the configuration parameters for UNIX systems (Appendix B of the "Caché Installation Guide") has been updated.
  
  
• The Upgrade chapter of the Release Notes has been updated.
  
  
• The SQL reference material underwent a thorough review, for example —
  
  • all date and time function descriptions were reworked as needed including new information on conversion and the addition of many new examples
  • the CREATE and DROP statement descriptions were upgraded
  • comparison tables were added for the functions IFNULL, NULLIF, ISNULL, and NVL
  • the SQL DDL datatype mappings were updated to match that shown in the Configuration Manager
  • correspondences between SQL and Objectscript functions were added when appropriate
  • the cross-references of commands, functions, and variable names has been improved

• The I/O Device Guide in the Reference section was updated with —
  • a rewritten section on using the SPOOLER
  • description of TCP /SENDIMEDIATE mode
  • new options available for Terminal OPEN
  
  
• Improvements were made to the Objectscript reference manual in the areas of —
  • the interaction of NLS with $ZDATE and $ZDATETIME
  • new examples for the date and time functions
  • linking between TSTART, TCOMMIT and TROLLBACK and the corresponding SQL commands

These are in addition to numerous, minor enhancements in examples, and the usual corrections to grammar and spelling.

This section provides a listing of changes between Caché 5.0.4 and Caché 5.0.5.

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 listing of changes with possible compatibility issues
• A listing of changes without compatibility issues

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.

At the time of this publication, the details on the following were available:

Date	Subject
December 4, 2003	Caché Server Pages
November 19, 2003	Caché Backup Error and Lost Updates
November 17, 2003	IBM 64 bit - Caché Floating Point Zero Boolean Issue
November 14, 2003	Caché Server Pages
November 6, 2003	CSP Error Messages Corrupt in Caché 5.0.4 Only
October 17, 2003	Microsoft IIS 6.0 on Windows 2003 with CSP
October 6, 2003	Caché Process Local Variable Corruption [VMS]
March 13, 2003	Caché Process Local Variable Corruption
September 26, 2003	Caché and McAfee product conflict
September 22, 2003	Update: Hyper-Threading and Caché
January 15, 2003	Intel's Hyper-Threading technology and Caché
July 28, 2003	Caché and MultiNet
July 23, 2003	Journal Suspension and Data Loss
June 27, 2003	Caché and write permissions on UNIX systems
June 23, 2003	Wrong answer for certain OR conditions when multiple index strategy used
June 20, 2003	Caché Networking and New Format Databases, Addendum
June 20, 2003	Caché Networking and New Format Databases
May 20, 2003	Transaction Processing over DCP
May 14, 2003	Telnet Connections on Caché Windows
May 12, 2003	Caché and AIX
March 13, 2003	Caché Process Local Variable Corruption
March 7, 2003	Multi-homing and Caché Clusters on OpenVMS
January 15, 2003	Intel's Hyper-Threading technology and Caché

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.

• Critical - A value of "yes" in this column indicates that a production application environment 'may' be at risk or the deployment of an application may be impeded.

Reference	Summary
JCN465	Port linuxit platform to GCC 3.2 compiler
ALE349	Revamped Apache CSP installation on Unix
MXT541	Use binary streams for XML content in web service and web client
PVA058	Fix issues with conditional table maps
SML413	Fix ECP lock zero time out.
MXT526	Correct security flaw in CSP broker.
RJW791	Preferred Server in Registry is not updated when changed
ALE258	Upgrade from 2.1.9 does not convert configuration automatically
JCN479	Build thirdparty executables for Linux on SUSE with GCC 3.2 compiler
DPV2102	LogicalToDisplay() will now report %EXTERNAL(xxx) as type VARCHAR.
MXT499	Fix bug in assigning names of classes created for inline complexTypes by the XML schema wizard
DPV2109	Fix incorrect setting of $Bit for SQLStorage
JCN440	Fetch password from registry if Username passed in matches registry entry
DPV2053	Fix privilege checking with privileges granted indirectly through roles
DPV2131	Order By DESC does not always work with $Piece mapping
HYY837	Fix a problem with index sorting handling wide character strings
LFT1166	INTEGRIT misses database error on 2K database
RFD095	Fix ^SHUTDOWN hang on cluster recovery
RFD066	Allow process to recover MONITOR sessions
JO1742	Resolve issues using GTABSZ as maximum global reference length for 2KB databases
DMD043	Fix a system quiesce problem caused by a missed wakeup to a slave write daemon
JCN452	Fix for WTS connections to loopback address
DPV2079	Correct <LOCK TABLE FULL> on DELETE
STC490	Fix MAXSCOPE error in DDPMASTER
GK255	Fix the way journal checkpoint was used
CFL984	Fix DDP configuration startup issue
MAK942	If %SYS database was 2K then CSP could get SUBSCRIPT error
DLP1125	Add GetColumnExtInfo() method to %ResultSet

PLEASE EXAMINE THE REFERENCES IN THIS SECTION CAREFULLY.

• Installation.UNIX
  • Revamped Apache CSP installation on Unix
• Languages.Cache Basic
  • Implement CacheBasic Sleep command
• Object
  • Port linuxit platform to GCC 3.2 compiler
• Object.C++
  • CPP Binding Erase removes selected element but nulls subsequent elements
  • Unicode character stream data is truncated on the right half
• Object.Class Compiler
  • Add GetColumnExtInfo() method to %ResultSet
• Object.Soap
  • Add support for input and output of SOAP headers by SOAP web methods.
  • Use binary streams for XML content in web service and web client
• SQL.JDBC
  • Double single quotes in literals won't work
• SQL.ODBC
  • Unicode stream data problem from VC++/ODBC
• SQL.Query Processing
  • Fix issues with conditional table maps
• System
  • Fix DTM color compatibility in %XDTM2
  • Implement CPUS_USE_ONLN for AIX
  • Fix lock count inconsistencies.
  • Serialize DDP request for each remote job.
• System.Lock
  • Fix ECP lock zero time out.
• System.TCP Devices
  • Disable TCP Nagle algorithm on all HP sockets.
• Utilities
  • Add total pages to prompt in ^%SPOOL
  • %GSIZE does not properly format the output for global names with > 10 characters.

The CSP installation on Unix has been changed to use the same mechanism as on Windows and VMS. Previous versions of Caché installed the files into cgi-bin. With this change Caché does not use the /cachesys/csp directory with symbolic links anymore. Instead, <cachesys>/csp directory is set in the Apache configuration file (httpd.conf) and all CSP applications are executed from this directory. This eliminates most questions previously asked during this part of the install.

The URL to see the CSP systems management suite is now:

   http://<ip_address>/csp-bin/nph-CSPcgiSys.

CacheBasic Sleep Command: The Sleep command suspends execution for the specified number of seconds. Its syntax is

where Interval is the number of second to wait. Fractional seconds are supported. The resolution of the timer is the same as for the ObjectScript HANG command.

The compiler for the Linux platform has been upgraded. The compiler is now GCC 3.2 which uses the new C++ standard; the previous compiler was 2.95.

The Vector Erase() method on the C++ side of the binding should work like the RemoveAt() method in Caché. It did not, but rather removed the selected element and all subsequent elements.

With this change, it now behaves as expected.

Under some conditions, the C++ binding would fail to return all of the characters in a string converted to Unicode. This has been corrected.

A new method, GetColumnExtInfo() has been added to %ResultSet. This method accepts the column number as an input parameter and will return a $list containing the class name and property name of the property corresponding to the column in the query. If the column is not based on a property then the returned information will be an empty $list.

SOAP web services and SOAP web clients are enhanced to support input and output of SOAP headers within the SOAP envelope. This new header support works only for web methods that are defined as Methods in an instantiable class, not for ClassMethods. Web service methods can be plain Methods.

A new XML enabled class, %SOAP.Header, is introduced to represent a SOAP header. The mustUnderstand and actor attributes are defined as properties in the base class %SOAP.Header. The default for mustUnderstand is "0" and the default for actor is "".

Additional properties must be defined in the subclass that represents the header. The NAMESPACE parameter should be specified in the SOAP header subclass to specify the XML namespace that the SOAP header is defined in.

Two new properties and a new parameter are introduced in %SOAP.WebService and %SOAP.WebClient:

• Property HeadersOut As %SOAP.Header (collection=array);
  

  Any web service or web client method may add instances of any %SOAP.Header subclass to this array. The index is the element name of the header. The corresponding headers are then added to the SOAP response message.

• Parameter SOAPHEADERS = <list of headers>;
  

  where <list of headers> is a comma separated list of input header specifications. Each specification is of the form "headerName:headerClass" where headerName is the element name of the supported header and headerClass is the %SOAP.Header subclass that corresponds to that header. This list defines all headers supported in the SOAP request.

• Property HeadersIn As %SOAP.Header (collection=array);
  

  Any SOAP header in the SOAP request that is found in the SOAPHEADERS list is imported as a %SOAP.Header subclass and added to the HeadersIn array. The web method may then act on these headers as appropriate.

If any header in the SOAP request has mustUnderstand="1" and the header element name is not in the SOAPHEADERS list then a SOAP fault will be returned without processing the message.

The SAX parser interface was changed to treat characters streams as containing Unicode data. In fact, the streams used by web service and web client are actually in the encoding specified by the XML declaration at the beginning of the XML document. Therefore, web service and web client support now works with binary streams.

Externally visible effects of this change:

This change corrects several issues regarding JDBC preparser processing literals with quotes inside and literals enclosed in parentheses. Double quotes are now treated as single quotes for parameters.