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 in the following example diagram.

The contents of realman include the following:

• 15 - This directory contains the build software required to perform an on-site build of Reality.

• 15.0 - Directories with names in this format contain the executables for the corresponding version of the Reality software (in the example above, V15.0). Several 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 V15.0 is in the sub-directory 15.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 To use an environment variable: On UNIX, $variableName; On Windows, %variableName%. 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 V15.1 as the live release, REALROOT is set to /usr/realman/15.1 (UNIX) or C:\realman\15.1 (Windows) and PATH includes /usr/realman/15.1/bin (UNIX) or C:\realman\15.1\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/15.0
/usr/realman/15.1 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, 15.0) contains a particular version of the Reality executables. The software is contained in three subdirectories, bin, files and lib:

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:

  dbsavePerforms a multi-deck Reality save or restore.

  lockdbasePrevents users other than the database owner logging on to a database.

  realityStarts up a Reality user environment.

  tlmenuAllows 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.

  unlockdbaseRe-enables logons to a database previously locked by lockdbase.

• Reality utilities, less commonly used, including:

  chkdevChecks that the mapping information in the devices file is valid.

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

  On Windows, terminates a specified database service.

  mkdbaseBuilds a Reality database.

  mklogCreates 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.

  perrorGenerates a report for an error number returned by Reality software.

  realdbckChecks the consistency of a partition database and fixes errors.

  realresizeEnables 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.

  realservWindows only. Starts and stops the Reality services.

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

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

  rladmAdministers raw logs for Transaction Processing.

  rmdbaseRemoves a Reality database from the system.

  sizemonScans 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:

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