Caché Release Note and Upgrade Checklist Archive
Caché 2013.1
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

This chapter provides the following information for Caché 2013.1:

New and Enhanced Features for Caché 2013.1
The following new features have been added to Caché for this release:
In addition, many more localized improvements and corrections are also included. In particular, if you are upgrading an existing installation, please review the detailed list of changes in the Caché 2013.1 Upgrade Checklist.”
Rapid Application Development
Support for %FIND in WHERE Conditions
With this release we implement a new SQL Condition with the following syntax:
<f> %FIND <x>  [ SIZE <const>]
<x> represents a set of values S used as a filter for <f>, or more precisely, the condition is satisfied if <f> is a member of S.
XEP Enhancements
This version of Caché contains the following improvements and extensions to XEP:
JDK 1.7
This release now includes the Java 7 libraries as well as those for Java 6. In addition, Caché now supports JDBC 4.1.
GLOBALS Enhancements
The version of GLOBALS $query is now supported for both Java and .NET APIs. The Globals ValueList now support decimal values. Globals methods can now call Cache Object Script function, procedures with multiple arguments and return types; and Globals methods can now call Cache Object Script class methods. Support for Visual Basic is now available along with a sample that demonstrates its use.
RETURN Statement
The RETURN statement is now available for application developers to optimize code execution and readability. Its definition is analogous to the QUIT statement, but it returns from an enclosing subroutine to its caller.
Support Arguments By Reference With Args...
The args... syntax for receiving and passing a variable number of arguments can now be used when passing an argument by reference.
Websocket Support
The CSP Gateway now includes support for the HTML 5 specification for Web Socket connections between the web server and an HTML 5 compliant browser. This is available for Apache 2.2 and above, and will be available for IIS 8.0 which is part of Windows Server 2012.
There is a base class that must be extended by the user to handle / create WebSockets called %CSP.WebSocket
Improved FrameStack Handling
<FRAMESTACK> errors can now be handled in error traps. Caché will no longer remove items from the execution stack before calling an error trap.
Third-Party Library Upgrades
In this release, ANTLR has been upgraded to version 3.4; Xerces has been updated to version 3.1.1 on UNIX®.
Studio Assist For MVB
Studio assist now recognizes the following syntax elements:
Caché Basic: "ClassName".ME. MV BASIC: "ClassName"->@ME->
XML Support For List of Streams
A list of streams will be projected correctly to XML. A list of streams may be specified by either using 'list Of' syntax or creating class which is a sublcass of %ListOfObjects with ELEMENTTYPE specifying a streamclass.
JSON Improvements
InterSystems made a major enhancements to our public JSON APIs. We now have non-internal function calls that can generate JSON strings from objects, arrays, or SQL statements. These can be subsequently be used to drive a third party client interface that supports JSON as a data transport mechanism. In addition to converting internal structures to JSON, we also support taking JSON sent by the client and converting it into a COS array that can then be consumed within an application.
DeepSee Improvements
DeepSee includes a new editor for creating and editing dashboards. The new dashboard editor takes advantage of improved ZEN charts and other new ZEN components. To edit a dashboard, you click on the bar along the left side of the dashboard. The new dashboard editor provides many more options for controlling the display of charts and tables.
The DeepSee User Portal also includes a new "Covers" view option which displays items on the home page as images. The new covers editor allows you to configure the covers (images, text, colors, etc.). Also, the types of items listed on the User Portal home page now include reports and URL links (in addition to dashboards and pivots).
Performance And Scalability
XML Performance
Performance for XML has been improved by improving the handling of XML between Caché and Xerces. Customers may see improvements of up to 50% for %XML.Reader imports, and up to 25% with SOAP messages.
HTTP 1.1 Keep-Alive
This release of Caché adds support for Keep-Alive with HTTP 1.1. It enables clients to keep the TCP/IP socket to the web server active so that multiple requests can be made via the same socket rather than constantly closing the socket and opening a new one for each request.
Improved De-Journaling Performance
InterSystems has improved de-journaling performance in this version by further optimizing the pre-fetching algorithms used. De-journaling - used by Shadowing, Mirroring, and journal roll-forward during startup recovery - uses a pre-fetching mechanism to speed up the actual roll forward of sets and kills to the databases. These pre-fetchers are responsible for "reading ahead" blocks into the buffer pool so that the actual updater process can move through very quickly and apply updates, and not be slowed down by waiting for disk reads to finish. This version includes a supplementary algorithm that allows the pre-fetchers to read in additional supporting (link) blocks, further speeding up the overall de-journaling performance.
Improved ROLLBACK Performance
In this release, ROLLBACK performance is roughly 10%-30% faster than in previous versions. This improvement applies to rolling back single (large) transactions, as well as bulk rollback (as would occur during startup recovery).
AES Encryption On Intel Hardware
Intel support AES-NI with their latest processors, which greatly improves encryption and decryption for AES. Early benchmarks have shown significant performance improvements over software execution of AES, which greatly minimizes the performance overhead for encrypted databases with high a high frequency of physical I/O.
Improved Async I/O Performance
This version includes improvements to asynchronous I/O that benefits sequential workloads. The new algorithm detects multiple sequential updates and performs larger coalesced writes, and has been measured to speed up sequential workload-related writes by a factor of 1.6 to 1.8.
Improved Encryption Performance
Previously, a performance feature called "parallel WIJ encryption" was enabled on the AIX platform. This feature has now been enabled on HP-UX, Linux, and Solaris, and can increase the speed of database encryption during write cycles by up to a factor of 4.
MultiCompile On By Default
Caché now uses MultiCompile for class compilation as a default, which will decrease compile time on multi-core processors.
Optimize Multi-Key Joins
This release removes some older case-specific functions used to optimize multi-column joins in favor of a more generic approach that results in much greater performance across all types of multi-column join statements.
Export/Import TuneTable Statistics
With this release, Caché SQL has added support for exported and importing TuneTable Statistics for a given namespace. This allows one to export TuneTable Data, Selectivity, and ExtentSize details from a given system and reload it without having to ship a class definition and compile it.
Improve Concurrent Update Performance
This version contains an optimization for concurrent updates on very large-scale systems. With this optimization, benchmarks have demonstrated 20% to 30% improvement in overall database access scalability.
Add Indices To A Class With Minimal Downtime
This version introduces a new feature, %Library.IndexBuilder. This class and its methods permits one or more indexes to be added to an existing class. It is specially designed to address the circumstances where:
Lock Escalation Improvements
This release introduces a new locking mode, “E”, whose goals are to automate lock management and provide better management of the lock table. In this mode, when the number of existing locks held by a transaction crosses a threshold, and Caché determines it is safe to do so, the lock will be “consolidated” as a higher level lock. The lower level locks will then be released thus freeing space in the lock table.
Reliability, Availability, Maintainability, Monitoring
Support Advanced Format (4K) Disk Drives
This version includes support for native 4KB disk sectors as implemented by Advanced Format (AF) disk drives.
TIFF Output In Zen Reports
Zen Reports now has the capability to create content in TIFF format in addition to our previously released formats such as HTML, XML, PDF, Excel, and so on.
Application Specific Licensing
Some Caché customers wish to license their own applications as a whole or in functional units. Among the challenges they facein doing so is the proper accounting for license units in the face of varying application workflow and abnormal terminations. In addition, some customers desire to link their licenses to the underlying system license provided by InterSystems.
With Application Specific Licensing, InterSystems provides mechanisms to support the customer need to create, deploy and use application licenses. InterSystems itself uses this form of licensing for its products HealthShare and TrakCare.
Very Large Global Buffer Size
This version includes support for a very large global buffer pool. Previously, the limit was around 107 GB; global buffers can now be configured up to 16 TB.
Large Shared Memory Heap
This version includes support for a very large shared memory heap. Previously, the limit was around 4GB; the shared memory heap can now be configured up to 1 TB.
Eliminate Configuration-Related Restarts
The following Caché configuration options can now be updated dynamically, and do not require the system to be restarted for the new setting to take effect:
Autostart Pre-Fetch Daemons As Needed
The block pre-fetching mechanism ($PREFETCHON / $PREFETCHOFF) requires system-wide pre-fetch daemons to be initialized. This version of Caché automatically ensures that the pre-fetch daemons are started as needed, and are stopped when no longer needed, thereby eliminating the need to manually start and stop these daemons.
Improved SQL Performance Tools
With this release Caché contain additional utilities that provide useful functions for analyzing SQL behavior on production data: how many times an Index is used; identify Queries that result in table scans, or that have dependencies on building temporary structures; and identify queries based on Joins and rank how well supported they are by existing indices.
Simpler Disaster Recovery Failover And Failback
In previous releases, Caché Database Mirroring has provided an Asynchronus Mirror configuration for Disaster Recovery purposes. In this release, InterSystems has made it easier to switch over to an Asynchronous DR Mirror node in the event of a disaster (or for testing purposes); and also made it easier to switch back to the main production failover mirror at a later date.
Security
WS Reliable Messaging
With this release Web Services Reliable Messaging can be used to reliably (identify, track and manage) deliver messages between a source and a destination.
Technology Preview
This category is new with this release. It is intended as a way of introducing and providing access to new software capabilities that InterSystems believes will be useful in enhancing the effectiveness of existing and future applications.
The capabilities listed here are ready for use by customers, but they are not yet complete in functionality and design. Customers who take advantage of these capabilities must understand:
InterSystems stongly encourages those who incorporate these items in their software to provide feedback on their experiences.
Rapid Application Development
iKnow - Customized Summaries
This release of Caché contains the capability to generate custom summaries for sources. Custom summaries are developed for those who desire to tune the content of iKnow generated summaries to their specific needs.
Main parameters for tuning the summaries are the following:
The options for custom summaries can be set by means of an extra parameter in the SourceAPI.GetSummary method.
iKnow Support For Negation
This release of Caché introduces iKnow negation detection. The uniqueness of iKnow negation detection resides in the fact that not only linguistic markers of negation in a sentence such as “not”, “no” and “didn't” are detected, but that iKnow also marks their semantic scope. In the example:
John has no signs of headache but has a fever.
the linguistic negation marker is “no”. iKnow negation detection will not only detect the marker, but also detect the semantic span of the negation. This means it will establish that “John has no signs of headache” is the negative part of the sentence. The span of the negation is indicated by negation attribute markers that can be accessed and used by the following method calls:
Refactoring
Beginning in this release InterSystems has included the first support for the refactoring of code in the Studio. Initially, the available options will be:
Additional options will be incorporated in future releases.
In this release, refactoring is only available on Windows systems.
Caché 2013.1 Upgrade Checklist
Purpose
The purpose of this section is to highlight those features of Caché 2013.1 that, because of their difference in this version, affect the administration, operation, or development activities of existing systems.
Those customers upgrading their applications from earlier releases are strongly urged to read the upgrade checklist for the intervening versions as well. This document addresses only the differences between 2012.2 and 2013.1.
The upgrade instructions listed at the beginning of this document apply to this version.
Administrators
This section contains information of interest to those who are familiar with administering prior versions of Caché and wish to learn what is new or different in this area for version 2013.1. The items listed here are brief descriptions. In most cases, more complete descriptions are available elsewhere in the documentation.
Version Interoperability
A table showing the interoperability of recent releases is now part of the Supported Platforms document.
Management Portal Changes
Numerous changes have been made in the Management Portal for this release both to accommodate new features and to reorganize the existing material to make it easier to use. Among the more prominent changes are the addition of pages to assist with database mirroring and the separation of roles.
Operational Changes
This section details changes that have an effect on the way the system operates.
Check CACHETEMP/CACHE Encryption Status On Upgrade
The installer will check the encryption status of CACHE and CACHETEMP on upgrade and will ask for encryption key file location, username and password if it finds either database is encrypted. This information will be validated before file copying begins and the values will be passed to ^INSTALL.
Note:
This behavior is not avauilable for RPM and DMG kinds of installs. In these cases, database encryption should be turned off prior to upgrade with RPM/DMG installers and re-enabled afterward.
Default Answer For ^JRNSTOP Changed To No
The default answer for ^JRNSTOP has been changed from “Yes” to “No”:
%SYS>d ^JRNSTOP
Stop journaling now? No => 
This change may affect scripts that assume a default of “Yes”.
Ask User For Confirmation Before Starting Journal Restore
A new prompt is now part of the journal restore utility (^JRNRESTO). The user must confirm the restore request before journal restore actually starts. With the change, the screen output looks like this:
...
  DEFAULT: Continue despite database-related problems (e.g., a target 
  database is not journaled, cannot be mounted, etc.), skipping affected 
  updates 
  
  ALTERNATE: Abort if an update would have to be skipped due to a 
  database-related problem (e.g., a target database is not journaled, 
  cannot be mounted, etc.) 
  
  DEFAULT: Abort if an update would have to be skipped due to a 
  journal-related problem (e.g., journal corruption, some cases of missing 
  journal files, etc.) 
  
  ALTERNATE: Continue despite journal-related problems (e.g., journal 
  corruption, some missing journal files, etc.), skipping affected updates 
  
