jBASE 5.5.0 Linux Installation Guide

Table of Contents

1. Prepare for the Installation

1.1. 64 Bit operating system

jBASE 5.5.0 is a 64-bit release and must be installed onto a 64-bit operating system.

1.2. Root Access

This document assumes you have superuser (su) or root access to the computer. Root or superuser commands will be represented with the pound sign / hash (#) character.

1.3. Disk Space

Ensure the volume in which you are installing jBASE 5.5.0 has sufficient free disk space, approximately 500MB is required, plus additional space for any temporary files.

# df -h              [ will show the current disk usage within each Linux volume ]

jBASE is generally installed on whichever volume contains the '/opt' directory structure.

1.4. Packages needed for jBASE on Linux

The jBASE installer will check for the following required packages and install them automatically. The required packages are:

1.5. License Key

In order to complete the installation you will need to enter your jBASE license key. jBASE cannot be installed without either a permanent or evaluation license key. If you are performing an upgrade, the installer will attempt to locate your existing license keys and allow you to reuse them.

2. Installation

2.1. Download the jBASE installer binary

Download the jBASE 5.5.0 installer using the credentials that will have been supplied to you. Place the installer in a convenient directory, for example, /tmp.

Ensure that the installer is executable.

Depending on the source of the installer file, the execute mode of the installer file may have been lost. Check the file mode, and change if necessary. First cd to the directory where the installer is located:

# cd /tmp

# ls -l LINUX_jBASE_5.5.0_64bit.bin
-rw-r--r-- 1 root root 78M Feb 24 14:42 LINUX_jBASE_5.5.0_64bit.bin

# chmod +x LINUX_jBASE_5.5.0_64bit.bin

# ls -l LINUX_jBASE_5.5.0_64bit.bin
-rwxr-xr-x 1 root root 78M Feb 24 14:42 LINUX_jBASE_5.5.0_64bit.bin

2.2. Run the jBASE Installer

The jBASE 5.5.0 installer is an interactive script-based installer. The installer will prompt you with various questions about the installation and after all of the information has been gathered, it will perform the installation automatically.

To launch the installer script, assuming your current directory is where the installer script resides, type:

# ./LINUX_jBASE_5.5.1_64bit.bin

That is, a dot, a slash, followed by the installer file name (no spaces). The file shown above is an example - use the actual name of the installer binary which you have downloaded.

2.3. Installation Conventions

Many of the installer's prompts accept several options, for example Yes, No or Cancel. A single letter followed by the <Enter> key is expected. The default answer is shown in angle brackets, for example <Y>es. Other answers are shown in square brackets, for example [C]ancel. Upper or lower case responses are accepted. If an unexpected response is entered, the prompt will be repeated.

2.4. Installation Process

When you launch the installer, operating system compatibility is verified. If the operating system is compatible, the installer then verifies that all of the required Linux commands used during installation are available. Once the pre-installation tests are complete, a welcome message is displayed:


jBASE Release 5.5.0 Installation


You are about to install the jBASE MultiValue Database. During this process you will be asked to provide:

* The target directory for this release and the symbolic link to that directory

* The Unix user and group which own the jBASE system files

* Either an evaluation or permanent licence key

* Optional: - JBASEADM account directory

The installation process will make the following updates to the system:

* Install pre-requisites needed for jBASE: ksh, gcc, ncurses-devel, libcrypto

* The jBASE system files will be placed in the release directory.

* A symbolic link will be added to that release directory.

* If the user and/or group do not exist, they will be created, along with the user's home directory.

Press <Enter> to start the installation process or [C]ancel

Press <Enter> to dismiss the welcome page and begin the installation.

2.4.1. Choose your company location


Company Location and License Agreement


Company is registered <O>utside the EU, [W]ithin the EU or [C]ancel :

Enter 'W' if your organization is located within the European Union, otherwise enter 'O', then press <Enter>.

2.4.2. Review and accept the software license agreement

Press the spacebar to scroll through the license agreement. On the final page, type the word 'YES' to indicate your acceptance of the agreement.

2.4.3. Choose an installation mode

The jBASE installer provides three installation modes: Express, Advanced and Minimal:


Type of Installation


[E]xpress : Install jBASE with typical options and services

[A]dvanced : Select components to install and services to start

[M]inimal : Install jBASE system files only

[C]ancel installation Install type:

Express: install jBASE with typical options and services. Select this option if you are new to jBASE and wish to get started quickly. Express mode installs jBASE, creates a jBASE Administrator user and account, creates a SYSTEM file to organize jBASE accounts, initializes the spooler, installs and starts jBASE services.

Advanced: allows you to select which features and services to install. Select this option if you need to customize the location of the SYSTEM file, administrator account, or jBASE spooler, or if you do not want some of these features installed. Also select this option to select which optional services to install (jDLS and jRCS).

Minimal: install the jBASE system files only. Select this option if you are comfortable with configuring jBASE manually.

2.4.4. Select the installation directory


Release Directory


Please specify the directory to install jBASE, or press <Enter> to accept the default directory: /opt/jbase/5.5.0

jBASE release 5.5.0 will be installed in: /opt/jbase/5.5.0

If the installer is able to locate an existing jBASE installation, the previous release directory will also be shown on this page. The installer will look for existing installations at the location pointed to by the JBCRELEASEDIR environment variable, as well as commonly used directories for past jBASE releases.

The default installation directory is /opt/jbase/<release number>.

The installer will validate the specified installation directory. If it is a new directory, or an empty directory, installation may proceed. If the directory exists and contains a jBASE installation of the same release as the one being installed, the installation may proceed. Otherwise a different directory must be selected.

If you are performing an Express mode install, the parent of the installation directory will be used as the location for the SYSTEM file, the JBASEADM account and jBASE spooler. For example if jBASE is installed in the default directory, the parent is '/opt/jbase', so the SYSTEM file will be created as '/opt/jbase/SYSTEM'.

2.4.5. Minimal Install

If you are performing a minimal install, the installer will now copy the jBASE release files to the installation directory.


Minimal Install


jBASE release 5.5.0 will be installed in /opt/jbase/5.5.0

Proceed with installation ([Y]es/[N]o/[C]ancel) : Y

Creating release directory /opt/jbase/5.5.0

Changing permissions to 777 for /opt/jbase/5.5.0

Loading /opt/jbase/5.5.0 release directory

You may want to chown /opt/jbase/5.5.0 to other than root:root.

#

A minimal installation is now finished.


Symbolic Link (JBCRELEASEDIR)


Please specify the symbolic link for jBASE release directory (JBCRELEASEDIR). Press <Enter> to accept the default symbolic link: /opt/jbase/CurrentVersion

Symbolic link to JBCRELEASEDIR: /opt/jbase/CurrentVersion

Choose the name for a symbolic link for the new release. The symbolic link name is typically used for the JBCRELEASEDIR environment variable. For jBASE 5.5.0, the default symbolic link name is 'CurrentVersion'.

If the installer identified a previous jBASE release, the symbolic link name for the previous release will also be displayed. If you have existing scripts that rely on the previous symlink name, you may want to use the same name here to avoid having to update any existing scripts.

Express install will use the default symbolic link name 'CurrentVersion'.

2.4.7. Select jBASE administrator user and group


jBASE User ID


Please specify the Linux user ID to own the jBASE system files, or press <Enter> to accept the default jBASE user ID: jbaseadm

User id "jbaseadm" does not exist. Create new user ([Y]es/<N>o/[C]ancel): In Linux, all files are owned by a Linux user and group. The default owner for jBASE release files is 'jbaseadm', and the default group is 'jbase'. If the user does not yet exist on your Linux system, the installer will create a new user (and group, if necessary). In this case you will be required to supply a password for the new user:

Password for "jbaseadm":

Again for verification :

After defining the jBASE administrator user name, select the jBASE group name:


jBASE Group ID


Please specify the group ID for the jBASE system files, or press <Enter> to accept the default group ID: jbase

jBASE system files will be associated with group "jbase"

2.4.8. Optional Tasks (advanced)


Optional Tasks


[X] 1. Create JBASEADM account for administrative functions

[X] 2. Create SYSTEM file to organize jBASE accounts

[X] 3. Start jDLS distributed locking service

[X] 4. Start jRCS remote connectivity service

[X] 5. Initialize the print spooler

Enter number to toggle, [N]ext or [C]ancel:

Enter a number (1 to 5) to toggle the selection of optional tasks. By default, all optional tasks are performed. Express install will perform all optional tasks.

Create JBASEADM account for administrative functions The JBASEADM account can be used to perform jBASE administrative tasks such as creating or deleting other jBASE accounts.

Create SYSTEM file to organize jBASE accounts In jBASE, the SYSTEM file is optional. However, using a SYSTEM file provides a convenient way to organize your jBASE accounts, and is required for using Q-pointers and the LOGTO command in your jBASE applications.

Start jDLS distributed locking service jDLS is responsible for resolving all record locking conflicts for jBASE processes. If jDLS is not running, jBASE will use the normal operating system locks. This is acceptable for small user populations, but the operating system locking mechanism has limits on the number of locks available, and on performance. See the jBASE Distributed Locking User Guide for more information regarding jDLS.

Start jRCS remote connectivity service The jBASE Remote Connectivity Server (jRCS) provides remote access to your jBASE system. jBASE System Manager uses this service to perform management tasks on your jBASE system. By default, the jRCS server listens on TCP port 8236. See the jBASE Remote Connectivity Service knowledgebase article for more information regarding jRCS.

Initialize the print spooler Select this option to initialize the default print spooler configuration after a new installation. For upgrade installations, this option will restart the print spooler instead.

2.4.9. Directory for the SYSTEM file (advanced)


Directory for jBASE SYSTEM File


Please specify the directory where setup will create the jBASE SYSTEM file, or press <Enter> to accept the default directory: /opt/jbase

The SYSTEM file will be created in /opt/jbase

If you opt to create a SYSTEM file, you must specify the directory where the file will be created. The default is the parent directory of the jBASE release. If the default release directory is used, the SYSTEM file directory will be created in /opt/jbase (the path for the SYSTEM file will be /opt/jbase/SYSTEM).

2.4.10. Directory for the jBASE spooler (advanced)


Directory for jBASE Spooler Files


Please specify the directory where jBASE spooler files will be stored, or press <Enter> to accept the default directory: /opt/jbase/jspooler

The jBASE spooler files will be stored in /opt/jbase/jspooler

If you opt to initialize the print spooler, you must specify a directory where jBASE will store spooler files. The default is 'jspooler', created in the parent directory of the jBASE release. If the default release directory is used, the spooler directory will be /opt/jbase/jspooler.

2.4.11. Directory for the JBASEADM account (advanced)


Directory for JBASEADM Account


Please specify the directory where jBASE administrator account will be created, or press <Enter> to accept the default directory: /opt/jbase/JBASEADM

JBASEADM will be created as /opt/jbase/JBASEADM

If you opt to create a jBASE Administrator account (JBASEADM), you must specify the directory for the account files. The default is 'JBASEADM', created in the parent directory of the jBASE release. If the default release directory is used, the administrator account directory will be /opt/jbase/JBASEADM.

2.4.12. License Keys


License Keys


[E]valuation license :

[S]ystem license :

[M]ulti-session license :

[W]eb session license :

Enter license type to edit, or [N]ext or [C]ancel

In order to complete the installation you will need to enter your jBASE license key. jBASE cannot be installed without either a permanent or evaluation license key. If you are performing an upgrade, the installer will attempt to locate your existing license keys and allow you to reuse them.

2.4.13. jRCS TCP port (advanced)


jRCS TCP Port Number


Specify the TCP port to use for the jBASE Remote Connectivity Server (jRCS). Press <Enter> to accept the default TCP port 8236.

jRCS server will be installed on TCP port 8236

If you opt to start the jRCS service, you need to specify the TCP port which the service will listen on. The default port is 8236. See the jBASE Remote Connectivity Service knowledgebase article for more information regarding jRCS.

2.4.14. jDLS locking option (advanced)


jDLS (Distributed Locking Service) Options


jBASE locks can be maintained on a per-process or per-port basis.

If you opt to start the jDLS service, you can select port-based or process-based locks. The default is process-based locks. See the jBASE Distributed Locking User Guide for more information regarding jDLS.

2.4.15. Installation Summary


Installation Summary


Release directory : /opt/jbase/5.5.0

JBCRELEASEDIR : /opt/jbase/CurrentVersion

jBASE admin user : jbaseadm

jBase group : jbase

SYSTEM file : /opt/jbase/SYSTEM

JBASEADM account : /opt/jbase/JBASEADM

jRCS TCP Port : 8236

Create SYSTEM File : Y

Initialize Spooler : Y

Start jDLS : Y

Server License : xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Begin installation ([Y]es/[N]o) :

After verifying the information displayed on the summary page, type Y to begin the installation process. The installer will:

2.4.16. Installation Complete

If the installation is successful, the following screen will be displayed:


Installation Complete


jBASE release 5.5.0 is now installed.

You may want to restart the server if you changed options on jDLS or added any new licenses.


NOTE ABOUT FIREWALLS:

If you have a local firewall installed on this server, it may prevent network users from connecting to the application. Your system administrator may need to allow access to TCP port 8236.

Would you like to log in to JBASEADM now ([Y]es/<N>o)

Enter "Y" to open a jSHELL prompt in the JBASEADM account.

If any problems arise during the installation, an appropriate error message will be displayed explaining the problem, and if possible, recommending a solution.

2.5. Upgrading from a Previous Version

The jBASE installer will examine the directory pointed to by the JBCRELEASEDIR environment variable for a previous jBASE installation. If JBCRELEASEDIR does not point to a valid jBASE installation, the installer will test common installation locations for previous jBASE versions. The 'jdiag' command is used to that the directory contains a jBASE installation, as well as the previous jBASE release number.

If a previous jBASE release is found, the contents of the previous release 'config' directory will be backed up to 'config_pre_<new version> in the destination directory. For example, if, prior to installing this release of jBASE, JBCRELEAESEDIR points to '/opt/jbase5/5.2' and the new installation destination directory is '/opt/jbase/5.5.0', then the contents of '/opt/jbase5/5.2/config' will be backed up as '/opt/jbase/5.5.0/config_pre_5.5.0'.

If you have modified any of the configuration files in the previous release 'config' directory, you will need to apply your modifications to the corresponding files in the new installation 'config' directory. Such files may include:

Config_EMULATE - Contains the JBCEMULATE settings

Config_TERM - Contains translations from PICK TERM to linux TERM items

jediLoggerAdminLog, jediLoggerConfig, jediLoggerTransLock - Contains TJ log parameters

jnet_access, jnet_config, jnet_env, jnet_map, jrfs_config - jRFS configuration files

jspjobs_config, jspform_deflt, jspxl_deflt - jBASE spooler config files

jshlogin - if jsh shell is used as the login shell

jLibDefinition - Define shared object items

When upgrading a previous release of jBASE, the installer will not overwrite any existing JBASEADM account, SYSTEM file or jBASE Spooler configuration.

2.6. License Key Installation

License keys for jBASE 5.need to be added to the 'system.properties' file which is located in the 'config' directory under your jBASE release directory. The jBASE installer will update the license keys during Express and Advanced mode install. If you need to change the keys, for example , to enter a permanent key instead of an evaluation key, or if you performed a Minimal install, you can use any text editor (vi, for example) to enter the keys in the 'system.properties' file. You should have either a permanent system license key, or an evaluation license key. You may also have a 'Multisession' and/or 'Websession' key. Each key must be added as a separate entry in the 'system.properties' file. New keys should be added at the end of the file, after the 'jruntime.license' line, which should be left in the file without modification. When the keys have been added, the last few lines of your 'system.properties' file will look something like this:

#################################################################
jruntime.license = qP2XhdjqbdbiqzvfDBgPisP3ITiDfhyT
jruntime.azeroth= 5FLY3q6e4P6I1qdZLr2q4wadhM06VQvzoOGDVX0KZSs=
jruntime.multisession=5FLY3q6e4P6vTff9AETIQYwyjTnxDVK6sS1uFVfPeFQ=

For further information on jBASE licensing see the jBASE Knowledgebase article jBASE 5 Licensing

2.7. jBASE Daemons

The jBASE installer (Express or Advanced mode) provides an option to install "init scripts" for jBASE daemons. These scripts are used to start and stop the jBASE daemons automatically during system boot or shutdown.

If you did not opt to start the daemons during install, you can manually configure them at a later time. 'Init scripts' for the typical jBASE daemons are found in the $JBCRELEASEDIR/src directory, in the form of jXXX.init.d, where XXX is the daemon name. For example, the 'jDLS.init.d' script is used to start and stop the jDLS distributed locking services daemon.

Copy the 'init script' for the daemon you want to configure to the /etc/init.d directory. Edit the script to specify any special start or stop options. Rename the script, removing the '.init.d' suffix. Then create a symlink to the 'init script' in the /etc/rc2.d directory, with 'S99' as a prefix.

For example, to configure jDLS to start and stop automatically during system boot or shutdown:

# cp $JBCRELEASEDIR/src/jDLS.init.d /etc/init.d/jDLS
# ln /etc/init.d/jDLS /etc/rc2.d/S99jDLS

For more information about configuring jBASE daemons, see the jBASE Knowledgebase article jBASE Daemons.

3. jBASE Users and Accounts

This section describes the jBASE concepts of users and accounts.

3.1. jBASE Users

jBASE users are normal Linux users. As with any Linux application, the user must have the correct privileges to access jBASE programs and data files.

It is recommended that all jBASE users belong to the 'jbase' group, as their primary group. That way, they not only have access to other files belonging to the 'jbase' group, but any files they create will also belong to the 'jbase' group, and be accessible by other members of this group.

To create a 'jbase' group:

# groupadd jbase

To create a new jBASE user, for example, named 'jbaseuser':

# useradd -m -d /home/jbaseuser -s /bin/ksh -g jbase jbaseuser

Set the password for the new user:

# passwd jbaseuser

Update the login profile for the new user. Source the 'jbase_env.sh' script in the user's login profile - that is a dot, a space, followed by the path for the jbase_env.sh script.

# . /opt/jbase/CurrentVersion/jbase_env.sh

The remainder of the jBASE user's login profile will depend on several factors:

LOGTO <account name>

export HOME=<account path>
cd $HOME

export JEDIFILENAME_MD=$HOME/MD]D

