Release and Upgrade Information for Caché 2010.1
This chapter provides the following information for Caché 2010.1:
New and Enhanced Features for Caché 2010.1
The following major, new features have been added to Caché for the 2010.1 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 the Upgrade Checklist.
Major New Features
Class Compiler And Routine Dispatch Improvements
Version 2010.1 contains many improvements to the performance and reliability of our object implementation. Many of them are changes to the underlying implementation and therefore invisible to developers. Their effects are evident as much improved compilation times – some early testers report up to twice as fast - and faster run-time performance. The class compiler has been improved to support richer development options, better ease of use and faster compile times. The corresponding object runtime and dispatch mechanisms have also been enhanced for better performance and scalability. Version 2010.1 now supports runtime superclass resolution, system implementations for commonly generated property methods (Get, Set, isModified, setModified), and a shared class cache.
There are new compiler and class dispatch mechanisms that avoid errors associated with compiling a class while instances of the class are in use. The compiler also has improved logic for determining when changes to a superclass require recompilation of subclasses; this avoids unneeded recompilation. Details may be found in “Class Compiler Notes” in Using Cache Objects.
Java Dynamic Object Interface
This version of Caché introduces a new high-performance interface for Java programs that provides the following:
-
Multidimensional Storage (MDS) API
Java applications may now access and manipulate Caché globals directly via a JNI (Java Native Interface) without requiring a conversion to Java objects. It enables the Java application and Caché to execute in the same process space. Among the advanced features of Caché supported by this interface are:
-
Locking (incremental, non-incremental, exclusive, shared ...)
-
Transactions
-
Iterating over globals represented in the multidimensional data structure
-
Automatic parsing of Java arrays or strings to create or update Caché $LISTs
-
-
Java Dynamic Object API
The API provides very fast Java access to objects stored in Caché via an in-process connection based on JNI, the Light C++ Binding, and Caché callin. The API is dynamic; the classes accessed need not be known at Java application compile time, and no separate code generation step is required.
-
In-process JDBC
This enables JDBC to use a non-TCP/IP connection to Caché like the Dynamic Object API. Applications can execute SQL queries and other SQL statements via JDBC, and in the same transaction context as methods of the Java Dynamic Object API.
Rapid Application Development
Dynamic SQL
This release of Caché includes support for a new interface for dynamic SQL, which allows users to define and execute SQL statements at runtime. Dynamic SQL is now implemented through the %SQL.StatementOpens in a new tab and %SQL.StatementResultOpens in a new tab classes. %SQL.StatementOpens in a new tab includes support for the following methods:
-
%New – for instantiating a new statement object
-
%Prepare – for preparing an SQL statement, including one that supports runtime parameters
-
%Execute – for executing a prepared statement
Execution of a dynamic SQL statement creates a result object, which is an instance of the %SQL.StatementResultOpens in a new tab class. %SQL.StatementResultOpens in a new tab can hold simple data, a single result set, or multiple result sets, depending on the SQL statement that was executed. It includes functionality for iterating through a result set, handling errors, and so on; it also includes functionality for examining statement metadata, manipulating the form of data for display, and related operations.
For more information on dynamic SQL, see the chapter Using Dynamic SQL.
Performance And Scalability
ECP Scalability Improvements
In prior versions, if a request buffer from an ECP application server contained a synchronous request (such as a Set, Kill, $INCREMENT, and so on) that resulted in a disk I/O, subsequent requests in that buffer would wait till the disk I/O for the synchronous request completed. Now, the ECP server process daemon on the database server will continue to service subsequent read (or get) instructions that can be serviced from the buffer, in parallel while the disk I/O is completing, thereby speeding up responses to the application server.
Reliability, Availability, Maintainability, Monitoring
DataCheck
The DataCheck facility provides a mechanism to compare the state of data on two systems to determine whether the two are consistent. It accounts for the situation where the data on each system may be in transition, and includes logic to re-check discrepant ranges. A typical use of this functionality would be to verify that the source and destination of shadowing are consistent.
Compression During Shadowing
Caché version 2010.1 introduces compression of journal data from the primary to the shadow. The source (primary) compresses a source journal block before sending it to the receiver (shadow); the receiver decompresses it upon receipt, prior to saving it to the shadow copy of the source journal file.
ECP Responsiveness Metric
Fast responsiveness of a Data Server is key to good performance on the Application Server. To permit measurement of response times, a new property, ResponseTime, has been added to the SYS.Stats.ECPAppSvrOpens in a new tab class that allows you to measure the responsiveness of the Data Server(s) that this application server is currently connected to. If there are multiple connections, the value is the overall response time for all Data Server connections. To compute the average response time, use the number of connections contained in ResponseConn.
Security
Separate Delegated Authentication and Delegated Authorization
With this release applications can now use different third party technologies for Kerberos and OS authentication using the Delegated Authentication mechanism. This allows customers to use LDAP (Lightweight Directory Access Protocol), for example, to define the Roles of a user, while using Kerberos to authenticate the user.
Documentation
Removal Of $ZUTIL Documentation
In this release, InterSystems provides class components (methods, or properties) that have the same information and functionality as each of the documented $ZUTIL functions. This has been done to provide a more modern interface to system services available to a wider range of languages used in Caché applications.
In accord with this transition, the documentation for the $ZUTIL functions has been excised from the ObjectScript reference book. It is now part of a separate document stored in the legacy documentation archive. No further updates to it will be made.
The $ZUTIL functions will remain available for applications to use. However, all future functionality updates which would have been done by adding new $ZUTIL functions will use a class paradigm instead.
InterSystems encourages applications to convert to the new usage. To assist in the transition, a table giving the $ZUTIL function identifier and the new equivalent is given in the conversion checklist for this release. The information will also be reproduced temporarily in the ObjectScript reference work as well.
In a few instances, the $ZUTIL functionality is now provided by system variables ($NAMESPACE, and $DEVICE). Also, this information does not include those $ZUTIL functions affected by the removal of support for DDP and DCP.
Change In PDF Page Size
The page size for documentation PDFs has changed in the version. Previously, pages assumed a height of 9 inches and a width of 7 inches. Now they use a height of 11 inches and a width of 8.25 inches. The margins have also been been reduced slightly to 0.75 inches.
This new format permits larger tables and figures, and wider program listings. Waste paper as a result of cropping has been eliminated since the new format will fit on both A4 and U.S. letter-sized paper without need for cutting before binding.
Planned Changes
Database Extents Deprecated
The use of database extents was introduced in early releases to work around the fact that files sizes were severely restricted. Databases of that period often exceeded the limits on the size of an individual file. Database extents allowed a logical database to span multiple physical files.
The limits in the underlying technology are no longer relevant – operating systems, mature filesystems and volume managers currently provide support for extremely large files. Database extents have been rendered obsolete. In the interest of simplifying system management, database extents are no longer supported as of this release.
In a future version, Caché, Ensemble, HealthShare and TrakCare will no longer support database extents. A tool will be provided to assist any customers with extents to aggregate them into appropriate files.
DCP, DDP And LAT Deprecated
InterSystems introduced Enterprise Cache Protocol (ECP) in 2002. Since then, all of our major customers have adopted ECP to deploy scale-out architectures. Usage of DCP and DDP, earlier technologies used to network databases, has diminished considerably and is now almost exclusively used when data is shared between Caché and earlier M technologies.
We intend that, in the latter half of 2010, Caché and Ensemble releases will no longer support DCP and DDP. LAT support on Windows will be deprecated at the same time.
Caché 2010.1 Upgrade Checklist
The purpose of this section is to highlight those features of Caché 2010.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 2009.1 and 2010.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 2010.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 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:
Operational Changes
Journaling Status Change By Applications Requires Admin Privilege
Setting or clearing the "no journaling" process flag in programmer mode via DISABLE^%SYS.NOJRN or ENABLE^%SYS.NOJRN, respectively, now requires %Admin_Manage:USE privilege. A <PROTECT> error is generated if the privilege requirement is not met.
Journal History Log File Critical To Journal Management
Beginning with this version, journal restore has been improved with an option to locate journal files to be processed via a journal history log. The history file, journal.log, is located in the manager's directory and should not be modified by customers.
No changes to journal.log should be made by any means other than InterSystems-supplied utilities. Failure to observe this rule can result Caché determining that the file has been corrupted. This will result in journaling being disabled.
If journal.log is deleted, Caché will create a new one when creating a new journal file; however, information on previous journal files will be lost.
Changes In Memory Usage
This version introduces several object-related optimizations which involve additional data elements to be cached (both at a system-wide and per-process level). As a result, there are implications for both system and process memory utilization that must be noted.
The optimizations in this version require additional routine buffers to be available. As a result, the following should be considered:
-
If the default routine buffer pool is in effect, then a 2010.1 Caché installation will consume an additional 8MB system-wide.
-
If, however, a custom routine buffer pool is used (for example, one greater than 17MB), the additional amount of shared memory space to be allocated to routine buffers will depend on the routine buffer usage/utilization:
-
If a rough estimate is desired, increase the routine buffer pool by roughly 20%-30% of the current allocation. For example, if the current allocation is 50MB, increase it to 60MB-65MB.
-
If an accurate estimate is desired, the current system routine buffer utilization will need to be reviewed. This can be done by running the ^GLOSTAT utility and monitoring the "Routine not cached" statistic. The goal is to minimize this value, and this can be achieved by increasing the size of the routine buffer pool.
-
In 2010.1, each process will cache more classes and class info so as to optimize performance. This can result in a 10KB to 30KB memory footprint increase per process.
In 2010.1, shared class descriptors will be cached. This memory is allocated from the generic memory heap (gmheap). As a result, the following should be considered:
-
The default value for gmheap in 2010.1 has been increased from 3200KB to 6400KB. This is to accommodate the additional memory used due to system-wide class descriptor caching. This can occupy anywhere from 1MB to 1.5MB of the gmheap. The amount occupied depends on the number of classes and objects used.
-
If a non-default gmheap value is used for an object-based application,
-
If the configured gmheap is within 10% of the default (that is, it is between 2880KB and 3520KB), it will be increased automatically by 1600KB when the instance is upgraded.
-
If the configured gmheap is outside of the above range, a warning will be included in the cconsole.log indicating that the gmheap value should be manually increased. If a rough estimate of the increase is sufficient, InterSystems recommends an increase of 1600KB. For a more detailed estimate, thecstat can be utilized to gather system statistics and provide a more accurate estimate. For additional guidance and information, please contact InterSystems Worldwide Customer SupportOpens in a new tab.
-
This version of Caché will increase the gmheap to a minimum value when the system is upgraded. This minimum value is 4800KB for all non-HP platforms; on HP platforms the default is 9600KB.
-
If the size of the gmheap is found to be less than the default, the upgrade installation process will increase it to that value.
-
If the size of the gmheap is more than the default, upgrade writes a message to the cconsole.log file advising that it should be increased by an additional 1600KB.
Licensing Added To CacheProvider
Client licensing is now standardized in this version to provide consistency in license usage between ODBC, and DotNet.
Exporting Classes To XML Omits Generated Classes
When exporting classes to XML format, Caché now removes any classes that are generated by other classes already in the export/compile list. The reason for this is that compiling the class that generates this other item will recreate the omitted class. Often these generated classes are things such as classes for SQL projection which are also marked as deployed. Before this change, an attempt to export a package which contained a persistent class with a collection property would result in an error message about not being able to export deployed classes. Now this deployed class is automatically removed from the export list and no error is reported.
Check For Global Name Errors On Truncation
When a global name is longer than 31 characters, Caché truncates the name to 31 characters for all operations. This can result in the last character of the name being a period which is invalid as the last character. In prior releases, Caché was not detecting this condition and using the invalid global name in the global or LOCK operation which resulted in errors. In this version, Caché will return a <SYNTAX> error when the long name is truncated.
The behavior in previous versions can be restored for the system by setting the GlobalNameTruncated property in the class, Config.MiscellaneousOpens in a new tab.
Counters For SNMP And WMI Changed
This version, eliminates the use of a class of metric counters which had to be specially enabled, and substitutes counters which are always "on" and more closely integrated into the system code. This should noticeably improve the overhead of using either SNMP or WMI for monitoring. The Lines counter is replaced by Commands; GlobalSets becomes GlobalUpdates; GlobalKills has been eliminated. The changes are documented in the MIB and MOF.
^PATROL has been changed to use the new counters. The old behavior and variable names are available by activating $$Light^Patrol(0).
Changes To Temporary File Management
Beginning in this release, Caché has improved the handling of its temporary files to the point that deleting them at startup is no longer necessary. Therefore, Caché startup will no longer delete any files in the Temp directory.
Startup will no longer delete any user files in the Temp directory. If an application uses this directory to store temporary files, it is the responsibility of the application to manage the files it creates across system restarts.
Platform-specific Items
This section holds items of interest to users of specific platforms.
$ZF For OpenVMS Changed Privileges
An error that caused $ZF calls on OpenVMS systems to execute with more privileges than designed has been corrected. If this affects your application, please contact InterSystems Worldwide Customer SupportOpens in a new tab for assistance.
Caché Registry Permissions Explicitly Set For Non-Windows Platforms
The Caché registry file, cache.reg, will now have its permissions explicitly set by the installation process. The file will have root as the owner and be writable only by it.
Resource Statistics Gathering Off By Default For Some 64-Bit Platforms
Beginning with this version, the gathering of resource usage statistics is disabled by default on Itanium, POWERPC, and x64 platforms. Enabling and disabling the collection of statistics is done via the Config.MiscellaneousOpens in a new tab class. Set the CollectResourceStats property to true to enable the collection of statistics and false to disable it.
LAT Configuration For Microsoft Windows
The [LAT] section of the cache.cpf file is incomplete in this version of Caché. The System Management Portal does not configure the advertised services: ServiceName, ServiceDescription, and ServiceRating. Therefore, the LAT daemon (lat.exe) now it reads its startup parameters from a lat.ini file in the installation directory instead of from the cache.cpf configuration file. Users employing LAT finctionality should copy the [LAT] section from the existing cache.cpf file into a new lat.ini file or create the information with a text editor.
A sample [LAT] section is shown here. There can be a maximum of eight LAT services advertised. This sample has two. Each service consists of a ServiceName, a ServiceDescription, and a ServiceRating.
[LAT] NodeName= MessageRetransmitLimit=8 HostMulticastTimer=60 NodeGroups=0 UserGroup s=0 ServiceName_1=CACHE ServiceDescription_1=Cache LAT service ServiceRating_1=1 ServiceName_2=Cache2 ServiceDescription_2=Second LAT device ServiceRating_2=1
The LAT service will be deprecated in Caché version 2010.2.
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.
General Operational Changes
Interactive And Command Invocations Use SHELL Environment Variable
Previously, when invoking an interactive UNIX™ shell via $zf(-1) (or “!” or “$”), Caché used the setting of the SHELL variable if it was defined, otherwise Caché used just sh to start the shell; when a command name was specified, Caché always used /bin/sh.
Now, Caché will check for the SHELL environment variable (and use it if defined) in both cases. This can affect any UNIX™ commands that depend on using /bin/sh.
Changes In Licensing Display
In the output from licensing display functions, under some circumstances fields could run together (leaving no space between columns). When such output was sent to a file and then a program attempted to parse it, the program could fail because it could not distinguish the field boundaries.
Now, field output will break to the following line if this occurs; new types of parser errors are possible. The recommended way to obtain and work with license data is via queries in the %SYSTEM.LicenseOpens in a new tab class.
$SYSTEM.License.Login Now Appends Client IP Address
Applications that call ##class(%System.License).Login(UserId) will find that the license Id has a client IP address appended. This will affect license counting, if the customer previously had users log in to CSP sessions and enabled username-based licensing to cause other types of connections to also use $USERNAME as the license Id. The CSP login will no longer have the same license identifier as other connections.
Also, $System.License.Login() will produce different license Identifiers when called on this version of Caché than on earlier versions. This will cause two license units to be consumed.
Kernel Error Codes Made More Exact
When running out of argument stack space, Cache would sometimes report the condition as a <STORE> error, other times as a <STACK> error, and still others as <ASTACK>. Now detection of insufficient argument stack space always reports the condition as <ASTACK>; running out of heap storage will generate a <STORE> error. The error code, <STACK>, is no longer used.
The argument stack and the string stack share the same block of memory. When a program is using an excessive amount of one kind of stack, it is possible that the error will be detected while attempting to allocate space from the other kind of stack. Therefore, <ASTACK> and <STRINGSTACK> are both possible errors when either of these stacks is being heavily consumed.
Objectscript Changes
$ZOBJ<xxx> Functions Replaced
The $ZOBJ<xxx> functions have been replaced with standard Caché functions. The $ZOBJ<xxx> functions are still available to applications, but they are no longer documented. The calling sequences for the replacement functions remain the same as before; a textual substitution is all that is required to update the application usage. The replacements are given in the following table:
Previous Function | New (Replacement) Function |
---|---|
$ZOBJCLASSMETHOD | $CLASSMETHOD |
$ZOBJMETHOD | $METHOD |
$ZOBJPROPERTY | $PROPERTY |
$ZOBJCLASS | $CLASSNAME |
The function, $ZOBJCLASS, was not documented in prior versions.
Remove Descriptions For Obsolete And Deprecated Functionality
In this version of Caché, documentation for legacy networking facilities DDP and DCP has been removed. The functions themselves are classed as deprecated and will be removed in a future release; no replacement functions have been provided. This is also true for several other features because they no longer function as intended. The list of functions that will not have equivalent replacements is:
$ZUTIL Function | Description |
---|---|
67, 1, … | Returns the activity state of a specified process, and resets. |
68, 6, … | Enables or disables reliable SET networking mode for the current process. |
68, 27, … | Sets or clears network hardening for the current process. |
68, 28, … | Restricts or permits kills of root-level global nodes for the current process. |
68, 55, … | Selects $X/$Y behavior for TCP devices for the current process. |
69, 6, … | Sets reliable SET networking mode system-wide. |
69, 13, … | Sets logging of asynchronous SET/KILL errors. |
69, 14, … | Sets logging of asynch errors to console. |
69, 19, … | Sets DDP password security system-wide. |
69, 20, … | Transfers global nodes with null subscripts with DSM-DDP. |
69, 27, … | Enables or disables network hardening system-wide. |
69, 28, … | Controls root-level (unsubscripted) global node kills system-wide. |
69, 31, … | Sets network locks handling system-wide following a DCP outage. |
69, 35, … | Sets silent retry for domainspace connection attempts system-wide. |
69, 55, … | Selects $X/$Y behavior for TCP devices system-wide. |
69, 67, … | Suppresses or displays the stack and register usage message box system-wide. |
90, 4, … | Starts up in a specified namespace (UNIX™/OpenVMS. |
100 | Determines which Windows operating system is running. |
113 | Reclaims routine and directory blocks. |
130, … | Sets or returns the domain ID or index. |
133, … | Maintains a set of metric counters. |
Remove $ZUTIL Functions From Documentation
In this version, the Objectscript $ZUTIL functions are no longer documented. The functions remain available for use by applications as in prior releases, but the actions they perform are now also available by other means. The list of functions that have been replaced, their description, and the new means of accomplishing the same objective are given here. Customers should migrate their applications to use the replacement facilities.
Code | Description | Class | Property / Method |
---|---|---|---|
4, … |
Terminates a Cache process. |
Terminate() |
|
5, … |
Returns current namespace or switches to another namespace. |
<Special variable> |
|
9, … |
Broadcasts a message to a specified device. |
Broadcast() |
|
12, … |
Converts file or directory name to canonical form. |
NormalizeDirectory() |
|
15, … |
Converts RMS filename to canonical form. |
NormalizeFilename() |
|
18, … |
Sets undefined variable handling for the current process. |
Undefined() |
|
20, … |
Specifies the namespace(s) that contains the routine dataset. |
RoutineSearchPath |
|
21, … |
Returns the location of process-private globals |
PrivateGlobalLocation() |
|
21 |
Deletes all process private globals |
KillPrivateGlobals() |
|
22, 0, … |
Specifies the form feed or backspace control code sequence. |
SetFFBS() |
|
28, … |
Performs collation conversion. |
$SYSTEM.Util |
Collation() |
39, … |
Specifies a search path for percent (%) routines. |
PRoutineSearchPath() |
|
49, … |
Obtains database information. |
<various class properties> | |
53 |
Passes TCP device name to child process |
TCPName() |
|
53, … |
Returns TCP statistics. |
TCPStats() |
|
55, … |
Returns or changes the current language mode. |
LanguageMode |
|
56, 2 |
Locates source file and line of code for last ObjectScript error. |
ErrorLine |
|
56, 6 |
Returns the operating system error code for a sequential file error. |
OSError() |
|
62, … |
Performs a syntax check of command line code. |
CheckSyntax() |
|
67, 0, … |
Returns the activity state of a specified process. |
IsGhost |
|
67, 4, … |
Returns the process state. |
State |
|
67, 5, … |
Returns the routine name of a specified process. |
Routine |
|
67, 6, … |
Returns the namespace name for a specified process. |
NameSpace |
|
67, 7, … |
Returns the device name for the specified process. |
CurrentDevice |
|
67, 8, … |
Returns the number of lines executed by the specified process. |
LinesExecuted |
|
67, 9, … |
Returns the number of global references made by the specified process. |
GlobalReferences |
|
67, 10, … |
Returns the job type of the specified process. |
JobType |
|
67, 11, … |
Returns the username of the owner of the specified process. |
UserName |
|
67, 12, … |
Returns the name of the system for a client application. |
ClientNodeName |
|
67, 13, … |
Returns the name of the executable for a client application. |
ClientExecutableName |
|
67, 14, … |
Formerly returned the operating system running a client application. Now returns the CSP Session ID |
CSPSessionID |
|
67, 15, … |
Returns the IP address of a client application. |
ClientIPAddress |
|
71, … |
Sets date to a fixed value for the current process. |
FixedDate() |
|
78, 21 |
Searches journal file for open transactions. |
SearchOpen() |
|
78, 22, … |
Returns journaling information. |
Info() |
|
78, 23, … |
Deletes a journal file. |
PurgeOne() |
|
78, 28 |
Returns journal directory block information. |
DirectoryBlock() |
|
78, 29 |
Flushes journal buffer. |
FlushBuffer() |
|
82, 12, … |
Redirects I/O operations. |
ReDirectIO |
|
86 |
Returns configuration file pathname and config name. |
CPFFileName() |
|
90, 10, … |
Tests whether a namespace is defined. |
Exists() |
|
94, … |
Broadcasts a message to a specified process. |
Broadcast() |
|
96, 3, … |
Return error number for user-defined command. |
ThrowError() |
|
96, 4, … |
Sets $TEST to reflect I/O redirection. |
IODollarTest() |
|
96, 5, … |
Sets the $DEVICE special variable. |
<Special variable> |
|
96, 9 |
Returns the calling routine name. |
CallingRoutine |
|
96, 10 |
Returns the calling routine database. |
CallingDatabase |
|
96, 14 |
Returns the current device type. |
GetType() |
|
110 |
Returns the name of the system that is running. |
GetNodeName() |
|
114, … |
Determines Ethernet address. |
EthernetAddress() |
|
115, 11, … |
Specifies whether a value can be inserted into an identity column. |
AllowRowIDUpdate |
|
128, 1 |
Returns location of last single step during debugging. |
StepInfo() |
|
132 |
Makes the last device in use the principal I/O device. |
ChangePrincipal() |
|
140, 1, … |
Returns file, directory, and disk information and performs file operations. |
(various) |
|
140, 7, … |
Returns a bitmap of file attributes. |
Attributes() |
|
147, … |
Handles spaces in pathnames for the host platform. |
NormalizeFilenameWithSpaces() |
|
158, 0 |
Displays currently installed printers. |
InstalledPrinters() |
|
168, … |
Returns location of current working directory, or sets current working directory. |
CurrentDirectory() |
|
186, … |
Sets display in programmer prompt for the current process. |
TerminalPrompt() |
|
188 |
Returns local date and time with fractional seconds system-wide. |
<Function> |
|
189 |
Checks if TCP device is disconnected. |
Disconected() |
|
193, … |
Converts Coordinated Universal Time (UTC) to local date and time (and vice versa). |
<Function> |
Code | Description | Class | Property / Method |
---|---|---|---|
68,0 |
Sets undefined variable handling for the current process |
Undefined() |
|
68, 1, … |
Enables or disables use of null subscripts for the current process. |
NullSubscripts() |
|
68, 2, … |
Sets sequential file open mode for the current process. |
OpenMode() |
|
68, 3, … |
Sets automatic sequential file creation option for the current process. |
FileMode() |
|
68, 5, … |
Enables or disables processing of argumentless BREAK commands for the current process. |
BreakMode() |
|
68, 7, … |
Retains or strips extended global reference from globals returned to the current process. |
RefInKind() |
|
68, 11, … |
Enables or disables read line recall for the current process. |
LineRecall() |
|
68, 15, … |
Enables or disables I/O device disconnect detection for the current process. |
DisconnectErr() |
|
68, 21, … |
Sets synchronous commit mode for the current process. |
SynchCommit() |
|
68, 22, … |
Sets handling of escape sequences when $X is updated for the current process. |
DX() |
|
68, 26, … |
Sets namespace display in programmer prompt for the current process. |
TerminalPrompt() |
|
68, 30, … |
Sets error handling behavior for the current process. |
PopError() |
|
68, 32, … |
Sets date range and invalid date behavior for the current process. |
ZDateNull() |
|
68, 34, … |
Sets whether asynchronous errors can interrupt the current process. |
AsynchError() |
|
68, 39, … |
Enables or disables caching for the current process. |
EnableCaching() |
|
68, 40, … |
Sets sequential file end-of-file handling for the current process. |
SetZEOF() |
|
68, 42, … |
Sets $JOB format for the current process. |
NodeNameInPid() |
|
68, 43, … |
Sets clearing of global vectors for the current process. |
OldZU5() |
|
68, 45, … |
Sets truncation mode for string-to-number conversions for the current process. |
TruncateOverflow() |
|
68, 51, … |
Sets whether or not changing namespaces changes operating system directories for the current process. |
SwitchOSdir() |
|
68, 60, … |
Sets handling of asynchronous Telnet disconnect errors for the current process. |
AsyncDisconnectErr() |
|
68, 63, … |
Enables or disables the use of “e” as scientific notation symbol for the current process. |
ScientificNotation() |
|
68, 66, … |
Suppress Telnet NUL at end-of-line for the current process. |
TelnetNUL() |
|
68, 67, … |
Suppresses or displays the stack and register usage message box for the current process. |
ExceptionLog() |
|
68, 70, … |
Enables or disables $DOUBLE returning INF and NAN values. |
IEEEError() |
|
68, 71, … |
Sets IP address format for the current process. |
IPFormat() |
|
68, 72, … |
Sets MVBasic handling of undefined variables. |
MVUndefined() |
|
69, 0, … |
Sets undefined variable default handling system-wide. |
Undefined |
|
69, 1, … |
Sets null subscript mode default system-wide. |
NullSubscripts |
|
69, 2, … |
Sets sequential file open mode default system-wide. |
OpenMode |
|
69, 3, … |
Sets automatic sequential file creation system-wide. |
FileMode |
|
69, 5, … |
Enables argumentless BREAK processing system-wide. |
BreakMode |
|
69, 7, … |
Retains or strips extended global reference from globals system-wide. |
RefInKind |
|
69, 8, … |
Sets ZA and ZD locking modes system-wide. |
ZaMode |
|
69, 10, … |
Sets system behavior when journal is full. |
FreezeOnError |
|
69, 11, … |
Sets Read Line Recall mode system-wide. |
LineRecall |
|
69, 13, … |
Sets logging of asynchronous SET/KILL errors. |
NetErrToLog |
|
69, 15, … |
Sets I/O device disconnect detection system-wide. |
DisconnectErr |
|
69, 21, … |
Sets synchronous commit mode system-wide. |
SynchCommit |
|
69, 22, … |
Sets $X update mode for escape sequences system-wide. |
DX |
|
69, 24, … |
Sets $ZF process deletion behavior for OpenVMS STOP/ID system-wide. |
StopID |
|
69, 26, … |
Sets namespace display in programmer prompt system-wide. |
TerminalPrompt |
|
69, 30, … |
Sets error handling behavior system-wide. |
PopError |
|
69, 32, … |
Sets date range and invalid date behavior system-wide. |
ZDateNull |
|
69, 34, … |
Sets interruptability of processes by asynchronous errors system-wide. |
AsynchError |
|
69, 35, … |
Sets silent retry for domainspace connection attempts system-wide. |
||
69, 37, … |
Sets physical cursor mode system-wide. |
PhysicalCursor |
|
69, 39, … |
Sets caching for future processes system-wide. |
EnableCaching |
|
69, 40, … |
Sets end-of-file handling for sequential files system-wide. |
SetZEOF |
|
69, 42, … |
Sets $JOB format default system-wide. |
NodeNameInPid |
|
69, 43, … |
Sets clearing of global vectors system-wide. |
OldZU5 |
|
69, 44, … |
Sets use of the Nagle algorithm for Telnet transmissions system-wide. |
UseNagleAlgorithm |
|
69, 45, … |
Truncates numbers during string-to-number conversion system-wide. |
TruncateOverflow |
|
69, 49, … |
Sets logging of transaction rollbacks system-wide. |
LogRollback |
|
69, 51, … |
Sets namespace default directory assignment behavior system-wide. |
SwitchOSdir |
|
69, 60, … |
Sets handling of asynchronous Telnet disconnect errors system-wide. |
AsyncDisconnectErr |
|
69, 63, … |
Enables or disables lowercase “e” as scientific notation symbol system-wide. |
ScientificNotation |
|
69, 66, … |
Suppress Telnet NUL at end-of-line system-wide. |
TelnetNUL |
|
69, 68, … |
Enables or disables the encryption of journal files system-wide. |
DBEncJournal |
|
69, 69, … |
Enables or disables the use of long strings system-wide. |
EnableLongStrings |
|
69, 70, … |
Enables or disables $DOUBLE returning INF and NAN values system-wide. |
IEEEError |
|
69, 71, … |
Sets IP address format system-wide. |
IPV6 |
|
69, 72, … |
Sets MVBasic handling of undefined variables system-wide. |
MVDefined |
|
69, 73, … |
Set global name compatibility checking |
GlobalNameTruncated |
$ZDATEH And $ZDATETIMEH Format 4 Parsing
In version 2008.1, the $ZDATEH and $ZDATETIMEH function were inadvertently changed to accept any nonambiguous date instead of only a European format date. The correct behavior has been restored; $ZDATEH(date,4) and $ZDATETIMEH(datetime,4) will only accept strings using European format dates.
For those applications expecting the post-2008.1 behavior, a new date format code, 15, has been added that uses European date ordering, DD/MM/YYYY, but also accepts any other date input that is nonambiguous.
Number Format Parsing Via $INUMBER And $FNUMBER Now Locale-Independent
Prior to 2008.2, the $INUMBER and $FNUMBER functions worked with European-style numbers: “,” as decimal point, “.” as group separator, “-” as minus sign, and “+” as plus sign. In 2008.2, these functions were changed parsing would use the system default locale to determine the minus sign and plus sign; usually this is “-” and “+”, but not always.
In this version, the behavior has been returned to the way it was before 2008.2, so that is always uses “,” as decimal point, “.” as group separator, “-” as minus sign, and “+” as plus sign.
Improved Detection Of Incorrect $HOROLOG Dates And Times
Some of the routines that accept a $HOROLOG string (and/or a $ZTIMESTAMP string) do not fully validate their input string. Their behavior on illegally formatted string is undefined. In some cases that undefined behavior may change between Cache versions.
A legally formatted $HOROLOG string (or $ZTIMESTAMP) string consists of a <date> followed immediately by a comma (,) and then followed immediately by a <time>. Optionally, the comma and the <time> may both be omitted; this is assumed to implicitly represent 0:00:00, the beginning of the day, or a date without reference to a particular time.
A <date> part consists only of decimal digits. A <date> may not include any fractional part nor an exponent part nor any non-digit characters.
The <time> part is a string of decimal digits optionally followed by a decimal point (.) and some fractional decimal digits. A <time> may not include an exponent.
If a routine accepts just a <time> string that is not preceded by a <date> and a comma, a leading minus sign, (-) is permitted to represent negative time intervals.
$INCREMENT Changes
Previously, $INCREMENT() of a variable containing a very large number would not change the value of the variable when the increment value is insignificant compared to the original value. Thus, successive calls to $INCREMENT() could all return the same value, which is incorrect. Beginning with this version, this situation will cause the increment operation to throw a <MAXINCREMENT> error instead of returning an incorrect result.
Routine Changes
KillAllObjects Takes No Action
The function, KillAllObjects^%apiOBJ(), used to remove all object memory from the partition has been changed to a no-op. Applications can remove an object by letting the object go out of scope.
Routine Compiler Changes
Routine Compiler Skips Generated Code
The routine compiler, ^%RCOMPIL, will no longer compile code that has been generated. Previously, if you attempted to compile *.mac, and there existed MAC code which was generated by compiling classes, the generated class MAC code would be compiled. This would cause the methods in that class to not be runnable. Other code which is marked as generated will also not be compiled. This includes .INT code which comes from MAC code and classes, and cached query code.
It is possible to compile a "generated" routine, but only if the name of the generated routine is specified exactly as one of the routines to compile.
Class Changes
Namespace Changes And OREFs
Assume you create an OREF to a class instance, and then change the namespace the application runs in. In prior versions, you would normally get a <NOROUTINE> error when you tried to access a method of this OREF in the second namespace because it could not find the code to run. Caché was looking for the code in the current namespace and not in the namespace where the OREF was created.
Beginning with this version, an application can create an OREF and change its namespace; when it attempts to use this OREF and it will run the code from the original namespace. However, any references to global data or locks made during execution will be relative to the current namespace. This means that it the executing code does a %Save(), the data will be saved it will save the data to the current namespace and not the namespace where the code is running. Similarly, a method that does a $GET(^Global) will look up the global in this namespace rather than the original namespace.
When an application changes namespaces, it changes the visibility of data. Cross-namespace access to OREFs does not preserve the global data visible from the original namespace. When an object is opened in Namespace A and it loads data from ^MyGlobal, then ^MyGlobal is expected to be in Namespace A. In changing to Namespace B with an OREF from Namespace A, then any access by that OREF to ^MyGlobal looks for the data in Namespace B.
Caché cannot check for this condition. The use of object references created in other namespace may result in subtle data loss or corruption undetectable at the time of execution.
Class Deletions
The following classes were present in version 2009.1 and have been removed in this version:
-
Package %BI – SOAP
-
Package %CPT – RegenerateImpl, RegenerateSource
-
Package %CSP.UI.System – MappingsTablePane, MappingsTitlePane, MenuTree
-
Package %Compiler – JavaScript
-
Package %ISQL – SP
-
Package %Net – Event
-
Package %TSQL – SP, SPContext, SimpleStreamLexer
-
Package %XSQL – CacheMetadata, Convert, Debug, DelimitedReader, Settings, Transaction
-
Package %cspapp.exp – utilexpglobaledit, utilexproutineinfo, utilsysdbglobalinfo
-
Package %cspapp.mgr – utilconfiggblmappings, utilconfigprjmappings, utilconfigrtnmappings, utilsysaccess
Class Reservations
The following classes which were publicly exposed in earlier versions of 2010.1, and/or prior versions of Caché, are being reserved solely for InterSystems use:
-
Package %TSQL – FileBuffer, LineBuffer, ResultSet, StreamLineBuffer, StreamLineBufferWF, SysFunc, Transformer
-
Package %TSQL.sys – cacheMsgXRef, messages, messagesXRef, snf
-
Package %XSQL.DS – Call, ContextStatement, Cursor, DML, IResultSet, Statement, TSQL, TempTable, spexecutesql
-
Package %XSQL.DSI – Call, Cursor, DeferredStatement, GlobalPrivateTable, IteratorFunction, JPAQuery, Statement, TSQL, TempTable, spexecutesql
-
Package %XSQL – Compile, DLLInterfaceUtil, Dictionary, Exception, Format, Reporting, StatementBatch
-
Package %XSQL.Informix – FunctionQuery
-
Package %XSQL.System – CacheMessageXRef, Message, MessageXRef
-
Package SYS.WSMon – Client, EventSink, Service, wsDatabase, wsEvent, wsResource, wsSystem
-
Package SYS.WSMon.wse – Delivery, EndpointReference, Identifier, MyRefProp, ReferenceProperties, Renew, RenewResponse, Subscribe, SubscribeResponse, Unsubscribe, UnsubscribeResponse
-
Package SYS.WSMon.wsen – Enumerate, EnumerateResponse, Items, Pull, PullResponse, Release
-
Package SYS.WSMon.wsman – Client, Locale, MaxEnvelopeSize, OperationTimeout, RequestTotalItemsCountEstimate, ResourceURI, SelectorSet, Service, TotalItemsCountEstimate
Class Component Reservations
The following class components are being reserved for InterSystems use. They will no longer be displayed in the Class Reference and are subject to change without notice. Sites using these components should contact InterSystems Worldwide Customer SupportOpens in a new tab for assistance in replacing these with other published API components.
Class | Type | Name(s) |
---|---|---|
%Installer.ClassMapping | Method | %OnGenerateCode |
%Installer.ClassMapping | Method | %OnGenerateCode |
%Installer.Configuration | Method | %OnAfterGenerateCode, %OnBeforeGenerateCode, generateCode |
%Installer.CopyClass | Method | %OnGenerateCode |
%Installer.CopyDir | Method | %OnGenerateCode |
%Installer.CopyFile | Method | %OnGenerateCode |
%Installer.Credential | Method | %OnGenerateCode |
%Installer.CSPApplication | Method | %OnGenerateCode |
%Installer.Database | Method | %OnGenerateCode |
%Installer.Default | Method | %OnGenerateCode |
%Installer.Else | Method | %OnGenerateCode |
%Installer.Error | Method | %OnBeforeGenerateCode |
%Installer.ForEach | Method | %OnAfterGenerateCode, %OnBeforeGenerateCode |
%Installer.GlobalMapping | Method | %OnGenerateCode |
%Installer.If | Method | %OnAfterGenerateCode, %OnBeforeGenerateCode |
%Installer.IfDef | Method | %OnAfterGenerateCode, %OnBeforeGenerateCode |
%Installer.IfNotDef | Method | %OnAfterGenerateCode, %OnBeforeGenerateCode |
%Installer.Import | Method | %OnGenerateCode |
%Installer.Installer | Method | CopyClass, CopyDir, CopyFile, CreateDatabase, CreateNamespace, CreateResource, CreateRole, CreateUser, CSPApplication, DeleteVariable, EnableEnsemble, eval, Evaluate, GetVariable, GlobalMapping, Import, InstallFromCommandLine, IsLoggable, IsVariableDefined, LoadManifestXML, LoadPage, Log, PopNS, Production, ProductionExists, PushNS, RoutineMapping, SetVariable, special, SystemSetting |
— | Property | Logger, LogLevel, NSStack, Variables |
%Installer.Invoke | Method | %OnBeforeGenerateCode |
%Installer.LoadPage | Method | %OnBeforeGenerateCode |
%Installer.Log | Method | %OnBeforeGenerateCode |
%Installer.Manifest | Method | %OnAfterGenerateCode, %OnBeforeGenerateCode |
%Installer.Namespace | Method | %OnAfterGenerateCode, %OnBeforeGenerateCode |
%Installer.Production | Method | %OnAfterGenerateCode, %OnBeforeGenerateCode |
%Installer.Resource | Method | %OnGenerateCode |
%Installer.Role | Method | %OnGenerateCode |
%Installer.RoutineMapping | Method | %OnGenerateCode |
%Installer.RunInstall | Method | %OnGenerateCode |
%Installer.Security | Method | %OnAfterGenerateCode, %OnBeforeGenerateCode |
%Installer.Sequence | Method | findChild |
%Installer.Setting | Method | %OnGenerateCode |
%Installer.SystemSetting | Method | %OnGenerateCode |
%Installer.Var | Method | %OnGenerateCode |
%Library.ProcedureContext | Property | Results |
%Net.FtpSession | Method | endCommand |
%Net.POP3 | Method | GetHeadersArray |
%SYSTEM.Config.SharedMemoryHeap | Method | DisplayUsage |
%ZEN.Component.abstractPage | Method | %IsEmbedded |
Class Component Deletions
The following class components have been removed in this version.
Class | Type | Name(s) |
---|---|---|
%Activate.UI.Wizard | Property | lblExit, lblFinish |
— | Parameter | DOMAIN, TEMPLATEMODE |
%CPT.CalloutDump | Method | DumpParseTreeNodeMap, DumpSourceAndMap |
%CSP.UI.Portal.Config.Device | Method | DrawLocatorExtra, onloadHandler, UpdateDetails |
%CSP.UI.Portal.Config.Devices | Method | DrawLocatorExtra, saveItem, validate |
%CSP.UI.Portal.Config.ValueEditor | Method | DrawLocatorExtra |
%CSP.UI.Portal.FileManTemplate | Method | %OnAfterCreatePage |
%CSP.UI.Portal.NLS | Method | AddLocator |
%CSP.UI.Portal.NLSEdit | Method | AddLocator |
%CSP.UI.Portal.ObjectGateway | Method | doStart, doStop, itemChanged |
— | Property | msgConfirmSaveStart, msgConfirmStart, msgConfirmStop |
%CSP.UI.Portal.ObjectGateways | Method | deleteSetting, editSetting, editSettingD |
— | Property | PID |
%Compiler.Informix.COS | Method | %OnClose, InformixDT2CacheDT, SeparateName, delimitIdentifier, getTypeCategory, normalizeIdentifier, resolveTableName |
— | Property | blockTypeStack, codeStack, contextStack, exceptionDepth, exceptionStack, opStack |
%Library.IProcedureContext | Property | Message, RowCount, SQLCode |
%Library.IResultSet | Property | %RowCount, %SQLCode |
%Library.ODBCCatalog | Method | co25Close, co25Execute, co25Fetch, cr25Close, cr25Execute, cr25Fetch, ek25Close, ek25Execute, ek25Fetch, ik25Close, ik25Execute, ik25Fetch, pc25Close, p25Execute, pc25Fetch, ti25Close, ti25Execute, ti25Fetch |
— | Query | co25, cr25, ek25, ik25, pc25, ti25 |
Parameter | CHARSET, CONTENTTYPE | |
%Library.ObjectJournalTransaction | Method | PurgeUpToTxn |
%Library.ProcedureContext | Property | ReturnValues |
%Library.qccServer | Method | OnPage |
%MV.File | Property | %AAA01VarType, %AAA02FileName, %AAA03Namespace, %AAA04DictFlag, %AAA05Global, %AAA06Account, %AAA07TargetAccount, %AAA08TargetFileName, %AAA09IsBinary, %AAA10IsTranslated, %AAA11COSName, %AAA12LockName, %AAA13Class, %AAA14IndexType, %AAA15IndexRoutine, %AAA16IndexName, %AAA17IndexColl, %AAA18BSCAN, %AAA19IndFlag, %AAA20IndNames, %AAA21IndColl, %AAA22IndMV, %AAA23Options, %AAA24TriggerRoutine, %AAA25TriggerOperations, %AAA26FireTriggers, %AAA27CasePreserveName, %AAA28IOTable, %AAA29ClassNamespace, %AAA30SectionName |
%MV.PropertyParameters | Parameter | MVITYPERTN |
%MV.SelectList | Property | %AAA01Type, %AAA02LastReturnedId, %AAA03NextOffset, %AAA04GlobalName, %AAA05Namespace, %AAA06Values, %AAA07Count, %AAA08IndexName, %AAA09IndexFlags, %AAA10IndexColl, %AAA11InReverse, %AAA12LastReturnedMVPos, %AAA13LastReturnedKey, %AAA14CurSub, %AAA15MaxSub, %AAA16ExplodeFlag |
%ResultSet.Static | Method | %RowCountGet |
%Studio.Project | Method | deployToGbl |
%SOAP.Security.SecurityTokenReference | Property | Id |
%SYS.PTools.Stats | Property | CursorName. NameSpace, RoutineName |
%SYSTEM.CPU | Property | nTheadsPerCore |
%TSQL.Transformer | Method | ExecuteStringAsTSQL, ExpandTable |
%UnitTest.Manager | Method | ParseQualifiers, RunOneDirTest, RunTestSuite, SaveLog |
%UnitTest.Report | Method | IsSuccess, NoNameSpace |
%UnitTest.Utility | Method | processError |
%ZEN.Auxiliary.dataController | Method | %GetDataByName, %GetTypeByName, %OnNew, %SetDataByName, autoRefreshHandler, clearAutoRefresh, getData, getDataAsArrays, getDataAsObject, getDataByName, getDimSize, getDimensions, getError, getLabel, getModelId, getPropertyName, getTypeByName, hasData, invokeAction, isModelReadOnly, isPropertyValid, notifyController, onDelete, onloadHandler, raiseDataChange, register, sendEventToViews, setData, setDataByName, setModelId, startAutoRefresh, unregister, update |
— | Parameter | DEFAULTVISIBLE |
— | Property | alertOnError, autoRefresh, dataBag, dataLoaded, dataReadOnly, defaultSeries, modelChanged, modelError, modelId, oncreate, ondelete, onerror, onnotifyController, onsave, readOnly, timerid |
%ZEN.Component.abstractPage | Method | %DrawJSTestIncludes |
— | Parameter | SYSTEMPACKAGES, SYSTEMSVGPACKAGES |
— | Property | %ComponentIncludes, %IncludePackages |
%ZEN.Report.Aggregate.StDev | Property | Sum, SumOfSquares |
%ZEN.Report.Display.inline | Property | field |
%ZEN.Report.Display.p | Property | field |
%ZEN.Report.reportPage | Method | %IsTypeNumeric, OnSVGAttribution |
%ZEN.SVGComponent.svgPage | Parameter | SYSTEMSVGPACKAGES |
%ZEN.Utils | Method | NeedsIncludeFiles, WriteIncludeFiles |
Config.CommonMapProperties | Parameter | SECTIONTYPE |
Config.CommonMethods | Parameter | NAMESPACE |
Config.Config.MapPackages | Parameter | NAMESPACE |
Config.Config.MapRoutines | Parameter | NAMESPACE |
Config.MapGlobals | Method | NameIsValid |
— | Parameter | NAMESPACE |
Config.Miscellaneous | Property | NamespacePrompt |
Config.Namespaces | Method | MapPkg, MapSub, MapUserGlobals, MapUserPackages, MapUserRoutines |
Config.MapPackages | Parameter | NAMESPACE |
Config.MapRoutines | Parameter | NAMESPACE |
Method Return Changes
The following methods have different return values in this version of Caché:
-
Package %CSP.UI.System.ExportPane – DrawResult
-
Package %CSP.UI.System.ImportPane – DrawResult
-
Package %Library.CacheIndex – Check
-
Package %Monitor.Manager – SystemCountersActive
-
Package %UnitTest.Manager – PurgeLog
-
Package %ZEN.Dialog.fileSelect – GetSubDir
Method Signature Changes
The following methods have different calling sequences in this version of Caché:
Class Name | Method Name(s) |
---|---|
%BI.WebScheduler | addNewPivotTask |
%CPT.COSCallout | Compile |
%CPT.CalloutCheckTree | CheckParseTreeNode, CheckParseTreeNodeAnn, CheckParseTreeNodeChild, CheckParseTreeNodeSource, ReportAnn, ReportChild, ReportNode |
%CPT.CalloutDump | ExpandAnnIndex, ExpandAnnValue, ExpandChildIndex, ExpandNodeType |
%CPT.CalloutIndex | BuildNodeIndex, ListEnumIndex, ListNodeIndex, UpdateNodeIndexForEnum, UpdateNodeIndexForNode, UpdateNodeIndexFromLine |
%CPT.CalloutTesting | TestStream |
%CPT.CalloutTypeIndex | BuildTypeIndex, IsEqualOrDescendantOf, ListTypeClassHierarchy, ListTypeIndex, UpdateTypeIndexForNode, UpdateTypeIndexForNodeClass, UpdateTypeIndexFromLine |
%CPT.ISQLCallout | Compile |
%CSP.Session | Unlock |
%CSP.UI.Portal.SSL | SaveData |
%CSP.UI.System.AutoPageCSP | GetLocator |
%Collection.ListOfObj | GetObjectIdNext |
%Compiler.Informix.Flo | preparseSQL, parseStream |
%Compiler.LG.PropWrapper | SetIIJJKK |
%Compiler.TSQL.Flo | preparseSQL, sqlact |
%Compiler.XML.Generator.Adaptor | GenArrayCode, GenExportCode, GenListCode, GetSimpleExport |
%Debugger.System | StackVars |
%Installer.Installer | CreateDatabase |
%Library.ArrayOfObjects | %AddToSaveSet |
%Library.CacheIndex | Check |
%Library.Collation | FMDLTDate |
%Library.GlobalEdit | GetGlobalSize, GetSize |
%Library.ListOfObjects | %AddToSaveSet |
%Library.ProcedureContext | ResolveTableName |
%Library.RegisteredObject | %AddToSaveSet |
%Library.RelationshipObject | %AddToSaveSet |
%Library.RoutineMgr | UserType |
%Library.SyntaxColor | Color |
%Monitor.Manager | SystemCountersActive |
%Net.FetchMailProtocol | Fetch |
%Net.POP3 | Fetch |
%Net.Remote.Gateway | %Connect |
%SOAP.Descriptor | GetSoapParameters |
%SOAP.Security.SecurityTokenReference | Validate |
%SOAP.WSDL.Reader | GetCacheElement |
%SOAP.WebRequest | GetSoapParameters |
%SQL.Manager.Catalog | SetFieldSelectivity, SetTableExtentSize |
%SYS.PTools.SQLStats | Export, Init, Report, Start, Stop |
%SYS.PTools.Stats | Init, Report, Start, Stop |
%SYS.ZENReportServer | %ServeTransform |
%Studio.Project | Deploy, deployToDatabase, NormalizeName |
%UnitTest.Manager | AutoLoad, DebugLoadTestSuite, DebugRunTestCase, LogStateEnd, RunTest |
%UnitTest.ODBCSQL | processORSToStream |
%XML.Utils.SchemaReader | GetCacheElement, ProcessElement, ProcessSequence |
%XML.Writer | Object, RootObject |
%XML.XSLT.Transformer | TransformFile, TransformFileWithCompiledXSL, TransformStream, TransformStreamWithCompiledXSL, TransformStringWithCompiledXSL |
%ZEN.Component.tabGroup | showNextTab, showPreviousTab |
%ZEN.Report.Aggregate.StDev | ProcessValue |
%ZEN.Report.Display.caption | %DrawCellFO, %DrawCellToHTML |
%ZEN.Report.Display.item | %DrawToHTML, %DrawToXSLFO |
%ZEN.Report.Display.node | %GenerateCode, %StyleXSLFO |
%ZEN.Report.Display.tableOutput | %DrawCellFO, %DrawCellToHTML, %DrawFooterFO, %DrawFooterToHTML, %DrawHeaderFO, %DrawHeaderToHTML |
%ZEN.Report.group | %SortChildren |
%ZEN.Utils | %GenerateIncludeFiles |
Config.CPF | MoveToActive, UpdateLines |
Config.ComPorts | Load |
Config.CommonMapMethods | Load, MoveToActive |
Config.CommonMethods | Activate, Load, MoveToActive |
Config.CommonSingleMethods | MoveToActive |
Config.DTMnetBIOS | Load |
Config.Databases | Load |
Config.DeviceSubTypes | Load |
Config.Devices | Load |
Config.ECP | Load |
Config.ECPServers | Load |
Config.ETHServers | Load |
Config.IO | Load |
Config.Journal | Load |
Config.LAT | Load |
Config.MagTapes | Load |
Config.Map | MoveToActive |
Config.Miscellaneous | Load |
Config.Monitor | Load |
Config.Namespaces | Load |
Config.Net | Load |
Config.SQL | Load |
Config.SqlSysDatatypes | Load |
Config.SqlUserDatatypes | Load |
Config.Startup | Load |
Config.Telnet | Load |
Config.UDPServers | Load |
Method Displacements
The following methods have been removed from one class and added to another:
-
Method: KPI – from %BI.Soap to %BI.Util
-
Method: Pivot –: from %BI.Soap to %BI.Util
DBTIME Implementation Changed
The DBTIME parameter was first introduced in version 2008.2. When set to 1, it caused an index to be defined in the class on a property that was, by default, set to an incremented global on each insert and update; but the index entry for an object was not updated for deletes.
Beginning with this version, DBTIME no longer generates an index definition and property definition. A global, ^OBJ.DBTIME, is set for each insert, update and delete. The first subscript is the incremented global counter - ^OBJ.DBTIME; the second is the class name of the object being filed; and the third is the ID of the object. The value of the global node for each filing event is the type of filing - 0 for update, 1 for insert and 2 for delete. This structure is cumulative. It is used to support various features in Cache and it can be used by user applications for any purpose. Deleting entries from ^OBJ.DBTIME is not automatic and must be done by the user.
Permit Insert Of Trailing Objects In Collections
The SetAt method of a list collection allows the caller to specify an element value and a key. In prior releases, if the element at the key position was not already defined, then the attempt would fail.
This behavior is now changed. The call will still fail if the key is not 1 (the first element position) and the element at the previous position is not defined. Otherwise, the call will succeed and the behavior for calling SetAt(value,key) for a position that is undefined will be the same as Insert. That is, a new element at position “key” will be defined.
Update ID Counter When IDENTITY Set Explicitly On Object Insert
If a value is provided for the IDENTITY property of a new object and the INSERT_IDENTITY option is set TRUE, then the ID of the new object is set to the value of the IDENTITY property.
In previous versions, an error prevented subsequent inserts without the IDENTITY property from succeeding if the ID counter value was the same as a previously inserted object. This has been corrected and an explicit set of an IDENTITY property will update the ID counter as long as the explicit value is greater than the current ID counter value. As part of this correction, another error that prevented a check of the INSERT_IDENTITY option for batch inserts and direct saves has been fixed.
%OnDetermineClass Method Override Blocked
%OnDetermineClass is a class method implemented for persistent, stream and serial objects. It has always been defined to be PRIVATE, but PRIVATE for class methods has never been enforced until this release. Any application class that overrides %OnDetermineClass will now have to update the method definition to remove the PRIVATE keyword.
Indexes Permitted on %Stream.GlobalCharacterSearchable
Several defects that caused corruption in an index based on a property whose type class is %Stream.GlobalCharacterSearchable have been fixed in this version of Caché. These defects caused updates to the stream to be ignored and resulted in index entries based on the old stream value. Also, deleting a container object did not fully remove the index entries from the stream in all cases.
As part of the correction of these defects, indexing streams is only supported for instances of %Stream.GlobalCharacterSearchable. Instances of this class must be processed through the container. It is not legal to extract the stream OID from the container and process updates to the stream without saving the container.
Existing applications should work well with this change as no change to the existing data structures was made. However, the old behavior almost certainly introduced corrupt index structures. Those indices should be purged and rebuilt after installing this version.
Namespace Prompt Property Changed
The property, NamespacePrompt, in the Config.MiscellaneousOpens in a new tab class has been moved to the class, Config.StartupOpens in a new tab, and renamed to be TerminalPrompt.
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.
Class Inheritance Default Order Changed
In version 2009.1, the Inheritance keyword was introduced to specify the order of inheritance from superclasses. In that release, the default for classes that do not specify the order was “right”, as it had been before the keyword was introduced.
In this version, the default inheritance order for classes that do not explicitly specify an order has been changed to “left”.
Superclass Availability Required
In prior versions, subclasses compiled all the method code from their superclasses into themselves. In this version, subclasses contain references to their superclass methods thus avoiding the extra code and saving compilation time. A consequence of this organization is that the first reference to a method in a class requires that all the superclasses be accessible to resolve the reference, that is, either present in the namespace of the calling method or mapped to it.
Flags And Qualifier Removals And Deprecations
In this version of Caché, the following changes made to compiler flags and qualifiers may affect existing operations:
-
Optimization flags ignored
Due to the more dynamic nature of the class and routine dispatching in this version of Caché, the optimization flags (“o1”, “o2”, ...) are ignored if passed in as arguments. The system code was optimized to make up for any reduction in speed from turning these optimizations off.
-
Force flags
The force flag, “f”, is now deprecated.
-
SQL compilation deprecated
The “q” flag that specified SQL-only compilation is now deprecated.
-
Keep-valid deprecated
The “v” flag previously used to keep the objects valid after compilation finishes is now deprecated.
-
The following qualifiers are no longer allowed:
-
/deletextent – used to delete the extent associated with a class
-
/version4compatible – used to export CDL files that are version 4 compatible
-
$GET(..<property>) Require <property> To Be Multi-Dimensional
In previous versions, $GET applied to a class property which is not multi-dimensional may not have been caught as an error when certain optimization flags were set. This has been corrected. The expression
$GET(..AClassProperty)
is valid only if AClassProperty is marked as Multidimensional.
This restriction also applies to other commands with respect to class properties: KILL, MERGE, $DATA(), and $INCREMENT().
$PIECE References to ..<property> Require <property> To Be Multi-Dimensional
In previous versions, $PIECE treated a reference to ..<property> as a string. Because of changes to the compiler, such references will now result in an <OBJECT DISPATCH> error. Applications using this form should either add the Multidimensional qualifier to the property, or use a temporary string as in:
Set ..MyProperty = "Piece1/Piece2" Set temp = ..MyProperty Set $PIECE(temp,"/",2) = "Piece3" Set ..MyProperty = temp
Misuse of %this Prohibited
In prior versions of Caché, it was possible to gain access to the private properties of another object with the sequence
New %this Set %this = OtherOREF Set Value = ..PrivateProperty
This will not work in the new class compiler due to system changes. Any applications using this questionable practice must be updated.
System code public/private protection has now been changed; from a method of class X access to private members of another instance is possible only as long as the origin of the member is class X or a superclass of class X. This will allow most common use of “Set %this=” to be changed to just access the private properties directly.
InterSystems also found code where a classmethod was executing
Set value=##this.Property
which was implicitly referencing %this on older Caché systems where the value of %this happened to be the last instance method that was called. This is a very risky practice since the last instance is not well-defined; if the classmethod is called as the first thing, then %this will not be defined at all. Applications should be written to pass in the OREF of the object to the classmethod explicitly.
In the new compiler, references to “##this” are converted to $THIS, the current class context.
State Of Serial Object Now Held In %%OID
In prior versions, the serial state of an object was being kept internally. This has now been made visible in a real property called %%OID. It is also updated for serial and stream objects. It is used in %Save to correctly handle the case where a serial object is independently serialized so it reports %IsModified()=0 to the save attempt, but the container does not know the new serial value. Using %%OID, the container can always get the correct version of the serial object.
Setting A Serial Property To "" Causes It To Be Initialized
When a class defines a serial property, constructing a new instance of this class and referencing this serial property will cause it to be created using the NewObject() method. If the application then sets this property to "", the property is now reinitialized and the next reference will create it again using NewObject() just as if theoparent object had been newly created.
NotInheritable Keyword Removed
In previous versions, Caché allowed a user to define a 'not inheritable' property defined with an expression like:
Property A As %String [ NotInheritable ];
This concept breaks object inheritance because the superclass now has interfaces the subclass does not.
Beginning with this version of Caché, this is no longer permitted. Compiling a subclass of a class with a noninheritable property will result in the an error because property “..A” was not present in the subclass.
When upgrading to this version, the upgrade procedeures will automatically remove “NotInheritable” from any property and thus convert any noninheritable properties into inheritable ones. When it does this, it will add the comment [Previously notinheritable] to the property description.
Any new properties marked as “NotInheritable” will cause an error when they are compiled. Studio will be modified to remove the ability to set or display this keyword.
Private Classmethods Now Supported
Caché now supports private class methods. Private classmethods cannot be called from outside of the class (or a subclass). For backward compatibility, all class methods have been marked “public” so customer code will continue to work correctly. The descriptions of these methods have been altered to add the string, “[Previously private]”, to them.
New private classmethods added to classes in the future will be inaccessible from outside the class.
Change In Support For COSEXPRESSION
Prior to this release, the use of COSEXPRESSION in a parameter definition would be treated in the same manner as macro substitution. That is,
parameter P1 as COSEXPRESSION = """Red"",""Green"",""Blue"""; ... ... Set X = $LISTBUILD(..#P1)
would be treated as if it were
Set X = $LISTBUILD("Red","Green","Blue")
In this version of Caché, a COSEXPRESSION is constrained to return only a single value. So the parameter definition must be rewritten as
parameter P1 as COSEXPRESSION = "$LISTBUILD(""Red"",""Green"",""Blue"")";
or an error will be reported at the time the class is compiled.
Superclass Reference ##super
The usage ..ClassmethodName() now always calls that classmethod in the current class, not that of the superclass. Classmethod in the superclass are now accessed with the expression ##super.ClassmethodName().
Codemode=Call Cannot Using Variable-Length Argument List
Method marked as “codemode=call” are no longer allowed to use variable length argument lists. Such use will cause an error when they are compiled. They need to be rewritten to specify a fixed list of arguments.
Normalize Results of %Exists And %ExistsId For Subclasses
In prior versions, if an application called %Exists passing a fully-formed OID (one that included the classname in it), then Caché always polymorphically dispatched to the %Exist method of that class. For example, calling %Exists on Sample.Employee passing an OID of a Sample.Person would return true. After analysis, this is considered to be a error since calling %ExistsId on Sample.Employee passing the same OID would return false because this is not an instance of Sample.Employee or one of its subclasses.
In this version, the behavior is changed so %Exists and %ExistsId now both return the correct result in this case. It is possible, but unlikely an application may have been relying on this incorrect behavior.
Limits On Class Descriptor Size
Compilation of a class generates a data structure called a “class descriptor” that contains summary data about the class and its components: properties, methods, parameters, indexes, and so on. Information on each group (such as the methods defined) is stored in its own table and is subject to the maximum limit on Caché strings, 32KB.
In this version of Caché, the table formats have changed. The amount of information stored for each method has increased, while that for a property has decreased. The result is that classes which contain many hundreds of methods or properties may find that the resulting class descriptor exceeds one or more of its table limits resulting in a <CLASS TOO BIG TO SAVE> error.
Classes which encounter this error must be refactored to reduce the number of entries.
The number of methods, properties, indexes and so on includes inherited and generated components not only the ones explicitly visible in the class source. Also, properties may cause the generation of methods, for example, <propertyname>Get and <propertyname>Set.
Names Limited To 180 Characters
Compiled classes are stored in globals indexed by the package name, class name and component name. When each of these is a long string of characters, there is the possibility that the maximum length for a global subscript will be exceeded. To reduce the likelihood of this happening, this version of the compiler imposes a maximum size limit on the names of methods, parameters, and properties declared in a class. That limit is 180 characters.
Stored Procedure Return Parameter Types Checked
Prior to this version, return value type parameters were ignored. Beginning with this version, the return type parameters of a class method are now honored by the stored procedure projection. For example,
classmethod myproc() as %String(MAXLEN=100) [ sqlproc ] { ... }
will now project the xDBC column with a maximum string length of 100. Previously, it would have used the default of 50,
Object Binding Changes
Change In Properties Projected For Jalapeño
Prior to this version, all properties that are defined in Caché class that are not marked as Private or ServerOnly, or otherwise not projectible, are present in Java POJO class. Now, properties with names starting with “%” will not be projected in POJO. This will affect user classes if they have properties whose name begin with “%”.
SQL Changes
Changed Handling Of Procedures Names In Embedded SQL
In this version, Caché now treats unqualified procedures names in the &SQL statement differently from prior versions. The schema name used for unqualified procedure names now takes into account any #import value defined. This means if you have an embedded SQL CALL statement (“&SQL( ... )”) in a class method and the procedure name is unqualified, the default will be the schema that maps to the package of the current class. Previously, the default schema would be the system-defined default schema. The default schema for DDL statements remains the system defined-default schema.
Support For SQL Extension FOR ALL Removed
In this version, support for the FOR ALL statement has been removed. In version 2009.1, it was deprecated. Any application using FOR ALL will need to be modified. If necessary, the FOR ALL statement may be converted into a
NOT FOR SOME ...
statement with a condition carefully constructed to achieve the desired result.
Date And Time Conversion Errors Now Reported In SQL Statements
In an SQL statement that takes a %Date value as input in either DISPLAY mode or ODBC/JDBC mode, if the input value cannot be converted to a valid Logical %DateOpens in a new tab value, the SQL statement will return SQLCODE=-146. For similar errors involving %Time values that cannot be converted, SQLCODE=-147 will be returned. For example,
&sql(select name into :name from sample.person where dob = '02/29/2009')
will return “SQLCODE=-146 Unable to convert Date input to a valid Logical Date value”.
Reserved Word Checking More Comprehensive
In prior versions, a reserved word would be accepted as an identifier, for example:
-
As an alias following AS in a SELECT or FROM clause,
-
As a table reference in a FROM clause
These occurrences will now be reported as errors. This is unlikely to affect many queries since the reserved word could not be used in WHERE, GROUP BY, HAVING, or SELECT clauses, nor as the table qualifying name for a column.
ORDER Is No Longer A Reserved Word
ORDER is no longer a reserved word. It is now a non-reserved keyword. ORDER can be used everywhere a regular identifier is used.
Use Of TOP and ORDER In Subqueries
In prior versions, there were two equivalent ways to apply TOP to a UNION:
SELECT TOP ... FROM (SELECT .... UNION ... SELECT ...) ORDER BY ...
and
SELECT TOP ... ... UNION ... SELECT ... ORDER BY
Starting with this version, the first syntax form will be required. The second example is considered a defect where TOP always applied to the outermost processing level no matter where it was specified.
CASE Clause Result Type Change
In prior versions, the type reported by a CASE expression would be the same as the first potential return value of the CASE expression. This has been changed to return the best compatible type of all the possible return value types of the CASE expression. Caché will now also use the largest length, precision, and scale of all the potential return values; this applies to numeric return values only.
The precedence of return types (highest to lowest) is:
-
DOUBLE
-
NUMERIC
-
BIGINT
-
INTEGER
-
SMALLINT
-
TINYINT
Thus, if a CASE expression may potentially return TINYINT, INTEGER, or NUMERIC values, the type of the column will be NUMERIC because NUMERIC has the highest precedence.
SQL Gateway Changes
Settin Auto-Commit
In prior releases, it was necessary to call both SetAutoCommit^%apiGTW and SetAutoCommit^%apiSQL to change the auto-commit setting. With this release, the SetAutoCommit^%apiGTW call is the one that will take effect.
XML Changes
Exported xsi:type Now Matches Schema
The xsi:type attribute for datatype classes now reflects the actual type of the value. Previously, the xsi:type attribute was always set as the base predefined type, for example, s:string.
Mixed Content Now Properly Marked In Schema
For all elements identified as “complexType” with an attribute of mixed=”true", generate a CONTENT="MIXED" property as well as properties for each of the elements in the complexType. This change can cause compatibility problems if regenerating a previously existing set of classes from the XML schema because element properties were not previously generated by the Schema Wizard.
%XML.Reader Now Returns SAX Parser Errors
In this version of Caché, %XML.ReaderOpens in a new tab now returns SAX parser validation errors. Previously, the SAX parser was reporting the error, but there was a defect that prevented the error from being properly reported.
SAX Namespaces Change
In Xerces 3.0 (the version used in this release), there is a change to the way namespaces are processed. The flag to recognize namespaces is on by default. Turning it off will now cause the localname of the returned startElement callback data to be the empty string; previosly, it was a copy of the qname (fully-qualified name).
Zen Changes
Client-Side JavaScript Change
Zen applications that use client-side JavaScript methods will need to change the declarations of these methods. Where the method signature formerly began with the “Method” keyword, such as
Method test() [Language = javascript] { }
the declaration must be changed to
ClientMethod test() [Language = javascript] { }
Without this change, Zen classes will not compile or run on this version of Caché.
Changes To Include File Handling
The way that JavaScript and CSS files are generated for Zen components and the way that these files are used at run-time has changed with this release, namely:
-
Modules
Prior to this change, Zen would create a single JavaScript (.js) and stylesheet (.css) file for each class package containing Zen components. With this version, there is a mechanism for greater granularity – within a package, one or more Zen components can be placed into collections called modules.
-
Reorganization of JavaScript on pages
Zen pages are changed so that JavaScript includes and inline JavaScript are placed at the bottom of a page, after the HTML content is served. This should result in faster display of pages.
-
Dynamic loading of component JavaScript and stylesheets
When a component is created, the browser must have its JavaScript and stylesheet definitions on hand. This is accomplished by including the entire library within one large include file. This, in turn, allows dynamic creation of Zen components after a page has been loaded.
-
Use of include files for *all* non-page components
Prior to this, it was possible for a non-page component to have its JavaScript and stylsheet inline within a page. With this change, all non-page components will use include files.
-
Removal of Zen background file generation
The generation of JavaScript and stylesheet files now takes place as part of the compilation; the background file generation mechanism is no longer needed.
Zen dynaTree NodeCount Changed
ZEN dynaTree has a property that counts the nodes in the tree. With this version of Caché, the count now includes all the nodes in the tree, not just those at the top level.
Java Binding Changes
Caché Version 2010.1 Is Compatibility Break
Because of internal changes to the way the Java binding manages memory for objects, version 2010.1 represents a break in cross-version compatibility. Java clients on any version of Caché from version 5.0.13 to 2009.1 are compatible with Caché servers in that same range of releases. Those clients will receive an exception if they attempt to access a Caché server running 2010.1.
Java clients attempting to access a Caché server running version 2010.1 must also be running on 2010.1.
xDBC Changes
Make Catalog Queries Independent Of Version
For ODBC Catalog queries there are differences between ODBC 3.5 and 2.5. In version 2009.1, this was addressed by increasing the protocol number. This will not continue to work because SQL Server can dynamically switch between returning data for version 3.5 or version 2.5 by calling SQLSetEnvAttr. This sets the SQL_ATTR_ODBC_VERSION option to either 2 or 3 depending on which type of ODBC error messages or catalog information it wishes to present.
In this version, ODBC allows an application to dynamically switch between the two environment settings. Calling SQLAllocEnv sets the environment to version 2.5 by default. If you want to get the version 3.5 catalog information, you need to call SQLSetEnvAttr. If you use SQLAllocHandle (3.5) the driver manager will force you to call SQLSetEnvAttr before making a connection by giving you an out of sequence error.
Preserve Scale For %Numeric Values
In this version of Caché, the JDBC driver no longer ignores the scaling for %Numeric 0 values; it did in previous releases.
Callin And Callout Changes
Compatibility Between Caché And External Routines
When using Callin or Callout, the Caché instance and the external program exchanging data must have the same view of the characters exchanged. That is, they must both use a Unicode representation for strings, or both use an 8–bit representation. Mismatched exchanges where one side is Unicode and the other are not permitted. Failure to conform to this requirement may result in segmentation or access violations.
MultiValue Changes
Interpretation Of Sleep Value Changed
In prior versions, the MV shell SLEEP command would interpret 2:14 as sleeping for 2 hours and 14 minutes. Now it will be interpreted as a time of day. Beginning with this version the value will be interpreted in one of two ways:
-
If the value is of the form, HH:MM[:SS][AM|PM], it will be interpreted as a time of day. The system will sleep until the next occurrence of that time (which may be tomorrow if that time today is past).
-
Otherwise the value will be interpreted as the number of seconds to wait from the current time.
This interpretation also applies to the MVBasic SLEEP and RQM statements.
Platform-specific Items
This section holds items of interest to users of specific platforms.
Operators
System Management Portal
There have been a number of changes and improvements to the system management portal. These are detailed in the administrator section.