ReadMe - FrontBase 4.x on SuSE Linux

1. Introduction
2. The components of a FrontBase configuration
3. The innards of a FrontBase installation
4. Download and installation
5. Post installation
6. sql92 - super brief introduction
7. Getting started
7.1 The sql92 command line tool
7.2 The FrontBaseJManager Java application
8. Transactions - please read
9. Documentation
10. Installing a license string

1. Introduction

FrontBase is a high performance, scalable, SQL 92 compliant relational database server created in the internet age for universal deployment.

FrontBase requires a license to run in non-expiring mode. Licenses for the complete functionality of FrontBase are free and may be obtained from the Buy section of the FrontBase Web site: http://www.frontbase.com.

2. The components of the FrontBase configuration for SuSE Linux

a) FBExec The FBExec is a service background process that is typically started automatically when the computer is restarted. The FBExec provides status, management and access information to all client applications.
b) FrontBase FrontBase is the actual database server. There is a FrontBase process running for each running database. A FrontBase process is typically started by various management applications, but can also be started from the command line.
c) sql92 A command line tool for managing and accessing databases. sql92 will let you create, start and stop databases, connect to databases, and execute SQL statements.
d) FBTLogs A command line tool for summarizing the transaction log of a database.
e) FBTLog A command line tool for displaying (portions of) the transaction log of a database as SQL statements.
f) FBReplicator The replication daemon distributing transactions from a replication master to its replication clients.
g) FBRAccess A command line tool for inspecting and managing a replication setup.
h) FBKeyGenerator A command line tool for generating encryption keys.
i) FBChangeKey A command line tool for changing the encryption of a database.
j) FBInfoCenter A command line tool which prints out details about your FrontBase installation and your machine.
k) FBCAccess A C library providing the API that allows client applications to administrate and connect to FrontBase databases.

3. The innards of a FrontBase installation

FrontBase is installed into a number of directories on the target computer system. The core installation directory (FrontBase home directory) for SuSE Linux is /opt/FrontBase.

The subdirectory structure of the core installation directory is as follows:

   Backups         Default backup directories, one for each database
   Collations      Collation files
   Databases       Database main files and database specific files like SQL log files, cluster description files, etc
   Documentation   An SQL example, the FrontBase license agreement and this Readme file
   Library         Files used by the FrontBase server process
   TransactionLogs Transaction log directories, one for each database
   Translations    Translation files
   bin             The executable components
   include         Header files for e.g. the FBCAccess library
   lib             Client side libraries.

4. Download and installation

The latest version of FrontBase can always be downloaded from the Download area of the FrontBase Web site.

If you have an installation of a previous version of FrontBase, it should be uninstalled prior to installing the new version, as follows (in a terminal window, logged in as root):

   rpm -e FrontBase

Once you have downloaded the .rpm file, install it as follows (in a terminal window, logged in as root):

   rpm -i FrontBase-<version>.rpm

Please note that we do not support using the -U option for rpm.

Please note that the FBExec is installed to be automatically started when the computer is restarted. The FBExec is also started as part of the installation process, i.e. there is no need to restart the computer after installation.

5. Post installation

Once you have installed FrontBase it is a good idea to include /opt/FrontBase/bin in the search path of the various accounts that will use the FrontBase tools. This step is not necessary, but it can make your command line tool life easier.

There is no need to restart the computer after an installation, but it is a good idea to verify that the FBExec process is running by doing (from a terminal window):

   ps axc | grep FBExec

which should produce output like the following example:

15848 tty1     S      0:03 FBExec

If for some reason the FBExec isn't running, try to launch it from the command line:

   /opt/FrontBase/bin/FBExec &

In case of problems, you can e-mail support@frontbase.com and ask for help.

6. sql92 - super brief introduction

sql92 is an interactive command line tool which allows you to manage and access all databases in the network. sql92 is launched by issuing the following shell command:

   /opt/FrontBase/bin/sql92

To create and start a database:

   sql92> create database firstdb;

To connect to a database:

   sql92> connect to <database-name> [on <host-name>] [user <user-name>];

If you omit the host name, the current host name is used, and if the user name is omitted, the login name is used.

Always terminate sql92 commands with a ';'.

