ReadMe - FrontBase 3.x on Windows NT / 2000
1. Introduction
FrontBase is a high performance SQL 92 compliant relational database server. FrontBase scales with ease from a personal database to the the enterprise level with very little configuration and management needed. FrontBase employs a unique technology lab elled Instant Versioning (pat. pending) that offers unparalleled protection against unfortunate database problems in case of e.g. a system restart. Instant Versioning also means instant restart of a database after a system restart.
The basic package is called E-Starter, which contains a free non-expiring license. The E-Starter package is a fully networked version including 3 technical support instances. There is no limit to the number of concurrent connections or the number of us ers. Developers can request a free developer license which will enable all features and be valid for 6 months. To obtain an E-Starter or developer license consult our Web site: www.frontbase.com.
2. The components of the FrontBase configuration for Windows NT/2000
| 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 manageme nt 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/stop databases, connect to databases, and execute SQL statements. | |||
| d) | FBWebEnabler | A background process that services requests from the FBWebManager application. Please note that the FBWebEnabler can manage databases on all hosts in a network with a FrontBase installation. | |||
| e) | FBWebManager | A small program that is started by the Web server whenever a service request (request/response loop) is received from a client browser. The FBWebManager forwards the request to the FBWebEnabler, waits for a reply and forwards this to the Web server (e.g. Apache). | |||
| f) | FBCAccess | A C library providing the API that allows client applications to administrate and connect to FrontBase databases. | |||
| g) | FrontBaseManager | An application for managing databases. The FrontBaseManager also contains "SQL 92" functionality; i.e. SQL statements can be sent to a FrontBase database for execution. Please note that the FrontBaseManager can manage databases on all hosts, no matter the OS, in a network with a FrontBase installation. | |||
| h) | FBInfoCenter | A command line tool which prints out details about your FrontBase installation and your machine. | |||
| i) | PlugIn for WebObjects 5 | The FrontBase PlugIn for WebObjects 5 needed for accessing FrontBase through a JDBC connection. |
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) is per default C:\usr\FrontBase.
The subdirectory structure of the core installation directory is as follows:
Backups Backup directories, one for each database Collations Collation files Databases All databases and the associated log files Library Files used by the FrontBase server process Templates HTML template files used by FBWebManager TransactionLogs Transaction log files Translations Translation files bin The executable components include Header files for e.g. the FBCAccess library lib Client side libraries.
The Windows NT/2000 specific components should be installed in:
FrontBaseManager.exe <drive>:\Program Files\FrontBase Tools
4. Download and Installation
FrontBase can be downloaded from download.
Once you have downloaded the .zip file, you should unzip the file using whatever tool you prefer. The unzip process should yield 3 .exe files and one .zip file; double-click on each of these 4 files and install them according to the instructions provid ed by the installer application.
The packages are:
FBServer-3.x.exe FrontBase server and associated tools and client side libraries FrontBasePlugin-x.y.z.exe Plugin for WebObjects 5 FrontBaseManager.exe FrontBaseODBC.zip ODBC driver
5. Post installation
Once you have installed FrontBase it is a good idea to include <drive>:\usr\FrontBase\bin in the search path of the various accounts that will use the FrontBase tools from the command line. This step is not necessary, but it can make your command line tool life easier.
If you have installed FrontBase on a drive different from C:, you need to define a system wide environment variable called FB_HOME_DRIVE which is to point to the drive with the FrontBase installation, e.g. F:. Bring up the Control Panel (Start->Sett
ings->Control Panel), double-click on the System icon and add the FB_HOME_DRIVE system environment variable.
The FBExec should automatically be installed as a service during installation. If this installation didn't succeed, you need to define t
he FBExec as a service. Bring up a shell, e.g. a Bourne or CommandPrompt shell, and enter the following command:
<drive>:\usr\FrontBase\bin\FBExec -install
Start the FBExec service using the Service Control Manager (Start->Settings->Control Panel on Windows NT and Start->Settings->Control Panel, double-click on Administrative Tools on Windows 2000, double-click on the Services icon). Using the
Service Control Manager, you can also specify that the FBExec service is to be started automatically whenever the computer is restarted.
You can verify that FBExec now is running by launching the "Windows Task Manager" (Ctrl-Alt-Del, cli
ck on Task Manager).
Similar steps can be taken to install the database server itself. Usually the FrontBaseManager or sql92 applications will do this, but if you don't use those tools, you can install each database instance as an service. For each
database do:
<drive>:\usr\FrontBase\bin\FrontBase -install <database-name>
You can then use the Services control panel to start and stop the databases. First time you start a database, the database file will automatically be created (in <drive>:\usr\FrontBase\Databases).
To use the FBWebManager you must first have installed a http server. The FBWebManager should automatically be installed as a service during installation. If this instalation didn't succeed, you need to define the FBWebEnabler as a service on your machi ne. Bring up a shell, e.g. a Bourne or CommandPrompt shell, and enter the following command:
<drive>:\usr\FrontBase\bin\FBWebEnabler -install <database-name>
You can then use the Services control panel on Windows NT to control the FBWebEnabler. Furthermore, you have to copy the <drive>:\usr\FrontBase\httpd\cgi-bin\FBWebManager.exe to your http server cgi-bin directory and the <drive>:\usr\Front Base\httpd\htdocs\FBWebManager to the http server document directory.
If messages other than a single startup message are produced, you can e-mail these messages to support@frontbase.com and get 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:
<drive>:\usr\FrontBase\bin\sql92
To create/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 will print a short summary of the sql92 command options.
7. Getting started
7.1 sql92 command line tool
<drive>:\usr\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 FBWebManager
The FBWebManager allows you to use a normal Web browser as the interface to managing and accessing FrontBase databases in your network. Once the FBWebManager has been installed on some computer in your network, you can use a Web browser on any computer in your network to interface it.
Assuming that you have successfully installed the FBWebManager (and the FBWebEnabler), you can connect to it from a normal Web browser by using a standard URL:
http://<host name or IP address>/cgi-bin/FBWebManager
The <host name or IP address> designates the host on which the FBWebEnabler/FBWebManager combo is installed. If this is your local machine, you can use:
http://localhost/cgi-bin/FBWebManager
| 1. | Click on the "CREATE" menu item (in the left-hand side of the browser window). | ||
| 2. | On the new page, enter the hostname (on which you want to create a database) firstdb as the name of the database and click on the "Create" button. | ||
| 3. | Assuming that you entered proper host and database names, an icon is added for the new database. You may have to click "Refresh" before the icon is shown a s solid green (indicating that the database is now running). | ||
| 4. | Click on the green icon so it gets a yellowish background and click on the "CONNECT" menu item (left hand side of the browser window). | ||
| 5. | Enter _SYSTEM as user name and click on the "Connect" button. | ||
| 6. | On the new page, which is titled "DATABASE: <DATABASE NAME>@<HOST NAME>", click on the "User" menu item (button). | ||
| 7. | Click on the "Add new user" button; enter test as the "New user name" and click on the "Add" button. | ||
| 8. | Go back to the overview page (click on "DATABASE MONITOR VIEW"), select the green icon denoting the firstdb database and click on the "CONNECT" m enu item. | ||
| 9. | Enter the proper hostname, test, as user name and click on the "Connect" button. | ||
| 10. | In the "Commands" text field enter VALUES SERVER_NAME; and click on the "Execute" button. | ||
| 11. | One row should be returned and displayed. In the log text field, you should now see the SQL statement together with some statistics. | ||
| 12. | Go back to the overview page (click on "DATABASE MONITOR VIEW"), select the green icon denoting the firstdb database and click on the "DELETE" me nu item. |
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!
7.3 FrontBaseManager
Locate the FrontBaseManager application (<drive>:/Program Files/FrontBase Tools) and double-click on the icon to launch it.
| 1. | Click on the main menu item "Database->Create" enter localhost as host name, Test as database name and click on the "OK" button. Click on the ma in menu item "Database->Add", select localhost and Test, click on the "OK" button. The database named Test is now displayed as an icon, in the main window for FrontBaseManager, with a green "spot" indicating that the database is run ning. | ||
| 2. | Double-click on the icon for Test; enter _system as user name and click on the "OK" button. | ||
| 3. | Click on the Users tab in the management window that has appeared, click on the "Add User" button, enter test as the user name and click on the "OK" ; button. | ||
| 4. | Close the management window. | ||
| 5. | Double-click on the icon for Test once more; enter test as the user name and click on the "OK" button. | ||
| 6. | Click on the sql92 tab in the management window. | ||
| 7. | Enter the following in the scrollable text view: VALUES SERVER_NAME;, and click on the "Execute" button. A scrollable view displaying a single row with infor mation about the server version appears. | ||
| 8. | Close the management window. | ||
| 9. | Select the icon for the Test database, i.e. the associated text should have a blue background. | ||
| 10. | Click on the main menu item "Database->Stop". The icon for Test now ends up being marked with a red spot indicating that the database is not running. | ||
| 11. | Click on the main menu item "Database->Drop" and confirm the 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
Transactions are started automatically by the server when needed. Most SQL statements need a transaction. A COMMIT or a ROLLBACK (SQL statements) 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 the 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. FrontBase PlugIn for WebObjects 5
The FrontBase PlugIn for WebObjects 5 is required for WebObjects 5 applications to work properly with FrontBase databases through a JDBC connection.
9.1 The innards of a FrontBase PlugIn installation
The FrontBase PlugIn consists of three items which are installed into a number of directories on the target computer system.
The Windows NT / 2000 specific components are installed in:
FrontBasePlugIn.EOMplugin C:\Apple\Developer\EOMBundles FrontBasePlugIn.jar C:\usr\FrontBase\Java frontbasejdbc.jar C:\usr\FrontBase\Java
These items will enable you to connect to FrontBase from WebObjects 5 using the FrontBase plugin.
9.2 Usage
EOModeler: In the login panel it is only necessary to specify a URL in the URL field. Alternatively the user and password fields can be extracted and entered into the respective fields in the login panel. The URL format is as follows:
| |||||||||||||||||||||
Example: jdbc:FrontBase://localhost/MyDatabase/user=admin/upasswd=secret
Please note that the user name is compulsory for the connection to work. If you have not created any users then you could simply use _SYSTEM (user=_SYSTEM) to get started.
10. Documentation
The documentation for the FrontBase database server can be downloaded from the documentation.
Please take the time to peruse this documentation, so you at least have a good feeling for what's in there.
The documentation as a whole can be downloaded as one document for offline perusal and reference.
11. 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 the FrontBaseManager to install the license or use your favorite text editor. If you want to use a text editor, the instructio ns are 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:
<drive>:\usr\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 try to start FrontBase from a shell:
<drive>:\usr\FrontBase\bin\FrontBase -console <database name>
If there are problems with the license string, FrontBase will print out error messages. You can also try and run the FBInfoCenter tool to get some more detailed information about the current i
nstallation of FrontBase:
<drive>:\usr\FrontBase\bin\FBInfoCenter