Special Considerations When Upgrading

All versions.

This release allows $INCREMENT, in most cases, to function internally with only shared ownership of a data block. This enables concurrent reads of data stored in the same block and concurrent executions of $INCREMENT on global nodes stored in the same block (performed using compare-and-swap within the block). The semantics of $INCREMENT to application code remain unchanged.

Journal records for $INCREMENT operations that were performed with shared ownership may now appear out of order in the journal file (for example, the journal record for a $INCREMENT that set ^X to 100 may appear before the one setting it to 99). All $INCREMENT journal records still use the SET type, but now also feature an extended type that is either SET ($I) or SET ($I if greater). The latter value represents a $INCREMENT operation that may appear out of order and is only applied by a journal restore if the value captured in the journal record is greater than the current value of the current value of the global node. Note that the journal record a $INCREMENT results in is unpredictable, as the ability to use shared ownership is dependent on some internal conditions. $INCREMENT using a negative increment value is always done with exclusive access and is journaled with SET ($I) as its extended type.

Any custom logic that takes action using the value from a SET record may need to disambiguate between the new extended types, but only if the logic is sensitive to the order in which $INCREMENT records are encountered.

Read the journal file using SYS.Journal.Record objects to access the new ExtYpe and ExtTypeName properties.

Any custom logic that access journal records with macros in %syJrnRecord.inc can access the extended types, SET ($I) or SET ($I if greater), with $$$JRNTYPE1, which returns $$$JRNINCRYP or $$$JRNINCRIGTYP for $INCREMENT operations.

All versions.

Instances which build or synchronize InterSystems IRIS Business Intelligence cubes as part of a custom task or method.

When you invoke %BuildCube()Opens in a new tab or %SynchronizeCube()Opens in a new tab on any cube which has a relationship, the methods collate a list of all cubes which depend upon the specified cube. The methods then perform their respective update operations upon the dependent cubes in addition to the specified cube, determining the correct update sequence automatically. (Internally, the methods now invoke %BuildOneCube() and %SynchronizeOneCube() to update an individual cube.)

Because of this, custom tasks or methods which invoke these methods to build or synchronize related cubes one at a time may perform unnecessary, duplicate work upon upgrade.

To permanently address this:

1. Review your related cubes. Note which cubes depend upon others and which do not. (Dependent cubes do define a source expression for a relationship; independent cubes do not.) Refer to the output of the %DeepSee.CubeUtilsOpens in a new tab class’s %GetCubeGroups()Opens in a new tab method for guidance: if a cube has any cubes which depend upon it, the output pCubes includes a pCubes(<cubeKey>, “dependents”) array. This array identifies the dependent cubes which Business Intelligence will update automatically after the cube identified by <cubeKey> has been updated.

2. Edit your custom update tasks and methods. Remove any calls to %BuildCube() or %SynchronizeCube() for a dependent cube which immediately follow a call to %BuildCube() or %SynchronizeCube() on its independent counterpart.

All versions.

HealthShare Health Connect and InterSystems IRIS for Health users who previously migrated from Health Connect/HSAP based on the Caché/Ensemble platform.

The components.ini file in your installation directory may have a reference to the database MPRLLIB, which is no longer used by the product. This causes a misleading error message in messages.log saying that this database does not exist. This will prevent a misleading error message in messages.log saying that this database does not exist.

Comment out the reference to this database prior to the upgrade by inserting a semicolon at the start of each line.

Example:

;[MPRLLIB]
;Version=15.032.9686
[HSLIB]
Version=2018.1.0
Compatibility_HSAALIB=15.0
Compatibility_HSPILIB=14.0
Compatibility_VIEWERLIB=17.0

2022.3 and earlier.

All environments. Environments with active configuration in the Configure SSL Access dialog must perform additional steps.

The Configure SSL Access dialog in the Installer Wizard has been renamed to Configure Secure Communication. In the new dialog you must now specify an SSL/TLS Configuration in order to make the secure communication settings Active. A default value of HS.Secure.Demo is entered for the SSL/TLS Configuration setting upon upgrade.

If you had an active configuration in the Configure SSL Access dialog before you upgraded, identify the correct SSL/TLS configuration for your instance in the new Configure Secure Communication dialog after you complete your upgrade but before you reactivate your namespaces.

2022.1.5 and earlier.

Instances running on Windows.

The irisstop.exe file is removed upon upgrade. Without this file, you cannot stop the InterSystems IRIS for Health instance using any internal means. For example, the iris stop command does not work.

To permanently address this problem:

1. Obtain a copy of the irisstop.exe file. The easiest way to do this is to copy the file from the instance before upgrading.

   • You can copy the irisstop.exe file from any 2019.1 or newer instance.

   • If you do not have a suitable instance, you can install a temporary instance of InterSystems IRIS for Health (including version 2024.2) and copy the irisstop.exe file from it.

   • By default, the file is located in <install-dir>/InterSystems/<instance-name>/bin/.

2. Proceed with your upgrade as usual.

3. After upgrading, add the copy of the irisstop.exe file to the upgraded instance.

4. On the upgraded instance, execute the file: <install-dir>/InterSystems/<instance-name>/bin/iristray.exe.

5. Open the InterSystems IRIS for Health launcher menu for the upgraded instance, then click Exit.

6. Using the Windows Start menu, launch the instance by clicking the application: Launcher [<instance-name>].

Before performing the above steps, you can still stop the InterSystems IRIS for Health instance manually, using the Services Windows Administrative Tool. Open Services and right-click on the InterSystems IRIS for Health Controller for <instance-name> service, then click Stop.

2022.1.1 and earlier.

Environments with existing classes containing a property with MAXLEN="".

If an existing class contains a property with MAXLEN="", SQL queries on tables based on that class return an error after upgrading.

Recompile the affected classes.

2022.1.1 — 2021.1.0

Environments where all external language gateway configurations have been removed.

You may encounter validation errors during the upgrade process.

To prevent these errors, add a single gateway configuration of type Remote that points to the local gateway with an arbitrary port number. For example, you can set the Server Name / IP Address to 127.0.0.1 and set the Port to 1, naming it ForUpgrade. This can be done at any point prior to upgrading and will not impact normal system operation. This configuration can be deleted after the upgrade is completed.

2019.2 and earlier.

Environments using a durable %SYS from a 2019.2 or earlier release.

In this release, the distribution container has a nonroot default user. This improves the security of your container. Some file ownerships in the host’s durable directory must be changed before running this version of InterSystems IRIS. If you do not make these changes, the container will encounter an error starting InterSystems IRIS.

Please contact your InterSystems sales engineer or the InterSystems Worldwide Response CenterOpens in a new tab for instructions on changing the relevant file ownerships.