Welcome to the PrimeBase 4.5 SDK

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



Contents:

1. Overview
2. Documentation and Support
3. The PrimeBase SDK
3.1 Installation
3.2 Post Installation Setup

4. Examples
5. Building the Examples

Windows
Macintosh
UNIX


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, WebObjects 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 PrimeBase SDK

Before using the PrimeBase SDK please read the PRIMEBASE LICENSE AGREEMENT. Only proceed to use the SDK if you are in agreement with the terms of this license.

The package contains the PrimeBase SDK. The PrimeBase SDK includes all available PrimeBase Application Program Interfaces (APIs). This includes the following:

1. The PrimeBase Interface (PBI or PBAPI): This is a highly efficient interface for database client software. Functions begin with the prefix PBI, and the prototypes are specified in the header file 'pbapi.h'. The PBAPI is based on standard SQL.

2. The PrimeBase Item Stream Interface (PBISI): This is an optional interface for diverse applications that wish to take advantage of the advanced features of the PrimeBase Virtual Machine. The functions begin with the prefix CL and the prototypes are specified in the header file 'dalapi.h'.

3. The PrimeBase Native Interface (PBNI): This is an interface used by native extensions to the PrimeBase Virtual Machine. The function prototypes are specified in the header file 'pbnative.h'.

4. The PrimeBase Open Server Interface (PBOSI): The interface is used to create plug-ins for the PrimeBase Open Server. Open server plug-ins connect PrimeBase to 3rd party data sources.  This API is not yet released.

Further documentation for the PrimeBase APIs is provided in the document the "PrimeBase API Programmer's Guide".

This SDK, which is available for UNIX, Windows and Macintosh platforms, provides a Project/Makefile which builds an example application or plug-in for each of the PrimeBase APIs mentioned above (PBOSI when available).

3.1 Installation

To install the SDK under UNIX, please note the following:

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 SDK.

You must run this script as user "root".

Under Windows and Mac classic environments unpack the archive and following the instructions below.

3.2 Post Installation Setup

UNIX and Mach-O:

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.

Windows:

To complete the installation of the PrimeBase client software on your machine you need to install the PrimeBase DLLs and the PrimeBase Unicode(tm) mapping files.

Create a folder called 'PB-SETUP' in your 'WINDOWS' ('WINNT' under Wndows NT /2000) directory. Copy the folder called 'unicode', in directroy 'setup' in this package to the 'PB-SETUP' folder.

Copy the dynamic link libraries PBVM.DLL and PBDS.DLL in directroy 'lib' in this package to the Windows 'WINDOWS\SYSTEM' ('WINNT\SYSTEM32' under Wndows NT /2000) directory.

Mac OS Classic:

To complete the installation of the PrimeBase client software in the Mac OS classic environment you need to install the shared libraries and the PrimeBase Unicode(tm) mapping files.

Create a folder called 'PrimeBase Setup' in your system "Preferences" folder. Copy the folder called 'unicode', in directroy 'setup' in this package to this folder.

Copy the shared libraries carbon libraries, "PBVMLib" and "PBDSLib", and the classic libaries, "PrimeBase VM Library" and "PrimeBase DS Library", to your system "Extensions" folder.

Mac OS X Carbon:

To run carbon application under Mac OS X that access PrimeBase check the following:

The Unicode(tm) mapping files must be installed in the directory '/usr/local/primebase/setup/unicode' ($PRIMEBASEHOME/setup/unicode), as it is for Mach-O based applications.

The classic libraries, "PBVMLib" and "PBDSLib" must be installed in the folder '/Library/CFMSupport'.


4. Examples

There are 3 examples in this SDK:

pbshell:
 
This is a program that demonstrates the PrimeBase API. It provides assorted tests which you can execute individually that demonstrate different API calls and how to use them. It has been designed so that developers can easily add their own tests to it for execution and debugging.
 
The PrimeBase API is an advanced DBMS API which combines the best features found in other DBMS APIs with API calls unique to PrimeBase that allow you to set and get PBVM variable data directly.
 
The advantage of the PrimeBase API over the Item Stream Interface is that the user doesn't have to know anything about PrimeBaseTalk (the native language of the PrimeBase Virtual Machine) to use it. Only knowledge of SQL is required. It also  conforms more closely to the look and feel of the ODBC API and APIs used by other DBMSs.
 