Would you like to change the default actions? No => No 

Start the restore? Yes => Yes  
This change will affect scripts that are not prepared to respond to the prompt.
Allow Mirror Dejournaling On Reporting Async Members To Be Stopped
All mirror members have a new menu item in ^MIRROR – Pause dejournaling for a database. On a backup member or an async member this allows you to notify the mirror dejournaling system to skip dejournaling to this database. This can be used if maintenance needs to be performed on a database for some reason (for example, it needs to be dismounted so it can be encrypted or decrypted).
On a disaster recovery async member or a backup a mirrored database can simply be dismounted and, if the dejournaling system runs into an error such as a <PROTECT> error, the database will be marked to be skipped and dejournaling to other databases will continue. It is a bit cleaner though to first pause the database because this drains any pending data in the dejournaling system before blocking any future records from being processed.
On a reporting member, however, dismounting a mirrored database can result in the dejournaling system shutting down for all databases in that mirror if there are subsequent records in the journal for that database. This is done because, on reporting members, sites may want to keep all databases in a given mirror in sync with each other so if there is an error in any one, dejournaling should stop there.
If you want dejournaling to continue it can then be restarted using a new ^MIRROR menu item for reporting async members, Manage mirror dejournaling on reporting member, and it will continue without the dismounted database. Alternatively, the database can be paused before it is dismounted and then dejournaling for other databases in the mirror won't shut down if there is data for the paused database in the journal stream.
System Monitor Now Extended To User Databases
Beginning with this release users may create Sensor, Subscriber, and Notification classes to extend System Monitor in non-SYS namespaces. This change requires that all SYS.Monitor.Abstract classes be changed to %SYS.Monitor.Abstract. In particular, users of SYS.Monitor.AbstractSensor must change the declaration to be %SYS.Monitor.AbstractSensor.
Use VIRTUALALLOC() and MMAP() For Larger Stack And Error Frames
The frame stack and error stack are no longer allocated as byte arrays in the partition. They are now allocated using VirtualAlloc() on Windows or mmap() for UNIX® and OpenVMS. Using this mechanism, Caché can allocate a larger frame stack with little impact on the system when the memory is not actually used. It can afford to set a larger buffer between the end of the space allowed to be used and the actual end of memory.
Error processing will now recognize that there is still unused buffer space available. So instead of popping existing frame entries to make room for executing an error trap (which risks losing important things like an application error trap), it will now reset the frame size to the actual end of the stack memory, which makes the previously unused stack space available to the error trap.
There are new $SYSTEM methods that can be used for testing the effects of this change:
Note:
In concert with this new allocation policy, the size of the execution stack, which limits the levels of DO, XECUTE, and so on that are allowed, has been doubled. This does not, in practice, double the memory load on the system unless the full memory is actually used. However, systems with many processes may experience a heavier burden on system memory and/or paging space.
It is possible that for systems where the memory usage was close to the allowed limit, this change may cause memory exhaustion.
New Return Values From System And Memory Status Check
Anew register stored in shared memory and maintained by the System Monitor tracks system health. The values stored here are:
All System Monitor subscribers may post notifications. Yellow is set when level 2 alerts are posted. Red is set when 5 alerts have occurred in 10 minutes. The health goes back to green if there are no further alerts for 1 hour.
Users can obtain the status via the following commands:
ccontrol list
ccontrol qlist
cache -cV
or programmatically via $SYSTEM.Monitor.State() which returns the values defined. See also the SetState, Alert , Clear, and ClearAlerts methods.
Third-Party Library Changes
In this release, ANTLR has been upgraded to version 3.4; Xerces has been updated to version 3.1.1 on UNIX®; CacheSSH now uses libssh2-1.4.2.
Make DNS Name Parser RFC1123 Compliant
The DNS name parser grammar that handles TCP endpoint specifications is now properly compliant with RFC1123. Previously, the parser did not allow any portion of a dotted DNS name to begin with a digit. According to RFC1123, it is only the final dotted portion of the DNS name that has this restriction in order to distinguish it from an IPv4 address in dotted quad form.
Recompile Generated Code During Install
During an install, Caché normally recompiles all user Z*, z*, %Z*, and %z* routine and classes. However, prior to this release, it skipped any routines marked as "Generated". Generated routines are routines which are derived or created by compiling other routines or classes.
Beginning with this release, a routine can be marked as generated when there is no source present. This can happen in two cases: (1) the original source is deleted; and (2) a %RO of .INT code generated by a .MAC file is marked in the %RO file as being generated (%RI, it retains the Generated flag), but has no source.
Caché now detects this case during install, and if the generated code is present, with no corresponding source for it, Caché will recompile the generated code.
$VIEW Adds Peak Memory Usage To Output
Beginning withthis release, $VIEW(-1) adds the peak memory usage, in Kb, as the 17th value returned. For example:
Set VSS= $VIEW(-1, $JOB)
Write "Peak memory usage for this process in KB is "_$PIECE(VSS, "^", 17), !
Start Shadow Servers As The User Who Started Caché
The system starts Shadow servers with the same user characteristics regardless when they are started -- whether at Caché startup or after Caché is up and running. Previously, when they were started in the later scenario (Caché is up and running), they could take on the characteristics of a different user. When that happened, process limits and file ownership might differ depending on the circumstances. Now they are always the same
Changes To $ZCONVERT
If a Unicode string ending in a high surrogate character is passed to the 4-argument form of $ZCONVERT() for UTF-8 output translation, for example,
Set S = $ZCONVERT(string, "O", "UTF8" , x)
this function now saves the last character in the local variable (x in this example). The value in x will be prepended to the input string in the next iteration.
If the string in the next iteration starts with a low surrogate character, the prepended x and the leading character are treated as a surrogate pair and translated accordingly. Otherwise, the previous high surrogate character is translated as a 3-byte sequence, and the initial character is treated individually.
The same rules apply to the JSML (Javascript/XML) translation.
Licenses Prompt During Upgrade Changed
Beginning with this release, the installation process will not ask users to enter a license key during the install. Instead, it will ask for the location of the key file. If the location is not known at upgrade time, the file can also be copied to the manager’s directory or entered via the Management Portal after the installation finishes.
Output From Ccontrol Changed
When a mirror member is in the process of transitioning to become the primary, it temporarily blocks users from signing in for part of the transition. An application which is parsing any output from attempting to enter Caché may need to be updated to be sensitive to a new message which says:
Sign-on inhibited: Transitioning to primary mirror member
ECP Recovery Of Open Transactions Across Upgrade
ECP recovery delays handling of the ECP open transactions until the networking subsystem is initialized. During an upgrade, if the system was shut down during the startup recovery, and if there were open transactions that spanned multiple journal files, the second attempt to rollback those open transactions may fail after the system upgrade.
Note:
To avoid this circumstance, make sure the system is shutdown gracefully before upgrading.
USE Permission Required For DeepSee Portal
As of this release, to use any DeepSee page, a user must have USE permission for the %DeepSee_Portal resource, in addition to other privileges required for the page. Unless you are using minimal security (which is not recommended for production environments), this change may require you to adjust your role or user definitions.
In particular, if your application includes embedded dashboards, you must provide any applicable users with USE permission for %DeepSee_Portal as well, so that they can use the dashboard viewer. In previous releases, users of embedded dashboards did not require this privilege.
Conversion Of Control Characters Changed
Begining with this release, $ZCONVERT(string, "O", "JS") and $ZCONVERT(string, "O", "JSML") will now translate the $CHAR(1) through $CHAR(7), and "/", to their hexadecimal equivalents: \x01 through \x07 and \x2F equivalently. Previously these characters passed unchanged.
If your application relies on $ZCONVERT for Javascript or Javascript Markup, you must change your application to accommodate this change – most often by using the hexadecimal equivalent of these characters.
Resource Required For Viewing %Monitor Data
In order to view data collected by the %Monitor facility via CSP, the user will need to have %Admin_Manage, %Admin_Operate, and %Developer on the relevant CSP pages and any subclass pages.
Change To Memory Usage And Allocation
In this release, the XML reader now uses local variables for storing its information; previously, it used process-private variables. This results in both a performance improvement and an additional demand on memory. Depending on the sizes of XML files read and the processing mix on the system, the memory allocation may need to be increased to avoid fatal errors. this can be done:
Platform-specific Items
This section holds items of interest to users of specific platforms.
Windows
Windows And UNIX® / Linux
The Caché internal web server has been updated to version 2.4.2 on all Windows, UNIX® and Linux platforms. The installer will automatically update httpd.conf as needed. This behavior applies to Windows install, UNIX® install, standalone CSP Gateway installation script and RPM installation for Linux.
Linux RedHat 32-Bit And 64-Bit
None.
MacOS 64
None.
PowerPC And HP-Itanium
During an upgrade, Caché now modifies the CPF file and increases the amount of memory allocated to the lock table by twice its current amount. It does this by doubling the existing locksiz parameter in the [config] section. This change also adds the same amount of memory to the gmheap parameter which is where the lock table memory is allocated from.
During an initial install, the default locksiz is now increased by twice the default, and the gmheap is also increased by the same amount.
Customers who are configuring new systems should increase the size of the lock table they use by twice the former amount, and add the same amount of size to the gmheap parameter.
OpenVMS Itanium
In this version, the file CACHE.EXE has been separated into two files: CACHE.EXE and CKERNEL.EXE.
If you use the Caché command line, you should be unaffected by this change. Running CACHE.EXE should have the same behavior as before, providing you keep CACHE.EXE and the corresponding CKERNEL.EXE in the same directory.
If you have modified CZF.C or any other source file so that CZF.EXE now does callins (the default CZF.EXE does not do any callins), then changes are necessary. The CZF.EXE image is activated by $ZF("RoutineName",...) calls. If you have built any other image that does callins, changes in how that image is built are also necessary. Previously, these images were LINKed against the CACHE.EXE shareable image. They must now be linked against the CKERNEL.EXE shareable image.
The CLINK.OPT linker options file that is installed into the [InstanceDir.source.cache] directory has been modified so that it refers to CKERNEL.EXE instead of referring to CACHE.EXE. When doing an OpenVMS LINK using CLINK.OPT/OPTIONS, you must either define the CKERNEL logical name to point at the location of the [InstanceDir.bin]CKERNEL.EXE file, or you must have a copy of CKERNEL.EXE in what is the default directory during the execution of the LINK.
If you do not use the CLINK.OPT options file when linking an image that does a Caché kernel callin, you must modify any command file or LINK command that references CACHE.EXE. Most references to CACHE.EXE must be changed to references to CKERNEL.EXE so that your build procedures can use the universal symbols defined by CKERNEL.EXE.
If you have created an executable image that calls in to the Caché kernel, that image must do a LINK as described above. However, when you execute that image, it is also necessary to locate the corresponding copy of CKERNEL.EXE. You do this by defining the logical name CKERNEL before running your image. (You previously had to define the logical name CACHE so that your executable program could find the CACHE.EXE shareable library image.) Defining the CKERNEL local name will look something like:
$ DEFINE CKERNEL Device:[InstanceDir.BIN]CKERNEL.EXE 
If the image you built is INSTALLed as a known image with the addition of the /PRIVILEGED qualifier, the logical name CKERNEL must be created with DEFINE/EXECUTIVE_MODE or with ASSIGN/EXECUTIVE_MODE. Privileged executables that activate a shared library image require the shared library image to be a known image that is located by means of an executive mode (or kernel mode) logical name.
If you have an image that dynamically activates CACHE.EXE by calling LIB$FIND_IMAGE_SYMBOL, you must rewrite your call on LIB$FIND_IMAGE_SYMBOL so that it dynamically activates CKERNEL.EXE.
Developers
This section contains information of interest to those who have designed, developed and maintained applications running on prior versions of Caché.
The items listed here are brief descriptions. In most cases, more complete descriptions are available elsewhere in the documentation.
Global Name Reservations
InterSystems reserves to itself all global names in the CACHESYS database except those that start with:
In all other databases, InterSystems reserves all global names starting with “ISC.” and “%ISC.”.
Routine Compiler Changes
None.
Routine Changes
VarArgs May Now Contain References As Well As Values
Beginning in this version, the args... syntax for receiving and passing a variable number of arguments can be used when passing an argument by reference. For example,
   set x=2,y(3)=4 
   do sub1(.x,.y,.z) 
   ; now $DATA(x)=0, y(1,2)=3, z=5 
 quit 
