Skip to main content

Pre-2014.1 Upgrade Information

Upgrading Caché

Upgrading from Field Test Versions


InterSystems does not support an upgrade from any Field Test version to another Field Test version, nor from a Field Test version to an officially released version. The term “Field Test version” includes any version of Caché labelled as such, or distributed to customers at the InterSystems Global Summit or other events.

Upgrading From Prior Released Versions

Customers running on any prior released version of Caché may upgrade to this version of Caché during installation. When upgrading across multiple versions, intermediate upgrade steps may be necessary depending on the inter-release compatibility requirements. The release notes for the intervening releases will contain that information.


2K block size databases must be converted to 8K format before upgrading to 2012.2.x or beyond. See Supported Upgrade Paths in the “Upgrading Caché” chapter of the Caché Installation Guide for more information.

Prior to beginning an upgrade, InterSystems recommends that an instance be shut down using standard methods — not as the result of, for example, a system crash.

After each upgrade step, the following conditions apply:

  • Pure Routines

    Pure routines are upward-compatible from version to version and do not need to be recompiled. Pure routines are those that:

    • are not generated as a result of class compilation;

    • do not use classes as part of their operation; and

    • do not access routine or class meta-information (such as using source-level debugging on version X of code compiled on version earlier than X.).

    Most versions contain improvements in the routine compiler, in the generated code, and/or efficiencies in the runtime support, and customers may decide to recompile their routines to take advantage of new features.

    If you decide to recompile routines, they should be recompiled after classes are recompiled.

  • Classes, SQL, Projections, Proxy Classes

    InterSystems requires that all custom classes be recompiled after an upgrade. Users should recompile their application classes using either their own build procedure, or enter the following command to upgrade and compile the class dictionaries in namespaces with custom code:

     ZN "namespace"
     Set StatusCode = $SYSTEM.OBJ.CompileAll("u")
     Do $SYSTEM.Status.DisplayError(StatusCode)

    You must regenerate any proxy classes used in the upgraded instance by following the instructions in the appropriate guide(s) in the Caché Language Bindings set.

    It is also good practice to log the output from the preceding command sequence so that a detailed examination of the results is possible.

    You could also use the $SYSTEM.OBJ.CompileAllNamespaces() method to recompile all namespaces, but you should not do this when upgrading a HealthShare installation. You should not recompile a namespace used for HealthShare.

  • Other routines

    Routines that do not meet the preceding definition of pure routines must be recompiled after classes are recompiled. Make sure you have access to write to the database and execute the command:

    Do ##class(%Library.Routine).CompileAll()

    in each namespace of interest.

  • Exported XML

    Unless specified in the upgrade notes for a specific release, exported XML files can be imported into later releases.

    The reverse is NOT true. Later versions could be using new features not present in earlier versions, and could have a different class dictionary version number which alters how these classes are stored internally that cannot be undone when importing to a previous version.

  • Debugging

    InterSystems also recommends recompiling routines and classes for applications under development. This synchronizes the debugger with the expected format of the compiled code.

When Recompiling

There are several things to remember when recompiling:

  1. Because recompiling necessarily updates system data associated with the routine, users who recompile classes or routine must have write access to this data (^ROUTINE) in each namespace where the object being compiled is mapped. Failure to observe this requirement will result in “ERROR #302: the database is read-only”.

  2. Everything needed for compilation must be accessible in the namespace where the class or routine is mapped. For example, if a class or routine refers to a user-defined include file, this must also be mapped so it will be found by the compiler when the source is processed.

  3. By default, $SYSTEM.OBJ.CompileAllNamespaces does not compile the namespaces “%SYS” and “DOCBOOK”. If a site has classes in %SYS, these will need to be manually recompiled. Do not use $SYSTEM.OBJ.CompileAllNamespaces on a HealthShare installation.

  4. The recommendation to use features such as $SYSTEM.OBJ.CompileAll assumes that all information about dependencies between items being compiled is entirely contained within the declarations of the items themselves. For some complex applications, for example those that assemble an application “core” and then bootstrap themselves to the final version, this will not be the case. In such instances, users should create scripts to compile the code so that dependencies unavailable to the compiler are accounted for, especially in relation to schemas and domain-specific languages.

  5. Although it is not required, if a site has placed routines named [%]Z* in the %SYS namespace, InterSystems recommends that these be recompiled, for example, with

    ZnSpace "%SYS"
    Set sc = $SYSTEM.OBJ.CompileList("Z*,%Z*", "ck")

Compatibility With Earlier Versions

InterSystems strives to assure that applications written for a version of Caché will run without change on subsequent versions. While this is not always possible (and therefore the reason for this document), the reverse is not true.


In general, InterSystems does not support moving an application developed for version X to a version prior to X. This applies to both source and compiled versions of the application. Exceptions to this are few and explicitly noted.

Customers writing an application that will be deployed on multiple versions of Caché should design and develop the application to use only the features on the earliest of the intended versions.

Web Application Considerations

As part of your upgrade and deployment plans, please consider the following strong recommendations from InterSystems regarding web applications:

  • In secure deployment environments, do not allow Unauthenticated access to any web application. To do this, on the Edit Web Application page for each application, uncheck the Unauthenticated box under Allowed Authentication Mechanisms.

  • The /csp/broker web application should not have any allowed authentication methods. To do this, on the Edit Web Application page for /csp/broker, uncheck the boxes for all the choices under Allowed Authentication Mechanisms.

FeedbackOpens in a new tab