Quit sql92 by entering quit<enter> or by pressing Ctrl-D.

The sql92 help command:

   sql92> help;

will print a summary of the available sql92 specific commands.

7. Getting started

7.1 The sql92 command line tool

Open a terminal window and launch the sql92 tool:

   /opt/FrontBase/bin/sql92

Enter the following sql92 commands (the semicolons are important):

   create database firstdb;
   connect to firstdb user _system;
   create user test;
   commit;
   disconnect current;
   connect to firstdb user test;
   values(server_name);
   disconnect current;
   connect to firstdb user _system;
   stop database;
   delete database firstdb;

Congratulations! You have just created a database, connected to it three times, created a new user, committed a transaction, and deleted a database. It is as simple as that!

7.2 The FrontBaseJManager Java application

FrontBaseJManager is a Java application which you may separately download and install. The following is a simple example of its use, once the application has been started.

1. Click the "New" button in the "Monitored Databases" window, enter the proper host and database name and click the "Create" button. You should now see a line inserted into the "Monitored Databases" window, with the "Status" field eventually becoming "Running", indicating that the database has been created and is running.
2. Double-click on this line and then enter _SYSTEM as a user name in the "Open" window that appeared; then click the "Create" button.
3. Click the User tab in the management window that has appeared, click on the "New User" button, enter TEST as the user name and click the "Create" button.
4. Close the management window.
5. Click the "Connect" button in the "Monitored Databases" window; enter TEST as the user name and click the "Open" button.
6. Click "SQL Interpreter" in the management window.
7. Enter the following in the lower text view: values(server_name);, and click "Execute SQL". A window displaying a single row with information about the FrontBase Server appears.
8. Close the result and the management windows.
9. Select the database line in the "Monitored Databases" window.
10. Click the red "Stop" button and confirm that you wish to stop the database. The "Stop" button becomes gray indicating that the database is now stopped, and the "Start" button becomes green so that you may re-start the database.
11. Click the "Delete" button and confirm the delete action.

Congratulations! You have just created a database, connected to it twice, created a new user, committed a transaction, stopped and deleted a database. It is as simple as that!

8. Transactions - please read

A transaction is a grouping of a sequence of SQL statements into a unit; execution of the unit as a whole either succeeds completely, or, if one of the commands fails or is a ROLLBACK command, the database is left unchanged.

Transactions are initiated automatically by the server when needed. Most SQL statements need a transaction. A COMMIT or a ROLLBACK command ends the current transaction.

Most of the FrontBase tools use, as default transaction settings, SERIALIZABLE, WRITE, PESSIMISTIC, which has the consequence that access to referenced tables is effectively serialized.

The user may change the defaults according to the SQL 92 specification.

When you are working with the FrontBase tools, you should always remember to COMMIT or ROLLBACK transactions in order not to block access to the database.

If you try to access a table and it seems that your application or tool doesn't do anything, it is most likely waiting for some other session to COMMIT or ROLLBACK an active transaction. Neither your application/tool nor the FrontBase server is hanging!

FrontBase offers a feature called AUTO COMMIT, i.e. a way to tell the server that it should automatically commit each statement that is successfully executed. The sql92 command line tool uses, as default, this feature.

You can control the AUTO COMMIT feature by executing the following statements:

   SET COMMIT FALSE; -- Turns off AUTO COMMIT
   SET COMMIT TRUE;  -- Turns on  AUTO COMMIT

9. Documentation

The documentation for the FrontBase database server can be downloaded from the Documentation area of the FrontBase Web site.

Please take the time to peruse this documentation, so you at least have a good feeling for what's in there.

10. Installing a license string

Once you have obtained a valid license string, it must be installed on the computer where FrontBase is installed. You can use your favorite text editor to install the license, as follows:

Create a new file with a single line consisting of the 64-character license string, followed by a colon (:) and the 16-character license check, i.e. a total of 81 characters.

Save this file into:

   /opt/FrontBase/LicenseString

Once the license string has been installed, you need to restart all running FrontBase databases.

If you are in doubt as to whether the license string has been installed correctly, you can verify the installation by running FBInfoCenter from a shell:

   /opt/FrontBase/bin/FBInfoCenter 

This will print out the properties of the installed license string, including any problems.