sub1(args...) 
 set args(2,1,2)=3 
 do sub2(args...) 
 quit 
sub2(a,b,c) 
 kill a 
 ; b(1,2)=3 and b(3)=4 
 set c=5 
 quit
Note:
If current programs are passing arguments by reference with this notation, their behavior could change because the actions of the subroutine will now affect the original variables. Before this change, they were actually passed by value so the subroutine could not affect their value.
Z*.inc And z*.inc Include Files Renamed
In this release all Z*.inc include files are renamed to ISC*.inc; and all z*.inc include files are renamed to ISCz*.inc files. This is to avoid having Caché system include file names conflict with user include file names.
Class Changes
Class Deletions
The following classes were present in the previous version and have been removed in this release
Class Component Deletions
The following class components have been moved or removed in this version from the class where they were previously found.
Class Type Name(s)
%BI.CDC method OnPage
%BI.CodeTableCSP method OnPage
%BI.DMG method OnPage
%BI.DatePicker method OnPage
%BI.EdmundPageCSP method OnPage
%BI.ExportImport method OnPage
%BI.ExportList method OnPage
%BI.Generator method OnPage
%BI.GridPivoting method OnPage
%BI.Help method OnPage
%BI.ImportList method OnPage
%BI.KnowledgeCSP method OnPage
%BI.LanguageSVGCSP method OnPage
%BI.LanguageSub method OnPage
%BI.ListFolderData method OnPage
%BI.PerfAlert2 method OnPage
%BI.RulesSetup method OnPage
%BI.Scorecard method OnPage
%BI.SystemVariable method OnPage
%BI.TimeSeries method OnPage
%BI.Trees method OnPage
%BI.UserObjectListWeb method OnPage
%BI.ValueRange method OnPage
%BI.WebADTM method OnPage
%BI.WebAnalyzer method OnPage
%BI.WebAnalyzer2 method OnPage
%BI.WebAnalyzerSetup method OnPage
%BI.WebCMeditor method OnPage
%BI.WebCdnEditor method OnPage
%BI.WebClsCom method OnPage
%BI.WebColorScheme method OnPage
%BI.WebComBank method OnPage
%BI.WebComponentKPI method OnPage
%BI.WebComponentTree method OnPage
%BI.WebCurrency method OnPage
%BI.WebDList method OnPage
%BI.WebDashboard method OnPage
%BI.WebDataCapture method OnPage
%BI.WebDocBrwsr method OnPage
%BI.WebDtAnalysis method OnPage
%BI.WebETL method OnPage
%BI.WebEmail method OnPage
%BI.WebExcelTemplate method OnPage
%BI.WebFile method OnPage
%BI.WebFold method OnPage
%BI.WebGrid method OnPage
%BI.WebKPIClass method OnPage
%BI.WebKnowledge method OnPage
%BI.WebLesenReg method OnPage
%BI.WebListbackup method OnPage
%BI.WebLnkRpt method OnPage
%BI.WebMain method OnPage
%BI.WebMain2 method OnPage
%BI.WebMainTable method OnPage
%BI.WebManEnt method OnPage
%BI.WebMapTable method OnPage
%BI.WebMessaging method OnPage
%BI.WebMessagingExt method OnPage
%BI.WebMultiSites method OnPage
%BI.WebOCR method OnPage
%BI.WebPivTable method OnPage
%BI.WebPrinter method OnPage
%BI.WebPrn method OnPage
%BI.WebSCActions method OnPage
%BI.WebSMS method OnPage
%BI.WebSQLComGen method OnPage
%BI.WebSVG method OnPage
%BI.WebSVGTest method OnPage
%BI.WebSchema method OnPage
%BI.WebSchemaMain method OnPage
%BI.WebSecCorrection method OnPage
%BI.WebShortcut method OnPage
%BI.WebSqlWiz method OnPage
%BI.WebStoredProc method OnPage
%BI.WebSysFn method OnPage
%BI.WebTAClassDialogBox method OnPage
%BI.WebTableList method OnPage
%BI.WebTaskMgmt method OnPage
%BI.WebTransformation method OnPage
%BI.WebTranslationD method OnPage
%BI.WebUsersMtn method OnPage
%BI.WebUtil method OnPage
%BI.WebWorkFlow method OnPage
%BI.WebWorkFlowE method OnPage
%CSP.Login method DrawLogout
%CSP.UI.DocLocalize method DatabaseFreespaceCleanup, DatabaseFreespaceCompact, DatabaseFreespaceList, Journal, RemoteDatabase, RemoteDatabases
%CSP.UI.Portal.ClassList method allowSelectRow
property AllowSelectRow
%CSP.UI.Portal.DatabaseFreespace method clearSpace
%CSP.UI.Portal.DatabaseFreespaceCleanup method DrawTitle1
property msgValidate
%CSP.UI.Portal.DatabaseFreespaceCompact method DrawTitle1
property msgValidate
%CSP.UI.Portal.Dialog.ExportResource property ActionDone
%CSP.UI.Portal.ProcessDetails method doOwnerDrawTabs, drawOneTab, drawTabs, startRefresh, tabClicked
property TABAREAHEIGHT, TABHEIGHT, TABMAXWIDTH, TABOVERLAP, TABRADIUS, TABTEXTMARGIN, TABTOPREDUCTION, TEXTVOFFSET
%CSP.UI.Portal.RoutineCompare method getHTML
%CSP.UI.Portal.RoutineList method allowSelectRow
property AllowSelectRow
%CSP.UI.System.SecurityAdvisorPane property readOnly
%DeepSee.Report.UI.ExecuteReport method showFileSelectionWindow
%DeepSee.Report.UI.ExtractDSS property nameSpace
%DeepSee.Report.UI.reportModelServer method ServerCommand
%DeepSee.Report.UI.schemaEditPanel method IsSQLReservedWord, processFieldName
%DeepSee.UI.Dialog.DashboardSave method DrawIcons, selectLayout, updateGridControls
property dashboardDescription, dashboardGridCols, dashboardGridRows, dashboardKeywords, dashboardLayout, dashboardLocked, dashboardModify, dashboardResize
%DeepSee.UI.TermListManager method columnClick
%DeepSee.UI.WorksheetBuilder method CreateDataSet, GetLookupArray, GetWSData, LookupReferences, SaveToServer, SetRecord, applyChange, changeCell, changeColumn, changeGrid, changeRow, clearStyles, deleteItem, editCellHandler, editFormatString, getCellValue, getCurrPageCount, getCurrPageSize, getLogicalValue, gotoGridPage, gridChange, gridEditKeyDown, gridEditKeyUp, gridRender, initEngine, loadDataConnector, loadWorksheet, moveColumnLeft, moveColumnRight, moveRowDown, moveRowUp, nextGridPage, numberToColumn, prevGridPage, printWorksheet, recalc, renderNavBar, resolveFormulaRefs, selectCellHandler, selectColumn, selectGrid, selectRow, setActionTarget, setRecordValue, textEditorKeyup, textOKClicked, toggleSettings, updatePropertyPanel, updateStyleControls
property currPage, dataConnector, gridMode, gridSelected, pageSize, selectedColumn, selectedRow, worksheetDescription, worksheetKeywords, worksheetLocked, worksheetOwner, worksheetPublic, worksheetResource
%DeepSee.UserPortal.DashboardViewer method SaveDashboardToFolder, addWidget, editWidget
%DeepSee.UserPortal.Home method DrawFoldersList
%Library.EnsembleMgr method AddDelegated, CreateFoundationResources, EnableFoundationNamespace, GetHealthShareNamespaceType, InstallFoundationSecurity, IsFoundationInstalled, IsHealthShareInstalled, IsViewerInstalled, ValidateHealthShare, map2hslib, moveHSSiteDefaultFiles, unmaphslib, upgradeUTCIndices
%Library.RoutineMgr method IsServerOnly
%Library.SQLCatalog method GetCachedQueryInfo, MakePat, SQLCODEListClose, SQLCODEListExecute, SQLCODEListFetch, SQLCachedQueryInfoClose, SQLCachedQueryInfoExecute, SQLCachedQueryInfoFetch, SQLCachedQueryTableClose, SQLCachedQueryTableExecute, SQLCachedQueryTableFetch, SQLChildTablesClose, SQLChildTablesExecute, SQLChildTablesFetch, SQLConstraintsClose, SQLConstraintsExecute, SQLConstraintsFetch, SQLFieldsClose, SQLFieldsExecute, SQLFieldsFetch, SQLForeignKeysClose, SQLForeignKeysExecute, SQLForeignKeysFetch, SQLIndicesClose, SQLIndicesExecute, SQLIndicesFetch, SQLParentTableClose, SQLParentTableExecute, SQLParentTableFetch, SQLProcedureInfoClose, SQLProcedureInfoExecute, SQLProcedureInfoFetch, SQLProceduresClose, SQLProceduresExecute, SQLProceduresFetch, SQLRelationshipsClose, SQLRelationshipsExecute, SQLRelationshipsFetch, SQLReservedWordsClose, SQLReservedWordsExecute, SQLReservedWordsFetch, SQLTablesClose, SQLTablesExecute, SQLTablesFetch, SQLTriggersClose, SQLTriggersExecute, SQLTriggersFetch, SQLViewFieldsClose, SQLViewFieldsExecute, SQLViewFieldsFetch, SQLViewInfoClose, SQLViewInfoExecute, SQLViewInfoFetch
%Library.SQLCatalogPriv method SQLRolePrivilegesClose, SQLRolePrivilegesExecute, SQLRolePrivilegesFetch, SQLRoleUserClose, SQLRoleUserExecute, SQLRoleUserFetch, SQLRolesClose, SQLRolesExecute, SQLRolesFetch, SQLUserExistsClose, SQLUserExistsExecute, SQLUserExistsFetch, SQLUserPrivsClose, SQLUserPrivsExecute, SQLUserPrivsFetch, SQLUserRoleClose, SQLUserRoleExecute, SQLUserRoleFetch, SQLUserSysPrivsClose, SQLUserSysPrivsExecute, SQLUserSysPrivsFetch, SQLUsersClose, SQLUsersExecute, SQLUsersFetch
%Library.SysLog method ConfigurePage, DecodeData, OnPage, RenderBanner, ServeStyleSheet, ShowDataPage, ShowLogPage
%MV.Adaptor parameter MVAUTOLOCKED
%SQL.Manager.Catalog method CachedQueryInfoClose, CachedQueryInfoExecute, CachedQueryInfoFetch, CachedQueryTableClose, CachedQueryTableExecute, CachedQueryTableFetch, ConstraintsClose, ConstraintsExecute, ConstraintsFetch, FieldCalcSelectivityClose, FieldCalcSelectivityExecute, FieldCalcSelectivityFetch, FieldCurrentSelectivityClose, FieldCurrentSelectivityExecute, FieldCurrentSelectivityFetch, FieldsClose, FieldsExecute, FieldsFetch, IndicesClose, IndicesExecute, IndicesFetch, MakePat, NamespacesWithXdbcErrorsClose, NamespacesWithXdbcErrorsExecute, NamespacesWithXdbcErrorsFetch, ProcedureInfoClose, ProcedureInfoExecute, ProcedureInfoFetch, ProceduresClose, ProceduresExecute, ProceduresFetch, PropertyInfo, RWListClose, RWListExecute, RWListFetch, SQLCODEListClose, SQLCODEListExecute, SQLCODEListFetch, SchemasClose, SchemasExecute, SchemasFetch, SchemasOnlyClose, SchemasOnlyExecute, SchemasOnlyFetch, TablesClose, TablesExecute, TablesFetch, TablesOnlyClose, TablesOnlyExecute, TablesOnlyFetch, TriggersClose, TriggersExecute, TriggersFetch, ViewFieldsClose, ViewFieldsExecute, ViewFieldsFetch, ViewInfo2Close, ViewInfo2Execute, ViewInfo2Fetch, ViewInfoClose, ViewInfoExecute, ViewInfoFetch, ViewsOnlyClose, ViewsOnlyExecute, ViewsOnlyFetch, XdbcErrorsClose, XdbcErrorsExecute, XdbcErrorsFetch
%SYS.ProcessQuery method PPGClose, PPGExecute, PPGFetch
%SYS.Task.IntegrityCheck method DirectoryIsValid
%SYSTEM.Event method DefinedIP, ListIP, SignalIP
%UnitTest.Report method DeleteSuite, GetTestColor, GetTestState, NoNamespace, ShowAsserts, ShowCases, ShowIndices, ShowMethods, ShowSuites, writeStyle
%XML.Node method AppendChild, InsertChild, ReplaceNode
%ZEN.Portal.assistedText method ghostGotFocus
%ZEN.Report.Display.COSChart.cchart method calculateYAxisWidth
%iKnow.DeepSee.Dimensions.Dictionaries method GetId
%iKnow.DeepSee.UI.Analysis.AbstractAnalysis method GetDomainId, GetFilter
%iKnow.DeepSee.UI.Analysis.Content method SetListing
%iKnow.DeepSee.UI.Analysis.Entities method GetDetailChartData, GetDetailLabelX, GetSelectedItemName, ReBuildEntityList, SetSelectedCell, getDetailChartDataClient, getDetailLabelXClient
%iKnow.Domain property SortField
%iKnow.Matching.DictionaryAPI parameter GetDictionaryElementsRT
%iKnow.Matching.MatchingWSAPI.InvalidateMatchingResults property keepEntUniMatches
%iKnow.Queries.MetadataWSAPI.AddField property buildBitstring
%iKnow.Queries.MetadataWSAPI.UpdateField property buildBitstring
%iKnow.Queries.MetadataWSAPI.UpdateFieldById property buildBitstring
%iKnow.Queries.SourceAPI method GetByEquivalentIds, GetByEquivalents
%iKnow.UI.AbstractPortal method GetDomain, GetTerm
%iKnow.UI.IndexingResults method GetSentFrom, GetSentTo
Ens.Enterprise.Portal.EnterpriseSearch parameter AssistantClass
Ens.Enterprise.Portal.MsgFilter.Filter method DeleteFromTemp, LoadFromTemp, SaveToTemp
Ens.Enterprise.Portal.SystemList method getSSLConfigList, getSoapCredentials
Ens.Rule.Model.ruleDefinition method test
Method Return Changes
The following methods have different return values in this version of Caché:
Method Signature Changes
The following methods have different signatures in this version of Caché:
Class Name Method Name(s)
%CSP.UI.Portal.Config.ZenReport SaveData
%CSP.UI.Portal.DatabaseFreespaceCleanup GetSize
%CSP.UI.Portal.DatabaseFreespaceCompact GetFreeSpace
%CSP.UI.Portal.RoutineList doFullView
%CSP.UI.System.GlobalDrillPane SaveChange
%DeepSee.AbstractKPI %GetFilterLogicalValue
%DeepSee.Component.pivotController showMessage
%DeepSee.Component.pivotTable getDataSourceCaption
%DeepSee.Dashboard.Utils %GetMembersForFilter
%DeepSee.QualityMeasure.Utils %GetQualityMeasureClass
%DeepSee.Report.UI.CreateDCR scanForFieldNames
%DeepSee.Report.UI.reportPreviewer GeneratePresentationReport
%DeepSee.Report.UI.schemaEditPanel autopopulateDBItem, makeNode
%DeepSee.UI.WorksheetBuilder gridKeyDown
%DeepSee.UserLibrary.FolderItem %CheckResource
%DeepSee.UserPortal.DashboardViewer navGetContentForLevel, navSelectItem, widgetSelected
%DeepSee.UserPortal.Home refreshFolders, setFolderCategory
%DeepSee.UserPortal.standardPage navSelectItem
%DeepSee.extensions.iKnow.ClassifierBuilder genCrcTable
%Library.AbstractStream Read
%Library.CacheCollection CollectionToDisplay, DisplayToCollection
%Library.GTWCatalog SQLTablesExecute, SQLTablesJExecute
%Library.GlobalEdit CollationSet, CompactGlobal, Open
%Library.GlobalStreamAdaptor Read, ReadLine
%Library.RegisteredObject %OnValidateObject
%Library.RoutineMgr ImportItemListExecute, getBackupList, getPackageList
%Net.Remote.Service RunStartCmd, StartGateway, StartGatewayObject
%Net.Remote.Utility RunCommandViaCPIPE, RunCommandViaZF
%SOAP.Addressing.Properties GetDefaultRequestProperties
%SQL.Util.Procedures CSV, CSVTOCLASS
%SYS.PTools.SQLStats GetStats, GlobalSave
%SYSTEM.OBJ Load
%SYSTEM.iKnow IndexDirectory, IndexFile
%Stream.Object Read
%Stream.TmpCharacter Read
%Studio.Extension.Base OnAfterAllClassCompile, OnAfterClassCompile
%Studio.SourceControl.ISC BaselineExport, BaselineExportItem
%WebStress.Record Run
%XML.ImportHandler SerializeBase64Node, SerializeNode
%XML.Node AppendCharacter, AppendElement, InsertCharacter, InsertElement
%XML.Security.Signature ComputeSha1Digest
%ZEN.Auxiliary.jsonProvider %WriteJSONFromArray, %WriteJSONFromObject, getDataSourceCaption
%ZEN.Controller InvokeClassMethod, InvokeInstanceMethod
%ZEN.Dialog.fileSelect RebuildLookin
%ZEN.Portal.assistedText doAction
%ZEN.Report.Display.COSChart.cchart createSVGTextNode, getYAxisTitle, renderYAxisTitle, renderYLabels
%ZEN.Report.PrintServer %ServeTransformAndPrint
%ZEN.SVGComponent.chart calculateYAxisWidth, createSVGTextNode, getYAxisTitle, renderYAxisTitle, renderYLabels
%ZEN.SVGComponent.radialNavigator drawNode
%ZEN.SVGComponent.tabBar drawOneTab
%iKnow.Configuration %OnNew
%iKnow.DeepSee.UI.Analysis.Entities GetChartData, GetLabelX, getChartDataClient, getLabelXClient
%iKnow.Domain %OnNew
%iKnow.Filters.Filter GetFilteredCcFrequency, GetFilteredCcSpread
%iKnow.Matching.MatchingAPI GetTopMatchesByDictionaryItemId, InvalidateMatchingResults
%iKnow.Matching.MatchingQAPI InvalidateMatchingResults
%iKnow.Matching.MatchingWSAPI GetTopMatchesByDictionaryItemId, InvalidateMatchingResults
%iKnow.Queries.MetadataAPI AddField, UpdateField, UpdateFieldById
%iKnow.Queries.MetadataI AddField
%iKnow.Queries.MetadataQAPI AddField, UpdateField, UpdateFieldById
%iKnow.Queries.MetadataWSAPI AddField, UpdateField, UpdateFieldById
%iKnow.Source.Lister SetConfig
%iKnow.Source.Processor %OnNew
%iKnow.Utils.MaintenanceAPI AddUserDictionaryEntry
%iKnow.Utils.MaintenanceQAPI AddUserDictionaryEntry
%iKnow.Utils.MaintenanceWSAPI AddUserDictionaryEntry
Backup.General ExternalFreeze
Config.NLS.Locales ImportDir
Config.NLS.SubTables ImportDir
Config.NLS.Tables ImportDir
Ens.Director StartProduction
Ens.Enterprise.Portal.MsgFilter.EnterpriseAssistant EnumerateExecute
Ens.Rule.Generator generateActions, generateOneAction, generateOneRuleSet
Ens.Rule.Model.expression constructCOS, convertToCOS, test
SYS.Database Defragment
SYS.Monitor.Health.Chart %OnNew
JavaGatewayService Class Deprecated
In this release the %Net.Remote.Java.JavaGatewayService class has been deprecated. This was an internal class; it was not documented for external use.
If you have developed custom code that relies on this class, you should update the code to instead use the %Net.Remote.Service class that incorporates the functionality of the deprecated class.
Object Synchronization
If an object is synchronized to a namespace which does not contain the class, the Caché will now catch the <CLASS DOES NOT EXIST> error and log it rather than abandoning the synchronization attempt. This gives the application the ability to more gracefully recover from the error.
If an application expected a failure in this case, it must be modified to check the error reported and handle the error condition.
Change Collation Handling In %Library.GlobalEdit.Create()
Either the external collation name (e.g. "Spanish2") or its internal number (e.g. 32) can now be used as the 3rd argument to %Library.GlobalEdit.Create(). If the specified collation is invalid or is not loaded, an error is generated. Previously, this method would accept only the numerical value, and silently use the database default collation if it were invalid.
Fix To Symbol Binding For Delimited Identifiers
A defect that caused an identity property to not be set when saving a new object has been fixed. If a class defines a property whose name is a delimited identifier as the IDENTITY property, the property was not properly set following an insert.
HTTP Changes
In this release, by default, if you reuse an instance of %Net.HttpRequest to send multiple requests, Caché sends all the messages over a single HTTP socket (using a HTTP 1.1 keep-alive connection). Specifically, Caché keeps the TCP/IP socket open so that Caché does not need to close and reopen it. For information on disabling this keep-alive behavior, see Managing Keep-alive Behavior in the chapter “Sending HTTP Requests and Reading Responses” in Using Caché Internet Utilities.
Change%Net.Remote.DotNet.Test To Accommodate New Directory Structure
Beginning with this version, Caché has two directories for .NET Gateway: one for Version 2.0, and the other for Version 4.0. The test method ListTypeLibs() of the class %Net.Remote.DotNet.Test now references the directory for Version 2.0 by default. Users may change the version by executing:
Do ##class(%Net.Remote.DotNet.Test).ListTypeLibs(port,,"4.0")
where port is a valid port number not in use at the time of the call.
Resource Requirements For Studio Source Control
With this release, the %Developer resource is needed to use the following Studio Source Control classes: %Studio.SourceControl.UI, %CSP.StudioTemplateInsert, and %CSP.StudioTemplateSuper.
Class Compiler Changes
This version of Caché continues the work begun in earlier releases of improving the class compiler. The changes that may require changes to applications are detailed in this section.
IDs Used For Bitmap Index Must be Integers
The class compiler will now report an error if the class uses %CacheSQLStorage and attempts to define a bitmap index map and the ID of the table is not an integer type.
If your tables use SQL Storage, and there is an IDKEY index on the table, and the IDKEY is not defined on a single field that has a datatype with an SqlCategory of INTEGER, the following error will be reported:
Compiling class User.MyTable
ERROR #5485: Bitmap indices are only supported when the IDKEY is based on a single positive integer attribute 
 ERROR #5030: An error occurred while compiling class User.MyTable