export PATH=$HOME/bin:$PATH

export JBCOBJECTLIST=$HOME/lib

export JBCEMULATE=<platform emulation>

exec jsh -

3.2. jBASE Accounts

A jBASE account is a directory that contains jBASE data and executable files. An account can optionally have a "master dictionary" (MD) which may contain file pointers, PROCs (JPQ), and definitions used by the jBASE query processor (jQL).

Use of a SYSTEM file in jBASE is optional. However, a SYSTEM file is a useful place to organize your jBASE accounts. By adding a record in the SYSTEM file for an account, it is possible to use the LOGTO command to log to the account from another jBASE account or from a login profile. The SYSTEM file record also enables Q-pointers to files in that account. See SYSTEM File in the jBASE knowledgebase for details on the content of SYSTEM file records.

3.2.1. Using CREATE-ACCOUNT to create a new account

The CREATE-ACCOUNT command can be used to create a new jBASE account. The command is normally executed from the JBASEADM account. The CREATE-ACCOUNT command creates a directory for the new account, creates an MD for the account, and updates the SYSTEM file (a SYSTEM file is required when using the CREATE-ACCOUNT command). Optionally it will also create a 'remote.cmd' script for the account.

The basic syntax is: CREATE-ACCOUNT {-n} path {name}

where path is the full or relative path for the new account directory and name is the account name registered in the SYSTEM file. If name is not specified, the final directory name in path is used as the account name. The -n option inhibits creation of a MD for the account.

