Reality on UNIX
Installation Guide
This Installation Guide describes installation of Reality on a UNIX system.
Before starting the installation or upgrade, ensure that you have the necessary prerequisitesand information you must supply.
If upgrading, read Upgrading from an Earlier Release.
Reality is a software environment supporting multiple databases on a UNIX or Windows host. For information about the extensive capabilities of the Reality database management system, see the Introduction to Reality in the online documentation.
Transaction Handling is a feature that maintains the consistency of the database by keeping defined transactions (sets of updates) intact. Rapid Recovery File System, Transaction Logging, Shadow Database, and FailSafe are features offering further levels of resilience. Transaction Logging and Rapid Recovery require a single ‘raw log’, per Reality version being run at the same time, to be configured. Further resilience features require at least one clean log per database to be configured. Minimum configuration is described in this guide, with additional information in resilience reference material.
Comprehensive communications facilities enable communications between a Reality database environment and another Reality database, or a host system environment (UNIX or Windows). UNIX-Connect forms an integral part of the Reality software and must be installed on a UNIX host along with the base Reality software.
Reality is supplied with comprehensive on-line documentation that you can view in a Web browser.
There is one installation CD containing the PDS History Tool, Reality, the online documentation and all of the Reality client and server components. Refer to the Reality Release Information for details.
The PDS History Tool must always be installed first and will be installed automatically if not already present.
For a description of how to install the client components and the Reality remote tape server, please refer to the Reality Client Components Installation Guide.
· Refer to the Reality Release Information for details of supported hardware and operating systems.
· 128Mb memory minimum (512Mb recommended, 2-6Mb per Reality user)
· 500 Mb of available disk space to accommodate setup (actual hard disk used once installed will be between 220Mb and about 350Mb, depending on the system components installed).
· 'realman' UNIX user-id (see Set up Before Installation).
· Korn shell.
· Perl - this is normally supplied with the operating system.
· ‘pam’ libraries (for Linux only).
· UNIX-Connect for networking (supplied on Reality Solutions CD).
· C compiler and debugger. These are supplied with Linux. On Solaris, if a C compiler is not available you can install the GNU C Compiler from the Northgate Solaris Customisation CD. For AIX, refer to Compiler and Debugger.
· The Northgate Customisation program appropriate to your UNIX system. For AIX, customisation programs are provided on the Reality Solutions CD, while a separate CD is available for Solaris. There is no customisation program for Linux.
'rosi' UNIX user-id with a home directory on a file system with at least 25 Mbytes free.
The on-line documentation can be installed on a web or file server, or on your local system. On Windows systems, it can also be viewed from the Reality CD.
To view the on-line documentation you will require one of the following web browsers:
· Internet
Explorer 6.0 or 7.0 (PC only).
-or-
· Mozilla Firefox 2.0 (PC or UNIX).
Note: You can also view the on-line documentation on some earlier versions of the above browsers and on some other types of browser. A message will warn you that your browser is not fully supported.
The table below lists the information you will need when installing Reality. You can fill in the second column of the table so that you have the information to hand during the installation process (print out this page if you are viewing it on-line).
Contact Northgate for software keys. These are normally supplied in a keyfile (held anywhere on the system) and loaded from that file or you can type them in during the installation procedure.
Note: The serial number key is only valid for installation on the specified date and for the two days following.
|
Name and location of keyfile. |
|
|
Serial number key for date of software install. |
|
|
Customer ID. |
|
|
Version number key for Reality V14.0. |
|
|
User Licences key (see Note 1). |
|
|
Despooler Licences key (optional). |
|
|
FailSafe or Shadow key (optional). |
|
|
Disaster Recovery key (optional) |
|
|
root password. |
|
|
realman password. |
|
|
rosi password. |
|
|
Location for the on-line documentation (see Note 2). |
|
Refer to the topic Licencesfor more information about user licences and other software keys.
Notes:
1. If you intend using Database Isolation, you will need a User Licences key for each instance of Reality.
2. If you already have a Web server installed, this can be the document root directory for your Web server. Alternatively, the documentation can be installed in the default location and accessed through the Reality mini web server, which is designed to handle simple document requests with no risk to system security. See Installing the On-line Documentation.
When you purchase your hardware from Northgate, the system is configured for Reality according to your requirements; for example, the number of users and the resilience options will be defined. If you purchase your hardware from an alternative vendor, you need to carry out the procedures described in this section.
This section gives some details of the requirements of UNIX to support the Reality product. It does not, however, deal with the performance related configuration parameters of UNIX.
On the host system there must be a user-id calledrealman (Reality manager). If one is not present, the system administrator should create one. The Reality software will be installed in the realman user’s home directory, so it must be on a partition with at least 250Mb of free space.
A soft link to the realman home directory must be set up in /usr by the administrator:
ln -s /filesystem/realman /usr/realman
where filesystem is the partition holding the realman home directory. Root privileges are required to set up this link.
The host system must also have a user-id called rosi. This must have a home directory on a partition with at least 25Mb of free space.
Note: On Linux systems, ‘group’ and ‘other’ need read, write and execute permissions to be set up on the home directories for the realman and rosi user-ids.
Reality requires tape device drivers to have certain characteristics for successful operation. The name of the device driver is not important, because Reality cross references the device number as used in the ASSIGN statement with the UNIX device name as detailed in Configuration Parameters for Database. The characteristics required are that the device needs to be a no-rewind device and to run the Berkeley tape driver (if available). Some examples are:
· Solaris -/dev/rmt/0mbn
· AIX -/dev/rmt0.1
· Linux -/dev/nst0
The Users’ Reference: Administration gives more detailed examples.
Reality uses the UNIX terminal independence mechanism, terminfo. A set of terminfo definitions for use with Northgate PRISM terminals is supplied on the Northgate Customisation CD.
Check that the file /etc/hosts includes an entry for the local system; that is, an entry that specifies the IP address of the system with the name returned by the command uname –n. On Linux systems, the host name must be fully qualified. For example:
152.114.226.12 aharries1 aharries1.northgate-is.com
The Northgate Solaris Customisation CD configures Solaris to run Reality. After running the configuration program, you will need to build a new kernel by rebooting the system.
Reality uses shared memory to exchange data between processes and to cache common data used by many processes. Solaris systems default to a small limit on shared memory and this limit will need to be raised in order to run a Reality database. The actual amount of shared memory required is dependant on the number of users and the size of the application. A good starting point is to set the shared memory limit to 16 Mbytes (you can make this change by using the Northgate Solaris Customisation CD).
On Solaris, if you are going to install UNIX-Connect and you also want to use any OSI transport services or X.25, you must install these first.
The Northgate AIX Customisation programconfigures AIX to run Reality. You will also need to configure the system as described below.
On AIX installations, the file system on which Reality will be installed (typically under /usr/realman) must not have the ‘nosuid’ mount option set. You can use the smit utility to change the characteristics of the file system concerned.
On AIX, if you have no licensed complier and debugger, those on the AIX Tools CD can be used. Refer to the README file in the base directory on AIX Tools CD for more information.
No customisation program is available for Linux. Configure the system as follows.
On Linux, the Korn shell needed by Reality is not installed by default. It can be loaded as follows:
1. Insert Red Hat Linux CD 2 into the CD drive and, if necessary, mount it.
2. From the KDE Desktop run System/Package Manager.
3. Select the new tab and then search for “pdksh”.
4. When found, tag the package and install it.
On Linux, by default only root can access tape devices. To make them available to all users, change the permissions for the relevant device nodes (use chmod 666 deviceNode).
Remote user access to a Reality database uses incoming telnet. On Red Hat Linux, only outgoing telnet is configured. Incoming telnet can be enabled from the KDE Desktop by using KDE Control Panel/Services Configuration and selecting telnet.
For transaction handling and rapid recovery, you will need a raw log, but no clean logs. It is recommended that this is held on a separate disk in its own partition. Alternatively, you can use a file as the raw log - this must be created after you install Reality.
For transaction logging, shadow database and FailSafe, you will need a single raw log, used by all databases on the system, plus a clean log directory for each database. It is recommended that you allocate a separate disk for these logs, with one partition for the raw log and a second for the clean logs. Using a file as a raw log is not recommended for transaction logging and shadow database.
Note: Linux does not support raw disk access. For the raw log, use a block mode partition or a file instead.
The disk used for the raw and clean logs must be configured as follows:
· There must be no swap partitions - if there are any, they should be disabled and their use prevented in the future.
· There must be no virtual partitions. If there are any, they should be unmounted, disabled and their use prevented in the future.
· There must be no existing user file systems.
Carry out the following steps to create raw log and clean log partitions.
1. Check all partitions defined for the disk and ensure they are freed off as above.
2. Repartition the disk to define raw log and clean log partitions. There are no restrictions on the sizes of these partitions.
Caution
You should be extremely careful to name the partitions correctly; otherwise, another valid file system may be corrupted.
3. Make the mount point for the clean log file system.
4. Set general read/write permissions
To install Reality on a UNIX host, you must do the following:
1. Run the Reality installation program (see Preliminary)
4. Build the Reality Executable.
5. Install the On-line Documentation (optional).
1. Log in using the root/superuser user-id.
2. Confirm that the partition (for example, /realman) has enough space for the new release. You will need at least 220Mb.
3. Load the Reality Solutions CD into the drive.
4. Mount the CD:
· On Solaris the CD is normally automatically mounted to the /cdrom/cdrom0 directory.
Note: If the CD is not automatically mounted, it can be mounted manually using:
mount –F hsfs –r /dev/sr0 /cdrom
· On other systems, create a mount point using:
mkdir –p /mnt/cdrom
then:
q On AIX manually mount the device 0 CD using:
mount -vcdrfs -oro /dev/cd0 /mnt/cdrom
q On Linux, manually mount the CD using:
mount /dev/cdrom /mnt/cdrom
5. Change directory to the mount point:
cd /cdrom/cdrom0 (Solaris)
cd /mnt/cdrom (other systems)
6. If you are installing Reality on AIX, run the customisation program by entering:
./custom/setup
7. Run the installation procedure by entering:
ksh ./setup
8. The Reality licence agreement is displayed. Press the space bar to move through the agreement page by page, or q to skip to the end. You will then be asked if you accept the licence - you must answer y to continue the installation.
A menu similar to the following is then displayed:
9. From the top level Installation Menu, select option a) Install Reality:. A menu similar to the following is displayed.
Reality Installation Menu
Please select one of
a) Install base software
u) Install UNIX-CONNECT
f) Install common files
m) Build this release
r) Archive and remove an earlier release
p) Install 5.0 Failsafe patch
l) List image components
v) List image versions
q) Quit
?
10. Select option a. You will be prompted to enter your name or initials for the history file record.
11. If you are upgrading from a previous version, you will be asked if you want to overwrite the previous version. If you answer Y, you will be asked if you want to save the previous version.
Note: The previous version will be saved in cpio format.
12. The installation will then proceed (this might take several minutes). Follow the prompts that appear.
13. When the installation is complete you will be asked if you want to install the Reality keys.
Both the Reality system itself and some of its features are targeted. This means that you must obtain a date-sensitive Serial Number Key, and a set of feature keys that must include a Version Key and User Licences Key,from the Northgate commercial department for each system on which Reality and any targeted features are being installed (see Information You Must Supply). The feature keys are supplied in a “keyfile”.
You can install the keys at this point, as part of the main installation (strongly recommended), or as part of the set-up after installation.
Note: If you are upgrading from a release prior to V10.0, you must install the keys at this point; you cannot install them later.
If you prefer, you can choose an evaluation version. You do not need any software keys for this option, but will be limited to 3 concurrent users.
· If you already have the necessary keys, or intend using the evaluation version, enter y. You will then be asked if you want to install the evaluation version – enter y or n as appropriate. Then follow the prompts that appear.
· If you do not have the keys available, enter n. Refer to Installing the Software Keys for how to install the keys at a later time.
Notes:
· If your Serial Number Key was supplied separately from the other keys (that is, not in the keyfile), enter this first and then load the remaining keys from the keyfile.
· If you wish to use the evaluation version to carry out performance/stress testing, you can increase the number of users for a 30-day period by registering with Northgate via the Northgate web site.
14. Enter option u to install UNIX-Connect.
Note: If upgrading, you must remove the previous version of UNIX-Connect first.
15. Enter the rosi password if prompted. A menu similar to the following is displayed:
UNIX-Connect CD-ROM Component Installation Utility
Current CD-ROM: /cdimage/5/uxc
Version: V1.4.1.2
Please select one of
a) Install base
b) Install service pack
c) Install a fix
m) Rebuild the installed
version
p) What is the installed
version ?
r) Remove the installed
version
i) What is the current
userid ?
u) Switch userid
v) List image versions
t) Run the installation
check
k) Run a shell
q) Quit
?
16. Select option a. You may be prompted to enter the root password in order to run the install script.
17. When prompted to confirm that you want to install UNIX-Connect enter y.
18. An onsite link of UNIX-Connect is run automatically. When this is complete, press RETURN to return to the UNIX-Connect menu, and then enter q to return to the Reality Installation Menu. Then enter q again to return to the top level Installation Menu.
19. From the top level Installation Menu, select option a) Install Reality:. Then select option m to build the release.
20. The modules that will be excluded from the build are listed and you are asked for confirmation before continuing. If you want to include any overlays, RPQs or fixes, answer n and follow the prompts.
21. When you enter y in response to the confirmation prompt, the build completes.
Note: If any error messages are displayed during the build process, take a note of them and contact Northgate support.
22. If you have not yet installed the software keys, you will be prompted to enter them.
23. When the build completes, you will be asked if you want to start the Reality central daemon by running realstart.
· Enter y to start the Reality central daemon.
· If you have not installed the Reality keys, enter n. Refer to Installing the Software Keys for how to install the keys at a later time. Once you have installed the keys, run realstart as described in the section Running realstart.
24. If you are upgrading from a previous version, you will then be prompted:
Rawlog
currently pointed to by /usr/realman/n.n/bin/Rawlog
Continue
y/n [n]
· If you intend to continue using your existing raw log with the new version of Reality, enter y.
· If you enter n, you will need to create a new raw log (see Configuring a Log Disk).
25. If you are building a new installation of Reality, you will be asked if you want to make the new version LIVE. (If you do not enter y here, you can edit the file /usr/realman/installed to make the new version LIVE at a later date.)
Note: The LIVE version of Reality is the version that is used automatically when a user logs on to the UNIX host. Non-LIVE versions require special actions, after host logon, in order to use them.
To install the on-line documentation, select option f, Install On-line Documentation, from the top-level installation menu. When prompted, enter the required location - the documentation will be placed in the subfolder onlinedocs relative to the install location you specify.
It is recommended that you install the Reality documentation on a Web Server, though it can also be installed on a file server or on individual PCs (for details, refer to the Reality on Windows, Installation Guide). In all cases, the file system must support long file names.
Note: If you do not have a suitable web server, you can install the documentation on the Reality server in /usr/realman/html and access it via the Reality mini web server. The mini web server listens on port 3080 (see below).
The Reality documentation can be viewed in a web browser (see On-line Documentation for details of supported browsers).
Note: PDF topics are displayed in a separate browser window. To view these topics you must configure your browser's popup blocker feature to allow popups from the location where you have installed the Reality documentation.
If you install the documentation in your web server’s document root, your users will be able to access it via a URL such as:
http://systemname/onlinedocs/default.htm.
If you are using the Reality mini web server, they will need to include the port number in the URL; that is, use:
http://systemname:3080/onlinedocs/default.htm.
If you do not use a web server, you will have to open the file default.htm in the folder installLocation/onlinedocs.
You will normally install the system serial number and software keys during the installation process.
Note: If you are upgrading from a release prior to V10.0, you must install software keys during the main installation – you cannot enter them subsequently.
If the key file was not available at that time, the keys can be installed by running:
{$REALROOT/bin/}installkeys keyFile
(Entering the full path should be unnecessary, because a successful installation adds $REALROOT/bin/ to the executable path.)
Caution
If the root partition of the system or the /etc directory are reloaded for any reason, the installed serial number will become invalid, and will have to be re-installed from a new key file.
Before you can start using Reality you must start the Reality central daemon. If you did not run realstart when building the Reality executable, you can do this as follows:
1. Change user to root.
su
password:
2. Ensure that the environment variable REALROOT is defined and exported.
REALROOT=/usr/realman/14.0
export REALROOT
3. Run the realstart script:
cd $REALROOT/bin
./realstart
...
... (A commentary will be given
as various tasks are completed by realstart)
...
DAEMON nn WRITING TO realman/realman/14.0/files/daemon.log
exit
The new Reality is now installed (and LIVE if you accepted that option).
Before you can start using Reality you must create at least one database. Different types of database are available (refer to Types of Database) – this section shows you how to create a partition database using files on a single disk partition so that you can start using Reality. You can create this type of database at any convenient location in the UNIX file system.
To create a Reality database, log on to UNIX, change to the directory that will hold the database and then run the mkdbase command. For a database on a single partition, include the –S option to specify the size of the database:
mkdbase -S size –N databaseName
Where size is the size of the database in Mbytes (M suffix) or Gigabytes (G suffix). For example:
mkdbase -S 100M –N pdbase
creates a 100Mbyte database called pdbase.
Notes:
1. By default, a new database consists of 10 equal-sized host files. It can easily be enlarged by adding more files.
2. When you create a new database, a Reality user-id is created for the database owner (the UNIX user who created it). This user-id should be used when connecting to the database for administration purposes. The database owner’s user-id does not initially have a password.
When a database is created, it is locked to all users except the database owner. It can be unlocked with the unlockdbase host command or the TCL command ENABLE-LOGONS.
When you create a new database, a Reality user-id with SYSMAN privileges is created for the database owner (the Windows user who created it). The owner of the database can log on even when the database is locked, without specifying a user-id. If you need to administer the database, you should log on as the database owner.
Note: The database owner’s user-id does not initially have a password.
To start reality and log on as the database owner, use the reality command, specifying the database required. For example, to log on to the database dbase0, enter:
reality dbase0
Reality V14.0 can be configured to suit particular user requirements by using the following configuration parameters. The parameters required should be defined in the config file /usr/realman/14.0/files/config if they are applicable to all new databases. Otherwise change the config file for the database concerned (DatabasePath/configs/config). Missing parameters are given their default value.
Note: Changes to a specific database config file only take effect when the daemon for the database is restarted. Hence, all users should be logged off and the daemon shut down using the command:
killreal -d database
|
Parameter |
Default Value |
Purpose |
|
MaxPortNum |
400 |
MaxPortNum defines the maximum real port number which may connect to this database. A real port is one that is referenced in the devices file. Such ports are always allocated the same device ID. Reality will map such port identifiers, in a fixed way, to real port numbers. |
|
NumPseudoPorts |
400 |
NumPseudoPorts defines the number of pseudo ports that may connect to this database. A pseudo port is one which made its connection to the host dynamically, for instance by using the rlogin or telnet protocol or via some form of network server. Pseudo ports are also always used for TIPHs. Pseudo ports are allocated device IDs dynamically. Reality will map such port identifiers to the next available pseudo port. |
|
NumConnections |
128 |
NumConnections is the maximum number of connections that may be active on the database at any one time. This includes TIPHs, despoolers, etc. |
|
DateFormat |
International |
DateFormat defines the format in which the days' date will be represented in certain English expressions and DATA/BASIC OCONV statements. · "Standard" for mm/dd/yy · "International" for dd/mm/yy |
|
NumItemLocks |
NumConnections*3 |
NumItemLocks defines the maximum number of item locks that can be held on the database at any one time. |
|
NumDataSects |
400 |
NumDataSects defines the maximum number of data sections that may be OPEN at any one time. |
|
NumIndexSects |
50 |
NumIndexSects defines the maximum number of index sections that may be OPEN at any one time. |
|
ShareSize |
8000 |
ShareSize defines the size of memory available for shared DataBasic programs. The default is 8000Kb. Details of assessing the ShareSize and ShareModulo requirements are given in the User’s Reference: Administration. |
|
ShareModulo |
101 |
ShareModulo defines the modulo of the shared item hash table. |
|
HashType |
|
If HashType is set to 1 or omitted, any new database created will use the old hashing algorithm. If HashType set to 2, the new hashing algorithm will be used. |
|
Parameter |
Default Value |
Purpose |
|
TapeNum |
2 |
TapeNum defines the number of tape drives on the database, named Tape1, Tape2, etc. |
|
TapeDevTypen |
3 |
TapeDevType1, TapeDevType2,
etc define the type of tape drive for TAPE1, TAPE2, etc, respectively. The types
currently supported are: |
|
TapeDevSizen |
|
TapeDevSize1, TapeDevSize2, etc defines the tape capacity size of the tape used in dbsave. Still relevant with virtual tape drives. |
|
Tapen |
As defined in the supplied config file |
Associates a tape number with a UNIX device name. |
|
0 |
Specifies the default compression level (0 to 9) for tape images created from this database. 0 is no compression (fastest); 9 is maximum compression (slowest). Recommended level: 2. |
The Tapen entries define the default devices for tape attachments without density specifications. For example, the TCL command T-ATT 2 will use Tape2. Additional entries in the form Tapen:density can be used to define different devices. For example, the command T-ATT 1 DEN = 6250 would require an entry Tape1:6250=/dev/rmt/0cbn.
How to configure tape devices is described in greater detail in the User’s Reference: Administration.
For all resilience features - Transaction Handling, Rapid Recovery, Transaction Logging, Shadow Database or FailSafe – you must use the mklog command to create the raw log.
When you have created the rawlog, for all resilience features other than Shadow Database, you should then refer to the Resilience section for details of how to complete the configuration using tlmenu. If you are running Shadow Database, you should initially refer to the topic Shadow Database later in this section.
· If you intend using a dedicated partition for the raw log, you should have already created this - refer to Configuring a Log Disk. Now log in as root and use the mklog command to create the raw log. For example:
# mklog –r /dev/rdsk/ct01d0s1
· If you intend using a file as your raw log, log in as root and use the mklog command to create a raw log file. For example:
# $REALROOT/bin/mklog -r -ts10 /user5/rawlog
This command creates a 10 MB file /user5/rawlog, to be used as the raw log.
Note: Linux does not support raw disk access. For the raw log, use a block mode partition or a file instead.
When you have run mklog, stop and restart the central Reality daemon:
# killreal
#
realstart
Shadow Database is an optional feature that, when installed on a standalone host platform, provides all the functionality of Transaction Logging for data security and resilience, but in addition maintains a copy of the database in a separate disk partition that shadows the live database.
This section covers how to create the first shadow, pair0, using mount points /real0 (primary) and /real1 (secondary). A second shadow pair would be pair1 with mounts /real2 and /real3, etc.
1. Log on as superuser.
2. Create the directories to act as mount points for the primary and secondary databases.
# mkdir /real0
# mkdir
/real1
3. Change the ownership of the database directories. For example:
# cd /real0
# chown
dbaseowner .
# chgrp
other .
# cd
/real1
# chown
dbaseowner .
# chgrp
other .
where dbaseowner is the user-id of the intended database owner.
4. Logon as the database owner.
5. Create the databases. For example:
$ mkdbase /real0/pdbase1
$
mkdbase /real1/pdbase1
6. Refer to the Resilience section for details of how to complete the configuration of shadow database using tlmenu.
If you did not accept the option to make the new version of Reality live on installation, you can do so now by editing the /usr/realman/installed file to show a space and then the word LIVE (all caps) after the entry for the new version, and removing the word LIVE against any other version.
Reality records error details in various error logs depending on what class of error has occurred. Below is a list of useful log files for diagnosing problems when starting and running Reality on UNIX:
$REALROOT/files/daemon.log
Records major events and errors with Reality daemons and Reality processes.
/var/adm/RCS/RCS_SESS_LOG
Records incoming and outgoing connections both successful and failed.
/var/adm/RCS/RCS_EVENT_LOG
Records other SMANAGER (Reality session manager) activity.
Reality error numbers can be converted into human readable messages by using the perror command from the UNIX shell; for example:
$ perror
2004
Error 2004: RFE_NOITEM Item does not exist
From Reality TCL you can use:
: sys perror 2004
Below is an example of a message logged in the daemon log.
Oct 30 07:55:20 #2240 tlrestore WARNING: Image 000000E4 Result (2027) File section already exists
This message indicates that an attempt was made by the ‘tlrestore’ process (part of Reality resilience) to create a file, which already exists on the database. Running perror 2027 would report:
Error 2027: RFE_SECTEXISTS File section already exists.
Note: More verbose error logging can be activated by running killreal –l 6 from the UNIX shell prompt.
Below is an example of information logged in the session log:
Session :11 Thu, 21 Nov 2002 15:14:29
IC
System :demodb, User Id :SYSMAN,
Account :SYSMAN, Server :SQLSRVR
Client Id :, PLID
:INET-207.238.117.133-9
Class :Process, Flags :0, Timeout 1
Session
:11 Thu, 21 Nov 2002 15:14:29
Session Terminated by Server Rejection
Database Initialisation Failed 2008
Running perror 2008 would report:
Error 2008: RFE_INVACCPASS Invalid logon attempt
There are three ways in which you can upgrade to Reality V14.0:
· If you have a UNIX system with RealityX Release 5.0x, or Reality Release 8.1 or later, you can upgrade directly to V14.0 (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 V14.0 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 V14.0 (hardware upgrade). To do this, you will need to install Reality V14.0 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 V14.0, 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.
Before starting the upgrade, make sure you have the Reality V14.0 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.
1. 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.
2. Save any communications software overlays loaded on the /realman partition.
3. Save any RPQ directories.
4. 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 V14.0 is to be used in parallel with the previous release, a new raw log must be created after V14.0 is installed.
5. Save any printer interface scripts from $REALROOT/files/interfaces to a safe location.
6. 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 4, 5 and 6 above).
7. From Reality V9.1, the default amount of shared memory available to DataBasic programs has been increased from 256Kb to 8Mb. If you are running Reality on Solaris, you may need to configure your system to increase the maximum size of a shared memory segment by 8Mb. You can use the Northgate Customisation CD to make this change.
Note: This will only be necessary if you have not set the ShareSize parameter (see Configuration Parameters for Database).
1. Follow the procedure described in the Installation section - 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 V14.0 the live version immediately, or you can delay this until configuration is complete.
2. Install the Version key for the new release. See Installing the Software Keys.
3. Restore any customised configuration by editing the configuration files in the UNIX directory /usr/realman/14.0/files. You should have saved the previous configuration files in step 6 of the previous section.
4. Update any customised files in the /usr/realman directory.
5. 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 4 of the previous section into the UNIX directory /usr/realman/14.0/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.
6. 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 V14.0 is called rc.8.1D.14.0.
7. Change any users’ .profile and .realityrc entries that contain the absolute path name, to $REALROOT or the Reality executable path.
8. If this is a FailSafe system, refer to the section Upgrading FailSafe.
On each Reality database:
1. Log on to the database as SYSMAN and enter the following commands:
2. INHIBIT-LOGONS *
3. If applicable, run TL-STOP to stop Transaction handling.
4. If upgrading from a version earlier than Reality V9.1, load the system tools. Enter 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
5. Run SYS-UPDATE, entering the release of Reality from which you are upgrading (see SYS-UPDATE Details).
6. Log into the database and integrate any customised changes made in SYSPROG-PL, PROCLIB, BP, SYSBP, SYSBP.MSGS, etc. (saved in Pre-upgrade step 1). Note that customised changes to NEWAC must be moved to the USER data section of that file.
7. FILE-SAVE and VERIFY-SAVE.
8. Start Transaction Processing, if applicable.
9. ENABLE-LOGONS *
This section gives details of the prompts you might see when running the SYS-UPDATE utility from TCL.
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.
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.
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.
If FailSafe is to be run between Reality V5.0 and V14.0, you must install the 5.0 FailSafe Patch (option p on the Reality Installation Menu.) For further information on upgrading a FailSafe system, please refer to the Resilience section.
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 V14.0.
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
If you want to install database overlays – for example, ALL, RPL, or Wordmate – you should install these by running CDINSTALL from within Reality.
It is recommended that you reinstall the Remote Tape server on all systems that provide this service.
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:
1. Additional versions of Reality are limited to 8 concurrent users across all databases used.
2. You can only run two Reality versions on a system – the latest installed version and the previous version. You cannot run V14.0 together with V9.1 or any earlier version.
If there is insufficient space on the filesystem containing the /usr/realman directory (see Prerequisites), 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 (see Installation).
Once the installation has completed, edit the file /usr/realman/installed and add the line /usr/realman/14.0 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.0 to /filesys1/realman/14.0.
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.
Note: Each Reality database is associated with a particular version and must only be accessed when running that version. Having carried out the procedure above, you will need to use mkdbase to create a new database. You will then have to specify this database when starting Reality.
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 The ROUTE-FILE in 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.0
You do not need to enter the path to the Reality executable.
This section describes problems you might experience when upgrading to Reality V14.0.
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 256Kb to 8Mb. You may need to configure your UNIX system to increase the maximum size of a shared memory segment by 8Mb.
Note: On Solaris and AIX systems, you can use the appropriate Northgate Customisation CD to make this change.
Updates to Reality are made available on the Northgate web site in the Reality Knowledge Base (http://www.northgate-reality.com/support.php). In the list on the left of the page, click the V14.0 support link to see a list of relevant updates. Click the update you require and download the attachment file.
Other support information is available on the Reality web pages (http://www.northgate-is.com/reality/).
Before downloading, please read the documents Description of Recommended Updatesand Installation Info Filefor details of the contents of the updates and any additional configuration that might be necessary.
Caution
Before you install an update, ensure that you have an up-to-date backup of your existing data.
1. Download the required update from the Northgate web site to your UNIX system. It is recommended that you create an updates subdirectory in the realman user’s home directory and save the update there.
Note: If you have several updates to install, save them all in the same directory.
2. Ensure that no users are logged into Reality. If necessary use the LOGOFF command.
3. Login to UNIX as root.
4. Execute the command:
$REALROOT/bin/killreal
to shut down the Reality daemons.
5. Switch UNIX user-id to realman.
6. Run the command:
install_fix update
where update is the full path of the file containing the downloaded update.
For example, for update V14.0.0.0001 saved in the directory /usr/realman/updates the command would be:
install_fix /usr/realman/updates/V14.0.0.0001.tar
Note: If you have several updates to install, run install_fix with the –a option and specify only the path of the directory containing the updates. For example:
install_fix -a /usr/realman/updates
7. install_fix will ask you for your name or initials. Once you have supplied this information, the process will display a description of the update and ask you to confirm installation. If you are installing several updates you will be asked to confirm each update in turn.
Note: If the process detects that the current version of the update is already loaded, a message is displayed and the update is not installed.
If necessary, the installation process then rebuilds Reality and/or informs you that you should logon to each database to complete the installation.
8. Log into UNIX as root and run the command:
$REALROOT/bin/realstart
to restart the Reality daemons.
9. If your were informed that you need to log onto each database to complete the operation, log on to each database as the database owner and ensure that you are logged on to the SYSMAN account. Then from TCL run:
DBUPDATE updateNumber
where updateNumber is the number of the update you have installed (for example, 14.0.0.0001) or * for all updates. Follow the on-screen prompts.