Prior to this change, if a bitmap index map was defined, no check was performed for SQL Storage to make sure the ID was compatible.
Note:
Any existing applications that have tried to use this probably have bad index data if the ID contains anything but positive integers. In this circumstance, the index should be deleted and rebuilt.
Multicompile Is On By Default
Beginning with this release, the ability to use multiple processes to speed compilation, or loading XML classes from a directory, (“/multicompile”) is enabled by default. To change the default to off for a system you can execute:
  Do $SYSTEM.OBJ.SetQualifiers("/multicompile=0", 1)
Projections Now Utilize Multiple Jobs
When you run a class compile with /multicompile turned on, Caché will now run the class projection calls to CreateProjection using the worker jobs in the same way it compiles classes. This improves the performance of this phase of the compile if class projection code is doing a significant amount of work.
Most projection code will continue to function as it has prior to this change; however, the two areas that should be noted are:
  1. Projections may be run in multiple, simultaneous jobs so if a projection is using $JOB to store information to co-ordinate with other projection code it should change to use %ISCName which will be defined and be the same amongst all multicompile jobs.
  2. It is important to lock data when you need exclusive access to prevent interference. With multiple projections running at the same time, there is a chance another projection may be manipulating the same data structure in another process. This was a potential issue prior to this change when you compiled the two classes at the same time in different jobs, but with multicompile it makes the chance of this occurring higher.