3.3. Setting up the jBASE environment for users

jBASE is defined by its environment. The login profile (.profile or .bash_profile) in the user's home folder can define the jBASE environment for a user when he logs in to Linux.

3.3.1. Using IJU to set up the jBASE environment for users

The IJU utility (Initialise Jbase User) can be used to initialize an account directory for a user and create a suitable '.profile' file to set up the jBASE environment.

Log into the jBASE system using your jBASE user login. Once connected, run the command IJU.

This command will prompt you to supply details for a number of environment variables which will be used to populate the .profile in order for it to properly interact with jBASE.

In most cases the default options will be fine. However, make sure to answer Y to the prompt asking Do you wish to use the jsh as this will ensure that you access a jShell session after logging in.

4. Further Reading

Further reading relating to jBASE and it's component technologies is available from the jBASE Knowledgebase.

jBASE Agent

Accepts and Processes incoming client requests

jEDI Development Kit

Provides access to RDBMS from jBASE applications

jBASE jDBC Driver

Provides jDBC access to jBASE data files

jBASE ODBC Driver

Provides ODBC access to jBASE data files

Transaction Journaling

Logs jBASE database updates

jBASE Dataguard

Database Resilience within jBASE

jRCS

jBASE Remote Connectivity Service

jBASE Spooler

