Upgrading Ensemble

Upgrading from Ensemble 2007.1 or Later

If you are upgrading from Ensemble 2007.1 or later to this release of Ensemble, in addition to deleting the files outlined in the Caché upgrade documentation, the upgrade procedure deletes the following Ensemble files:

• Any user files in the ENSDEMO namespace

• Any user files in the packages normally reserved for Ensemble (CSPX, Demo, Ens, or EnsLib)

If you have customized any files in these namespaces or added new files to these namespaces, you should preserve them before upgrading. To preserve such files, export them before proceeding with the upgrade. You may import them to any namespace after the upgrade is complete.

To upgrade an existing Ensemble installation to this release of Ensemble:

1. Stop all running productions.

2. Disable the production auto-start option for all productions in all namespaces. See “Managing Production Auto-Start” in Managing Ensemble.

3. Perform exports to preserve files that are deleted on upgrade.

4. If you use custom search tables and are upgrading from Ensemble 2010.2 or earlier, run the following command from a terminal in the ENSLIB namespace before the upgrade to prepare the existing metadata for relocation:

   ENSLIB>Merge ^%SYS("Ensemble","Upgrade","SearchTable","Data") = ^Ens.Config.SearchTablePropD
   
   

   

   Ensemble checks this location during upgrade and adds any of the existing metadata into namespaces where the originating search table classes exist. This occurs before any compilation of search tables in the namespace. For details, see “Updated Search Table Validation” in the chapter “Upgrade Compatibility Issues” in the Ensemble Release Notes.

   Ensemble automatically recompiles all search table classes during the upgrade process, so do not Kill the global nor import the contents after the upgrade. The upgrade process ensures that Ensemble correctly retains search table metadata after the upgrade. It also ensures that the converted data is consistent, so InterSystems strongly recommends that you thoroughly test your upgrade process so that you can address any issues in the original metadata prior to the actual upgrade.

5. If you have a large message warehouse and have either run Tune Table or have set the extent size and selectivity values manually, you should either verify that the new default values match your existing system or run Tune Table after the upgrade. If you have not run Tune Table or manually set the Selectivity value, the default values are likely to be an improvement on your performance.

   If you have taken action to optimize access to this table, take the following actions to ensure that the system performs well after the upgrade:

   1. Record the ExtentSize and Selectivity values of your current system. One way to do this is to open the Ens.MessageHeaderOpens in a new tab class in Studio. ExtentSize and Selectivity are listed at the end of the class definition in the code window.

   2. If your values are significantly different than the new defaults, then after upgrading, either run Tune Table or use Studio or the Management Portal to manually update the ExtentSize and Selectivity values to describe your system.

   Important:

   You can run Tune Table against a running system as long as you select the Keep class up to date check box.

   For details on using Tune Table, see “ExtentSize, Selectivity, and BlockCount” in the chapter “Optimizing Tables” in the Caché SQL Optimization Guide.

6. Prepare for an upgrade to Ensemble as described in “Upgrading Caché” in the Caché Installation Guide.

7. Install Ensemble using the instructions in the appropriate platform-specific chapter of the Caché Installation Guide:

   • Installing Caché on Microsoft Windows

   • Installing Caché on UNIX® and Linux

   • Installing Caché on Mac

   Each chapter provides special instructions for upgrades.

8. If you exported custom schemas or any other production components or classes from a previous Ensemble installation, import them using Studio or the Management Portal. Be sure to import each item into the same namespace from which you exported it.

9. After upgrading Ensemble, you must recompile all objects that you have defined. One way to do this is to recompile all objects in namespaces that contain your custom code. To recompile all objects in a namespace, open a Terminal window and issue the following commands:

    ZN "namespace"
    DO $system.OBJ.CompileAll("u")

   

   This method both upgrades and then compiles the class dictionaries in the specified namespace.

   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.

   Important:

   It is important to compile classes and schemas before compiling the DTL or BPL that uses them. In a complex application, you might have other dependencies to consider as well.

   The recommendation to use $SYSTEM.OBJ.CompileAll() assumes that all information about dependencies between items being compiled is entirely contained within the declarations of the items themselves. You can establish such information by including compiler keywords such as DependsOn and CompileAfter. Alternatively, you can create routines to compile the code so that dependencies unavailable to the compiler are accounted for, especially in relation to schemas and domain-specific languages.

10. The Ensemble upgrade process reports important information regarding upgrades into a log file. After upgrading, review the contents of the ensinstall.log file in the \mgr subdirectory of your Ensemble instance to review the results of your upgrade.

11. Regenerate proxy classes if you previously generated them using the Java Gateway or one of the Caché language bindings, by following the instructions in the appropriate guides:

    • Using the Java Gateway

    • Other books in the Caché Language Bindings set

12. In some previous releases, in order to automatically start productions or execute code on production start, you inserted this code in the Caché user startup routine ^%ZSTART. This code should now belongs in other locations; consequently, remove all Ensemble-related code from the user startup routine ^%ZSTART. Use the following replacement mechanisms:

    • To automatically start productions, use the Ensemble production auto-start options instead of your custom code. For details, see “Managing Production Auto-Start” in Managing Ensemble.

    • Identify any code that you want to run for a production when it is started. Override the OnStart() callback method in the production class and place that code into this method.

    • Identify any code that is designed to act on specific business hosts upon production startup. Override the OnProductionStart() callback method in the corresponding business service, business process, or business operation class and place that code into this method.

    For information on these callback methods, see “Less Common Tasks” in Developing Ensemble Productions.