Notice Of Serial Property Change
In prior versions, the REQUIRED constraint was never effectively enforced. It will be in the next version.
Any existing application with properties whose type class is %Library.SerialObject and are defined as REQUIRED will now see that constraint enforced. This can cause objects that once saved to no longer save without error if the referenced serial object is modified or swizzled.
Parameter Properties Format Changed
The stored format of parameter values for compiled programs has been changed to be a $LIST. If your application parses the stored value of a parameter using SQL, it will need to be changed. The new method GetParameterValue has been added with the %Dictionary to assist in this. Also, the query %Dictionary.LegacyQuery will return the values in the previous format.
Language Binding Changes
XEP EventPersister Changes
The OPTION_REFERENCES and OPTION_INHERITANCE (and related flags) have been removed. After removal of these two options, no options are left and the EventPersister.setOption and getOption methods have also been removed.
Since these last two options are really generation/import time flags, the following two importSchema flavors have been added in their place:
String[] importSchema(String classOrJarFileName, int options)

String[] importSchema(String[] classes, int options)
where the options are:
Changes To Enum Handling
This release changes the projection of Java and DotNet enums. Names, and not ordinal positions, are now stored on the Caché side. This change should be completely transparent for new applications.
Old applications, that already have some enums stored, will have to delete and then re-import the data to avoid errors.
SQL Changes
The SQL Filer No Longer Calls IsValid For Reference Properties
The SQL Filer will no longer call the <property>IsValid method for a reference to a persistent class (for example, the Sample.Person.Spouse property). It is rare that a <property>IsValid method would even exist (it must be defined by the developer of the class). The Object %Save method does not call <property>IsValid methods for properties of type persistent or serial either, so now the Object and SQL filers are in sync in this behavior.
If an application depends on this behavior, the reference will have to be validated in another way, perhaps through a trigger.
Correction To StorageToLogical And LogicalToStorage
This release corrects an existing problem storage and retrieval of list or array collections where StorageToLogical and/or LogicalToStorage methods were defined for the property or datatype of the property. Previously, Caché was not properly applying the StorageToLogical or LogicalToStorage to each element of the collection. Now it does with the effect that the returned values for list or array collections may differ from previous releases.
Correct Translation Of Delimited Identifier To Numeric Literal
A Dynamic SQL bug that caused a delimited identifier to be translated into a numeric literal has been fixed. Previously, when a delimited identifier that is also a valid numeric literal was encountered by the statement preparser, it would be translated into a numeric literal. For example, in the query:
SELECT Name FROM Sample.Person WHERE  %ID = "1"
the literal “1” was interpreted as the integer value 1. The correct translation is that the delimited value "1" is retained and the statement will now report an error when prepared.
Correction To TRUNCATE SCALE In DISPLAY Mode
Previously, “{fn TRUNCATE(value, number)}” where number is greater than 0 and not 2 would display the wrong SCALE for the results when the column was selected in DISPLAY mode; the output of the result in DISPLAY mode would always use a SCALE of 2.
Now the output is properly scaled.
When DDL Compiles A Class, Compile Sub-Classes Too
When an SQL DDL statement is executed and a class definition needs to be compiled, the class now compiled using the “b” flag. This will compile any sub-classes for this class. This behavior is needed for many types of DDL statements, for example, where an index was added to a class with a CREATE INDEX statement, and the class has a subclass. Without this, the building of the index will not work for any rows in the subclass extent until the subclass has been compiled.
Note:
It is thought to be rare that customers run DDL against tables where the class has subclasses.
SQLTablePrivileges And SQLColumnPrivileges Changes
In prior versions, the ODBC SQLTablePrivileges and SQLColumnPrivileges catalog queries, along with the JDBC getTablePrivileges and getColumnPrivileges catalog queries, would only return privileges where the current user was the grantee of the privilege or a role held by the user was a grantee of the privilege. Now a row is also returned if the current user is the grantor of the privilege.
DROP TABLE From Management Portal Subject To Checking
In this release, you will no longer be able to drop a table, view, or procedure from the Management Portal if DDLAllowed=False is defined in the class that projected the SQL object.
Note:
This does not apply for linked tables. If a class is defined as a linked table, the Drop action will drop the linked table on the local system even if the linked table class is defined as DDLAllowed=0; but it will not drop the table this link references on the server he actual table resides on.
Compiled Names Of Queries Have Changed
In previous versions, if embedded SQL defined a query within a routine or method, and the routine or method was called recursively, the generated name of the cursor would cause the earlier value to be overwritten by the later statement execution. Unpredictable results ensued.
Begining in this release, the SQL Query Processor has changed how cursor variable names are generated and each compile of the statement will generate a different variable name. If application code is relying on SQL to generate certain variable names for an SQL cursor, this code will likely need to be updated to not rely on the variables names generated by SQL. SQL Cursor names must still be unique within a single routine or class method.
Statement-Level AFTER Triggers No Longer Recurse
In this version, the following changes have been made to how statement-level triggers AFTER behave:
  1. In previous versions, an AFTER statement level trigger was only executed if SQLCODE for the statement was 0. Now the trigger will be executed if SQLCODE for the statement is >=0. This means that if the statement does not find any rows to INSERT, UPDATE, or DELETE (SQLCODE = 100), the trigger is now executed.
    This behavior is required for proper behavior of language=TSQL triggers.
  2. Caché now prevents AFTER statement-level triggers from executing recursively.There are a couple of ways triggers can recursively call themselves. Direct recursion is when a table T1 has a trigger which performs the same operation on table T1. Indirect recursion can also occur if table T1 has a trigger that performs an insert into table T2 and table T2 has a trigger that performs an insert into table T1. Another example of indirect recursion is when table T1 has a trigger that calls a routine/procedure and that routine/procedure performs an insert into T1. With this change, when recursion occurs the trigger will not be executed if it detects it has been called previously in the execution stack. No error will be returned when either type of recursion is encountered, the trigger will simply not execute a second time.
    There are a couple of ways triggers can recursively call themselves.
    With this change, when recursion occurs the trigger will not be executed if it detects it has been called previously in the execution stack. No error will be returned when either type of recursion is encountered, the trigger will simply not execute a second time.
