Reality Software

The realman Directory

The Reality software, located in the realman directory (/usr/realman on UNIX; c:\realman on Windows), consists of executables, data files and, on UNIX, build software (used to produce the latest executables). The main directories and files are shown below.

realman directory

The contents of realman include the following:

14 (UNIX only) – This directory contains the build software required to perform an on-site build of Reality V14.
14.0 – This directory contains the executables of Reality V14.0 software. A number of different versions can be installed in realman, but only one can be the live release/version. On UNIX, this is specified in the installed file; on Windows it is specified in the registry.

Note: If required, you can create isolated instances of Reality. Each of these will be in a sub-directory of realman, with the same name as the base instance, but with an underscore and the instance number appended. For example, instance number 1 of Reality V14.0 is in the sub-directory 14.0_1.
html – A directory in which web pages can be made available via the Reality mini web server. It is recommended that you install the Reality documentation in this directory.
perl (Windows only) – A folder containing perl programming language software, including the interpreter and DLLs required by the Reality utilities. On UNIX, the perl software supplied with the operating system is used.
installed (UNIX only) – This file contains a list of Reality releases/versions installed on the system and defines the live release/version. The significance of the live release/version is explained below. On Windows this information is held in the registry.
copyrights – This file contains copyright information for the Reality software.

Defining the Live Version

The live version of Reality is the one that supports the maximum number of database users for which your Reality software is licensed and is the one executed by default. When a user logs onto the host system, the environment variables REALROOT and PATH are set to point to the live version. This ensures that the live versions of any Reality host commands executed are used. For example, with V14.0 as the live release, REALROOT is set to /usr/realman/14.0 (UNIX) or C:\realman\14.0 (Windows) and PATH includes /usr/realman/14.0/bin (UNIX) or C:\realman\14.0\bin (Windows)."

On UNIX, the live release is set by editing the file /usr/realman/installed, which lists all installed versions of Reality. Appending the word 'LIVE' to a line makes that version live. For example:

/usr/realman/12.0
/usr/realman/14.0 LIVE

On Windows, you can set the live release via the Control Panel Add/Remove Programs option.

If required, you can use the realroot command to specify a non-live version of Reality. However, non-live versions allow only a limited number of database connections.

Reality Executables Directory

Each Reality executables directory (for example, 14.0) contains a particular version of the Reality executables. The software is contained in three subdirectories, bin, files and lib:

Reality executables directory

Reality executables software includes:

Executables in $REALROOT/bin.
Daemons (UNIX) or database services (Windows) in $REALROOT/bin/daemons.
Master database files in $REALROOT/files.
Reality API for C programs and PROIV in $REALROOT/lib.

Reality Executables

The Reality executables located in $REALROOT/bin can be divided into two groups:

Main Reality programs which are regularly used by users and administrators, including:

dbsave Performs a multi-deck Reality save or restore.

lockdbase Prevents users other than the database owner logging on to a database.

reality Starts up a Reality user environment.

tlmenu Allows you to manage the Reality resilience features (Transaction Logging, Rapid Recovery, Shadow Database, Failsafe and Disaster Recovery). You can also save and restore databases using tlmenu.

unlockdbase Re-enables logons to a database previously locked by lockdbase.
Reality utilities, less commonly used, including:

chkdev Checks that the mapping information in the devices file is valid.

killreal On UNIX, terminates the central daemon and database daemons. Refer to the topic Reality Daemons.

On Windows, terminates a specified database service.

mkdbase Builds a Reality database.

mklog Creates and configures a raw log and clean log sub-directories for Transaction Processing and Rapid Recovery.

netadmin This allows you to carry out network configuration and administration tasks. UNIX and Windows systems have different versions of this utility.

perror Generates a report for an error number returned by Reality software.

realdbck Checks the consistency of a partition database and fixes errors.

realresize Enables a Reality file to be resized while allowing continuous access to it by database users. Only required if you are not using automatic file sizing. Refer to Sizing Files and Indexes for more details.

realserv Windows only. Starts and stops the Reality services.

realstart UNIX only. Starts up the Reality central daemon. Refer to the topic Reality Daemons.

realusers UNIX only. Enables and administers UNIX/Reality password integration.

rladm Administers raw logs for Transaction Processing.

rmdbase Removes a Reality database from the system.

sizemon Scans all or part of a database and reports badly sized files.

Other executables in this directory are run by those listed above.

Reality Daemons (UNIX)

Reality daemons are UNIX background processes, the executables of which are located in the directory $REALROOT/bin/daemons, which manage the operation of multiple databases running under Reality. Two are supported by standard Reality software:

