Welcome to the PrimeBase 4.5 Application Server

Copyright © 2008, PrimeBase Systems GmbH. All rights reserved.



Contents:

1. Overview
2. Documentation and Support
3. The Enterprise Application Server
4. Installing and Running the Server
4.1 Post Installation Setup
4.5 Starting and Stopping Servers
4.5 Developer and Demo Versions
5. Getting Started
6. Documentation & Tutorial
7. Using the Application Server with a Web Server
7.1 Setting up the PrimeBase Application Server's Apache Server Module
8. Description of Contents

>PRIMEBASE LICENSE AGREEMENT



 


1. Overview

Welcome to PrimeBase 4.5

PrimeBase is a development platform for the production of client/server and web applications. It consists
of 3 main products: the PrimeBase Database Server, the PrimeBase Application Server, and the PrimeBase Open Server, all of which are based on open standards.

The PrimeBase Database Server is a relational Database Management System (DBMS) for Mac, UNIX
and Windows platforms. The PrimeBase Database Server supports all common database access
standards (PBT, SQL, ODBC, JDBC, PHP, Perl, RealBasic, EOF and DAL) and protocols (TCP/IP,
Shared Memory and Appletalk).

The PrimeBase Application Server allows rapid development and deployment of Web applications. The PrimeBase Application Server has many features that make implementing a Web application simple and efficient, including: an object-oriented programming environment and framework and multi-processor capabilities to ensure unlimited scalability.

The PrimeBase Open Server allows the PrimeBase Application Server or other applications using the PrimeBase Virtual Machine to connect to alternate data sources via PrimeBase Open Server plug-ins oaded by the PrimeBase Open Server. For example the Oracle plug-in enables you to access an Oracle database, or by loading the ODBC plug-in you will be able to access data servers via their ODBC drivers.


2. Documentation and Support

Some of the PrimeBase documentation including reference manuals and user guides is provided in PDF (Portable Document Format) and may be read and printed using Adobe Acrobat available, free of charge, from http://www.adobe.com. Other documentation is provided in HTML format and can be viewed with any browser.

Should you still have problems with the installation of this software, or you have any other questions then you are free to contact us by telephone at ++49 3890440 or via e-mail: support@primebase.net. If you have general support questions that may be interesting to the entire PrimeBase community, then we suggest you visit our Web-site, www.primebase.net, and join our mailing list.


3. The Enterprise Application Server

There are 2 versions of the PrimeBase Application server, the single process "Standard Application Server" and the multi-process "Enterprise Application Server". The "Standard Application Server" uses the executable file 'pbas' and the one process handles all requests. The "Enterprise Application Server" uses the executable files 'pbeas' and 'ase' which run in a master/slave configuration where 'pbeas' is the master or application server manager and 'ase' is the slave or application server engine.

Depending on the number of engines allowed by the activation key, the application server manager will start as many application server engine as specified in the environment file. Load balancing is then used to distribute the HTTP requests amoung the application server engines. If one of the application server engines shuts down unexpectedly the application server manager will automatically start another application server engine to replace it. In this way the application server manager guarentees 24/7 availability.


4. Installing and Running the Server

Before starting the PrimeBase Application Server please read the license agreement at the end of this document. Only proceed to use the PrimeBase Application Server if you are in agreement with the terms of this license.

If you have not already done so, we recomend that you create a new user (by convention called 'primebase') on your system for the PrimeBase software. Ensure that you have a least 20 MB of free disk space in the user's home directory.

Under Windows, simply unpack the archive to install the server. Under UNIX a shell script called "Install_PrimeBase" is provided to install the server.

You must run this script as user "root".

You will be asked where you want to install the server (choose a location in the home directory of the user primebase), who the owner of the server should be, and whether the server should be started at boot time.

Important Security Concern:
If you are running the Application Server as user 'root' or equivalent then anyone who is able to connect to the Application server may be able to upload and download files as 'root'. This can be very dangerous if a malicious user were to overwrite a file which the Application Server executes automatically on start up. So for this reason it is strongly recommended that the Application Server NOT be installed as root.

4.1 Post Installation Setup

In addition to the actual server installation, the installer places global resources in the location called $PRIMEBASEHOME. This is by default '/usr/local/primebase'.

After running the installer we recommend that you add the following path to your system PATH:

/usr/local/primebase/bin

This is the default location of all the PrimeBase executables.
 

4.5 Starting and Stopping Servers

You may use 'pbctl' to start, and stop any server installed on your machine, and to make changes to the installation. Enter 'pbct -h' for more information on 'pbctl'.

Alternatively you can use the 'start_standard_server' or 'start_enterprise_server' shell scripts to start the server and 'stop_application_server' to stop the server.