The jBASE Spooler

jSHELL

The jBASE Shell

mv.NET

Visual Studio development for MultiValue Data

For support related queries, please email Support.

5. Glossary of Terms

5.1. jBASE

An open database product that brings the strengths of MultiValue technology into the mainstream computing market; providing a multidimensional database, a development environment including a development language, and a middleware component allowing other mainstream and standards-based products to communicate with the jBASE products.

5.2. jBASE Distributed Locking Service (jDLS)

jDLS is responsible for resolving all record locking conflicts for jBASE processes. It runs in the background on your system and is commonly referred to as the lock daemon.

If jDLS is not running, jBASE will use the normal operating system locks. This is acceptable for small user populations, but the operating system locking mechanism has limits on the number of locks available, and on performance.

5.3. jBASIC

The language built in to jBASE, jBASE BASIC (jBC) is a dialect of BASIC that combines the power of stored procedure languages with a fully-fledged development language.

5.4. jCL

The jBASE Command Language is an implementation of the PROC processor found in other multivalue offerings. The jCL processor stores a complex series of commands that can be executed later by a single word or command, but does not require any compilation.

5.5. jed

The jBASE Editor. jed is a fully featured screen editor, which can be used for creating, modifying, or deleting records.

5.6. jEDI

The jBASE External Device Interface(jEDI). The jEDI enables applications to achieve seamless integration with foreign databases without changes to the jBASE MultiValue BASIC application code and logic. JEDIFILENAME_SYSTEM

