Upgrading from an Earlier Release

There are three ways in which you can upgrade to Reality V15.1:

If you have a UNIX system with RealityX Release 5.0x, or Reality Release 8.1 or later, you can upgrade directly to V15.1 (see Software Upgrade).

Note: You can run two Reality versions on a system - the latest installed version and the previous version. However, you cannot run V15.1 together with V9.1 or any earlier version.
If you have a Series 18/19 system, a Windows system with Reality, or an older UNIX system, you might wish to replace your old system with a new UNIX system with Reality V15.1 (hardware upgrade). To do this, you will need to install Reality V15.1 on the new system and then transfer your database(s) from the old system to the new. For details, see the separate document Transferring a Database.
If you have a supported UNIX system with RealityX Release 3.1C or 4.1x, you can upgrade that system to V15.1, but must create new databases and transfer your data as described in the separate document Transferring a Database.

Note: To ensure that your databases operate at maximum efficiency, you should periodically save the files to tape and then restore to a new database. It can be convenient to carry this out when upgrading the Reality software.

Software Upgrade

Caution

Before starting the upgrade, make sure you have the Reality V15.1 software keys available. A complete new set of keys is essential. Also, if you are upgrading from V9.1 or earlier, these keys must be installed during the main installation - they cannot be installed separately.

Pre-Upgrade

Make sure users are logged off and prevented logging into all databases while administration work is carried out. You can use lockdbase for each database at host command level or INHIBIT-LOGONS from within each database. Only when the upgrade is complete and you want users to login in again should you enable logins.
Install the latest Reality and UNIX-Connect updates for the release you are currently running; see Installing Updates.
Backup all software key files.
Back up the following host directories:
```
/usr/realman
/etc
/usr/RCS
```
For each Reality database:
- Save to elsewhere in the database any system file items that you have customised. Files that might have been customised include SYSPROG-PL, PROCLIB, BP, SYSBP, SYSBP.MSGS, SYSPL, SYS.BASLIB, BASIC-COMPILERS and NEWAC.
- Check that all users are logged off.
- Carry out FILE-SAVE and VERIFY-SAVE.
  
  Caution
  
  These saves should be retained indefinitely; at least until the next version or release upgrade.
  
  Note: The use of Fast Save, using a Physical Backup, can only be used when moving to the same host platform byte ordering (for example, from Intel to Intel, or from SPARC to SPARC), and where source and destination versions of Reality support this feature. A standard FILE-SAVE should be used if possible. In all cases, a FILE-SAVE and a VERIFY-SAVE must be carried out.
- Save the contents of the configs host directory.
Save any communications software overlays loaded on the /realman partition.
Save any RPQ directories.
If Transaction handling is enabled, a raw log will be required:
- If the new release will replace the current release, the current raw log can be used. Save the file containing the raw log configuration information (/usr/realman/RealityVersion/bin/RawLog, where RealityVersion is the version number of the current Reality release).
- If V15.1 is to be used in parallel with the previous release, a new raw log must be created after V15.1 is installed.
Save any printer interface scripts from $REALROOT/files/interfaces to a safe location.
Save any customised configuration files, such as config and realityrc. These are located in the UNIX directory /usr/realman/RealityVersion/files (where RealityVersion is the version number of the current Reality release).

Note: Option r (Archive and remove an earlier release) on the Reality Installation Menu can be used to save the raw log configuration, printer interface scripts and customised configuration files (steps 7, 8 and 9 above).

Note: This will only be necessary if you have not set the ShareSize parameter (see Configuring a Database).

Installing the New Release