13. Re-enable the production auto-start options, as desired. See “Managing Production Auto-Start” in Managing Ensemble.

Upgrading from Ensemble 4.0 or 4.0.1

Upgrading from Ensemble 4.0 or 4.0.1 to the current release of Ensemble uses the same procedure as upgrading from later versions of Ensemble, but with some additional considerations. These are:

• The upgrade procedure deletes any HL7 custom schema definitions (*.HL7).

  Caution:

  To preserve such files, export them before proceeding with the upgrade. You may import them to any namespace after the upgrade is complete.

• For each Ensemble-enabled namespace, run these commands from your Terminal session:

   ZN "nextEnsembleNamespace"
   DO ##class(Ens.MessageHeader).%PurgeIndices()
   DO ##class(Ens.MessageHeader).%BuildIndices()
   DO ##class(EnsLib.HL7.Message).%PurgeIndices()
   DO ##class(EnsLib.HL7.Message).%BuildIndices()
   DO ##class(EnsLib.HL7.Message).%BuildIndices(($LB("Extent")))

  

  These commands are required for the ENSDEMO and ENSEMBLE namespaces, and for any user-defined Ensemble-enabled namespaces.

Upgrading Ensemble Mirror Members

This section documents the steps to follow to upgrade an Ensemble mirror configuration. You should be familiar with standard Caché upgrade procedures. For general information on running Ensemble on a mirror, see “Ensemble Considerations for Mirroring” in the Caché High Availability Guide and for upgrade procedures, see “Minimum Downtime Upgrade with Mirroring” in the Caché Installation Guide for details.

Any upgrade involving a mirror includes two kinds of changes:

1. Changes that should occur on all mirror members, such as replacement of library code in CACHELIB and ENSLIB.

2. Changes that affect the mirrored data and should occur only once (on the primary failover member) because database access is read-only on the backup mirror members.

The Ensemble upgrade code is sensitive to this distinction and may need to make both kinds of changes during the course of an upgrade. It is important to note that the Ensemble upgrade code performs upgrades to Ensemble-enabled namespaces on a namespace-by-namespace basis, and checks whether each namespace contains mirrored data. If a namespace contains any mirrored data, then the “only once” steps only occur for that namespace when the upgrade code is running on the primary failover member. As such, it is crucial that the data Ensemble uses to determine whether a namespace has been upgraded is shared across the mirror.

The following sections describe the details of the data as well as the important issues and procedures necessary to upgrade the Ensemble instances in a mirror configuration:

• Important Mirror Global Data

• Mirror Considerations

• Performing the Mirror Upgrade

Important Mirror Global Data

The most important location for upgrade data which need to be shared is the ^Ens.Mirror global located in each namespace that contains any mirrored data. The ^Ens.Mirror global is used to determine which upgrade steps need to occur for that namespace. As such, you must ensure that each namespace containing mirrored data includes this global in the mirrored database(s). More specifically, for each namespace which contains mirrored data, you must map the ^Ens.Mirror global in that namespace to a mirrored database so both members of the mirror can determine whether “only once” steps in the upgrade process for that namespace are complete.

You should also map the ^Ens.AutoStart global to a mirrored database for each namespace containing mirrored data. The ^Ens.AutoStart global specifies the name of the Ensemble production to start automatically after startup and, generally, it makes sense to have such an auto-start be identical across mirror members.

It may be simpler to illustrate what is meant by the above two directives using an example. Assume a given Ensemble namespace makes use of two user databases: DATA1 and DATA2. (The namespace also includes mappings to ENSLIB, but that is handled by Ensemble.) Assume DATA2 is a mirrored database, but DATA1 is not mirrored. In this situation, you must explicitly map both ^Ens.AutoStart and ^Ens.Mirror to the mirrored DATA2 database so the contents of the globals are visible to both members of the mirror.

Before the upgrade commences, disable the auto-start of productions for namespaces containing mirrored data on both instances. If, as recommended, the ^Ens.AutoStart global is mirrored across the two instances for a given namespace, then you only need to perform this step on the primary mirror member; otherwise, perform this step on both failover members. This is in keeping with the standard Ensemble upgrade procedure and prevents any productions from being started during the upgrade.

Note:

Use the following commands to identify if the two important globals are mapped correctly for a given NAMESPACE:

  Write ##class(SYS.Database).%OpenId($P(##class(%SYS.Namespace).GetGlobalDest
        ("NAMESPACE","Ens.Mirror"),"^",2)).Mirrored
  Write ##class(SYS.Database).%OpenId($P(##class(%SYS.Namespace).GetGlobalDest
        ("NAMESPACE","Ens.AutoStart"),"^",2)).Mirrored

Important:

In this case, do not use the system-wide configuration startup setting EnsembleAutoStart to turn off auto-start, because this is in the CPF file and is not mirrored. Instead, disable auto-start for each namespace, one at a time.