Release and Upgrade Information for Caché 2012.2
This chapter provides the following information for Caché 2012.2:
New and Enhanced Features for Caché 2012.2
The following major, new features have been added to Caché for this release:
Furthermore, this version of Caché has been improved and enhanced in the following areas:
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 “Caché 2012.2 Upgrade Checklist.”
Major New Features
Using Unstructured Data In Analytics
DeepSee support for unstructured data
DeepSee now supports unstructured data. DeepSee cubes can use free-text as the source for dimensions and measures. Using the iKnow technology, this text is analyzed, and the results of this analysis ( the "concepts" from the text) are available as members of the dimensions.
Cubes can contain a mixture of dimensions based on structured and unstructured data. Like all DeepSee cubes, these cubes can be queried via DeepSee Analyzer, dashboards, and programmatically via MDX queries.
Term Lists
DeepSee includes new Term List functionality. A Term List is a set of key/value pairs that can be used for lookups and translations. Term Lists can be used during cube building, and also in MDX via the %TERMLIST function. For defining Term Lists, there is a Term List Manager option on the DeepSee menu in the Management Portal.
Business Rules
Ensemble business rules can be used at cube build-time. A sourceExpression can use the new %Rule method to invoke a business rule. The business rule is passed an instance of the current source object, and the result of the business rule is returned.
DeepSee Visual Reporting
This release introduces a new capability that enables Caché, Ensemble, and HealthShare users to interactively define reports via a drag-and-drop browser interface. This new technology, DeepSee Visual Reporting, consists of three parts:
-
Report Data Definition
DeepSee provides a browser-based UI for creating report data definitions. This is analogous to creating a query that gathers data for the report and specifying how that data will be formatted when it is displayed. The user creating the definition needs an understanding of the underlying source data and its interrelationships.
-
Report Format Definition
Once the data definition is complete, you can display the data in any number of formats. You define these layouts also via a browser-based interface that provides the ability to preview the output using the actual data chosen.
-
Report Execution
Once the user completes that definition of the data and output formats, the report can be run at any time by the author or those with whom the report is shared.
For 2012.2, the Report Data Definition and Report Format Definition components of DeepSee Visual Reporting are available for evaluation, but are not supported for production. These components will be fully supported in a future release.
Reports created with DeepSee Visual Reporting are supported in production in 2012.2.
Rapid Application Development
iKnow Enhancements
In this release, the iKnow API has been extended with the new Semantics package. This package contains two major new feature sets.
Semantic Dominance
Semantic dominance is a term used to describe how important a specific element (can be a word, a concept, a set of concepts or a sentence) is in the context of specific text and in relation to the other information in the text. The semantic dominance API allows applications to identify:
-
the semantically most dominant elements in a single source, that is, the most dominant elements in a domain or a domain subset;
-
how dominant elements are shared by different texts; the most typical sources in a domain-the most atypical sources in a domain.
The uniqueness and added value of the semantic dominance API resides mainly in two elements. First, of all the algorithm implemented works based on the context of a single source only and doesn't need a reference corpus to identify the base line importance of a text element. Second, the algorithm generates values that are comparable between different texts and between different text elements. For example the semantic dominance value of a single concept can be compared with the semantic dominance value of a pathway consisting of multiple concepts and relations.
The semantic dominance API can be used to easily find out what the important common content of a series of text is or to find out what texts are the most typical for a given set of texts. It allows also to quickly find out what the important new information is in a text.
Proximity
With the new capabilities in the proximity API, it is easy to find out which concepts appear in the context of a chosen reference concept. The functions in this API are used to find out what concepts are associated with the reference concept and how strong the association is. Based on the contents of the domain for which the semantic proximity is calculated the semantic proximity profile for the concept “bakery” will contain concepts such as “muffins”, “belgian waffles”, “cake” and “pie” each with a different value to express the strength of the association with bakery.
HTML5 Is The Default
Beginning in this release, the default doctype for all Zen pages is HTML 5 for browsers that support HTML 5 and CSS 3. Also included is a new generated css file that will be served only when Caché detects an HTML 5 supported browser and the output contains CSS 3 syntax. You may override this behavior by changing the %OnDetermineCSSLevel() callback to return 2 instead of 3 or by modifying a global node in the managers database. With this change, we also start using the native SVG renderer in IE 9 and above.
Improved Arabic Rendering In Reports
Starting with this version, Caché officially supports Arabic output in Zen Reports using Apache FOP.
Regular Expressions
With 2012.2, InterSystems introduces a feature-rich alternative to ObjectScript pattern matching, Regular Expressions. Using Regular Expressions not only detects if a complex pattern is present, but also provides location and results of successful matches. This allows more complex manipulation of strings in less code. For details on usage, please refer to the class documentation for %Regex.MatcherOpens in a new tab.
Support For Node.js
This release adds support for Node.js. Node.js a platform built on the Google Chrome JavaScript runtime. It uses an event-driven, non-blocking input/output model for building web and data-intensive applications. The Node.js integration with Caché is native and has direct access to Caché globals. More information on Node.js is available at nodejs.orgOpens in a new tab.
Unlimited Local Arrays
As part of version 2012.2, InterSystems offers a simple way for application developers to dynamically change the memory allocation for processes during runtime, or define large memory allocations during process startup time. Available system memory can be by fully utilized to perform complex and high performance operations by keeping arrays in memory.
While this feature is most useful on 64–bit operating systems, process private memory can also be changed in 32–bit environments. Customers need to verify that use of this feature does not trigger unexpected performance profiles in the operating system, for example, excessive swapping.
.NET eXtreme
This release includes support to .NET for the Globals API. This enables direct global access and manipulation of globals from .NET. This API enables .NET and Caché to run intraprocess on the same computer providing high speed data access.
Java eXTreme Over TCP
This version of Caché allows XEP to run over TCP. XEP is a lightweight Java object persistence technology for Caché. Initially it executed intraprocess because it was built only on top of the Globals API for Java. While it still leverages the Globals API concepts in many respects, being able to use TCP means that it is now optionally intraprocess.
.NET 4.0 Components For Object Provider And .NET Gateway
This release provides .NET 4.0 compiled versions of the Object Provider for Caché and the .NET Gateway. Though previous releases were compatible with .NET 4.0, there is now an option to only have .NET 4.0 components in applications.
Long Strings Are The Default
Beginning with 2012.2, support for long strings is now enabled by default for new installations as well as upgrades.
Performance And Scalability
ECP Rollback
Beginning in this release, rollback operations issued by a process on an ECP Application Server will be addressed by the Database Server asynchronously. This approach allows continued parallel processing of other requests. Previously, a rollback operation was handled synchronously: the Database Server would serially handle the entire rollback before continuing with other requests from a given ECP Application Server. The new technique prevents a long rollback operation from disrupting other application work on a given ECP Application Server.
Use AES Hardware Encryption When Available
Many processor vendors now include support for encryption algorithms directly in hardware. Beginning with this release, Caché takes advantage of this feature (when present) in the Advanced Encryption Standard (AES) calculations. In doing so, it provides increased performance by using the instruction set of the processor.
The initial use of this option will take place on Intel 64-bit processors, beginning with the Intel® Xeon® Processor X5680 (Westmere). On such systems, Caché makes direct use of the hardware instructions to perform AES encryption. The systems for which this is true are: Microsoft x86-64, Red Hat Enterprise Linux for x86-64, SuSE Linux Enterprise Server for x86-64.
Reliability, Availability, Maintainability, Monitoring
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.
Configurable UNIX® Installation
In this release UNIX® installations can now be done in a manner similar to Windows installs that use command line options. New configuration parameters are available with the new cinstall_silent installation script to define the instance name, installation directory and packages to install.
Security
Public Key Infrastructure
Increased concerns about information security in many industries have correspondingly increased the need to encrypt and sign documents using the X.509 certification. However, generating, safe-guarding, and distributing X.509 keys and certificates is a complex and time-consuming process.
In this release, InterSystems users have the ability to automate the process that generates certificates by defining a server to act as a certificate authority. Clients cannot only request certificates from the certificate authority, but automatically receive them for their local use.
Caché 2012.2 Upgrade Checklist
The purpose of this section is to highlight those features of Caché 2012.2 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.1 and 2012.2.
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 2012.2. 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 releasesOpens in a new tab 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.
Extended Memory
In prior releases, there was a limit on the maximum a Caché process could consume. By default, the limit was 16MB, but could be increased to 49MB.
Beginning with this release, the limit has been extended. It is now 2TB, subject to limitations imposed by the platform and operating system. For example, most 32–bit systems will be restricted to 2GB or less. Also, larger Caché partition sizes may need larger swap space allocations in the underlying platform.
Administrators should note the following changes:
-
bbsiz: This parameter is now renamed to “Process Private Memory”.
-
Installation defaults: New installations will set the value of Process Private Memory to 256MB. For upgrades from previous releases, the value will not be changed.
-
Management Portal: The Process Private Memory value is shown with the label, “Maximum Per-Process Memory”.
There are two system variables, $STORAGE and $ZSTORAGE, available for developers to determine how much process private memory is still available and what the maximum value is. At process, start both system variables have the same value derived from the Process Private Memory setting, Application developers can increase the value of $ZSTORAGE at any time during process execution, for processes that are designed to require larger than the default process private memory allocation. In addition, the exhaustion of process private memory resulting in a <STORE> error, no longer results in process termination. Application developers have now the options on how to proceed in this case:
-
Increase memory by increasing the value of $ZSTORAGE and continue running.
-
Increase memory to capture error/stack information and HALT the process.
-
HALT the process.
InterSystems utilities to capture error information will automatically increase the value of $ZSTORAGE to allow the recording of the error and stack information, and then HALT the process.
Extended Memory — Platform Details
Windows and OpenVMS systems have no configuration controls for virtual memory. For UNIX® platforms, there are two configuration parameters of interest:
-
Data space: This is controlled by the “ulimit –d” command.
-
Virtual memory (or process) space: The “unlimit –v” command sets the value.
For specific versions of UNIX®, the changes are
-
HPUX (32– and 64–bit); IBM AIX
In prior versions, application data space was controlled via the “ulimit -d” command. Now, the command has no effect. The only control is via the Caché $ZSTORAGE value.
-
Linux (Red Hat and SUSE)
No change. Both data space and virtual memory space are controlled by the operating system via the “ulimit -v” command.
-
Mac OS X
No change. Neither data space nor virtual memory space are controlled by commands.
-
Solaris
In previous versions, the data space was controlled by the “ulimit -d” command. Starting with this version, the application memory is taken from the virtual memory space and is controlled via the “ulimit -v” command.
Collection Indexes May Need Rebuilding
Prior to this version, if an application used a collection with a non-exact collation (for example, MVR) and allowed NULL elements, an SQL INSERT or UPDATE of the collection could store the wrong value in the index. This is also true for applicatons that have an index on a collection(ELEMENT) or collection(KEYS) value, and the collection value can be NULL.
Applications with such indexes must rebuild them in this version in order to index the existing NULL collection values properly.
Mirroring-Related Changes
-
Mirroring .CPF Changes
All mirror members are now configured in the MapMirrors section of the CPF file. The [MirrorAsyncMemberSources] section in CPF file is obsolete, it exists onlyafter the instance is upgraded to 2012.2. When the async member starts up and connect to the failover member, the [MirrorAsyncMemberSources] section is automatically converted to Mirrors and MapMirrors sections
The MapMirrors section in CPF file contains all types of mirror members (failover and async). Caché adds a member to the MapMirrors section if the incoming connection from a failover or async member is not in the MapMirrors section yet.
The AsyncMemberGUID in MirrorMember section indicates whether the system is an async member (is a non-null string) or failover member (is a null string). The JoinMirror in the MirrorMember section will be 1 for async member using MapMirrors/Mirrors to configuration the mirror. Previously, the JoinMirror had to be zero for async member when it used MirrorAsyncMemberSources section to configure the async member.
The AsyncMemberType is now part of the MirrorMember section for all mirror sets in an async mirror member; previously it resided in MirrorAsyncMemberSources. A value of 1 indicates this is a reporting async member and allows the mirrored databases to be read-write; the value of 0 indicates this is a disaster recover async member which implies all the mirrored databases are read-only.
-
Primary Mirror Identification Changes
In previous versions, the result from ##class(%SYSTEM.Mirror).IsPrimary or $SYSTEM.Mirror.IsPrimary() was only TRUE if the system was the active primary. In this version, it is now true if the system is the primary mirror member, and will remain the primary mirror member until it is shutdown (that is, regardless of its trouble state). If $SYSTEM.Mirror.GetInfo() contains both "PRIMARY" and "ACTIVE", then $SYSTEM.Mirror.IsPrimary() will return TRUE.
Note:There is a small window during primary startup where $SYSTEM.Mirror.GetInfo() contains "PRIMARY" but not ACTIVE (it contains either FAILOVER or RECOVERY at this point). During this time $SYSTEM.Mirror.GetInfo() returns FALSE.
If an application was using $SYSTEM.Mirror.IsPrimary() to detect whether the primary is up and healthy, the logic involved will have to be rewritten for the new situation.
-
Async Mirror Members May Now Use Journal Purge Interval
Async Mirror members can now be configured to purge journal files based on the system journal file purge setting (System>Configuration>Journal Settings) rather than as soon as the async member is done with journaling. This means the system to be configured to retain the journal files for longer if there is some reason to do so.
In 2012.2, InterSystems removed the [MirrorMember] DaysBeforePurge parameter from the .cpf file. When upgrading a 2011.1 async member to 2012.2, if this parameter is non-zero then the upgrade propcess sets the new AsyncUseSystemPurgeInterval parameter is set to 1. This means that mirror journal files on the async member will be purged according to the system setting for purging journal files.
Important:If the time period for the system setting is less than the prior value of the DaysBeforePurge parameter, mirror journal files are not retained for as long as the system manager had intended.
Change to Journal Restore Dialog
In prior releases, if journal restore got errors updating a database, it would dismount it to prevent users from accessing the database inadvertently. With this release, it no longer automatically dismount the databases upon errors; instead, at the end of journal restore, it gives the user an option to dismount them:
Some updates of the following database(s) were skipped during journal restore, due to errors. The database(s) might be in an inconsistent state. <list of skipped databases> Do you want to dismount the above database(s) (yes/no)?
The prompt is present only if journal restore gets into the situation as described above. It does not count non-journal target databases, which are always skipped. The prompt must be answered with either y(es) or n(o); no default is presumed.
Users who script journal restore based on input/output may need to adapt the script to this potential prompt. Users of the journal restore API (Journal.Restore class) may set the Dismount property specifically to have the skipped databases dismounted. The default for this property is No.
Temporary Files Deleted When FileStream Is Removed
This version changes the behavior of the %IO.FileStreamOpens in a new tab class so that, if it is used to create temporary file instances, the corresponding temporary disk file is deleted when the file object instance is killed or goes out of scope.
This change also introduces a new property of the %IO.FileStreamOpens in a new tab class, IsTemp. Setting IsTemp to 0 preserves the behavior of previous releases.
%Admin_Manage Role Needed for Broadcast
The ability to broadcast messages using the Broadcast method of %System.Process($ZU(94)) to terminals and processes now requires the application doing so to have the %Admin_Manage role.
The Caché Control Process Now Spawns Processes Under the Service Userid
The Caché control process serving the local connection now spawns jobs ($ZF(-1)) in the same user/permission context that all other Caché processes do. That is, it uses the userid declared for the Caché service.
Null Character Conversion from Unicode to Caché Locale Unified
In previous releases, the conversion of a null string from Unicode to the current Caché locale equivalent differed between UNIX® and Windows systems. The resulting string was zero characters long on UNIX®, and a single NUL character on Windows. In this release, both platforms return a NUL character.
Unauthenticated Access and Two-Factor Authentication
When the Terminal or Bindings service is configured to allow Unauthenticated access and also to require two-factor authentication, the second factor (security token sent to mobile phone) will not be performed for the UnknownUser unless that user is configured with a mobile phone number.
Health Monitor And Application Monitor Functionality Now Under System Monitor
In this release, Health Monitor and Application Monitor are unified under a single entity, System Monitor. System Monitor encompasses the following:
-
Management Portal Dashboard (formerly implemented as an Application Monitor class %Monitor.System.Dashboard run by ^%MONAPP in the %SYS namespace)
-
any other Application Monitor class running in %SYS
-
Health Monitor
In addition, ^%MONAPP and Health Monitor are no longer started at startup; instead, System Monitor is started, which runs these applications.
System Monitor is configured via a new utility, ^%SYSMONMGR. Application Monitor configuration for %SYS(%MONAPPMGR), and Health Monitor (MONHEALTHMGR) can also be run from this single entry point.
System Health components can only run in %SYS. This requirement affected %Monitor.Health.Period.Create() and %Monitor.Health.Period.Modify() which have been renamed to SYS.Monitor.Health.Period.Create() and SYS.Monitor.Health.Period.Modify(), respectively.
Name And Format Changes For Monitor Log
In this release, the Health Monitor log file, HealthMonitor.log, is renamed to SystemMonitor.log. This log is acccessible through the Management Portal under System > System Logs.
Also,to improve searching in the HealthMonitor.log for details of Health Monitor notifications, the datetime format used is the same as that in the cconsole.log file.
Long Strings Enabled By Default For New Installs
Beginning with this release, new installations of Caché have long strings enabled by default.
New Maximum Size And Default Values For Configuration Parameter bbsiz
The bbsiz parameter in the CPF file now allows a maximum of 2147483648KB. The default on a new install is now 262144KB. On an upgrade, the value remains unchanged.
New Default Size For gmheap
In this release the default size for gmheap has been increased to account for the iKnow Spanish and English language models which are loaded as part of the default configuration. When upgrading to this release. if the existing value for gmheap is less than the default, it will be set to the default. If the value is greater than the default, it will be left unchanged.
Change Listening Strategy For .NET Gateway
The DotNetGatewaySS.exe process takes three arguments: port, host and logfile. The port argument is required, but the others are optional.
The default value for host had been 0.0.0.0; the gateway listens on all TCP/IP adapters for a connection. Starting with this version, the default is now the loopback port 127.0.0.1.
This is being done to restrict access to the TCP/IP port from anyone other than the machine the DotNetGatewaySS.exe is running. The gateway default is now consistent with the Management Portal. Users can still configure the host to listen on other IP addresses, with additional firewall configurations as they wish..
Journal File Integrity Checking Now Verifies File Chronology
The class reference documentation for CheckIntegrity() of %SYS.Journal.FileOpens in a new tab has been updated to make it clear that the journal file paths that are passed as an array to the method are expected to be in chronicle order of their creation. The method has also been updated to check the headers of the given journal files. If it is found that the journal files are specified out of order, a single value 0 is returned and the top node of the array is set to the number index of the offending element.
Change Locale Defaults Of Locale JPUWFrom EUC To UTF8
Beginning with this release, applications running in locale jpuw (Japanese/Unix) that open files or printers without specifying a translation table (that is, relies on the locale default) will show different results. To produce the results from prior releases, the application must explicitly set the desired locale.
Changes Made To Czech Locale
Czech locales (csw8, csy8 and csyw) now have localized strings for currency, weekdays and months properly set. In addition, they have the proper date format (for example, 23.03.2012) and number format (1 234 567,89).
Question Sequence Change To Journal Restore
Running ^JRNRESTO on a failover mirror member triggers a new question regarding whether the user wants to restore mirrored or non-mirrored databases. Mirrored database restore is handled via catchup, non-mirrored database restore continues to use the existing ^JRNRESTO interface. This release adds a menu option to ^JOURNAL to restore mirrored databases.
Customers who have scripted the journal restore process will need to account for this change when ^JRNRESTO/^JOURNAL is executed on failover mirror members.
CACHE Database Is Always Read-Write
The CACHE database will now be treated like the CACHESYS database. An attempt to change it from read-write to read-only using ^DATABASE, the Management Portal, or the SYS.Database object will be ignored. The database always remains in read-write mode.
Delimiter Change In Listing Namespaces
During the field test versions of this release, the method ##class(%SYS.Namespace).ListAll(.x) returned an implicit namespace string with the system name enclosed between two at-sign characters, “@”. For the general release, the delimiters are now “^” characters.
Package Mapping Overrides Routine Mapping
When routine has a name containing a period (.) and the name preceding the period is the same as a name involved in a package mapping, the package mapping overrides routine and the routine will not be visible. Routine names must not collide with the names of packages involved in package mappings.
Platform-specific Items
This section holds items of interest to users of specific platforms.
Windows
-
Do Not Rollback If Database Update Fails In Upgrade
The Windows installation activity will not initiate rollback during an upgrade if there is an error in performing the DatabaseUpdate action. If there is an error during DatabaseUpdate, there will be an error message displayed and update will proceed to the final dialog.
This change does not affect new installs where, if there is an error in DatabaseUpdate action, it will still be rolled back.
-
Second Ethernet Address Unavailable
This release removes EthernetAddress(2) from the class $SYSTEM.INetInfo on Windows because the underlying support is not available on this platform.
-
Timeout For Windows Startup Removed
Previously, when restarting an instance on Windows, Caché would wait up to 180 seconds for Windows to create the shared memory segment it needed to run. When the requested segment was larger than 5GB and memory was fragmented, this limit could be exceeded and the instance failed to start. This release removes the time limit altogether.
-
RoseLink Files No Longer Installed
In this release, Caché no longer installs and registers RoseLink-related files.
Windows And UNIX® / Linux
-
Callin Linking
Beginning with this release, some Caché kernel components are now implemented in C++. Therefore, any callin module linking with the Caché static library/object (cache.o) must include the platform standard C++ lib to their link command. (This is not required when linking with the Caché dynamic library, libisccache.dylib).
-
OpenSSL Version
In this release, InterSystems has updated the openssl library to version 1.0.0e for Windows and Unix. In addition, the distribution includes the International Data Encryption Algorithm (IDEA) cipher. All InterSystems projects depending on openssl have been modified to use new version. Applications affected by changes in the new version should be updated as well.
Linux RedHat 32-Bit And 64-Bit
In this version, InterSystems has rebuilt httpd for the 32-bit and 64-bit platforms to remove a dependency on libexpat.so.0 library. This library was previously installed as part of a normal installation but may no longer be present depending on the initial system configuration.
MacOS 64
Upgrading a macOS 64–bit installation deletes the following LDAP libraries:
-
libldap-2.4.2.dylib
-
libldap-2.4.2.1.0.dylib
-
libldap.dylib
-
liblber-2.4.2.1.0.dylib
-
liblber-2.4.2.dylib
-
liblber.dylib
OpenVMS
Sites using HPSWS on OpenVMS must configure the CSP Gateway to generate a content-length for all Management Portal responses. To set this, select Application Access for /csp in the System Portal pages for the CSP Gateway, and verify that “Response Size Notification” is set to “Content-Length”.
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.
Routine Compiler Changes
$ZTRAP Inside a TRY Block Not Allowed
The use of $ZTRAP inside a TRY block has always been illegal because the error handling order is ambiguous., but until this version, it was not detected by the routine compiler when the TRY occurred inside a procedure. Beginning with this version, the compiler reports such usage as an error.
Routine Changes
$COMPILE-Generated Object Code Will Not Use Routine Path Setting
Customers who are setting $SYSTEM.Process.UserRoutinePath() (formerly $ZU(20)), will see a change in behavior from version 2011.1. The change re-adopts the behavior of version 2010.2 and earlier.
Before 2011.1, routine utilities such as $SYSTEM.OBJ.Load() would save the compiled object code in the current namespace. In 2011.1 and later, if a UserRoutinePath has been set, the compiled object code would be saved in the routine path namespace instead of the current one. This version restores the previous behavior so the routine utilities will ignore the UserRoutinePath.
Enhanced Check For Illegal Global References
A previous release enforced the rule that global names cannot end with a period. However, the check did not also examine indirect references with subscripts. In this release, that case is also checked so that
Set name = "^zzz.(3)" Set @name=99
will result in a <SYNTAX> error.
Class Changes
Func() Method Added To Query Classes
A new query member method is available for use, Func. Func() accepts actual values corresponding to the formal parameters defined by the query. It returns an instance of %SQL.StatementResult. When the Func method executes successfully that instance of %SQL.StatementResult is a result set.
If an application has a class with a method whose name is the same as a query name concatenated with "Func", then a member method name collision will be reported at compile-time. Refer to the %Library.QueryOpens in a new tab class for more information.
Callbacks Added For Persistent Class Index Maintenance
Four new callback methods are now available for persistent classes — %OnBeforeBuildIndices, %OnAfterBuildIndices, %OnBeforePurgeIndices and %OnAfterPurgeIndices. These callbacks are invoked by %BuildIndices and %PurgeIndices when the callback implementation is runnable.
The “Before” callback is called prior to doing any purge or build work but after any validation, index list processing and extent lock work. The “After” callback is called after all work is complete but before the extent lock is released. If a “Before” callback returns an invalid status value, then the Build/Purge method is exited immediately with no build/purge work performed and the invalid status value is returned to the caller of the Build/Purge method. For more information refer to the %Library.PersistentOpens in a new tab class documentation.
%ResultSet.* Classes Superceded
The %ResultSet.SQLOpens in a new tab and other classes in the %ResultSet package have been superseded by the Caché Dynamic SQL implementation. Refer to the class documentation for %SQL.StatementOpens in a new tab and the Dynamic SQL section of the Caché documentation for more information.
%Library.ResultSetOpens in a new tab continues to be used by a number of Caché features but for Objectscript InterSystems recommends using %SQL.StatementOpens in a new tab.
Extent Manager Reports Deletion Of A Non-Existent Extent As An Error
In this version, attempting to delete a class extent using the DeleteExtentDefinition(<extentname>) of %ExtentManager.Utilnows return an invalid status error if the extent name does not exist. Applications that depend on the previous behavior must add a check for the existence of the extent before attempting to delete it.
Global Stream Classes Now Report Status Properly
The %SaveData method of the legacy global stream classes (for example, %Library.GlobalBinaryStreamOpens in a new tab or %Library.GlobalCharacterStreamOpens in a new tab)was not properly returning a failure status if an error occurred during save. This omission is fixed and %SaveData returns an accurate status value indicating success or failure.
%Exception.AbstractException — DisplayString Method Must Return %Library.String
The %Exception.AbstractExceptionOpens in a new tab class DisplayString method must return the string to display for this exception.. However, previously, the method signature did not have a return type defined at all. The method is now defined to return an instance of %LibraryString.
Applications that have subclasses of the exception class that have overridden DisplayString must change those classes to add %StringOpens in a new tab as the return type.
Changes To Export And Import Selectivity
In prior releases, Caché did not include selectivity information as part of a class export unless the caller passed in the /exportselectivity qualifier. As a consequence, exporting a class from one namespace and importing it in another did not by default not move the selectivity information. This caused problems because this selectivity information is needed to analyze SQL query issues. Without this information, the compilation of a query could result in choosing a sub-optimal query plan.
Starting with this release, Caché uses different defaults. On export, Caché will export the selectivity information by default as the exported class should fully reflect the class we have stored in the database. On import, Caché will use /importselectivity=2 by default, that is, keep any existing selectivity value if the class already has some but if a property does not have an existing value then use the selectivity from the import XML file.
This test is done on a property by property basis.
Class Deletions
The following classes were present in the previous version and have been removed in this distribution:
-
%Library.Storage — %SQLDelete
-
%Monitor.Health — AbstractCallback, AbstractSensor, Chart, Control, HealthAlert, Period, Rule, SensorClass, SensorReadings, SystemSensors, Test
-
%Net.Remote.Java — ReentrancyTest
-
%ResultSet — SQLQuery
-
%cspapp.exp — utilexpclasscompile, utilexpclassdelete, utilexpclassexport, utilexpclassimport, utilexpclasslist, utilexproutinecompile, utilexproutinedelete, utilexproutineexport, utilexproutinefind, utilexproutineimport, utilexproutinelist, utilexpviewroutine %cspapp.op utilcspsessions, utilensembledashboard, utilopaction
-
%cspapp.sec — utilsysresource, utilsysresources, utilsysssl, utilsysssllist
-
%iKnow.UI.Zen — extendedDataCombo, iKnowSuggestBox
-
%iKnow.Utils.MaintenanceWSAPI — AddEntity
-
%template — soapclientwizarddone, webservicepolicy, webservicepolicycreate, webservicepolicydone, xmlschemawizarddone, xsltwizard, xsltwizarddone
-
Config — Mirror, MirrorSetMembers
-
SYS.DataCheck — LocalDatabasePath
-
Security — Authentication, BooleanYN, Password, Permission
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) |
---|---|---|
%CPT.CalloutIndex | Method | ModuleDirectory |
%CPT.CalloutShell | Method | StandardLanguage |
%CPT.CalloutTypeIndex | Method | ShowChild |
%CPT.HPT.LoadingState | Property | NodeIndex |
%CPT.Tree.Fragment | Method | MatchPlaceholder, Root |
Property | RootNodeIndex | |
%CSP.Util.SMTitlePane | Method | DrawQuickJumpList |
%CSP.UI.Portal.About | Parameter | APPLICATION, CSPURL |
%CSP.UI.Portal.Dialog.ChangePassword | Property | UserRoles |
%CSP.UI.Portal.Dialog.ZenReportServerAction | Method | ondialogFinish |
%CSP.UI.Portal.NLS | Method | DrawHelpText |
%CSP.UI.Portal.ObjectGateway | Property | HasModified |
%CSP.UI.Portal.TaskInfo | Method | GetPIDOBJ |
%CSP.UI.Portal.ZenReportServer | Property | IsModified |
%DeepSee.Component.chartLegend | Method | onloadHandler |
%DeepSee.KPI | Method | %OnGetFilterMembers |
%DeepSee.Query.query | Method | %ProcessFilterSpec |
Property | %filterIncludes, %slicerIncludes | |
%DeepSee.Report.UI.chartInfoWizard | Property | seriesTxt |
%DeepSee.UI.Analyzer | Parameter | CSPURL |
%DeepSee.UI.Architect | Parameter | CSPURL |
%DeepSee.UI.ArchitectSA | Parameter | CSPURL |
%DeepSee.UI.Dialog.WidgetBuilder | Method | ChangeWidget, adjustWidgetSize |
%DeepSee.UI.Dialog.WidgetCatalog | Method | %OnDrawHTMLHead, adjustWidgetSize, dashboardEventHandler |
%DeepSee.UI.FolderManager | Parameter | CSPURL |
%DeepSee.UI.LogViewer | Parameter | CSPURL |
%DeepSee.UI.MDXQuery | Method | setQuery |
Parameter | CSPURL | |
%DeepSee.UI.Settings | Parameter | CSPURL |
%DeepSee.UI.WorksheetBuilder | Method | getColorsPopup, getColorsWidget |
Parameter | CSPURL | |
%Dictionary.ClassDefinition | Method | ClassTypeIsValid, LanguageIsValid |
%Dictionary.MethodDefinition | Method | LanguageIsValid |
%Exception.AbstractException | Property | Code, Data, InnerException, Location, Name |
%Library.CacheLiteral | Method | IsModified, SetModified |
%Library.DynamicQuery | Method | SQLClose |
%Library.EnsembleMgr | Method | setupHealthShare |
%Library.Storage | Method | %SQLLogicalToOdbcFields, %SQLOdbcToLogicalFields |
%Net.Remote.Gateway | Method | %CallServer |
Property | Proxies | |
%Net.Remote.Java.JavaGateway | Method | %JavaBindingAttach, %JavaBindingDetach |
Parameter | JAVABINDINGATTACH, JAVABINDINGDETACH | |
%SQL.Statement | Method | %MetadataGet, %MetadataSet |
%SQL.Statement | Property | %StatementClass |
%SYNC.Transporter | Method | OpenFile, TimeTransport |
%SYS.Task.DiagnosticReport | Method | AuthPassDecode, AuthPassEncode |
%SYSTEM.Help | Method | %ClassName |
%Stream.GlobalCharacter | Method | %Exists, %GetLockReference, %IsModified, %LogicalToStorage, %NormalizeObject, %ObjectModified, %OnClose, %OnConstructClone, %OnNew, %OnRollBack, %StorageToLogical, %ValidateObject, BuildValueArray, Clear, CopyFrom, Flush, IsNull, LastModifiedGet, MoveToEnd, OutputToDevice, Read, ReadIntoBuffer, ReadLine, ReadLineIntoStream, Rewind, SizeGet, Write, WriteLine |
Parameter | BUFFERLEN | |
Property | Buffer, IOSize, LineTerminator, MaxNodeNo, Mode, NodeNo, Position, RemoveOnClose, TempGbl, mLastModified, rollback | |
%Stream.TmpCharacter | Method | CopyFromAndSave |
%TSQL.ResultSet | Method | %Execute, Execute |
%UnitTest.Result.TestAssert | Method | SaveIndices |
%UnitTest.Result.TestCase | Method | SaveIndices |
%UnitTest.Result.TestInstance | Method | SaveIndices |
%UnitTest.Result.TestMethod | Method | SaveIndices |
%UnitTest.Result.TestSuite | Method | SaveIndices |
%WebStress.Scripts | Method | ShowProgress |
%XML.ImportHandler | Property | HandlerType |
%ZEN.Dialog.routineSelect | Method | DrawRoutineItem |
%ZEN.Report.Display.controller | Parameter | NAMESPACE, XMLFORMAT |
%ZEN.Report.Display.node | Method | %GenerateCode, %QuoteValue, %QuoteValueEmbedded, %QuoteValueL10N |
Property | composite, id, parent | |
%ZEN.Report.Display.pagefooter | Property | orientation |
%ZEN.Report.Display.pageheader | Property | orientation |
%cspapp.op.utilsysjobinfo | Method | GetTitlePane |
Parameter | PARENTPAGE | |
%iKnow.DirectInputDO | Property | IKSCRC, IKSENT, IKSPATH, IKSTYPE |
%iKnow.Matching.MatchingWSAPI.GetDictionaryMatches | Property | profileId |
%iKnow.Matching.MatchingWSAPI.GetDictionaryMatchesById | Property | profileId |
%iKnow.Objects.DictionaryElement | Property | MinMatchType, Position, Role |
%iKnow.UI.AbstractPortal | Method | BuildFilterForm, StoreFilter, onChangeOperatorClient, onToggleFilterClient |
%iKnow.UI.IndexingResults | Method | DeleteCurrentVirtualSource, ProcessInput, displayInputScreen, realTimeInputClient |
Property | Loader | |
%iKnow.UI.MatchingResults | Method | DoMatching |
%iKnow.Utils.MaintenanceQAPI | Method | AddEntity |
%iKnow.Utils.MaintenanceWSAPI | Method | AddEntity |
Config.CommonMapMethods | Method | Download, UploadClose, UploadExecute, UploadFetch, Upload |
Query | Upload | |
Config.CommonMultipleMethods | Method | Download, UploadClose, UploadExecute, UploadFetch |
Query | Upload | |
Config.CommonSingleMethods | Method | Download, Upload |
Config.MirrorAsyncMemberSources | Method | UpdateDatabasesForRWAsyncMember |
Config.MirrorMember | Method | DaysBeforePurgeSet |
Property | DaysBeforePurgePresent | |
Security.System | Property | BypassSecurity |
Method Return Changes
The following methods have different return values in this version of Caché:
-
%CPT.CalloutCommon — NodeLineRange
-
%DeepSee.Query.scalarFunction — %EvaluateScalar, %IsScalarFunction
-
%Exception.AbstractException — DisplayString
-
%Exception.SQL — SQLMessageString
-
%Exception.StatusException — DisplayString
-
%Library.CacheLiteral — SQLCompute
-
%SQL — DynamicStatement
-
%XSQL.Log — logSQLCODE
-
SYS.DataCheck.Destination — Connect
-
SYS.MirrorConfiguration — GetOtherFailoverSystemConfig, RetrieveMirrorMemberConfig
-
SYS.Mirroring.GetMirroringInformationSoap — GetFailoverMemberInformation
-
SYS.Mirroring.GetMirroringInformationSoap.GetFailoverMemberInformation — Invoke
-
SYS.Mirroring.MirroringWebServices — GetFailoverMemberInformation
Method Signature Changes
The following methods have different signatures in this version of Caché:
Class Name | Method Name(s) |
---|---|
%CPT.CalloutCommon | BuildAllIndices |
%CPT.CalloutTesting | SetupSettingsString |
%CPT.SQLCallout | Compile |
%CPT.Tree.Fragment | %OnNew, IndexTree |
%CSP.StudioTemplateMgr | AddTemplate |
%CSP.UI.Portal.ZenReportServer | SaveData |
%CSP.UI.SQL.UserPrivPane | LoadPriv, LoadRole, LoadUserRole |
%Collection.ListOfDT | LogicalToOdbc, OdbcToLogical |
%Compiler.COS.Refactor | ChangeClassNameExecute, oneClass |
%Compiler.XML.Generator.Adaptor | GenLiteralImport, GetSimpleExport |
%DeepSee.AbstractKPI | %GetFilterMembers, %GetKPIValue, %OnGetFilterMembers |
%DeepSee.Component.pivotController | getIconHTML, updateState |
%DeepSee.Component.pivotTable | GetQueryStatus, selectCellRange |
%DeepSee.ComputedDimension.Base | %GetComputedMembers |
%DeepSee.ComputedDimension.iKnow | %ProcessIKnowFact |
%DeepSee.Generator | %BuildCubeInfo, %GetSQLFieldExpression |
%DeepSee.KPI | %GetFilterMembers |
%DeepSee.KPIWorksheet | %GetKPIValue |
%DeepSee.Query.Engine | %AggregateEnd, %Consolidate, %GetBranchesForSlicer |
%DeepSee.Query.query | %RewriteCompoundQuery, %RewriteGroup |
%DeepSee.Query.scalarFunction | %EvaluateScalar |
%DeepSee.Report.UI.dataPickPool | setDataTree, setDataTreeFromDSS |
%DeepSee.Report.UI.reportPreviewer | GenerateDataSet, execute |
%DeepSee.Report.dataPresenter | CreateOutputStream |
%DeepSee.ResultSet | %ExecuteListing, GetDefaultFormat, %GetQueryStatus, %GetStatus |
%DeepSee.TaskMaster | DequeueTask |
%DeepSee.UI.Dialog.Analyzer | SavePivotTable |
%DeepSee.UI.Dialog.WidgetBuilder | AddWidgetToDashboard |
%DeepSee.UserPortal.Utils | %ClearDashboardSettings |
%DeepSee.Utils | %GetCubeLevels, %GetCubeList, %SaveSubjectAreaDefinition, %SynchronizeCube |
%ExtentMgr.GlobalRegistry | FindReference, IncompatibleUse, LockUse, RegisterReference, UnLockUse |
%ResultSet.Static | %OnNew |
%Installer.AbstractLogger | flushIO |
%Library.EnsembleMgr | OnSystemStartup |
%Library.FilemanTimeStamp | LogicalToDisplay |
%Library.Persistent | %KillExtent |
%Library.ProcedureContext | Prepare |
%Library.RegisteredObject | %OnNew |
%Library.Routine | normalizeName |
%Library.SerialObject | %Open |
%Library.Storage | %SQLDelete |
%Net.Remote.Gateway | %Connect |
%SOAP.Security.Policy | CheckEncryptedSupportingTokens, FindToken, GetSecurityToken |
%SQL.DynamicStatement | Prepare, findStatement |
%SOAP.WST.RequestSecurityToken | CreateIssueResponse |
%SOAP.WebParameters | ParseParameters, ParseParametersElement |
%SOAP.WebService | Fault, ReturnInternalStatusFault |
%SYNC.Transporter | ExportFile, Import, getTransporter |
%SYS.Journal.File | GetNext, GetPrev, MirrorByTimeReverseOrderExecute |
%SYS.NLS.Locale | %OnNew |
%SYS.Portal.Resources | %SetCustomResource |
%SYS.ProcessQuery | CONTROLPANELExecute, NextProcess, VariableByJobNumberExecute, VariableByPidExecute |
%SYS.Task.History | WriteLog |
%SYS.TaskSuper | DisplayGUID |
%SYS.ZENReportExcelExporter | ExportToExcel, ExportToXlsx |
%SYSTEM.SQL | ImportDir |
%SYSTEM.Security | GetGlobalPermission |
%Studio.SourceControl.ItemSet | Import, Load, LoadToNS, LoadToOS |
%UnitTest.SQLRegression | verifyResults |
%WebStress.Playback | RunStop |
%WebStress.Record | Run |
%WebStress.Scripts | CacheRecorder |
%XML.Implementation | AnalyzeTiming |
%XML.ImportHandler | %OnNew |
%XML.Namespaces | PushNodeForExport |
%XML.Security.Signature | ComputeSha1Digest |
%XSQL.DSI.GlobalPrivateTable | %OnAfterGenerate |
%XSQL.DSI.TempTable | %OnAfterGenerate |
%ZEN.Generator | %DoesXDataExist |
%ZEN.Report.Display.bidioverride | %DrawToXSLFO |
%ZEN.Report.Display.block | %DrawToXSLFO |
%ZEN.Report.Display.body | %DrawToXSLFO |
%ZEN.Report.Display.br | %DrawToXSLFO |
%ZEN.Report.Display.call | %DrawToXSLFO |
%ZEN.Report.Display.callsvg | %DrawToXSLFO |
%ZEN.Report.Display.caption | %DrawCellFO, %DrawCellFO1 |
%ZEN.Report.Display.category | %DrawToXSLFO |
%ZEN.Report.Display.class | %DrawToXSLFO |
%ZEN.Report.Display.container | %DrawToXSLFO |
%ZEN.Report.Display.cssinclude | %DrawToXSLFO |
%ZEN.Report.Display.div | %DrawToXSLFO |
%ZEN.Report.Display.fo | %DrawToXSLFO |
%ZEN.Report.Display.foblock | %DrawToXSLFO |
%ZEN.Report.Display.group | %DrawToXSLFO |
%ZEN.Report.Display.html | %DrawToXSLFO |
%ZEN.Report.Display.img | %DrawToXSLFO |
%ZEN.Report.Display.init | %DrawToXSLFO |
%ZEN.Report.Display.inline | %DrawToXSLFO |
%ZEN.Report.Display.inlinecontainer | %DrawToXSLFO |
%ZEN.Report.Display.item | %DrawToXSLFO |
%ZEN.Report.Display.line | %DrawToXSLFO |
%ZEN.Report.Display.link | %DrawToXSLFO |
%ZEN.Report.Display.masterreference | %DrawToXSLFO |
%ZEN.Report.Display.node | %StyleHTML, %StyleXSLFO |
%ZEN.Report.Display.p | %DrawToXSLFO |
%ZEN.Report.Display.pagefooter | %DrawToXSLFO |
%ZEN.Report.Display.pageheader | %DrawToXSLFO |
%ZEN.Report.Display.pagemaster | %DrawToXSLFO |
%ZEN.Report.Display.section | %DrawToXSLFO |
%ZEN.Report.Display.smallMultiple | %DrawToXSLFO |
%ZEN.Report.Display.table | %DrawToXSLFO |
%ZEN.Report.Display.tableOutput | %DrawCellFO, %DrawCellToHTML, %DrawFooterFO, %DrawFooterToHTML, %DrawHeaderFO, %DrawHeaderToHTML |
%ZEN.Report.Display.tbody | %DrawToXSLFO |
%ZEN.Report.Display.td | %DrawToXSLFO |
%ZEN.Report.Display.th | %DrawToXSLFO |
%ZEN.Report.Display.thead | %DrawToXSLFO |
%ZEN.Report.Display.timeline | %DrawToXSLFO |
%ZEN.Report.Display.tr | %DrawToXSLFO |
%ZEN.Report.Display.xslinclude | %DrawToXSLFO |
%ZEN.Report.Ping | ping |
%ZEN.Report.reportPage | %DrawToXSLFO, %GetFileByAbsoluteURL, %GetFileByRelativeURL, %MakeToXSLFOFile, CreateOutputStream |
%cspapp.exp.utilexpfindreplace | Cleanup, SaveData, SaveRoutine |
%iKnow.DirectInput | ProcessPath |
%iKnow.Filters.GroupFilter | %OnNew |
%iKnow.Filters.SimpleMetadataFilter | %OnNew |
%iKnow.KB.Knowledgebase | LoadDir |
%iKnow.LB.Languagebase | LoadDir |
%iKnow.Matching.DictionaryAPI | CreateDictionaryTerm |
%iKnow.Matching.DictionaryQAPI | CreateDictionaryTerm |
%iKnow.Matching.DictionaryWSAPI | CreateDictionaryTerm |
%iKnow.Matching.MatchingAPI | GetDictionaryMatches, GetDictionaryMatchesById, GetTopItems, GetTotalDictionaryScoresBySource, GetTotalDictionaryScoresBySourceId, GetTotalItemScoresBySource, GetTotalItemScoresBySourceId, ProcessAggregate |
%iKnow.Matching.MatchingQAPI | GetDictionaryMatchesByIdExecute, GetDictionaryMatchesExecute, GetTopItemsExecute, GetTotalDictionaryScoresBySourceExecute, GetTotalDictionaryScoresBySourceIdExecute, GetTotalItemScoresBySourceExecute, GetTotalItemScoresBySourceIdExecute |
%iKnow.Matching.MatchingWSAPI | GetDictionaryMatches, GetDictionaryMatchesById, GetTopItems, GetTotalDictionaryScoresBySource, GetTotalDictionaryScoresBySourceId, GetTotalItemScoresBySource, GetTotalItemScoresBySourceId |
%iKnow.Queries.EntityAPI | GetByFilterInternal |
%iKnow.Queries.CrcAPI | GetCountByDomain |
%iKnow.Queries.CrcQAPI | GetCountByDomain |
%iKnow.Queries.CrcWSAPI | GetCountByDomain |
%iKnow.Queries.EntityQAPI | GetCountBySource |
%iKnow.Queries.EntityWSAPI | GetCountBySource |
%iKnow.Queries.MetadataAPI | AddField, AddListOfValues, GetFieldId, GetValue, GetValueById, UpdateField, UpdateFieldById |
%iKnow.Queries.MetadataQAPI | UpdateField, UpdateFieldById |
%iKnow.Queries.MetadataWSAPI | UpdateField, UpdateFieldById |
%iKnow.Queries.SentenceAPI | GetLanguage |
%iKnow.Queries.SentenceQAPI | GetLanguage |
%iKnow.Queries.SourceAPI | GetTopLanguage |
%iKnow.Queries.SourceQAPI | GetTopLanguage |
%iKnow.Source.Lister | BuildExtIdFromName |
%iKnow.Source.Loader | ProcessBuffer, ProcessVirtualBuffer |
Config.Journal | JournalFilePrefixIsValid |
Config.MapShadows | ListExecute |
Config.NLS.Locales | ImportDir |
Config.NLS.SubTables | ImportDir |
Config.NLS.Tables | ImportDir |
Ens.Adapter | OnKeepalive |
Ens.Alarm | CheckAlarmTasks, RemoveAlarm |
Ens.BPL.UI.Diagram | GetBPLStream, Open |
Ens.Config.Production | addSchema, getDTLSchemas, getItemSchema |
Ens.Job | Launch, RecoverActiveMessage, Start |
Ens.Rule.Model.expression | parseExpression, parseToken, test |
Ens.Util.Documentation | BuildURL, CreateDoc |
Ens.Util.LookupTable | %Import |
SYS.DataCheck.Destination | %OnNew, Connect, ManagerWorkflow |
SYS.DataCheck.Phase | %CreateQuery |
SYS.DataCheck.Query | Answer |
SYS.DataCheck.RangeList | ListElementsExecute |
SYS.DataCheck.System | %OnNew |
SYS.Database | Copy, Defragment |
SYS.Mirror | CatchupDB, PurgeAsyncMemberJournalFiles |
SYS.MirrorConfiguration | AddFailoverMember, CheckMemberConnection, CheckNewMirroredDB, CreateNewMirror, CreateNewShadow, JoinExistingMirror, RetrieveMirrorConfig, RetrieveMirrorMemberConfig |
Security.Events | Create, Set |
Security.Resources | Create |
Security.Roles | Import |
Security.Users | Import, UpdateOne |
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.
Change to Internal Representation Of Signatures
Beginning with this release, the internal representation of non-literal formal argument initial values may be delimited by “{” and “}”. Applications, such as programming tools, that do their own interpretation of parsed formal specifications in the class dictionary must be rewritten to handle this case.
ONDELETE Checking Improved
The ONDELETE keyword is only supported for use with foreign keys, or in relationship declarations specifying “Parent” (the declaration of the child table) or “One” (the declaration of the “many” table). Its use is invalid in all other contexts.
This restriction was not enforced in prior releases, but it now is. For incorrect uses, the class compiler will report an error similar to:
ERROR #5331: OnDelete keyword value 'cascade' is only valid for a relationship: XXX
with the appropriate ONDELETE value, class name and property name replacing the “XXX”.
Language Binding Changes
Java XEP Changes
-
Java XEP: Event Persister importSchema Removed
This version removes all methods that accepted an InterfaceResolver as one of several arguments. Applications that use these methods should be changed by replacing
persister.importSchema(className,resolver);
with
persister.setInterfaceResolver(resolver); persister.importSchema(className);
-
Java XEP: Event Persister Method Changes
In this release, the following three event persister methods have been removed: callCOSProcedure, callCOSFunction, and executeUpdate; the following two new methods have been added:
void callProcedure(String procedureName, String routineName, Object ... args) Object callFunction(String functionName, String routineName, Object ... args)
The method, Event getEvent(String className, int indexMode) is new in this release and is used to control indexing. The default setting for indexMode is Event.INDEX_MODE_ASYNC_ON.
The method, Event.close, no longer conditionally calls stopIndexing. Now it never calls it, so if that behavior is desired, the users will need to call stopIndexing explicitly prior to calling Event.close
Finally, the startIndexing and waittForIndexing methods now check to see if synchronous indexing option is enabled, and if so, they will throw an exception.
-
Java XEP: Event Persister Option Changes
The following options have been removed:
-
OPTION_INDEXING_GET_EVENT_*
-
OPTION_INDEXING_CLOSE_EVENT_*
-
OPTION_FETCH_LEVEL_*
-
OPTION_REFERENCES_*
-
OPTION_INHERITANCE_*
The following options have been added: INDEX_MODE_ASYNC_ON, INDEX_MODE_ASYNC_OFF, INDEX_MODE_SYNC.
Because of the option removal, applications can select the JNI query flavor via the method,
void useJNIQuery(boolean jni_flag);
where jni_flag selects JNI querying when true, and Java querying when false.
Finally, these events have been moved from Event Persister to Event: FETCH_LEVEL_ALL, FETCH_LEVEL_DATATYPES_ONLY, FETCH_LEVEL_NO_ARRAY_TYPES, FETCH_LEVEL_NO_OBJECT_TYPES, FETCH_LEVEL_NO_COLLECTIONS.
-
XDO (And Dynamic LCB) Cleanly Prohibit Accessing Subclasses
These bindings do not support subclasses. However, in prior releases the eXTreme Dynamic Objects (XDO) and dynamic Light C++ Binding failed to throw an exception if an attempt was made via one of them to create a dynamic object for a class which inherits from another persistent class (that is, a subclass), and also failed to prohibit data to be stored via this dynamic object.
In the release, if an attempt is made to create a dynamic object for a class which is a subclass, an XDOException (for XDO) or Db_err (for dynamic LCB) is thrown with the message “Subclasses are not supported by this binding”.
Changes to Java Packages
In this release, CacheClassBuilder is now contained in com.intersys.objects; before this it resided in com.intersys.cache. Package com.intersys.objects is considered to be public package for application developers while com.intersys.cache contain only internal classes intended for direct use InterSystems modules. InterSystems provides JavaDoc for classes in com.intersys.objects.
Class CacheClassBuilder defines an API that can be used by a Java application to create and modify Caché classes inside a Caché server. It is used by some advanced customers and therefore its place is in the public package.
The old class, com.intersys.cache.CacheClassBuilder, exists as a stub for compatibility. It is now deprecated but usable. BuildClass.java is now part of the Java samples and shows how to use CacheClassBuilder
Jalapeño Schema Incompatibility
Applications created with versions of Jalapeño earlier than 2012.2 are incompatible with the server for Jalapeño 2012.2 or higher. To update an older application, use Jalapeño 2012.2 to generate new schemas and recompile the application on this release.
SQL Changes
TO_CHAR Now Honors Locale Decimal Separator
This release now correctly uses the NLS configured DecimalSeparator for the format option "D" of the function, TO_CHAR, hen converting numbers to strings.
Changes to Lock Behavior for CREATE INDEX
When the execution of a DDL statement locks the class definition to be edited, the lock timeout is nopw set equal to the SQL Lock Timeout setting for the process. The old behavior used a lock timeout of 0 meaning the lock would not wait at all to see if the lock became available.
Also, for a CREATE INDEX statement execution, the class definition lock now remains until the completion of the execution of the entire statement, including the population of the index data. In preceding versions, the class definition lock was released before the index was built. This caused problems if the building of the index failed and the create index had to be rolled back.
SQL Gateway Now Supports BINARY and VARBINARY in %SQL.JDBCResultSet
The SQL Gateway now supports the datatypes BINARY and VARBINARY for use in %SQL.JDBCResultSet. Prior to this release, columns declared as binary would be retrieved as hexadecimal strings.
SQL Shell Displaymode Change
The SQL shell no longer opens statement results automatically when the displaymode is not set to the current device. Instead, the Shell allows the user to specify a path and file name where statement results are stored. If the file name is not given, a random file name is generated and used. A list of files used for a particular statement is displayed on the current device after the statement is executed.
Suppress PKEY/UNIQUE Constraint Creation on IDENTITY Column
In prior versions, when creating a table through DDL that specifies an IDENTITY column, if the column definition also included a UNIQUE or PRIMARY KEY column constraint, Caché SQL would suppress the PRIMARY KEY or UNIQUE index definition in the class; this was done because the IDENTITY column is already equivalent to the IDKEY and is projected as the PRIMARY KEY of the table. However, if the PRIMARY KEY or UNIQUE constraint was defined as a table constraint instead of a column constraint, Caché SQL did not suppress the definition of the PRIMARY KEY or UNIQUE index definition in the class.
Beginning with this release, it does; but it also means Caché has a limitation in this area. If you attempt to alter a table and drop a primary key or unique constraint where Caché did not previously create an index for the constraint because the field is the IDENTITY field, the drop of the constraint will return an error because the key could not be found. InterSystems intends to correct this in a future version with enhancements to the constraint model in the class definitions.
Round Scalar Function Now Rounds Scale Factor
The second argument to the SQL ROUND scalar function is now itself rounded to the nearest integer. For example:
ROUND(1234.567,2.5)
will be the same as
ROUND(1234.567,3)
This change makes the ROUND function consistent with the TRUNCATE function behavior.
Correction to DATETIME handling in Data Import Wizard
In prior versions, when that Data Import Wizard converted a DATETIME value with a format similar to “June 24 1947 03:04:05:006PM”, the milliseconds portion of the time was not handled properly when ":" separated the seconds from the milliseconds. The millisecond value is now properly converted.
Increase Lock Timeout for Cached Query Metadata
In previous versions, the lock timeout used when the system needs to lock cached queries was the same as the SQL Lock Timeout, which defaults to 10 seconds. However, it is sometimes desirable to have a longer lock timeout for cached queries. In this release. there is a new API that a system administrator can invoke to change the lock timeout for cached query locks. It is:
Set StatusReturn = $SYSTEM.SQL.SetCachedQueryLockTimeout(timeout, .oldvalue)
In addition, this release cvhanges the default timeout for cached query locks to 120 seconds.
CSP Changes
Correct Header Display by $SYSTEM.CSP.Show
Until this release, the showhttp flag was interpreted the wrong way in the $SYSTEM.CSP.Show function. Now, when it is true, it shows the HTTP headers; when it is false, it does not not show them.
New Default for javascript Static Files with No Charset
In order to align Caché behavior with major web vendors such as Apache and IIS InterSystems is changing the default way static javascript files are rendered. This change only effects *.js files if they are rendered by Caché using the stream server; javascript files served from the web server are not affected.
In this release, javascript files are now be marked as Content-Type of application/javascript where as before they were marked as text/javascript. (application/javascript has superseded the previous content type and is the correct type defined in the HTML standard.) In addition, Caché will default to not sending a charset for javascript files; this is consistent with the default behavior of the major web servers.
This means that if the file contains a BOM (byte-order mark), the browser will automatically detect this and use the correct charset; if the javascript file does not contain a BOM, then the browser will default to reading this in utf-8. The previous behavior sent a charset based on the default file translate table which, if the file contained a BOM, prevented the browser from detecting and using this information.
AN application that wishes to override this new behavior to specify a charset for the javascript files by setting the global, ^%SYS("CSP","MimeFileClassify","JS") to the list value $listbuild(contenttype, binary, charset). For example,
SET ^%SYS("CSP", "MimeFileClassify", "JS") = $listbuild("text/javascript", 0 ,"ISO-8859-1")
which sets the older content-type and uses the iso-8859-1 charset. In addition, if the CSP translate table is defined to be something other than “”, or if the ^%SYS("CSP","DefaultFileCharset") global is set to a null value, Caché will use this charset for javascript files as well as other text files. By default, neither of these items are set.
XML Changes
Reset Current Device Translate Table When %XML.Writer Finishes
If an invocation of %XML.WriterOpens in a new tab uses a different translate table from the process invoking it, Caché re-establishes the process translate table as the default when %XML.WriterOpens in a new tab returns. Previous versions did not do this.
Validity Checking Now Done for NUL-Terminated Empty Strings by XMLImport
In prior releases, a defect bypassed validity checking for imported strings consisting of the value $CHAR(0). In this release, Caché checks the validity of a %String value that has the value, $CHAR(0).
This change treats $CHAR(0) as having a length of zero for purposes of enforcing MINLEN and MAXLEN comparisons. This also applies to VALUELIST: to include $CHAR(0) as a valid value, two consecutive commas are needed in the VALUELIST, for example,
VALUELIST = ",,a,b,c"
SOAP Changes
Control Inheritance of Header Data
Previously all headers in the parameters XData were ignored if the parameter SOAPMETHODINHERITANCE was set to 0. Beginning with this release, when the web service or web client parameter SOAPMETHODINHERITANCE is 1, then header information from the XData for the parameter is always inherited. This change also inherits the header information which is not specific to a method (request or response element as direct child of parameters element) even if SOAPMETHODINHERITANCE is 0.
New, Single Method to Add to SOAP Security Header
In previous releases, when you added items to the SOAP security header, you had to choose the method to use: AddToken() or AddElement(). In this release, these methods are deprecated and replaced by the new method AddSecurityElement(). You are not required to make any changes to existing web services or clients. If you want to update them to use the new method, you can do so easily; it is not necessary to adjust the calling sequences.
In previous releases, if the item being added just carried data, you used AddToken(). This rule means that you used this method to add the following items: <BinarySecurityToken>, <DerivedKeyToken>, <EncryptedKey> (if it does not include a <ReferenceList>).
If the item being added causes either signing or encryption, you used AddElement(). This rule means that you used this method to add the following items: <Signature>, <EncryptedKey> (if it includes a <ReferenceList>), <ReferenceList>.
Argument Order Correction for WebMethod
In past versions, WebMethods created by the SOAP Wizard had the Output arguments always at the end. In this version, a ByRef argument is now placed correctly, based on the WSDL, after an Output argument.
The incorrect ordering worked for client WebMethods because XMLSequence=0 was specified for the descriptor class. However, it did not work for web services. An existing client which is rebuilt will, in this case, have its arguments reordered and require called routine to change calling sequences. This change has no effect at runtime unless the client is rebuilt using the wizard.
BASIC and MVBASIC Changes
MVBASIC Now Passes Multidimensional Array Elements by Value
Prior to this release, the parameter passing behavior for using array element variables as actual parameters in MVBASIC calls to subroutines and methods was inconsistent. When an MVBASIC application called a subroutine or function passing an array,
-
it passed a subscripted array element variable of an MVBASIC array declared in a DIM statement with explicit integer dimensions by reference;
-
attempting to pass an array element variable of a COS multidimensional array containing 1 or 2 subscripts generated a run-time error.
Furthermore, when an MVBASIC application called a method, it passed all subscripted array element variables by value.
Beginning with this version, when an MVBASIC application calls either a subroutine, a function or a method, a subscripted array element variable of an MVBASIC array declared in a DIM statement with explicit integer dimensions is passed using by-reference while a subscripted array element variable of a Objectscript multidimensional array is passed using by value. This means there is no longer an error when passing an Objectscript multidimensional array element variable as a parameter. This is alsoa change to the way arrays are passed to methods.
If an application wishes to preserve the previous behavior where a change to a formal parameter in the method did not change the value of the corresponding actual parameter, it should enclose the parameter in parentheses; the compiler then interprets that actual parameter as an expression value instead of a variable.
There is no change to passing any variable (array or scalar) that does not include subscripts.
Change The Definition Of IFS() When The Condition Includes Singletons
In this release, the definition of the MVBASIC IFS(B, X1, X2) function has changed. In previous versions, it always produced a dynamic array with same number of fields, values, and subvalues as the shape of the boolean, B. The new definition covers the following three situations:
-
If argument B contains is a singleton (that is, it does not contain any field marks, value marks or subvalue marks), either the result is all of X1 or the result is all of X2 depending on whether B is true or false.
-
If B is a dynamic array that contains a field component which is a singleton, the corresponding field of the result is all of the corresponding field of X1 or X2 (including all values and subvalues) depending on whether the singleton Boolean field component is true or false, respectively.
-
If B is a dynamic array that contains a value component which is a singleton, the corresponding value of the result is all of the corresponding value of X1 or X2 (including all subvalues) depending on whether the singleton Boolean field component is true or false, respectively.
SUM Function Now Returns Dynamic Array
The SUM() function is defined as returning a dynamic array string. However, in previous releases the compiler was incorrectly treating it as returning just a single number; only the first component of the dynamic array was returned. This defect has been fixed and SUM() now returns all the components of the dynamic array result.
MVBASIC IO Status Handling Changes
Formerly, MVBASIC placed the error status from a failing I/O statement into @SYSTEM.RETURN.CODE. Unfortunately, this conflicted with other uses of this same variable so MVBASIC I/O statements no longer put I/O status values there.
MVBASIC I/O statements now place the status value into the system variable, @IO.STATUS. If the I/O statement succeeds, a zero is placed in @IO.STATUS; if the I/O statement fails then a non-zero error code is placed there. I/O error codes are also placed into the system variable, @IO.ERROR, but this variable is unchanged on a successful I/O statement. Therefore, @IO.STATUS gives the status of the most recently executed I/O statement, while @IO.ERROR gives the status of the I/O statement that most recently failed.
Some I/O statements also put the error code into the @STATUS system variable; this behavior has not changed. The I/O error message codes correspond to the items in the ERRMSG file.
MVBASIC programs that used I/O error codes stored in @SYSTEM.RETURN.CODE must be rewritten to instead use @IO.ERROR (and possibly @IO.STATUS.)
xDBC Changes
Support Binary Values In JDBC Linked Procedures
In this version, output arguments declared as binary will be returned that way. In past versions, they were returned a hexadecimal values. The same is true of values in a select list.
Avoid Rounding In Return Values From ODBC
Previously, a C++ application read decimal values from ODBC by calling GetData(). That method requested the value as a string value which the C++ binding then converted to decimal. When the data was processed in this way, ODBC converts it to a number and then back to string, and may lose some precision in doing so. In this release, the data is requested in a way that avoids the intermediate conversion to a string, so the original precision is preserved.
DeepSee Changes
Change to Interpretation of Combined Filters
In this release, DeepSee combines filters differently than in previous releases, in a subset of cases. This is not a change in the behavior of MDX, but instead a change in how DeepSee interprets a pivot table definition as an MDX query.
Previously, if you dragged and dropped multiple members of the same level to the Filters box (in Analyzer), DeepSee combined those members with a logical OR. Now it combines them with a logical AND.
To combine the members with a logical OR, you must instead do the following:
-
Drag and drop the level to the Filters box.
This action adds a drop-down list to the bar above the filter table.
-
Select the members from this drop-down list.
This change potentially affects the results shown by your existing pivot tables, depending on how you created them. InterSystems suggests that you examine your pivot tables and adjust any as needed. You can do this in the Analyzer.
Alternatively, you can do this in Studio, by carefully editing the applicable .dfi items in the Other folder in the Workspace window (or by editing the container class that you use to hold the pivot tables). If you dragged and dropped multiple members of a single level to the Filters box, the pivot table definition contains multiple <filter> elements that refer to the same level. For example:
<pivot ...>
...
<filter spec="[ColorD].[H1].[Favorite Color].&[Blue]" key="Blue" value="" text="Blue" ...>
</filter>
<filter spec="[ColorD].[H1].[Favorite Color].&[Green]" key="Green" value="" text="Green" ...>
</filter>
</pivot>
To change this to the other form, which is in interpreted as logical OR, replace the two <filter> elements with a single <filter> element that has a combined value for key:
<pivot ...>
...
<filter spec="[ColorD].[H1].[Favorite Color].Members" key="{&[Blue],&[Green]}" ...>
</filter>
</pivot>
If you are not comfortable with making such manual changes, open the pivot table in the Analyzer and make the change there.
For examples that show the two approaches, see “How DeepSee Combines Filters” in the chapter “Filtering Pivot Tables” in Using the DeepSee Analyzer.
Change to Handling of Local Overrides to Pivot Table Definitions
This release changes how DeepSee handles overrides made to pivot table definitions from within dashboards.
A dashboard widget can include the Mini Analyzer button, which permits users to override the pivot table definition. The override was saved as the localDataSource attribute within the XML for the pivot table, and this override was visible to all users. DeepSee now saves local overrides separately for each user, within a global. The localDataSource attribute no longer has any effect.
Zen Changes
Changes to Generated Names For CSS3 Stylesheets
Until his release, the filenames generated for CSS3 stylesheets were not compatible with all OpenVMS releases. This is due to the inclusion of an extra “.” character in the filename. Starting with this release, the filenames that Caché generates for CSS3 stylesheets will end with “_3.css” instead of “.3.css”.
This should be completely transparent for most applications, however, it is possible that application code explicitly references the previous filenames. If that is the case, the application must be changed to use the new filename.
Zen Reports Changes
Replace Apache FOP with Skynav FOP
This release replaces Apache FOP with Skynav FOP. Skynav FOP was developed by Glenn Adams, who is sponsored by Basis Technologies. Skynav FOP is a branch of Apache FOP though it exists under a separate source repository. It has an Apache license. It offers complex script support for languages like Arabic and Hebrew which is why InterSystems made the switch.
This change requires no change to the administration of FOP. There is no change to configuration settings. Our software acts as before except now supports complex scripts if the font for the complex script is in a supported font, for example, Arabic. This information is obsolete. This complex script support is in Apache FOP.
Change for SVG Processing
This release of Caché installs revision 1229814 of the batik trunk. This is done to address a defect in version 1.7 of batik that prevents ZEN Report COS Charts and ZEN Page Charts from using the same SVG files.
The RenderServer Now uses Environment Variables
Beginning with this release, runwithxep.bat will now use the environment variables JAVA_HOME and XEP_HOME in determining location of Java binary files and the XEP library.
Zen Pages Uses CSS Level 3
This release modifies the base Zen page class so that the CSS level defaults to 3 for any browser whose user agent contains Mozilla/5.0 or above (basically, any modern browser including IE9 and above; false for IE8 and below. This tells the browser the page uses HTML5. Some pages may not work well in HTML5 mode (usually due to invalid CSS values). Developers should either correct the pages or set cssLevel to 2 as described in this section.
If the application wants to force CSS level to 2 (because of incompatabilities), it can override the %OnDetermineCSSLevel method for the page and return 2, or change the cssLevel globally by setting the ^%ISC.ZEN.cssLevel global to 2.
GenerateReport Produces HTML5
GenerateReport now generates HTML files that are HTML5 compliant. This may lead to problems in displaying the results of GenerateReport on a non-HTML5 compliant browser such as IE 8.
To generate an HTML file that opens in an HTML 5 browser, the file extension must be ".xhtml" not ".htm" or ".html".
Element bidioverride Changes
In prior releases, Zen Reports generated bidioverride as a div for HTML. In this version, it generates a fo:bidi-override instead. The direction attribute of Zen Reports element, bidioverride, sets the dir attribute of fo:bidi-override. The unicode-bidi attribute of bidioverride is ignored.
Elements <write> and <inline> Do Not Insert Spaces
This release corrects the processing of the <write> and <inline> elements so that they no longer emit extra spaces. Application that previously relied on this behavior will need to be modified.
Section Now Inherits Writing-Mode From Containing Report
The fo:page-sequence generated by a section now inherits the writing-mode from the containing report if the writing-mode is not specified for the section.
Remove Orientation Attribute
The “orientation” attribute (used to set portrait or landscape mode) was not used in a meaningful way in previous releases. If report definitions are using orientation within pageheader or pagefooter, the developer should remove it. The report should have no change in its visual appearance.