Chapter 1: New System and Language Features
Table of Contents | Chapter 2 | Chapter 3 | Chapter 4
Caché 3.2 introduces and brings together many exciting new features for rapidly creating
robust, portable, and high-performance applications. This document provides an overview of
these new features and enhancements.
Caché 3.2 is supported on the following platforms.
Table 1-1: Caché Supported Platforms
| Operating System |
Hardware |
| Compaq Tru64 UNIX 4.0F and 5.0 (Digital UNIX) |
Alpha computers |
| Digital OpenVMS 7.1 and 7.2 |
Alpha computers |
| DG/UX 4.2 |
AViiON (Intel) computers |
| HP/UX 11.0 |
Hewlett-Packard computers |
| IBM AIX 4.3.2, 4.3.3 |
IBM PowerPC computers |
| IBM AIX 4.3.2 |
IBM RS/6000 computers |
| Red Hat Linux 6.1 |
Intel-based computers |
| SCO UNIX 5.0, 5.02, 5.0.4, and 5.0.5 |
Intel-based computers |
| SCO UnixWare 7.1 |
Intel-based computers |
| Sun Solaris 2.7 |
Intel-based and SPARC-based computers |
| Windows NT 4.0 (with Service Pack 4, 5, 6, or 6A) |
Intel-based and Alpha-based computers |
| Windows 2000 |
Intel-based computers |
| Windows 95 and 98 |
Intel-based computers |
Refer to your Caché installation guide for memory and disk-space requirements.
Notes: It is recommended that customers who are recompiling or relinking Caché
on IBM AIX platforms install Version 3.6.6.0 (or later) of the C compiler.
The SCO UNIX 5.0.x platforms do not support CDL.
The following direct upgrade paths to Caché 3.2 are supported:
- Caché 3.1
- Caché 3.0
- Caché 2.3
- Caché 2.1.6, 2.1.7, 2.1.8, and 2.1.9
The following conversion and upgrade paths to Caché 3.2 are supported:
- DSM 7.2
- DTM 6.6
- DTM 4.10
- ISM 6.4
- MSM 4.4.1
If you are using a previous InterSystems database product, such as Caché 2.0 or
DSM 6.6, you must first upgrade to one of the above versions.
The Advanced tab of the Caché Configuration Manager has many enhancements that
now let you configure:
- SQL system-wide settings (SQL section)
- WAN (Wide-area Network) License Allocation (License section)
- number of job servers to start up (General section)
- shutdown timeout, in seconds (General section)
- up to 16MB of memory per process (Process section)
- display information from the ViewPoint server (ViewPoint section)
- DTM collation, letting you configure the DTM-NetBIOS Server to use the DTM
Compatible Collation type for DTM globals (Network section)
- DDP Group numbers from 0 to 15, allowing communication to any of the valid DDP Groups
(Network section)
- number of days before the ^ERRORS global gets purged (Journal section)
- the size (in MBs) by which an image journal file can grow before the transaction
index in the image journal is updated. The smaller the value, the more frequently the
transaction index gets updated, and the less time Caché startup spends in
looking back for any open transactions during system startup. A value of 10MB or greater
is recommended. (Journal section)
- whether to log transaction rollbacks (Miscellaneous section)
In addition, on non-VMS platforms, five versions of a given .cpf file are retained as
backups after editing in the Configuration Manager. The format of these files is
file.cpf00n, where n is a digit from 1 to 5.
Note: The Caché 3.2 Configuration Manager can be used to configure and manage only
3.2 and 3.1 systems. That is, it cannot be used to configure or manage pre-3.1 systems (such as
Caché 2.1.x), nor can it be used on Open M products (DSM, ISM, MSM, etc.).
The Caché Control Panel includes these enhancements:
- The Namespaces section lets you delete namespaces.
- The Local Databases section has a delete option and also displays the last expansion time.
- Integrity check (available from Local Databases section) now also checks maps.
- Print capability
- More information displayed for processes
The Caché Explorer has these enhancements:
- For routines: added find/replace and compile functionality, as well as the ability
to set the language mode and showing the first n lines.
- For globals: added find and print functionality, as well as allowing
cut-and-paste operations in the Global Viewer.
- For classes: added print functionality
The Caché Studio has the following changes:
- Autosave feature that lets the user specify a time period for the Studio to
automatically save their modified routines to disk as a backup. These
backup files will be deleted when the user saves the modified routine, or when the routine
or the Studio is closed down properly. The user can configure the interval between auto-saves
in intervals of one minute.
- Pushpin functionality added to the Find dialog box. The pushpin feature keeps the dialog
box on the screen after the specified text is found.
- The Studio recognizes a new extension on the server called .RTN, with text
"Caché Routines". When looking for files .RTN is expanded from "X.RTN" to
"X.MAC" and "X.INT". Therefore, looking for *.RTN will list all the .MACs, as well as any .INT
that has no associated .MAC file. The purpose is to show users the file they should open and
avoid confusion caused by a MAC and an INT file with the same name.
- The syntax checker reports SQL extended syntax as an error, because SQL computed code is
not supported.
- A "View Other" button has been added to the toolbar. If you are currently viewing a MAC
routine, pressing this button will bring up the associated INT routine and vice versa.
This toolbar button is disabled for INC routines.
- Shift-F3 reverses in the opposite direction when you are searching with the F3 key.
- You can set a system flag to automatically add a timestamp to the
first line of INT routines:
SET ^%SYS("STUDIO","ADDTIMESTAMP")=1
Setting the value to 1 enables timestamping for INT routines. Setting it to 0 (zero) stops
adding the timestamp. This feature is off by default.
- The Studio sometimes performs reverse DNS lookups to convert an IP address back to a
hostname. On some networks that have DNS configured badly, this can cause delays in
loading routines while the reverse DNS query times out. You can now disable reverse DNS lookups
by creating the following REG_DWORD key in the Windows registry:
HKEY_CURRENT_USER\Software\InterSystems\Cache Studio\Settings\ReverseDNS
Setting the value to 0 (zero) will prevent reverse DNS lookups.
In the Caché Object Architect, the Persistent/Serial parameters to classes are
no longer added automatically when they are saved. This logic is different from the 3.1
version of the Object Architect.
Caché 3.2 introduces the Caché SQL Manager, which is a Windows utility
used to manipulate SQL tables. It is invoked by name (CSQLMgr.exe) from the
CacheSys\Bin directory.
The Caché SQL Manager provides a common graphical user interface to several common
browse and update tasks for SQL databases. In particular, it can be used to invoke a
graphical user interface for loading an external file into an SQL table.
Caché 3.2 allows wide-area network (WAN) allocation of Enterprise Licenses. Sites with
a WAN configuration and unreliable connections can preallocate license units to various
hosts on the network. Because these licenses are administered by a license server running
locally on the remote host, it permits continued operation in the event of disrupted network
service between the satellite host and the central license server. The license units are
preallocated with the Caché Configuration Manager. Contact your InterSystems sales
representative for further information on WAN allocation of Enterprise Licenses.
A second enhancement is for multi-user PC clients. A single-user PC client can open a maximum
of 12 connections. If multi-user clients are configured for a Caché server (via
the Advanced->License tab of the Configuration Manager), the PC client becomes a multi-user
client when it requests the 13th connection.
As a third enhancement, the License Wizard lets you enter a TCP/IP node name for the license
server. Previously, only IP addresses were accepted.
Note: Any customer with a Version 2.1 Division license must exchange it for a
Version 3.2 Department license, because the 2.1 Division license will not work with
Caché 3.2. There is no charge for the exchange.
Caché 3.2 ObjectScript is enhanced with a new $NUMBER function that validates
numbers supplied in a variety of external formats.
In addition, the $DATA, $ORDER, and $QUERY functions are extended with an optional argument
that returns the data value of the node.
See the Caché ObjectScript Language Reference for details on these functions.
The %PRIO utility has been enhanced to give you better control of jobs. The first (and
original) purpose of %PRIO was to adjust the priority of the job; the
second purpose is to set the batch-mode flag in non-interactive
jobs. Once the batch-mode flag is set, this job is prevented from flushing global buffers
that are actively in use by non-batch-mode jobs.
Developers were using LOW^%PRIO as a means of setting the batch-mode flag, and then discovering
that the lowered process priority sometimes had unintended consequences, especially on
OpenVMS platforms. Therefore, to give you tighter control over the behavior of jobs, you can
now control the priority and batch-mode status of a job with the syntax:
DO SET^%PRIO("keyword1[,keyword2])
string can be one priority keyword and/or one batch keyword (which must be in uppercase):
- LOW — decreases the priority of the job
- NORMAL — returns the priority of the job to normal
- HIGH — increases the priority of the job
- BATCH — sets the job to a batch status
- NOBATCH — sets the job to a non-batch status
If both priority and batch keywords are used, they must be separated by a comma; for example:
DO SET^%PRIO("HIGH,NOBATCH")
If neither "BATCH" nor "NOBATCH" is present in the string, the batch status of the job is
not changed. The same applies to the priority. Conflicts among these specifiers are resolved
by the order of their appearances in the string, with the latest one having the precedence.
To get the pre-3.2 behavior of SET^%PRIO, use the following instead:
DO SETPRIO^%PRIO
The existing entrypoints LOW^%PRIO, NORMAL^%PRIO, and HIGH^%PRIO are still supported and adjust
the priority and the batch status of the job in a predetermined way:
- HIGH^%PRIO increases the priority of the job and changes the job to non-batch status.
This is equivalent to the new syntax:
DO SET^%PRIO("HIGH,NOBATCH")
- NORMAL^%PRIO returns the priority of the job to normal and changes the job to
non-batch status. This is equivalent to the new syntax:
DO SET^%PRIO("NORMAL,NOBATCH")
- On non-OpenVMS platforms, LOW^%PRIO decreases the priority of the job and changes the
job to batch-like. This is equivalent to the new syntax:
DO SET^%PRIO("LOW,BATCH")
- On OpenVMS platforms, LOW^%PRIO only changes the job to batch-like while leaving the
priority unchanged. This is equivalent to the new syntax:
DO SET^%PRIO("BATCH")
Note that OpenVMS behavior was changed for Caché 3.2, because poor performance can
result when a low-priority job owns a high-priority resource.
The following enhancements apply to platforms that support the 16-bit Unicode character set.
The space efficiency of storing Unicode strings in the database has been significantly improved.
Unicode strings that have a high number of ASCII characters, repeated characters, and/or
sequential characters in the same Unicode Code Page will be compressed so that they take
less space in the database than before. No action on your part is necessary to make use
of this compact format.
There is also one backwards incompatibility issue of which you must be aware:
A Caché 3.1 Unicode client using DCP to connect to a Caché 3.2 Unicode server
will not be able to access any compact Unicode whose stored length is greater than 756 bytes
(such strings can have any number of characters from 378 to the maximum string size).
InterSystems recommends that if any servers in a DCP network are to be upgraded to
Caché 3.2 and the application makes use of Unicode long strings, then all the
clients be also upgraded to 3.2.
Note that Caché routines in .OBJ format are always stored in binary format. Thus,
routines are never are considered Unicode strings, even if the routine makes use of
Unicode characters internally.
You can now enter Unicode characters in the description field of a backup label. The string
will first be translated using the process's default translation type for the class of
device used for the backup (magtape or disk file).
Caché for Windows (NT and 95/98) now supports an improved interprocess communication
device for communicating between processes on a single system. For 3.2, this device can be
used only between separate Caché jobs on the same system, or for Caché to
communicate with the ODBC client.
The Windows 4.0 Terminal Server is supported as a Caché 3.2 platform. Several concurrent
Windows sessions can now be supported on the same Windows computer.
Caché now automatically determines the number of active CPUs on a UNIX system.
Previously, you needed to specify the correct number via the Caché Configuration
Manager, which was then stored in the cache.cpf file. Because of this enhancement, the
Configuration Manager's Microprocessor field (in the Advanced->General tab) has
been removed.
The following UNIX platforms now support locking the Caché virtual memory into
physical memory:
- Compaq Tru64 UNIX (Digital Unix)
- DG/UX
- HP/UX
- IBM AIX (on PowerPC and RS/6000)
- SCO 5.0 UNIX and SCO UnixWare 7.1
- Sun Solaris (on SPARC and Intel)
Note that this kind of locking is NOT supported on Linux.
The Solaris platforms make use of a feature called intimate shared memory, so
that page tables to shared memory can be shared, as well as the shared memory itself.
No special action is required for Caché to make use of intimate shared memory; it
will be enabled by default on Solaris systems that support it.
In addition, Caché 3.2 supports a new Sun platform type that introduced for the
64-bit UltraSPARC processor. It requires Solaris 7 with a 64-bit kernel. To check whether
you have a 64-bit kernel, issue the following command:
$ isainfo -v
64-bit sparcv9 applications
32-bit sparc applications
If the first line ("64-bit sparcv9 applications") is not displayed, then Solaris was not
installed in 64-bit mode.
Note that the original Solaris implementation of Caché will continue to run on
UltraSPARC processors. The new version, however, can take advantage of several optimizations
that would not be possible on generic SPARC processors. In particular, Caché makes
use of 64-bit arithmetic. Caché also includes an expanded level of assembly optimizations
for the UltraSPARC product.
The Alpha OpenVMS platform now makes use of the "Resident Memory Section" facility.
All OpenVMS Caché users are encouraged to make use of this facility.
For AlphaVMS systems running VMS 7.1 and later, two new features are available for global
buffer allocation. The new features, memory-resident global sections and shared page tables,
are always used as a pair. Caché 3.2 supports memory resident sections only for
the global buffer pool.
Using a memory resident global section for the global buffer pool has three main advantages:
- Access to the memory in a memory-resident global section is not charged against the
process pagefile quota nor the working set quota, nor do they use the processes working set list,
so process quotas may often be reduced.
- There is only one copy of the global buffer pool page table on the system, which
conserves physical memory and speeds up mapping the global section into a new process.
- This memory is accessed via system page tables, which means that no soft faults are
incurred in referencing it. This can be significant for very large buffer pools, because
soft faults represent wasted overhead for this type of memory.
The main drawback to consider in using these structures is that if you want to increase the
size of your global buffer pool, you may have to reboot OpenVMS in order to reconfigure
the amount of space reserved for the memory-resident global section. In most cases, space
for memory resident sections is reserved when the system image is created via SYSMAN and
AUTOGEN. Memory resident sections can also be created dynamically, but the request will fail
if there is insufficient space available when the request is made.
If Caché is asked to use a Memory-Resident Global Section and it cannot, it will
allocate the global buffer pool out of a non-Memory-Resident Global Section, as it does
in pre-3.2 (e.g., it will fall back to the existing mechanism). You will see a message
in the cconsole.log file during startup that Caché was unable to use resident memory
for the global buffer pool and that it is allocating the global buffer pool in a
"conventional" global section.
To use these structures you need to do the following six steps:
Step 1: Calculate how much memory you need to reserve, based on how many global
buffers on your system:
2500 bytes per global buffer (includes overhead)
times number of global buffers
rounded up to next 8K boundary
and then converted back to the next whole # of megabytes.
This calculation is (in Caché):
s numglobuf=200000 ;we want 200,000 global buffers
s membytes=2500*numglobuf ; ; See Note 1 below.
s membytes=membytes+8191 ;round up to an AlphaVMS page
s membytes=(membytes\8192)*8192
s memmb=membytes/1024/1024 ;convert bytes->megabytes
w !,"You need ",mem_mb," of memory for ",numglobuf," buffers"
w !,"Round this up to the nearest whole MB"
Note 1: A MB boundary is larger than a VMS page boundary (e.g., 1MB > 8192 bytes), so
you could just round up to the next MB. That is, add (1024*1024)-1 and then
do an integer divide by (1024*1024).
Step 2: Use SYSMAN to reserve a section of memory. You can call the named section
anything you want, as long as the name consists of alphanumerics (and the underscore) and
is not longer than 43 characters. The default section name is "ISC_Shared_Memory". The
syntax for SYSMAN is:
MCR SYSMAN ! run sysman SYSMAN> RESERVED_MEMORY ADD "ISC_Shared_Memory" - /ALLOCATE/PAGE_TABLES/ZERO/SIZE=<size in MB> SYSMAN> EXIT
Step 3: After asking SYSMAN to reserve the section, you need to run AUTOGEN to take
the reserved memory into account (and to get it reserved) and reboot the system. After the
system has been rebooted, the SYSMAN command:
RESERVED_MEMORY SHOW
will display the shared memory section you reserved.
Step 4: Modify the Caché configuration file to use the reserved section. This
is done by setting the reserved memory parameter in the [config] section (this can be done
via the Configuration Manager) so that it reads:
useresidentmem=1[,<resident-memory-section-name>]
The optional resident-memory-section-name is the name of the section you
specified in SYSMAN when you reserved it. If you use the default name of ISC_Shared_Memory,
this can be omitted from the configuration file.
Step 5: Restart Caché. If Caché cannot use the reserved memory section,
a message will be displayed (and logged to the operator console) and an error code will be
stored in the SYSLOG.
Step 6: The SHOW MEMORY command should show that the resident memory section
is "in use".
Other Caché 3.2 new and enhanced features are documented below.
The cvendian utility has been enhanced to support multivolume databases. The utility has
a new command interface:
cvendian file1 file2 [... file8]
For backward compatibility, however, the previous interface is still supported. For details,
see the Database Endian Conversion Guide.
For all platforms, the maximum supported partition size has been increased from
1 MB (1024 1KB blocks) to 16 MB (16384 1KB blocks). Because this change slightly
increased the memory cost of the NEW command, applications that encounter
NEW <STORE> errors should increase the configured partition size by 32 1KB
blocks (the minimum granularity of increase).
For the following UNIX platforms, the maximum supported size of a database file (CACHE.DAT) has
been increased from the previous 2 GB to 16 GB:
- Compaq Tru64 UNIX 4.0F and 5.0 (Digital UNIX)
- Digital OpenVMS 7.1 and 7.2
- HP/UX 11.0
- IBM AIX 4.3 (on IBM RS/6000 computers only)
- SCO UnixWare 7.1
- Sun Solaris 2.7 (on both Intel and SPARC computers)
Note that this change does not expand the maximum size of a whole database on these UNIX
platforms. Previously, Caché could always store up to 16 GB in in one database on UNIX,
but to do so, it created one CACHE.DAT and 7 CACHE.EXT files. Now the extension files are not
necessary for this purpose. The total maximum data stored in one instance of Caché (on any
platform) is about 4 terabytes (255 databases x 16 GB per database).
In addition, UNIX sequential files greater than 4 GB are now supported on the above platforms.
In previous versions of Caché, the total number of global mappings allowed in a
single namespace was 255 (including the default global mappings). Caché 2.1.x,
for example, had 8 default global mappings, so the user could specify a maximum of
247 global mappings.
Caché 3.2 increases the total number of global mappings to 65,536 (which effectively
removes the limit).
Caché 3.2 contains improvements in the performance of datasets that are used only
for temporary data. For these datasets, persistence of data after a system shutdown or
outage is not an issue. For these reasons, the ^CacheTemp* global is automatically mapped
to the CACHETEMP database, and global modifications in the CACHETEMP database are no
longer journaled under any circumstances.
The JOB process startup is enhanced on both UNIX and NT, leading both to faster processing
and more robust behavior. In addition, a problem was been fixed in which a JOB command
without timeout would fail without notification after 15 seconds if the reliable JOB
mode switch were on and the job could not be started.
Also, JOB servers are now supported on all platforms. For applications that can support
them, JOB servers can significantly increase the speed with which a routine can be jobbed off.
Changing a journaling state (e.g., from "not journaled" to "journaled") now takes effect
immediately. Previously, the journal state change of a global was not necessarily in effect
in existing jobs, although it was guaranteed to take effect in jobs created after the change.
Caché also includes the JCONVERT and %JREAD journaling utilities. JCONVERT is a utility
which reads a Caché journal file and converts it to a common format (flat text) file.
The common format file can then be read by the %JREAD utility and applied to a database. The
JCONVERT utility can run on any version of ISM 6.4 and later. It is useful for moving
journal data between different version systems.
Shadowing error and informative messages have been improved. For example, Shadow Server start/stop
messages are sent to cconsole.log instead of the Errors list. Error messages are more
user-friendly and descriptive.
The Caché Configuration Manager has two new options in the Advanced->Shadow panel,
which let you set:
- The time interval between two probes when the Shadow Server has caught up with the
Database Server. The longer you set the interval, the less likely the Shadow server is kept
updated.
- The maximum number of errors to keep in the globals (and display in the error log).
Shadowing itself is more robust, as in the Shadow Server's retry attempts if the Database Server
is not up or has disconnected.
DSM-DDP allows you to partion a network into subsets of DDP Groups. Only DDP nodes within
the same DDP Group can communicate with each other via the DSM-DDP protocol. DDP Group
numbers range from 0 to 15 and communication to multiple groups is also supported.
Previously, Caché was hardcoded to use only Group 0, which was a built-in group.
With Caché 3.2, you can specify DDP Group numbers from 0 to 15, allowing
communication to any of the valid DDP Groups.
When installing Caché 3.2 (new or upgrade), you must specify with which DDP group(s)
you would like Caché to communicate. Use the Advanced->Network panel
of the Caché Configuration Manager to specify the group numbers.
The INTEGRIT utility has been improved so that it continues even after encountering an error
in a database. Previously, it would always stop after finding a database error.
In addition, INTEGRIT now calls CHECKMAP as part of its operation.
The Caché installation procedure has been modified to maintain separate backups of
configuration files when reinstalling the same version or upgrading to a later version
(such as 3.2.0 to 3.2.1). The prior cache.cpf file will be renamed to
cache.cpf_nnn, where nnn is the configuration file version number
(for example, 323).
Thus, if you run into difficulty with a newer version of Caché, you can
reinstall the prior version and recover the corresponding configuration file.
Note: This is not a downgrade procedure, because downgrading is not supported.
It merely permits identifying and recovering a configuration file from a prior version in
case you need to drop back. In this case, you should perform a clean reinstall of Caché
(remove the system manager database at least) before installing an earlier version in
the same location.
The various $ZOS function forms are file system commands which MSM supports.
Caché 3.2 supports the following subset of $ZOS on all Caché platforms. The
functions are available only in MSM language mode.
- $ZOS(2)
- $ZOS(3)
- $ZOS(4)
- $ZOS(5)
- $ZOS(6)
- $ZOS(7)
- $ZOS(9) - Windows only
- $ZOS(10)
- $SOS(12)
- $ZOS(13)
- $ZOS(16)
- $ZOS(17)
Note that the $ZOS(9) return values are also different from what is returned in MSM. It
returns Nulls for pieces 1-4, bytes used for piece 5, bytes free for piece 6, and total
space for piece 7. For example:
w $zos(9,"c")
might return:
^^^^3120113043^752467968^3872581011
Unsupported $ZOS functions will return -1 as the value of the function. Note that $ZOS(8)
will end any $ZOS(12) search handle, but will not change the directory (returns -1).
The Caché documentation is installed as part of the default Caché for Windows
installation. A "Caché Documentation" link to the documentation is available in the
Caché Cube under the Help option.
All online documentation is available in HTML (with the exception of the
Caché ObjectScript Reference, which is in Adobe Acrobat PDF format).
PDF versions of the printed documents are also available on the Caché for Windows
product CD.
To view the PDF files, the client machine must have Version 4.0
of the Adobe Acrobat Reader installed. Acrobat Reader is free and can
be downloaded
from the Adobe website.
The configuration and management utilities, as well as the programming utilities (such as
Caché Studio), use the Microsoft HTML Help format for their online help. This
format requires that the Windows client have Microsoft IE (Internet Explorer) 4.01 (with
Service Pack 2) or IE 5 installed.
Table of Contents | Chapter 2 | Chapter 3 | Chapter 4
Top of Page