Follow the procedure described under Installation - install both Reality and UNIX-Connect (you must remove the previous version of UNIX-Connect first) and build a new executable. Select the options to include the overlays (ALL, RPL and Wordmate) as required. You can opt to make Reality V15.1 the live version immediately, or you can delay this until configuration is complete.
Install the Version key for the new release. See Installing the Software Keys.
Restore any customised configuration by editing the configuration files in the UNIX directory /usr/realman/14.2/files. You should have saved the previous configuration files in step 9 of the previous section.
Update any customised files in the /usr/realman directory.
If Transaction handling is enabled, you will need to remake the raw log:
- If this version is replacing the previous version the current raw log can be used. In this case, copy the raw log configuration file saved in step 7 of the previous section into the UNIX directory /usr/realman/14.2/bin/RawLog. Run the command mklog -rv to upgrade the raw log, then stop and restart the Reality services.
- If this release is to run in parallel with the previous release, a new raw log must be created - see Configuring Resilience Features.
Change any entries in /etc/ROUTE-FILE that contain the absolute path name, to $REALROOT or the Reality executable path. A script is provided for this purpose, called rc.OldRelease.NewRelease; for example, the script for conversion from Release 8.1D to V15.1 is called rc.8.1D.V15.1.
Change any users' .profile and .realityrc entries that contain the absolute path name, to $REALROOT or the Reality executable path.
If this is a FailSafe system, refer to the section Upgrading FailSafe .

Post-Upgrade

On each Reality database, log on to the database as SYSMAN and do the following:

Run INHIBIT-LOGONS *
If applicable, run TL-STOP to stop Transaction handling.
If upgrading from a version earlier than Reality V9.1, load the system tools with the following commands:
```
T-DEVICE 4 $REALROOT/files/upgfile.rti
ASSIGN = TAPE 4
T-REW
INSTALL
```
Follow the prompts to install the upgrade bootstrap. Then enter
```
CLEAR-ASSIGN
```
Run SYS-UPDATE, entering the release of Reality from which you are upgrading (see SYS-UPDATE).
Note: For information about any error messages displayed, see SYS-UPDATE.
Log into the database and integrate any customised changes made in SYSPROG-PL, PROCLIB, BP, SYSBP, SYSBP.MSGS, etc. (saved in Pre-upgrade step 4). Note that customised changes to NEWAC must be moved to the USER data section of that file.
Run FILE-SAVE and VERIFY-SAVE.
Start Transaction Processing, if applicable.
Run ENABLE-LOGONS *

SYS-UPDATE

This section gives details of the prompts you might see when running the SYS-UPDATE utility from TCL.

Error Messages

The first time you run SYS-UPDATE after upgrading, you may see error messages caused by underlying changes to Reality - for example, ERRMSG [2461]. These do not affect the upgrade and can be ignored. The next time you run SYS-UPDATE these initial errors should not be repeated. Any recurrent error messages should be reported to Northgate Public Services.

Machine Type

When you make a selection on the System Conversion Facility screen, the following prompt is displayed:

Restore from a different machine type? (Y/N) :

At this prompt enter Y if you are restoring from a save from a system with a different binary format; otherwise, enter N. This is to indicate to the update process that the byte order of the binary data has changed, enabling it to correctly update the system. The systems on which Reality is supported have the following binary formats:

Byte normal: Solaris, AIX.

Byte reversed: Windows, Linux.

Therefore, when restoring a save from a Solaris system onto an AIX system, for example, enter N. When restoring a save from an AIX system onto a Linux system, however, enter Y. If the platform is the same - for example, from one Solaris system to another- enter N.

DataBasic Conversion

During the SYS-UPDATE procedure, cataloged DataBasic programs in the POINTER-FILE will be upgraded if necessary. Two accounts are also populated during this procedure: BASIC.CONVERSION and UPGRADE.ACCOUNT. These two accounts are quite large and will only be required if a problem had occurred during the SYS-UPDATE. An explanation of this process is given in the separate document Transferring a Database.

If the database being upgraded is a release prior to RealityX 4.0 or ROS 7.2, the DataBasic object code will be converted. For more information, see the separate document Transferring a Database.

Changing Lower- to Upper-Case Dates

From RealityX 5.0 onwards, Reality has used mixed-case month names. If you have older applications that rely on having all upper case month names for date verification, you will have to force dates into upper case. This is described in the separate document Transferring a Database.

Upgrading FailSafe

If FailSafe is to be run between Reality V5.0 and V15.1, you must install the 5.0 FailSafe Patch (option p on the Reality Installation Menu.) For further information on upgrading a FailSafe system, refer to Resilience.

5.0 FailSafe Patch

This patch is only available for Solaris.

The patch should be installed on a 5.0 failsafe system. It enables tlmenu to operate correctly when failsafe is set up between Reality V5.0 and V15.1.

The patch does NOT require the 5.0 system to be shut down. However, tlmenu should not be running while installing the patch.

