Upgrade an Instance on Windows

Perform Attended Upgrade

The following steps outline how to perform an attended upgrade of your instance on a Windows system. Before beginning, make sure you have followed any pre-upgrade steps. If you are upgrading a mirrored system or ECP configurations, review the respective documentation. You can also perform an unattended installation using the command line.

Step 1: Confirm Prerequisites

Confirm that you have completed all necessary pre-upgrade steps.

If you are upgrading a mirrored system, review Upgrading a Mirror for specific details on upgrading mirrored systems.

If you are upgrading an ECP configuration, review Upgrading ECP Configurations for specific details on upgrading ECP configurations.

If you are using a manifest as part of your upgrade process, see the instructions in Creating and Using an Installation Manifest before performing the standard installation steps.

Step 2: Shut Down the Instance

Prior to beginning an upgrade of an instance, it is essential that the instance be shut down cleanly. To verify that the shutdown was clean, examine the messages.log file after the shutdown finishes. If the log contains entries similar to the following, then the shutdown was clean:

...
05/03/19-14:24:13:234 (5204) 0 Journal restore not required at next startup
05/03/19-14:24:13:234 (5204) 0 Transaction rollback not required at next startup
...

If these entries are not present, the instance did not shut down cleanly. Please contact the InterSystems Worldwide Response CenterOpens in a new tab before proceeding with the upgrade.

Step 3: Begin Installation

Double-click the installer file, for example, IRIS-win_x64.exe. The installer displays a list of all existing instances on the host. Select the name of the instance you want to upgrade and click OK.

Step 4: Add New License Key

When prompted for a license key, click License and browse for the new iris.key file. If the installer detects a new key file in the install-dir/mgr directory, it proceeds without prompting you for the license key.

Step 5: Configure Web Server

If a local Microsoft Internet Information Services (IIS) web server is detected, the Local Web Server dialog box lets you select whether or not the installer should automatically configure the web server for this instance. If you choose to not have the installer configure your web server automatically, you will have to configure it manually after the installation finishes. If a local web server is not detected, the dialog box instead asks if you want to Abort the installation or Continue the installation without Web Gateway. If you choose to continue anyway, you will have to configure the web server manually after the installation finishes.

Step 6: Run the Upgrade

After the installer validates the license key and you’ve selected all other upgrade options, click Upgrade. The system runs the upgrade process. After the upgrade is completed, click Finish.

Step 7: Examine Logs for Errors

Examine messages.log, iboot.log, and ensinstall.log in the install-dir\mgr directory for any errors. If any fatal error is found, correct the error, and then run the installer again.

If your operating system is configured to use large memory pages, check the startup messages to make sure shared memory is being allocated in accordance with these settings. If you see a message similar to the following, reboot your server to avoid an out-of-memory situation.

Failed to allocate 592MB shared memory using large pages.  Switching to small pages.

Unattended Upgrade or Reinstall

In addition to installing a new instance, the installer can be called on an existing installed instance. To do so, you must use the /instance flag to specify the name of the target existing instance. The action the installer takes depends on the version of the installation file compared to the version of the instance, as follows:

• If the installation file is the same version as the target installed instance, the installer reinstalls (repairs) the instance.

• If the installation file is a later version than the target installed instance, the installer upgrades the instance to the new version.

For example, to run an unattended upgrade of an installed instance IRISB that is an earlier version than the installation file, use the following:

C:\downloads\IRIS-2019.1.0.516.0-win_x64.exe /instance IRISB /qn

You can reinstall one or more specific features, as listed in the Custom-Installable Features table, by specifying the target instance and using the REINSTALL property (see the Command-Line Properties table). For example, to reinstall Studio for the installed instance IRISB, you can use the following command (assuming the installation file and IRISB are the same version):

C:\downloads\IRIS-2018.1.0.508.0-win_x64.exe /instance IRISB /qn REINSTALL=studio