5.7. jLP

The jBASE spooler program. This is the jBASE equivalent of the unix lp command.

5.8. jPLUS

jPLUS files provide large file support on 64 bit UNIX and Windows platforms, such that Hash files can extend beyond the normal 2GB operating system limit.

5.9. jQL

The jBASE Query Language (jQL) is a powerful and easy to use facility which allows you to retrieve data from the database in a structured manner and to present the data in a flexible and easily understood format.

5.10. jRCS

The jBASE Remote Connectivity Server. jRCS runs as a Windows service and provides jBASE functions to remote programs. jBASE System Manager uses jRCS to perform its management tasks.

5.11. jServControl

A jBASE command line utility allowing the install, configuration and removal of jBASE services

5.12. JSH.exe

A windows executable that initiates a jSHELL session.

5.13. jshmd

jBASE service that initiates the required areas of shared memory for systems which utilise operating system locking.

5.14. jSHELL

The jBASE shell. It can be invoked as your login shell by using the normal system administration software supplied with the platform. Either via .bat files (Windows) or .profiles (Unix ).

5.15. Environment Variables

jBASE uses a number of environment variables to modify jBASE behaviour

5.16. HOME

The 'HOME' environment variable. This stores the pathname of user home directory

5.17. Multisession

A Multisession license allows for up to ten concurrent sessions from a single IP address or system name to the database.

5.18. System.Properties

The 'system.properties' file resides in the %JBCRELEASEDIR%\config directory and stores jBASE license keys and compiler instructions.

5.19. Websession

A Websession license allows up to a ten sessions originating from a Web Server or Terminal Server (single IP address). For example with three of these licenses the Web Server would have 30 concurrent sessions available.