When 'pbshell' is executed a list of functions will be displayed. To execute a function from the list just enter the name of the function. The first function you should execute though is 'open' to open a connection to a PrimeBase server.

NOTE: The Perl and PHP interfaces for PrimeBase , which are available with source code, were both written using PrimeBase API. If you would like a more complete example, down load the Perl and PHP interfaces for PrimeBase and look at the source code.
 
dalshell:

This is an example shell based on the PrimeBase Item Stream Interface. This interace conforms to the original Data Access Language/Data Access Manager (DAL/DAM) interface.

The shell provides an interactive client application with direct access to the PBVM. PrimeBaseTalk (PBT) programs can be entered directly, and are submitted to the PBVM. When you enter the command 'go' the program is compiled and executed. Output from the program is then printed to the console.

Enter 'help' for a list of all commands available.
 
pbnative:

An example PrimeBase native plugin. The plug-in is a shared library (DLL) that when placed in the PrimeBase Virtual machine's setup/plugins directory will be loaded by the PrimeBase Virtual machine when ever it is loaded by a client application.
 
Native plug-ins enable developers to extend the PrimeBaseTalk language by adding their own functions which are accessed as if they where normal  PrimeBaseTalk functions but are implemented in 'C'.
 
The example plugin is a 'Hello World' type example but it demonstrates the major features of PrimeBase native plugins and can be used as the base for creating your own more useful plugins. The example implements a PrimeBaseTalk native function 'call_info()' which demonstrates getting parameter values and setting return values. The example also implements a PrimeBaseTalk Class 'NativeTest' with one method 'print_hello()' that prints a 'Hello World' type message.
 
After building the example PrimeBase native plugin and putting it in the PrimeBase Virtual machine's plugins directory. The PrimeBase Virtual machine searches for the plugin directory in this order:

UNIX and Mach-O:

  ./setup/plugins
  $PRIMEBASEHOME/setup/plugins

Windows:

  .\SETUP\plugins
  <Windows Directory>\PB-SETUP\plugins

Macintosh Classic:

  :setup:plugins
  <Preference Folder>:PrimeBase Setup:plugins

To test the plug-in:

Step 1:  Start the Automation Client (pbac) and open a session.
 
Step 2:  Enter the following:

  print call_info("Hello World");
  go

  Output:

    Parameter 1: PB_VCHAR[12,0] = Hello World
    Result 1: PB_VCHAR[1,0]
 

Step 3:  Enter the following:

  NativeTest nt = new NativeTest();
  nt:print_hello("Native Functions");
  go

  Output:

    A message from print_hello:
    Hello Native Functions!
 


5. Building the Examples

Windows:

The SDK for Windows provides a project which was create for MS Visual C++ version 4.0. Part of the project is a Makefile which can be build using NMAKE.EXE.

The project builds the following components:

pbshell:   PBShell.exe
dalshell:  DALShell.exe
pbnative:  PBNITEST.DLL

Once you have loaded the Example project, add the 'Include' directory in the SDK to your include paths, and the 'Library' directory to your directory paths.

The pbshell and the dalshell require the PBVM.LIB. When the programs run they require access to the PBVM.DLL, which can be found in the 'DLL' directory. Place the PBVM.DLL in your Windows System directory, or in the current working directory of the application.

Macintosh Classic:

The SDK for Macintosh includes a project for Metrowerks CodeWarrior Pro 8.

The project builds Classic, Carbon and Mach-O versions of the examples. The plug-in is also build for Windows:

pbshell:   Classic PBShell, Carbon PBShell, pbshell
dalshell:  Classic DALShell, Carbon DALShell, dalshell
pbnative:
Classic PBNITest Plug-in, Carbon PBNITest Plug-in, pbnitest.dylib, PBNITEST.DLL.

'pbshell' and 'dalshell' are Mach-O UNIX tools and can only be run from the terminal.

UNIX and Mach-O:

Use the unix command "make" to build the examples.

Makefile targets:

pbshell: Builds the pbshell example.
dalshell: Builds the dalshell example.
pbnative: Builds the pbnative example.
install: Installs the pbnative example plugin.
clean:  Removes any files that have been built.

If after linking the applications and executing them you get an error saying that the file "libpbvm.so" could not be found, check that the libpbvm.so file is executable and is either in /usr/lib or in some location in the dynamic loader's search path  as declared in the unix environment variable LD_LIBRARY_PATH.