Important:
Recursion protection is only performed for AFTER statement-level triggers. If recursion is attempted in a BEFORE statement-level trigger, a runtime <FRAMESTACK> error may occur if the trigger code does not handle the recursion itself.
Note:
A statement level trigger with language Caché that attempts to define direct recursion via embedded SQL will fail to compile with a <FRAMESTACK> error. If your application requires recursion for a Caché trigger, indirect recursion must be used. This can be as simple as using Dynamic SQL or Deferred SQL instead of embedded SQL in the trigger code.
%sqlcontext No Longer Automatically Created
In Release 2009.1, an embedded SQL CALL statement began to NEW the %sqlcontext variable during its execution and remove it upon return. Beginning with this release, this no longer happens except when the statement contains a USING clause.
iKnow Changes
Proximity Value Format Change
Beginning with this version, the signature of the proximity data value has changed. Previously, it was defined as a decimal value, but this caused problems in conversion when using certain C++ libraries. Now, the decimal proximity value is represented as an integer with a value between 0 and 256. This allows for an appropriate range without suffering loss of precision in using the library.
Access To iKnow UI Classes
Beginning with this release, access to the user interface pages of iKnow (%iKnow.UI.*) as well as the class, %iKnow.Queries.AbstractWSAPI, and any generated subclasses will need %Developer.
XML Changes
%XML.TextReader Use Of Temporary Storage
The development of %XML.TextReader predated the appearance of process-private globals; it used a hard-coded reference to ^CacheTemp for its temporary storage. beginning with this release %XML.TextReadernow uses the process-private global, ^||CacheTemp, and adds an option to change the global name via an additional parameter on the ParseXXX() class methods.
In the rare case where an application has subclassed %XML.TextReader and added its own code, the application will have to fix up the hard-coded global references.
Web Services And SOAP Changes
New Keep-alive Behavior
In this release, by default, if you reuse a Caché web client instance to send multiple request messages, Caché sends all the messages in a single HTTP transmission (using a HTTP 1.1 keep-alive connection). Specifically, Caché keeps the TCP/IP socket open so that Caché does not need to close and reopen it. For information on disabling this keep-alive behavior, see Disabling Keep-alive for a Web Client in the chapter “Fine-tuning a Caché Web Client” in Creating Web Services and Web Clients in Caché’.
Change to SOAP Body Available to ProcessBody()
If you have customized a web service by implementing ProcessBody(), you might need to modify that method. In previous releases, ProcessBody() provided access to the SOAP body as is, without all the XML namespace prefix definitions. That is, when you called the Read() method of the requestBody argument of ProcessBody(), Caché returned the body without all namespace prefix definitions. In this release, the returned body includes any prefix definitions which may have been done in the Body or Envelope elements.
XMLNAME Parameter Included in Generated Methods
In some cases, the SOAP wizard now includes the XMLNAME parameter in the web methods in the web service and web client that it generates. This occurs if the WSDL defines the return type of a web method in terms of an element whose name does not follow the form MethodNameResult. For example, in many WSDLs, the return type of a web method is defined like this:
<s:element name="TestResponse">
    <s:complexType>
        <s:sequence>
            <s:element name="TestResult" type="s:string"/>
        </s:sequence>
    </s:complexType>
</s:element>
In some cases, the return type is defined like this instead:
<s:element name="TestResponse">
    <s:complexType>
        <s:sequence>
            <s:element name="MyOutput" type="s:string"/>
        </s:sequence>
    </s:complexType>
