# Chapter 1: Installation Guide

## 1.1 Installing and Configuring Empress

This section of the manual describes the instructions for installing Empress Relational Database Management System.

Empress software is distributed on a single CD-ROM. The term distribution media maybe used in this document to refer to the CD-ROM that you received.

If there are any special instructions for reading the software on the media, you will find them on an accompanying sheet.

If you are updating your Empress system, please read Update Empress System before the installation process.

### 1.1.1 System Requirements

A full Empress development system needs about 60 to 100 megabytes of disk storage and 32 to 64 megabytes of memory pending on the type of license you acquired. Before installing Empress, please make sure there is enough space on the file system.

Empress executables are distributed in binary format so that the installation will be seamless and it will not require the use of a compiler; however, a C compiler is required if you choose to install Empress Perl Interface, run the test suite or intend to use any of the Host Language Interface for development such as mr, mx or Dynamic SQL.

If you intend to use Empress Web HTML Toolkit, an Internet browser will be required. Netscape browser for certain platforms are included with the Empress distribution.

If you intend to run Empress 4GL in an X Window environment, Empress GUI Builder or Internet browser, the X Window will be required.

### 1.1.2 Distribution File Ownership

When files are extracted from the distribution media, they should be system ownership by the account in which you are doing the extraction. That is, make sure you log in to the account that will own Empress distribution files before you start the installation process.

Empress recommends against running installation process as user `root`.

### 1.1.3 Loading Empress Software

The examples in the rest of the manual will assume that you are installing Empress in `/usr/empress`, using an account called `empress`.

- Log in as `empress` and set your umask to 022. This will preserve correct access permissions to the Empress files.

- Next, follow the instructions that is given on the media label or the CD-ROM insert.

### 1.1.4 Installing Empress

To invoke the installation process, do the following at the operating system prompt:

- For Unix:

  1. Mount the Empress CD-ROM.

  2. Change to the directory (file system) where the CD-ROM is mounted on, for example,

            cd /cdrom

  3. Execute the shell script:

            sh install.sh

- For Win32:

  1. Mount the Empress CD-ROM.

  2. System will Auto-run the install program.

  3. Follow the instruction.

If you have a Netscape browser set up in the Unix system, then the installation process will be executed from the Netscape browser. This process will guide you through the preparation of the installation, invoking installation program, verification of the installation and setting up Empress for general use.

If you don't have a browser set up in the system, `install.sh` will invoke the installation program .

The installation program displays a brief overview of the installation procedure followed by a prompt for the installation key set which came with your product. Enter your key set carefully, making sure not to use leading or trailing spaces. If one of the lines you enter is not in the format of a valid key, an error message will be printed and you are prompted for the same line of the key.

Once you have entered the key set, it is checked for validity. If the key set is invalid, an error message is printed and you are prompted again for the information. You have five chances to enter the key set correctly. If you enter an incorrect key set on the fifth attempt, the installation program aborts. Note that if the installation program aborts, you may try again. If it fails again, contact your Empress distributor or Empress Software Inc.

Once you have entered a valid installation key set, a list of optional modules is displayed and you are asked whether you wish to install each of the modules. You may answer with `yes`, `no` or `quit`. The following modules do not require installation key validation:

- Empress Manual Set
- Empress Document Server
- Netscape
- Empress Perl Interface
- Empress Tcl/Tk Interface
- Empress ODBC Clients

When you have finished selecting options, the list of options you selected is displayed and you are asked to verify the list by answering `yes` or `no`. If you answer `no` the installation procedure will be aborted, at which point you may run `sh install.sh` once more.

### 1.1.5 Installation Results

The installation status will be logged into a file named `install.log` under the Empress directory named `empinstl`.

If installation fails for some reasons (some of these reasons are system-related, others are Empress-related), a message will be displayed on the screen and will also be written into `install.log` file. Check this file for status information. It may provide you with the indication of why the installation is unsuccessful.

### 1.1.6 Setting Empress Related Environment Variables

At the end of installation process, Empress installation procedure will request your permission to modify your system startup file (for example `.cshrc`) to set up Empress related system variables:

       # ### Empress Installation Setup Block ###
       # Do not modify lines within the Empress Installation Setup Block
       source /usr/empress/Empress/v8.62/installation/bin/setenv.csh
       # ### Empress Installation Setup Block End ###

If these lines are not added to your system startup file, you shall run the script corresponding to your system settings everytime you want to use Empress. These scripts are in the `bin` directory under the Empress installation directory.

### 1.1.7 Configuring Empress for General Use

If you have not encountered any difficulties with the installation, continue as follows:

