Skip to main content

General Upgrade Information

InterSystems’ ultimate goal is to have a release which can be installed with no, or little, effect on the applications it supports. This release provides an easier upgrade path if you are upgrading from version 2013.1 or later. If you are upgrading from a release prior to 2013.1, you must still follow the prior recommendations; for details, see Pre-2014.1 Upgrade Information.

Important Considerations


The goal of each release is a smooth upgrade to new and improved functionality with no changes required to existing applications. However, because of error corrections, significant enhancements, or changes to applicable standards, this goal cannot always be met. In this case, InterSystems discloses all identified instances where changes to applications are necessary so that customers can gauge effort required to move to the new release.

This book describes the details changes made in that release that may affect applications upgrading from the prior release. Among the items listed are: changes to the way the system operates; enhancements to the class and routine compilers; detailed changes made to system classes in terms of parameters, properties, and methods removed; changes to method call signatures; and differences in method returns.

You may, after reading the release-specific changes, conclude that none of them affect your application. Even in this case, regardless of how robustly designed and how well implemented your application is, there is no substitute for quality assurance test results that confirm your judgement and demonstrate the application remains unaffected by the upgrade.


InterSystems recommends that each application be thoroughly tested in the upgraded environment before it is deployed to customers and begins processing live data.

Technology Previews

In recent releases, InterSystems made available software labeled as “experimental”, or “preview”. The purpose of these offerings is to allow customers to participate more closely in the development process by giving them access to software during a period where their feedback can influence the course of future evolution.

As long as its status remains “experimental”, this software will change during the course of a release and, depending on how long it remains in that state, even from one release to another. Some of these changes may be significant enough to make the latest software version incompatible with prior versions. Therefore, customers who wish to take advantage of such software in their application should consult with InterSystems beforehand. InterSystems will be happy to provide details on the implementation and its probable future path toward becoming a standard part of a release.

Field Test

Toward the end of development for each release, InterSystems makes available successively more complete copies of the final product to its customers. The notifications are published on the website and on public blogs. The purpose of this is two-fold:

  • It provides an early opportunity for customers to determine how the changes and enhancement in the release affect existing applications, to report issues found, and verify those issues have been resolved.

  • It also provides exposure of important proposed features (the experimental software) which may become part of future releases. Customer have a chance to try out the proposed ideas and give feedback on the usefulness of this feature for their business area.

InterSystems strongly encourages customers to plan on obtaining one or more instances of the field test and to test their application against it.


InterSystems does not support upgrading from a field test version.

Unresponsive Systems

One of the goals for field test is to expose the new release to real-world operating challenges to assure its reliability. Therefore, it is possible, although unlikely, that an unanticipated sequence of events may render Caché unresponsive. In this situation, it is extremely important to gather system diagnostic information while in the hung state for InterSystems to analyze. Should an instance of Caché become unresponsive,

  • Log in as an administrator

  • In a terminal window, run the CacheHung script in the directory, <install-dir>/bin.

    The scripts corresponding to supported systems are:

    • Windows: CacheHung.cmd

    • UNIX®, Linux, AIX, and so on:

  • Send the resulting output file to the InterSystems Worldwide Response CenterOpens in a new tab. You can email the file to, open a new problem using the WRC Online, or call the Center directly for additional assistance.

Upgrade Specifics

This section contains specific instructions applicable to this transition.


InterSystems recommends that customers recompile all their classes contained in each namespace. This will assure that:

  • Subclasses derived from the InterSystems product library will see improved product behavior if a method call results in executing code in its superclass(es).

  • All embedded SQL will use the latest versions of the SQL infrastructure.

  • All projections involved in language bindings will be updated.

  • All generated routines and classes will be updated.

Class compiler version utility

To assist customers in determining which class compiler version a class or classes in a namespace have been compiled with, InterSystems provides two assists

  • Method – $System.OBJ.CompileInfoClass(<classname>)

    This method returns the version of the class compiler used to compile this <classname> and the datetime the class was compiled

  • Query – $System.OBJ.CompileInfo(<sortby>)

    This query generates a report for the current namespace that includes all classes, the version of the compiler used to compile each one, and the datetime each was compiled. The first argument <sortby> may have the following values:

    • 0 – the time the class was compiled

    • 1 – the class name

    • 2 – the version of Caché the class was compiled in


ObjectScript routines, and MultiValue and Caché Basic programs do not need to be recompiled after upgrade with the following exceptions:

  • Routines containing embedded SQL must be recompiled.

  • MultiValue paragraphs containing queries must be recompiled.

Cached Queries

Cached queries are always purged during upgrade. They are recompiled and cached as needed.

Web Services and SOAP

It is not necessary to re-import any Web Service Definition (WSDL) files.

Upgrading System Using KMIP Server Encryption

When upgrading a system which uses database encryption keys from a KMIP server, you must set the database encryption option to:

Unattended key activation with a KMIP server

and select the keys on the KMIP server you want to activate using the ^EncryptionKey routine. Once you do this you can perform the upgrade.

FeedbackOpens in a new tab