</s:element>
In such cases, the SOAP wizard now includes the XMLNAME parameter in the generated web methods as follows:
Method Test(a As %String) As %String(XMLNAME="MyOutput") [ ... ]
{
...
}
Support REQUIRED Keyword For Web Services
The SOAP Wizard is now modified to now add REQUIRED=1 for required arguments. This has no affect on the behavior of the service or client; it affects the the WSDL which is created from a service.
The REQUIRED parameter is allowed for web method arguments to influence the generated WSDL. REQUIRED=0 (the default) results in minOccurs=0 in the WSDL. This change also adds support for the REQUIRED parameter in the return type. The default for the return type was REQUIRED=1, however, now REQUIRED=0 is valid and affects the WSDL.
The SOAP Wizard is also modified to now add REQUIRED=1 for required arguments.
XML Prefix Definitions Now In Request Stream Passed To ProcessBody
Previously, when calling ProcessBody call of web service, the body was copied as is. Beginning with this release, the body now includes any prefix definitions which may have been done in the Body or Envelope elements. Any code that depends on the exact form of the request including missing prefix definitions (for example, to add these definitions) must be modified to accommodate the new information.
Correct Processing Of Signed Requests When Using MTOM
When signing and validating signature for MTOM SOAP messages, the attached streams must be substituted for the MTOM reference before before computing the digest of the message body. Previously, the body including the references was incorrectly signed without substituting for the MTOM Include elements.
Note:
Caché will no longer interoperate correctly with web services that incorrectly do the signing before the substitution.
WebStress And UnitTest Classes Restricted To Developers
In this release, use of the %WebStress.Portal and %UnitTest.Portal classes requires the user to have the %Developer resource. Customers may also have to manually open up access to these classes by setting the ^SYS("Security","CSP") global as documented in Application Access To %CSP Pages Now Controlled to allow access to these classes via CSP.
MultiValue Changes
Log File Switching
When the mv.log file grows larger than 5MB (or the size limit of cconsole.log) it will be renamed and logging will start with a new file. This action is done by the %SYS.Task.PurgeErrorsAndLogs task.
Emulations @(–nn) Correction
For a number of MultiValue emulations, the @(-nn) implementations were wrong. These are all derived from the original Universe emulation and, since Universe doesn't differentiate between @(-nn) codes in its emulations, neither should Caché. For example, Caché doesn't provide a PRIME emulation, it provides a "PRIME as emulated on UNIVERSE" emulation.
The emulations affected are PICK, PRIME, PIOPEN and IN2. Applications will need source code changes if they use any of the following @(-nn) codes:
Changes To Handling Accounts In Root Directory
Beginning with this release:
Any automated procedure that deletes accounts unattended should be modified to include the “N” option in the command line. If this cannot be done then a lowercase “n” on attribute 5 of the DELETE.ACCOUNT verb will revert to the old behavior as a temporary measure.
Changes To TANDEM Command
The TANDEM command includes several new changes in this release.
  1. Input handling
    In previous releases, if the tandem slave was sleeping at an INPUT statement, then the tandem master could not interrupt the INPUT statement. This could often render the use of TANDEM less useful.
    With this change, once a tandem slave allows a future session (see below), then all INPUTs will have a maximum of 60 second timeout allowing a tandem master to interrupt with a maximum of a 60 second wait. Although the tandem slave process is continually doing timed out inputs, the application will not see this and will behave as normal.
  2. Future TANDEM Sessions
    A slave terminal can allow a future TANDEM session by executing one of the following commands: TANDEM ON; TANDEM SYSPROG; or TANDEM (N).
    All these 3 variants allow an optional numeric parameter to determine the timeout to apply during INPUT statement processing. The default is 60 seconds, as noted earlier. For example, to change the INPUT timeout to 10 seconds, you can do one of the following: TANDEM ON 10, TANDEM SYSPROG 10 or TANDEM 10 (N).
    By choosing a lower timeout value, it means that when a tandem master is initiated, if the slave is processing an INPUT statement then the master has to wait less time for an initial response. The downside of a lower timeout value is a marginal increase in CPU overhead during INPUT processing.
    Note that once the master has initiated a sequence with the slave, this timeout value no longer applies -it is purely for the initial connection.
  3. “(A)” Option
    The (A) option allows you to use <CTRL-A>as a sequence identifier instead of the ESCAPE key. For example, normally when you start a master sequence you do this SYSPROG:TANDEM 6 TANDEM to port 6 in VIEW ONLY mode. To exit TANDEM, enter ESC + “X”
    With the (A) option, the ESCAPE is replaced with <CTRL-A> so to TANDEM enter <CTRL-A> “X”.
  4. Input History Buffer
    A Tandem slave now keeps the last 20 INPUT statements in a circular buffer. The master can now see this history using the ESCAPE + “H” sequence (or <CTRL>A + “H”if the “(A)” option is in use). This will allow an operator to get some idea of what the slave process has recently been doing.
  5. Terminal independence in MultiValue is obtained using calls to CommandInit() and CommandNext(). These allow an application to easily interpret characters from keyboards. For example if you press an arrow key on some keyboards, instead of returning 3 characters (CHAR(27):“[A”) it would return an identifier saying "CURSOR UP". These functions did notwork very well when using TANDEM and the program would instead see 3 characters. This has been fixed now. The MultiValue editor JED uses these commands, and so now you can JED edit an item using TANDEM.
  6. Double Echoed Characters
    Due to an error, when a tandem master was in FEED mode (that is, sending keystrokes to the slave terminal), then these keystrokes would double-echo on the master terminal. This has now been fixed.
SP-ASSIGN Command Line Syntax Changes
This release makes slight changes to the syntax of the SP-ASSIGN command make it more compatible and remove anomolies:
Rebuilding Indices From Prior Releases
Multivalue users who upgrade their applications from a release prior to 2012.1 to 2012.1 or later may experience a slowdown in CMQL queries that had previously made use of an index. Previously, CMQL assumed the collation for left-justified strings was SPACE. It is now SQLSTRING(150). This will not match an existing index that was created with the previous default of SPACE collation.
To correct this issue, use studio to edit the class associated with the multivalue file and change the COLLATION parameter to SQLSTRING(150) on all properties that are used as index keys. Then rebuild the affected indexes.
Changes To Transaction Lock Handling
In previous releases, committing a transaction would release all locks held on the records involved. Beginning with this release, that behavior has changed. It now follows these rules:
  1. Any operation that creates or frees a lock during a nest of transactions will have any release of the lock delayed until execution of the COMMIT or ROLLBACK that exits the outermost transaction in the nest. Furthermore, any lock that is promoted from SHARED lock type to EXCLUSIVE lock type during a nest of transactions will have any demotion of that lock delayed until the exit from the outermost transaction in the nest.
    This behavior will be followed without exception, even in preference to subsequent rules.
  2. Numbered or named locks that are created and freed by the MVBasic LOCK and UNLOCK statements are not incremented. You can do any number of “LOCK 2” statements, but a single “UNLOCK 2” statement will free lock number 2.
    None of the file locks or the record locks are incremented.
  3. If a FILE or RECORD is locked with either the SHARED or EXCLUSIVE lock type on entry to an outermost transaction, then on exit from the outermost transaction (with either a COMMIT or a ROLLBACK) that FILE or RECORD will still be locked with the same lock type.Locks promoted from SHARED to EXCLUSIVE inside the transaction nest will be demoted when the nest exits. Locks newly created inside the transaction nest will be freed when the nest exits.
    Nonetheless, the following exceptions apply to this rule:
    1. If a FILE was CLOSEd during the transaction, then all FILE and RECORD locks on the closed file are released on exit from the outermost transaction.
    2. Executing either “FILEUNLOCK fvar” or “RELEASE fvar” (but not “RELEASE fvar, recid”) will free the file lock AND all record locks on the file referenced by fvar. If this occurs during a transaction, the locks will be released when the outermost transaction exits.
Note:
Delaying unlocking until the outermost transaction is a feature of the Caché implementation. Most legacy MultiValue implementations only delay the release or demotion of a newly created or promoted lock to the exit of the nested transaction level where the creation or promotion took place.
MV Spooler Changes To Named Queue Form Numbers
The Caché MultiValue spooler attempts to serve emulations where the spooler form queue is usually numeric as well as platforms where the spooler form queue is a name. For example we support “F23” (interpreted as form queue number 22) and “CANONLAB” (interpreted as a form queue name CANONLAB and internally represented by a form queue number assigned automatically and starting at 2 — STANDARD is always form queue 1).
The result of this practice is that there are cases when this automatically generated form queue number clashes with form queues that have explicit numbers.
Starting with this release, all named form queues created will default to a form queue number from 1000 upwards. That is,
If you wish to change the starting point from the default 1000, then you can add this as an option to the SP-NEWTAB command line with the (Qnnnn) option. For example, to start allocation of named form queues at number 400, do this
SYSPROG: SP-NEWTAB (Q400)
Note:
Any MultiValue application that creates named form queues and expects these form queues to have exact form queue numbers will fail; the default form queue number for new named form queues is now 1000 instead of 2. To resolve this, the developer must either remove that association from the application or use "SP-NEWTAB (S1)" to give results compatible with prior to this change.
Terminating A Process Now Runs Normal Wrapup Tasks
In this version, terminating a MultiValue process from the Management Portal now forces the process to perform the normal MultiValue wrapup tasks before halting.
Studio Will Not Overwrite Catalog Pointers In VOC That Point To A Different File
The MultiValue compile and catalog operation in Studio will no longer overwrite the catalog pointer if the existing catalog pointer refers to a program from a different file.
Correct MVR collation Generation For Long Embedded Numbers
In prior versions, MultiValue right-justified collation (MVR) generated incorrect keys for mixed alphanumeric values containing more than eight digits in a row and where the digit string followed a non-numeric character. This release correctly generates the keys.
Important:
All indexes based on right-justified fields with collation MVR that may contain mixed alpha numeric fields with an embedded sequence of more than eight digits should be rebuilt. This does not affect fields that are purely numeric or numeric with a non numeric suffix.
DATA Statement Changes
Prior to this release, the input stack would only contain the line from the last DATA statement. Multiple DATA statements will now stack multiple lines in PARAGRAPHS
Directory Copy Uses Binary Mode
The MuliValue COPY command will now copy items in binary mode when both the source and destination are directories. Previously the items were processed to convert between AMs and newlines. The current behavior now copies directories unmodified to the destination.
BASIC And MVBASIC Changes
Only “–>” Allowed For Object Component Access
The MV BASIC compiler would sometimes accept the dot, “.”, character in places where an right-arrow token, “–>”, should have been used for access to the property or method of an object instance. This was true even though the MVBASIC language definition permits dot, “.”, to be used only as an identifier character.
Beginning with this release, the MVBASIC compiler always interprets the “.” as part of a name. Those developers who incorrectly copied COS or Cache BASIC examples of object references using “.” into their MVBASIC programs will have to recode those examples to use “–>” instead.
Correct Processing Of @XXX–>Component
In prior versions, macro substitution was improperly done on names following a system variable and “–>”. In this release, the component name is properly associated with the system variable. This means that in the sequence
EQU UserId Lit "X->UserId" 
X = "MV.TestClass"->%New() 
X->UserId = 2 
@ME->UserId="99"
the last two lines would previously have been interpreted as
X->UserId = 2 
@ME->X->UserId="99"
but now are processed as
X->UserId = 2 
@ME->UserId="99"
Change Handling Of Substitution With –>
Previously, names which were part of a “A–>B–>C...” sequence were not expanded if they were defined using EQU. This was only true if no whitespace separated “–>” from a name (before or after). Now only names which follow “–>” are not expanded; the sequence, “–>”, coming after a name no longer inhibits EQU definition expansion. Whitespace between “–>” and a following name does not affect the inhibition of EQU definition expansion.
This means that the lines
EQU UserId Lit "X->UserId"
CRT UserId
CRT UserId->UserId
CRT UserId->UserId->UserId
CRT UserId -> UserId -> UserId
X->UserId = 2
used to result in
CRT X->UserId
CRT UserId->UserId
CRT UserId->UserId->UserId
CRT X->UserId -> X->UserId -> X->UserId
X->UserId = 2
but starting with this version they become
CRT X->UserId
CRT X->UserId->UserId
CRT X->UserId->UserId->UserId
CRT X->UserId -> UserId -> UserId
X->UserId = 2
Identifiers Can Start With $
Previously, MVBASIC identifiers starting with a dollar sign, “$” could only use letters as the remaining characters of the identifier. This restriction has now been lifted and any legal identifier character can be used after the dollar sign that starts such an identifier.
However, InterSystems reserves MVBASIC identifiers of the form $SYSTEM.XxX, where the letters “SYSTEM” in the identifier prefix may appear in any combination of upper and lower case, but the identifier characters following the “$System.” prefix are case sensitive. An MVBASIC identifier of the form “$System.XxX” is treated as the name of the system package, and the $System.XxX identifier may be followed by a right-arrow token, '->', then a method name and then a method argument list in order to call the appropriate method in the system package.
Note:
Package names using the $System.Xxx identifier syntax cannot have a blank before or after the dot characters that are part of the identifier. Previously,it was possible to put white space following the package name prefix. Programs that previously contained such white space must now be modified to remove the white space that follows any dot characters used in package names.
Change Triggers On WRITEV
Previously, when a WRITEV statement was executed on a file with WRITE, INSERT or UPDATE triggers, the record passed to the trigger routine consisted of just the attribute value to be modified rather than the entire record to be modified. This has been fixed and now these triggers get the entire record when a WRITEV modifies an attribute in that record.
Trigger routines executed because of a WRITEV statement that depended on being the passed record containing only the attribute to be modified must be rewritten. The passed record contains the entire record that will be modified and the attribute number so it can extract and/or modify the particular attribute value that will be modified.
Important:
Trigger routines that do additional I/O on the file containing the trigger must now be prepared for recursive calls on the trigger routines and must protect against infinite recursion.
Change Triggers On READ/CLEAR/DELETE/OPEN
Previously in MVBASIC, when a READV statement was executed on a file with a POSTREAD trigger just the attribute being read was passed to the trigger routine rather than the entire record containing that attribute. This has been fixed and now POSTREAD trigger routines always get the entire contents of the file record being read.
Also previously, any active trigger routine on a file disabled calling any additional triggers on that file while that trigger routine remained active. This prevented trigger routines from being called recursively. Now none of the triggers will disable additional trigger calls during the execution of trigger routine.
Note:
The trigger routine is not passed the attribute number as an argument so the attribute number must be passed by other means if the trigger routine needs to extract and/or modify the particular attribute value that will be read by the READV statement.
Important:
Trigger routines that do additional I/O on the file containing the trigger must now be prepared for recursive calls on the trigger routines and must protect against infinite recursion.
SETTING Clause Processing Changes
Before this release, an MVBASIC I/O statement which included a variable in a SETTING clause was setting that variable to the I/O error status after executing any THEN, ELSE or ON ERROR clauses.
This had two bad effects. First, the variable in the SETTING clause could not be tested in the THEN, ELSE or ON ERROR clauses. Second, any I/O operation executed by the THEN, ELSE or ON ERROR clauses of the current I/O statement would override the status that would be stored into the variable specified by the SETTING clause of the current I/O statement.
The MVBASIC compiler now generates code to store the I/O status into the variable specified by a SETTING clause before executing any THEN, ELSE or ON ERROR clauses.
I/O Statements Now Clear $MVSYSRETCODE On Success
Previously, most I/O statements did not zero @SYSTEM.RETURN.CODE when starting a new I/O operation. This meant that any I/O statement with a SETTING clause that executed without any I/O error would leave behind the previous error code that was still left over in the system variable @SYSTEM.RETURN.CODE. Now, @SYSTEM.RETURN.CODE is reset to zero just before executing any I/O statement.
More Emulations Have HEADING Statement
In this version, for the emulations jBASE, Reality, Unidata, Udpick, Information, and Piopen, when a second or subsequent HEADING statement for terminal output is executed, it takes effect immediately.
For the other emulations, the second or subsequent HEADING statement will not have any immediate effects until the terminal executes a page break; this is when the HEADING statement is used.
Duplicate Names Not Allowed In DIM Statement
Previously, the MV BASIC compiler allowed a name to be defined more than once in the same DIM statement. For example,
DIM X(), X();
was permitted. Under some circumstances this results in a corrupted symbol table that could crash the process doing the compilation.
Now such statement will generate a compile-time error message and the redundant symbol definition must be removed from the DIM statement. The compiler does allow a name to be redefined multiple times in separate DIM statements providing the name as not been defined as a COMMON name.
xDBC Changes
Automatic Conversion Of Long Strings To Streams Removed
It previous versions, applications could ask that literal strings longer than 16K to be automatically converted to character streams. While this supported INSERTs and UPDATEs, queries never supported streams in this way for literal values.
Now that Caché supports long strings in ODBC, the previous functionality is no longer needed. Applications that need to support huge literal string values in SQL statements should make sure that Caché has long strings turned on.
Change To Null Parameter Handling
Beginning in this release, Caché conforms to the Microsoft documentation regarding null parameter values, namely, when you send a null parameter value to the server, you must specify DBNull, not null. The null value in the system is an empty object that has no value. DBNull is used to represent null values.
Prior to this, Caché had been treating null and DBNull the same,, but the mapping for parameter values are as follows in terms of the $list values sent to Caché. The only change is for a null to specify a default value.
.NET $LIST SQL
null 01 default value
DBNull 02 01 null value
“” 03 01 00 empty string
This changes makes the behavior of Caché consistent with the ODBC native provider, and all other ADO providers in terms of null Parameters representing default values.
Accomodate New SQL Server Mappings
This version changes the JBDC mappings for varbinary and nvarchar (BLOB and CLOB, respectively) to use streams in accord with changes in Microsoft SQL Server version 2008.
SQLBindParam API Removed From ODBC
SQLBindParam is an older 2.x API that Caché added with Version 3.5 release. However, it conflicts with SQLBindParameter which was present then as well and its presence ended up causing problems with iODBC driver manager. It has been removed from this versionof Caché to allow iODBC to function correctly by calling SQLBindParameter with the proper arguments.
Support Binary In %SQL.Gatway.ODCResultSet
In previous releases, binary values returned by queries were converted to the corresponding ASCII values (visible in linked stored procedures). Beginning with this release, binary values are returned as is.
DeepSee Changes
Changes To Filter Handling In Pivots
In prior versions,
Now, in both cases, they are logically ANDed together. This is an improvement in several ways:
  1. It makes all filters consistent – all filters in the filter bar are now ANDed together with no exceptions.
  2. For list-type levels, it lets you filter on combinations (such as allergy on mites AND dessert toppings).
  3. It removes a lot of "Why do I get multiple counts when I add more filters" questions.
DeepSee Key Values Now Checked For Illegal Characters
KEY values for DeepSee members may not contain the characters “|”, “&”, “~”, or “:”. In previous releaqses this was not explicitly checked. Beginning with this release, attempting to build a cube with illegal KEY values will result in a validation error.
Improved Expression Checking
An expression or scalar function on a SET, such as,
ISNULL(Country.Members,0)
does not make sense. In previous version, executing the expression would give a nonsense answer. Now, it will return an error.
Add %DeepSee.ReportBuilder Resource For Access Control
In this release, a new resource has been added which grants access to the DeepSee Visual Reporting Report Builder. Users and applications that wish to access this functionality must now have %DeepSee_ReportBuilder and a valid license for the feature, or they will be denied access.
CSP Changes
Define Logout Handling
Beginning with this release, the recommended way to logout of a CSP session is to link to the application home page passing a URL that contains the string, “CacheLogout=end”. This will end the current session – release any license acquired, delete existing session data, remove the security context of the session – before it attempts to run the home page.
If this CSP application requires authentication, there will be no session and no authenticated user. In this case, Caché will not run the home page logic but will display the login page instead. When the user submits a valid login, this will start this new session and then display the home page.
SECURITYRESOURCE Parameter Added To %CSP.Page
In this release, the class %CSP.Page now has an additional class parameter, SECURITYRESOURCE which controls access to the page. The value of the parameter is a comma-delimited list of system resources and associated permissions. A user must hold the specified permissions on the specified resources in order to view this page or invoke any of its server-side methods from the client.
The format of each item in the list should be as follows:
Resource[:Permission]
Resource is a registered system resource. Permission is optional, and defaults to USE if not supplied. If it is supplied, it must be one of USE, READ, or WRITE.
You can also specify OR grouping using the “|” character, so
ResA,ResB|ResC,ResC|ResD
means you must have resource ResA, and one of ResB or ResC, and one of ResC or ResD. So if you have ResA and ResC, you will have access. If you have ResA1 and ResD, you will not since the ResB or ResC condition is not met.
Note:
The “|” binds more tightly than “,”.
Application Access To %CSP Pages Now Controlled
Beginning in this release, application access to arbitrary %CSP pages (and their subclasses) can now be better controlled. By default, the new rules allow a user application to access:
and also explicitly to the following classes:
This checking is performed in addition to any “Permitted Classes” checking defined for this CSP application. So a class reference must pass both sets of tests in order to be allowed.
An administrator can permit access to additional classes by configuring the global, ^SYS(“Security”, “CSP”, <category>) in the %SYS namespace by using the AllowClass, AllowPrefix, and AllowPercent keywords. The following sections describe these keywords.
Important:
Checking is done by applying the default rules first, then the categories in the order listed. This permits making an entire package accessible, except for one class in the package whose access is restricted.
Category: AllowClass
If your application relies on invoking a particular class, the AllowClass keyword creates an exception for that class and makes it available.
Important:
If your application relies on invoking any class other than those listed above, it could potentially be unsafe to use. InterSystems recommends that you determine if calling this class is required, and have performed a risk assessment for your deployment, so that you understand the implications of making the class available.
To create an exception for a particular class, set the ^SYS global subscript to a value of 1 as follows:
Set ^SYS("Security", "CSP", "AllowClass", "<web-app-name>", "<package.class>") = 1
where entire body of the command – except <web-app-name> and <package.class> – is used in the exact form as it appears here. For the variable content of the command:
Setting the data value of the global to 0 specifies explicitly that Caché does not permit access to the class.
For example, to allow a specific classname (in this case, %User.Page) to be called from a /csp/webapps/ application, the command is:
Set ^SYS("Security", "CSP", "AllowClass", "/csp/webapps/", "%User.Page") = 1
To allow, for example, the %User.Page class in all CSP applications, the command is:
Set ^SYS("Security", "CSP", "AllowClass", 0, "%User.Page") = 1 
Category: AllowPrefix
If your application relies on invoking one or more classes or packages that begin with the same set of characters, the AllowPrefix keyword creates an exception for those packages or classes and makes them available.
Important:
If your application relies on invoking any class other than those listed above, it could potentially be unsafe to use. InterSystems recommends that you determine if calling this class is required, and have performed a risk assessment for your deployment, so that you understand the implications of making the class available.
To create an exception using the AllowPrefix keyword, set the ^SYS global subscript as follows:
Set ^SYS("Security", "CSP", "AllowPrefix", "<web-app-name>", "<prefix>") = 1
where the entire body of the command – except <web-app-name> and <prefix> – is used in the exact form as it appears here. For the variable content of the command:
Setting the data value of the global to 0 specifies explicitly that Caché does not permit access to the relevant packages or classes.
For example, to allow the entire %MyApp package to be called from a /csp/webapps/ application, the command is:
Set ^SYS("Security", "CSP", "AllowPrefix", "/csp/webapps/", "%MyApp.") = 1
In this case, adding the dot prevents access to any packages whose names begin with and are longer than “%MyApp”.
To allow, for example, all packages that begin with “%My”, the command is:
Set ^SYS("Security", "CSP", "AllowPrefix", 0, "%My") = 1 
As a further example, you can allow %MyPkg.*, but disallow %MyPkg.Class1 in the /csp/samples/ application by setting:
Set ^SYS("Security", "CSP", "AllowClass", "/csp/webapp/", "%MyPkg.Class1") = 0 
Set ^SYS("Security", "CSP", "AllowPrefix", "/csp/webapp/", "%MyPkg.") = 1
Category: AllowPercent
If your application relies on invoking the packages that begin with the % character generally, the AllowPercent keyword creates an exception for those packages and makes them available.
Important:
If your application relies on invoking any class other than those listed above, it could potentially be unsafe to use. InterSystems recommends that you determine if calling this class is required, and have performed a risk assessment for your deployment, so that you understand the implications of making the class available.
To disable %-page checking totally in all CSP applications:
Set ^SYS("Security", "CSP", "AllowPercent") = 1
Note:
Setting the data value of the global to 0 specifies explicitly that Caché does not permit access to the percent packages.
Special Case: DeepSee
For a web application to use DeepSee, it needs access to all the classes in the %DeepSee package. By default, only the “/csp/samples” web app is set to allow Deep See access. If you want to use Deep See in any other web app, you must explicitly allow it.
For example, to enable the /csp/webapp web application to use DeepSee, the syntax is:
Do EnableDeepSee^%SYS.cspServer("/csp/webapp/")
which is the same as
Set ^SYS("Security", "CSP", "AllowPrefix", "/csp/webapp/",  "%DeepSee.") = 1
Set ^SYS("Security", "CSP", "AllowClass", "/csp/webapp/",  "%CSP.UI.Portal.About") = 1
To allow all web applications to use DeepSee:
Do EnableDeepSee^%SYS.cspServer(0)
which is equivalent to:
Set ^SYS("Security", "CSP", "AllowPrefix", "",  "%DeepSee.") = 1
If you have enabled Deep See access for all web apps and you want to disable it for a specific web app, you should set the global to a 0 value as shown in this syntax:
Set ^SYS("Security", "CSP", "AllowPrefix", <web-app-name>, "%DeepSee.") = 0
Note:
This is only for DeepSee versions released with Caché version 2011.1 or later – that is, only for what was previously known as “DeepSee II”. If you are using a version of DeepSee released prior to Caché 2011.1 even on a version of Caché that is more recent, there is no issue.
Special Case: iKnow
For a web application to use the sample UI pages for consulting or managing iKnow data, access also needs to be granted explicitly as follows:
Do EnableIKnow^%SYS.cspServer("<web-app-name>")
To disallow an application from using iKnow, the syntax is:
Set ^SYS("Security", "CSP", "AllowPrefix", <web-app-name>, "%iKnow.") = 0
Granting or disallowing access for all web applications works analogously the way it is done for DeepSee.
Translation For JS and JSML Changed
The EscapeURL(url) function of %CSP.Page first encodes a URL using the current device charset; then it escapes this using the standard encoding for URLs.
If the current device is set to the JS or JSML translate table, this function converts “/” characters into '%5Cx2F' with the result that the URL no longer functions correctly.
Zen Changes
Improve Parsing Of #(...)# Expressions
Zen allows for expressions in values of the form #(<object>.<propname>)#. In this release, the Zen compiler will only allow the names of properties to be used in place of <propname>.
ZenMethod Keyword Now Enforced
In the very early versions of ZEN, there was no ZenMethod keyword; Zen overloaded the WebMethod keyword for this purpose. Beginning with this release, support for the WebMethod keyword is now removed. Applications that use WebMethod must be changed to use ZenMethod instead.
ZenMethods Can Only Be Called From The Current Page
If a Zen class defines a ZenMethod, this method can now only be called from the client/browser.
You can define a security resource (using a class parameter) for a given Zen page. This prevents any methods on this page from being invoked unless the user has Use permission on the resource. Hence, any Zen methods defined on that page can only be called from methods on that page.
Note:
Zen methods of Zen components can be called from any page. Thisis due to the dynamic nature of Zen – pages can create instances of any compnent as needed at runtime. This means that care must be taken when creating new Zen components containing server-side methods.
Fix Parsing Of Escaped Data In Zen jsonProvider
The Zen jsonProvider component was correctly escaping data on output, but was not unescaping the same data on input. This change updates the parser to correctly handle the following escape sequences defined in RFC 4627:
 \/   \r   \n   \f   \b   \t
Furthermore, the escape sequences for Unicode values are also converted into the raw Unicode characters on input. The jsonProvider parser will now automatically convert escape sequences of the form \uXXXX to the character representation of the specified Unicode code point.
Warning:
This may cause problems for 8-bit Caché systems where incoming data containing code points beyond \u00FF, as the conversion process will now produce wide characters.
Charts
This version of Zen significantly updates the chart functionality in the following areas:
Caution:
Applications that subclass charts will need to be changed to use the new superclasses. Applications that do not use the default setttings may need to modify their styles for existing charts to achieve the desired visual effects.
Zen Reports Changes
Zen Report Must Use %SQL.Statement For Result Sets
As of this release, %ZEN.Report.ResultSet has been deleted. Zen report data generators and collectors should use %SQL.Statement instead for proper results. To define the method as an SQL stored procedure, use the method keyword, “sqlproc”.
Change To Multiple Line-Feed Handling
In prior releases, a sequence of multiple line-feeds sent to the output would ignore any after the first. To have multiple line-feeds appear in the PDF output, one must do the following:
On the item set the following attribute as follows: breakOnLineFeed="true"
Automatically Provide Unique Sheet-Names For Excel
Zen Reports no longer takes the sheet name from the group name. Instead, it now automatically provides unique sheet-names for Excel.
When generating multisheet output for Excel, each sheet must have a unique name. This may be done by specifying an expression in “excelSheetName”. By default (that is, when excelSheetName is not specified), each sheet in a multi-sheet report be given a unique sheet name using the same default names Excel uses for sheets: "Sheet1", "Sheet2", etc.
If any application is depending on our taking the sheet name from the group name they can use excelSheetName to set the sheet name equal to the group name.
Changes To ongetXXX Method Handling
Beginning with this release, the ongetXXX methods now pass a chart object as the final argument of the method. This allows the callback methods to access properties of the chart such as id.
A ZEN Report chart on a chart callback method that worked in prior releases will now get a parameter error. There are two ways to work around this situation:
You can work-around this parameter error two ways:
%ZEN.Report.ResultSet Removed
In this release, %ZEN.Report.ResultSet has been removed. Applications using %ZEN.Report.ResultSet must define their own ResultSet class to emulate its functionality, for example,
Class MyResultSet Extends %Library.ResultSet {

    Method %Get(name As %String) As %String [ ProcedureBlock = 1 ] {
        if (name '= "") && ($Data(i%Data(name))) { 
            set rReturnValue = $get(i%Data(name)) 
            }
    else  {
        s rReturnValue=""
        }
    quit rReturnValue
    }    
}
Two-Dimenional Arrays In CallbackTables Are Now Zero-Based
Beginning with this release, callback tables will now be zero-based to make them consistent with callback charts. For example,
<table callBackMethod="NamesAndAddresses">
    <item fieldnum="1" suppressDuplicates="true">
         <caption value="Name"/>
     </item>
     <item fieldnum="2">
         <caption value="Address"/>
     </item>
 </table>
will be interpreted as
Method NamesAndAddresses(ByRef var As %String) 
{
    // record of names
    // record 1
    Set var(0,0)="Santa Claus"
    Set var(0,1)="North Pole"
    
    // record 2
    Set var(1,0)="Zeus"
    Set var(1,1)="Olympus"
    
    // record 3
    Set var(2,0)="Robin Hood"
    Set var(2,1)="Sherwood Forest"
    
    // record 4
    Set var(3,0)="Robin Hood"
    Set var(3,1)="Nottingham"
    
    Quit
}