Step 1.

  If you have System Administrator privileges (i.e., the superuser password), follow the instructions in A. Otherwise, follow the instructions in B.

  A.
    Copy all the programs from the directory `$EMPRESSPATH/bin` to `/usr/bin`.

    Change the current directory to the directory `$EMPRESSPATH/bin`:

           % cd $EMPRESSPATH/bin

    Use the command `su` to become `bin` or `root` (or whoever owns the files in `/usr/bin`) and copy all of the files in the current directory to `/usr/bin`:

           % cp * /usr/bin

    Once this is finished, proceed to Step 2.

  B.
    Since you are unable to install the files in `bin` in the system default directories, you will need to either:

    1. use the full pathname of the programs when invoking them, or
    2. put the directory in which they are installed in your own search path.

    Note that you will need to log out and log in again after you have made these changes.

Step 2.

  Once you have installed the files from bin, copy the manual pages in `man/man1` to `/usr/man/man1` or `man/cat1` to `/usr/catman/man1` with either of the commands below:

  You must have write permission for the directory `/usr/man/man1` or `/usr/catman/man1` for this to be successful. Installing the manual pages is not an essential step in installing Empress (Empress will still work if they are not installed), but you may want to consider it as a manner of good system housekeeping.

         % cd ../man
         % cp man1/* /usr/man/man1

  or

         % cd ../man
         % cp cat1/* /usr/catman/man1

Step 3.

  If Shared Library is supported, do the following:

         % cd /usr/lib
         % ln -s $EMPRESSPATH/shlib/* .

  Alternative is to set `LD_LIBRARY_PATH` system variable.

### 1.1.8 Accessing the Empress Manual Set

The Empress CD-ROM contains the manual set for the Empress products. You can access this Manual Set using a Web browser either directly from the CD-ROM or via a HTTP server.

#### 1.1.8.1 Access Manuals from CD-ROM

If you are using a Web browser on an UNIX workstation:

1. mount the CD-ROM to a directory such as `/cdrom`,

2. set the Location (URL) of your Web browser to:

          file:/cdrom/docs/docroot/index2.htm

If you are using a Web browser on a Microsoft Windows machine:

1. put the CD-ROM to the CD-ROM drive such as the E drive,

2. set the Location or Address to:

          E:\docs\docroot\index2.htm

#### 1.1.8.2 Access Manuals from the Network

In this case, you need a HTTP server. Empress installation process sets this up automatically for you. However, in case of server shut down or circumstances require you to set this up manually, do the following step:

       $EMPRESSPATH/bin/empdocsv on

Later you can access the Documentation using the following command:

       $EMPRESSPATH/bin/empdocs

### 1.1.9 Converting Databases

Version 8.62 is not compatible with previous Empress versions. See the section related to Compatibility of Version 8.62 for more detail.

When upgrading to Version 8.62, all applications need to be recompiled, relinked. Furtheremore, all Persistant Stored Modules that use any Empress routines, if present in the database, would have to be recompiled, relinked.

To upgrade V6.2 and newer databases, Empress users can use Empress utility `empcnvt`. The upgrade involves data dictionary conversions which include adding new system tables into the data dictionary and updating some files and directories. Once database is fully upgraded, it will support all new features provided by the Version 8.62.

To upgrade V8.20 databases, Empress users can also use Empress utility `empupgrd`. Once database is upgraded, only Version 8.62 applications can access the database.

The utilities `empcnvt` and `empupgrd` are documented in the Manual Pages manual. With Empress V8.62 there is no need any more to set Empress variable MSPATH. The only required variable setting is for EMPRESSPATH. Empress variable EMPRESSPATH should point to a directory where Empress products are installed.

## 1.2 Update Empress System

### 1.2.1 Before Installation Process

When updating your Empress system, we recommend that you create a new directory in the `empress` account with the name of the new version number, for example v8.62, and install the new version in this new directory. Keep the previous version of Empress accessible until you are ready to switch over. Please check any enhancement and modification notes that may accompany your distribution media.

There are two items that require special attention before the installation:

- Environment path and the Empress path

  You are not required to set the environment path or the Empress path (`EMPRESSPATH`) for the installation, but you have to ensure that your environment path is not set to any previous versions of Empress. This is to ensure that the installation and the test procedure will use the current version instead of previous release of Empress.

- Empress system variables (only if you run the test procedure)

  Empress has a large number of system variables which control such things as the editor used by the `.zz` command, the shell used in shell escapes, the value separator in dump files, the number of commands remembered by the history mechanism, and so forth. The functions and default values of these variables are described in the Empress System Variables of the manual.

  The Empress test procedure produces test results which are compared with the standard results. The standard results are created based on the default values of the Empress system variables. The test results are also dependent on these variables; therefore, if there are any discrepancies in the system variable values, these may cause an incompatible result.

  If you have any Empress system variables set as an environment variable in the `empress` account and the values are different from the default values, remove those variables from your environment.

### 1.2.2 After Installation Process

If you have applications that use the mx and mr routines, recompile and relink these applications following the installation of the new version of Empress. You should do this because your application was linked with the previous version of Empress libraries and compiled with the previous version of Empress `include` files.

## 1.3 Terminal Setup for Empress 4GL

Empress 4GL supports many terminal types. You must specify which type you are using. To obtain a list of terminal names defined in the terminal database, run the following command:

       % emp4term

This will display the location of the terminal database, a sorted list of terminal names and their descriptions.

To run Empress 4GL, you must set your `TERM` variable to the name that matches your terminal. For example, if your terminal is a DEC VT100, use `vt100` as your `TERM` variable. If Empress runs under the Bourne shell, type in the following:

       % TERM=vt100
       % export TERM

Or, if Empress runs under the C shell, type in the following:

       % setenv TERM vt100

If your terminal is not included on the list or does not emulate one of these, you may have to make a terminal entry in the Empress 4GL terminal database. Refer to the Empress 4GL: Administrator's Guide manual.

## 1.4 Empress on NFS Platforms

### 1.4.1 Installing Empress on NFS

This chapter is for users running Empress in a homogeneous environment using NFS.

Empress on NFS was first developed on a Sun NFS network. Since then Empress has been ported to many NFS systems. While the following notes make reference specifically to Sun NFS, the description and implementation are identical on all NFS networks.

#### 1.4.1.1 System Requirements

In order to support file locking properly in a NFS file system, both NFS Client node and NFS Server node need to have the network lock daemon (`lockd`) running. In addition to `lockd`, your system may also need network status daemons (`statd`).

There are some NFS implementations that do not support network file locking. Empress cannot support locking in such NFS environment.

### 1.4.2 Access to Empress Databases on NFS

This discussion concerns access to Empress databases on NFS by users on several nodes. The issues raised do not apply to access to Empress databases by several users on a single node.

The discussion is directed to the administrator of any database that will be the object of access by users on several nodes.

#### 1.4.2.1 Administrative Variables

When an Empress database is created using the utility `empmkdb`, the database is created as an operating system directory. In that directory there is a file called `tabzero`. The file `tabzero` defines a number of Empress administrative variables, and the values of those variables can be changed by editing the values assigned to them in `tabzero`.

The version of Empress supplied for platforms running NFS includes the administrative variable `MSNFSSHARE`.

The variable `MSNFSSHARE` must be set to allow the database to be accessed concurrently by users on several nodes without risk of data loss or corruption. To set the variable, edit the appropriate line in `tabzero` to read:

       MSNFSSHARE=X

Note that this variable is database specific and must be set for every database that will be accessed concurrently by users on several nodes. The variable is not set by default. Setting the variable will degrade the performance of Empress on that database. The cost may be a two- or three-fold reduction in speed.

Setting the variable `MSNFSSHARE` guarantees that the memory buffers of each node from which Empress is accessed is flushed as often as required. This guarantees that in a concurrent access situation, users on every node will access up-to-date data. (Since users on a single node share the same memory buffers, the variable needs not be set to enable secure concurrency on a single node.)

If serial (sequential) access by users on several nodes is anticipated for a database, the variable `MSNFSSHARE` should be set for the database. Without setting the variable, an undetermined amount of time between such accesses is required to ensure that data loss or corruption will not occur. Serial access by users on the same node does not require that `MSNFSSHARE` be set.

### 1.4.3 File and Database Privileges on NFS

This discussion concerns file access permissions and database access privileges for Empress systems on NFS.

#### 1.4.3.1 File Access Permissions

File access permissions under UNIX are granted by user, group and other, with types of access being some combination of read, write and execute. In an attempt to access a file, the user id associated with the process is compared with the access permissions attached to the file. If the user has the appropriate permission, access is permitted.

On NFS, the user id of a user is determined by the node on which the user is logged in. This means that unless the creation of accounts and assignment of user ids is under centralized control, a given user could have different user ids on different nodes, and a given user id could belong to different users on different nodes. If the mapping between users and user ids is not one-to-one across the network, there is no guarantee that a user who creates a file while logged in to another node will have the appropriate access permissions if the user id is different. Furthermore, a file created by a user on one node, if residing on a file system that is NFS-mounted on another node, may be unintentionally accessible by another user.

#### 1.4.3.2 Database Privileges

Database privileges, in the broadest sense, concern the identity of the database administrator of the database, the ownership of tables in the database, and the access privileges to tables granted to users of the database. All information concerning these privileges is stored in the data dictionary, and identity is determined by the login name.

#### 1.4.3.3 Database Access under NFS

In order to access a table in an Empress database, a user must have both the appropriate UNIX file permissions and the appropriate database privileges. To guarantee that a user will be able to access a database that resides on an NFS-mounted file system, that user must have the same user id and login name that are normally used to access the database. The user id controls the UNIX system permissions and the login name controls the database access privileges.

Conversely, on a network where account creation is not centrally controlled, database security cannot be guaranteed. If the System Administrator of a node can NFS-mount a file system on which a database resides, then create an account using a login name /user id combination that is known to have access to the database, that database can be accessed.