realcd The central daemon. This is initially started when a version of Reality is installed, manages all databases running under that version of Reality. An ipc message queue (mq.cd) is created which enables all reality processes to communicate with realcd. Subsequently, realcd is started up and stopped automatically at system start-up and shutdown.

When a user runs reality to start a database session, a message is passed to realcd via the mq.cd, informing it that the user wishes to logon. The realcd then checks to see if a database daemon (realdd) is running for that particular database. If not, it starts up a realdd process, allocates a message queue (mq.dd) and an area of shared memory for locks, spooler, etc. The realcd then returns the mq.dd to the reality process. reality then communicates with the realdd via mq.dd and shared memory. Subsequent Reality users communicate with the realcd first, then with the realdd via mq.dd.

When a version of Reality is shutdown (by killreal or the stop script), realcd closes down and its message queue is removed.

realdd The database daemon.

Reality Services (Windows)

Reality services, located in the directories %REALROOT%\bin and %REALROOT%\bin\daemons, manage the operation of multiple databases running under Reality on a Windows platform. The following services are supported by standard Reality software:

realserv Windows service. This starts Reality when the Windows system is booted up. It then starts the Reality session manager and the central database service program. The realserv utility can be used to start and stop Reality while the system is powered up.

smanager Reality session manager. This process listens on a number of specified ports, accepts incoming calls to the Windows system, prompts for the Reality user-id and starts a reality user process.

realcd Central database service. This manages all databases running under the associated version of Reality. It is started and stopped by realserv.

When the first user runs reality to start a database session, a message is passed to realcd informing it that the user wishes to logon. The realcd then checks to see if a database service (realdd) is running for that particular database. If not, it starts up a realdd process. reality then communicates with the realdd and shared memory. Subsequent reality users communicate with realcd first, then with realdd. When a version of Reality is shutdown, the realcd closes down.

realdd The database service.

Database Daemon/Service

A database daemon (realdd) is started when the first user logs on to a database, and closes down after a period of between one and two minutes after the last user logs off. The functions of realdd include the monitoring of database users and the performance of housekeeping tasks for the lock tables in shared memory. In the event of a reality process aborting, the realdd tidies up any item locks, spooler locks, etc. that have been left behind.

Transaction Processing and FailSafe Daemons/Services

Transaction Processing and FailSafe software support a number of additional daemons to manage transactions. They are:

raw image processor (realrip)
Responsible for receiving raw log images from reality processes and writing them to the raw log. In FailSafe systems it is also responsible for transferring images to the secondary.

clean image processor (realcip)
Responsible for transferring committed transactions and independent updates to a clean log.

raw image receiver (realrir)
This is only used on FailSafe systems. It runs on the secondary system and is responsible for receiving the raw images from the rip and logging them in the secondary raw log.

Master Database Files

The following database files are located in $REALROOT/files, unless otherwise stated:

config Master copy of the database configuration file, used by mkdbase to build a new database. Any change required in the configuration of newly created databases can be entered in here. See Reality Configuration Parameters for details of the config file.

daemon.log Error message file. Messages from the various daemons (UNIX) and service programs (Windows) are logged in this file. The start date and time, process identification and level of significance of each message are also logged.

You can set the logging level as follows:

Use the killreal host command with the -l option. This sets the logging level for all currently executing processes. For example, to set the logging level to 5, enter:
```
killreal -l 5
```
You can also set the logging level for a particular process by including the process id. The following command sets the logging level for process 67:
```
killreal -l 5,67
```
Set the REALLOGLEVEL environment variable to the required level. Only processes started after this is changed are affected.
Use the MSG TCL command with the I option. This allows you to set the logging level for a particular port. For example, to set the logging level for port 411 to 5 enter:
```
MSG 411 5 (I
```

The following logging levels are available:

0 – none
1 – panic
2 – alert
3 – warning
4 – notice (default)
5 – info
6 – debug

Note: The operator can be informed of error messages logged in the daemon log using system alerts.

daemon.log.old Copy of old daemon.log.

The daemon.log file rotates to daemon.log.old when it is filled to a pre-defined limit and a new daemon.log is started. Optionally, daemon.log.old is copied before each rotation and kept in a pre-defined old logs directory. A defined number of old logs can be kept. Refer to the topic Daemon Log Rotation.

realityrc This file can be used to define environment variables for controlling the Reality system – the variables concerned affect all processes using the associated version of Reality. On UNIX, setting REALDBASE in this file will set the default database for the system; on Windows use netadmin to set the default database.

On UNIX systems, the Reality environment variables can be overridden for a particular UNIX user by defining them in a .realityrc file in that user's home directory.

Other data files are used to build a database and its language tables.