To attach a console to the application server running in the background, start the console (pbcon) program or use the 'application_server_console' script. The console executable may be started from any directory on the server machine.

You can then enter '#help' for help on the console commands.

You may enter CTRL-R to detach the console, leaving the server running in the background.
 

4.3 Developer and Demo Versions

The software in this directory will run for a limited period only. The activation information, including the expiry date is stored in the file 'pbas.key' in the installation directory.

When the demo period has expired the application server will still start but will return and error to any browser that accesses the application server.

You may request an extension to this demonstration period for development purposes by sending an e-mail to support@PrimeBase.net. Please state the nature and duration of your project.

We will send you a new 'pbas.key' file. To activate the application server, replace the file in this directory and restart the application server.


5. Getting Started

After you have started the application server you may access it using a Web Browser. To do this, start your browser and enter the following URL:

NOTE: If you are running the Enterprise Application Server then you will not be able to use the 47120 port but will have to connect via a web server.

http://<host_ip_address>:47120/system/

Where <host_ip_address> is the IP address or the host name of the machine running the application server and '47120' is the default port number used by the PrimeBase Application Server for HTTP (browser) access.

You can set the port number (and other system parameters) in the 'pbas.env' file using 'pbee' (PrimeBase Environment Editor) or the browser based interface provided by the application server.

If the application server is running on the same machine as your browser then you may use 'localhost' or the IP number 127.0.0.1 as <host_ip_address>.

After connecting with your browser, you can login to the application server using the user name 'admin' and password 'admin'.

NOTE: Please change the password of the user 'admin' immediately to prevent unauthorized access to your server.

The sub-directory 'system', included in the URL above, contains the PrimeBase Application Server developer's home page. The web site's users home page can be viewed using the URL:

http://<host_ip_address>:47120/

The default userís home page presents a list of installed modules.


6. Documentation & Tutorial

Documentation for the application server, including documentation of PrimeBaseTalk (a Java-like, integrated programming language), PrimeBase Enterprise Objects (pre-defined objects for creating Web applications) and an extensive tutorial describing how to use the new generation of PrimeBase tools is available on-line, after starting the application server.

In order to use the tutorial shipped with this package you will need to setup a PrimeBase Database Server. The "demo" application, which is pre-installed, also requires that the application server can connect to a database server.

In order to access a PrimeBase Database Server:

1) Download the latest version of the PrimeBase Database Server from www.PrimeBase.net.

2) Unpack and start the database server.

3) Start the application server and access the developer's home page (http://<host_ip_address>:47120/system/) using your browser.

4) Use the connection setup utility under "Configuration" to define a connection that uses the PrimeBase Virtual Machine ('libpbvm.so'). The PBVM can access pre-4.0 versions of the PrimeBase Database Server. Select this connection as the default.

If the database server is on the same machine as the application server then you can select the 'local_server' connection that has been pre-configured. If the database server is on a remote machine then you can edit and select the 'remote_server' connection.

5) Re-connect or logout for the change you have made to take effect.


7. Using the Application Server with a Web Server

Install a Web Server:

Install Apache (or compatible) Web Server on your machine if there isn't one installed already.

Install & Start the application server:

Install and run PBAS or PBEAS as described previously. For security reasons, do not place the application server's directory or it's contents in the Web Server's directory or any of its sub-directories.

Setup the CGI:

Copy the "primebase" executable from the 'cgi-bin' sub-directory to the Web Server's 'cgi-bin' directory (Web Server directory for CGI applications).

For Windows installations the 'cgi-bin' sub-directory also contains the dll "primebase.dll" which can be used with the Microsoft Internet Information Server (IIS).

Access PBAS from a Browser:

Start your browser and enter the following URL:

http://<host_ip_address>/cgi-bin/primebase/system/

Where <host_ip_address> is the IP address or host name of the machine running your Web Server.

'cgi-bin' is the Web Server CGI applications directory (this directory is usually called 'cgi-bin', but depends on how your Web Server is configured).

'primebase' is the executable started by the Web Server each time a page is requested from PrimeBase Application Server. This executable passes the request on to the application server and returns the result to the Web Server, then it quits.

The cgi will try to connect to an application server which has been published with the same name as the cgi executable, in the case of the default installation the cgi will look for an application server published as 'primebase'. If you have another application server running on the same machine that has been published as 'PrimeBase2' then you will need a cgi called 'primebase2'. In this way the URL:

http://<host_address>/cgi-bin/primebase/system/

will be handled by the PBAS published as 'primebase' and the URL:

http://<host_address>/cgi-bin/primebase2/system/

will be handled by the PBAS published as 'primebase2'.

7.1 Setting up the PrtimeBase Application Server's Apache Server Module

To do this you will need to know the location of the Apache Server's configuration files and the location of the modules directory. You can find the modules directory location by looking in the configuration file 'httpd.conf' for a line beginning with 'LoadModule'. The line will look something like:

'LoadModule cgi_module /usr/lib/apache/mod_cgi.so'

where '/usr/lib/apache' will be the modules directory. Usually the configuration files can be found in /etc/httpd/conf. You will also need to be able to restart the apache server. This can normally be done by entering the command:

'/etc/rc.d/apache restart' on a SuSE Linux installation
or
'/etc/rc.d/init.d/httpd restart' on a RedHat Linux installation.

If you cannot find these files or directories check with your system administrator on their locations and names.

Step 1:

Copy the file 'cgi-bin/mod_pbas.so' to the Apache server's modules directory.

Step 2:

Edit the Apache server's configuration file 'httpd.conf'. Assuming that your modules directory is '/usr/lib/apache/', search in the file for 'LoadModule'. If you don't see any lines beginning with 'LoadModule' then there is a good chance that your Apache server has not been configured to use dynamic shared objects (DSO). Ask your system administrator.

You should see several lines beginning with 'LoadModule', the order of these lines is important. Look for the one

'LoadModule cgi_module /usr/lib/apache/mod_cgi.so'

and just after it add the line:

'LoadModule PrimeBase_module /usr/lib/apache/mod_pbas.so'

After adding the LoadModule line go to the location in the file containing lines that start with 'AddModule' and insert the line:

'AddModule mod_pbas.c'

Apache now knows to load the PrimeBase module and now we must tell Apache when to call it. Assuming that the module is to be called with any URL starting with 'pbas' do the following:

Search the file for the string 'Location'.  You should see something like:

<Location /server-status>
 SetHandler server-status
</Location>

Add the lines:

<Location /pbas>
 SetHandler primebase-handler
</Location>

<Location /pbas_tcp>
 SetHandler primebase-tcp-handler
</Location>

There are 2 PrimeBase module handlers: "primebase-handler" communicates with the application server over shared memory while "primebase-tcp-handler" communicates over the TCP protocol.

Note:'primebase-handler, primebase-tcp-handler, and PrimeBase_module' are the internal name of the handler and must be entered exactly as they are here, case is important.

Save the file and exit the editor.

Step 3:

Restart apache by entering the command:

'/etc/rc.d/init.d/httpd restart'

If apache fails to start with an error that says something like:

Invalid command 'LoadModule'

then your apache server has not been configured to use dynamic modules.

Step 4:

Test the module by entering the command:

Start your browser, and enter the following URL:

'http://<host_address>/pbas/primebase/system/'

You should get the same results as when you do the same thing via the cgi by entering the URL:

'http://<host_address>/cgi-bin/primebase/system/'

Note that when using the module the component of the path that comes after 'pbas' must be the published name of the PrimeBase application server.

To connect to an instance of the application server published as PrimeBase2 you would enter the URL:

'http://<host_address>/pbas/primebase2/system/'
 


8. Description of Contents

This directory contains the following:

start_standard_server   - A shell script used to start the standard application
        server up in the background.

start_enterprise_server - A shell script used to start the enterprise
        application server up in the background.

stop_application_server     - A shell script used to stop the application
         server running in this location.

application_server_console  - A shell script used to connect an interactive
         console to the application server running in this
         location.

cgi-bin/   - directory containing Web Server comunication tools.

cgi-bin/primebase   - the CGI application started for each request by
                      the Web Server. It sends the request to the
                      application server and passes the reply back to
                      the Web Server.

cgi-bin/mod_pbas.so - the Apache server plugin module for PrimeBase.
       This can be used in place of the CGI when using
       tha Apache Web Server version 1.3.12 or later.
       It is loaded once by Apache at startup and
       then handles the sending of HTML requests to
       the applications server and passing replies back
       up to the Apache server. It has the advantage over
       the CGI in that a process isn't started for each
       HTML request.

docs/               - the application server document root directory.
                      This directory contains the documents executed
                      and served by the application server.

docs/index.htd      - the default document served by PBAS.

docs/manuals        - this directory contains PrimeBase documentation
                      in HTML format.

setup/              - directory containing environment, configuration
                      files and standard source code for PrimeBase
                      Enterprise Applications.

setup/pbas.env      - the application environment file containing
                      system parameters.

setup/pbvm.env      - the PrimeBase Virtual Machine environment file
                      containing settings and parameter values.

setup/connect.def   - the connection definition file. Defines
                      connections to various servers used by PBAS. The
                      top-most definition is used by default.

setup/exec/         - this directory contains system and startup code
                      used to boot Web applications.

setup/initialize/   - this directory contains code loaded when the
                      virtual machine is initialized. Initialize code
                      is shared by all sessions.

setup/startup/      - this directory contains code loaded when the a
                      session is created.