Once the binary part of the patch has been installed, all databases MUST be upgraded using the tape image provided.

The new tlmenu is not compatible with the old database PROCs.

You need the root password to install this patch.

The patch will be installed to /usr/realman/5.0{x}

Once the patch is installed, you must update each database with the TCL command

CDINSTALL $REALROOT/files/fspatch 50FSPATCH

Installing Database Overlays

If you want to install database overlays - for example, ALL, RPL, or Wordmate - you should install these by running CDINSTALL from within Reality.

Remote Tape Server

It is recommended that you reinstall the Remote Tape server on all systems that provide this service.

Running Multiple Versions of Reality

You can run different versions of Reality on the same system provided the system has enough disk space. In addition to the different versions of the Reality software, if you are using transaction handling or other resilience feature, you will require a separate raw log for each version.

Notes

Additional versions of Reality are limited to 8 concurrent users across all databases used.
You can only run two Reality versions on a system - the latest installed version and the previous version. You cannot run V15.1 together with V9.1 or any earlier version.
Each Reality database is associated with a particular version and must only be accessed when running that version.

If there is insufficient space on the filesystem containing the /usr/realman directory, you can install the new version of Reality on a different filesystem. Create a directory to hold Reality on this filesystem and define a variable called REALMAN containing the location of the additional Reality directory. For example, if your alternate filesystem is called filesys1, you might do the following:

$ cd /filesys1
$ mkdir realman
$ chown realman realman
$ REALMAN=/filesys1/realman; export REALMAN

You can now install Reality in the normal way, as described under Installation.

Once the installation has completed, edit the file /usr/realman/installed and add the line /usr/realman/14.2 if it is not already there.

Note: The file /usr/realman/installed must list all installed versions of Reality. The installation program creates a symbolic link from /usr/realman/14.2 to /filesys1/realman/14.2.

Running Reality Locally

To run a version of Reality other than the live version locally, enter the following at the command prompt:

$ REALROOT=/filesys1/realman/n.n; export REALROOT
$ PATH=$REALROOT/bin:$PATH; export PATH

where n.n is the version number of the required version. Then start the Reality services by entering:

$ runrealcd

You can then run Reality in the normal way.

Running Reality Remotely

To make a version of Reality other than the live version available remotely, log on as root and use the netadmin utility (normally found in /usr/RCS/bin) to create a Reality-type entry in the ROUTE-FILE (see UNIX-Connect System Administration) for each database associated with that version of Reality. Give the entry a unique name (normally the name of the database) and specify:

The full Reality database path.
The full REALROOT path of the required version of Reality. For example:
```
/filesys1/realman/14.2
```

You do not need to enter the path to the Reality executable.

Troubleshooting

This section describes problems you might experience when upgrading to Reality V15.1.

Message 'No Space' when starting the Reality Database Daemon (realdd)

There are two reasons why this error might occur:

Reality V9.0 and later require more shared memory than earlier versions, because item-ids have been increased in size from 98 to 240 bytes. The extra space required can be calculated as follows:
For each database, open the database configuration file (DatabasePath/configs/config) and find the value of the NUMINDEXSECTS parameter. If this is not set, it can be calculated by finding the value of the NUMDATASECTS parameter and dividing it by 2. If NUMDATASECTS is not set, its default value is 400.
The additional shared memory needed for a Reality V9.0 or later database can then be calculated by multiplying the increase in the size of an item-id (142) by the value of NUMINDEXSECTS (calculated if necessary). For example, if neither NUMINDEXSECTS nor NUMDATASECTS are set, NUMINDEXSECTS is 400 / 2 = 200, and the additional shared memory needed for this database is 142 * 200 = 28400.
Add the values for each of the databases together and increase the shared memory size configured in the kernel by this amount. Refer to your UNIX system documentation for details of how to do this.
From Reality V9.1, the default amount of shared memory available to DataBasic programs has been increased from 256 Kb to 8 Mb. You may need to configure your UNIX system to increase the maximum size of a shared memory segment by 8 Mb.

Note: On Solaris and AIX systems, you can use the appropriate NPS Customisation CD to make this change.

To	Reality
Version
Topic
Submitted by
Company
Location
Email address
Comment