Welcome to PrimeBase 4.5 ODBC

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



Contents:

1. Installation
2. About the PrimeBase ODBC Driver
3. Specifying Data Source Information
4. Options
5. Trouble Shooting
6. Performance
7. PrimeBase ODBC Specifications


Installation

Installation is done into the directory specified by the environment variable PRIMEBASEHOME. If it is not defined then PRIMEBASEHOME defaults to /usr/local/primebase. The PRIMEBASEHOME directory must be created and given read, write, and execute privileges for all users who may use the PrimeBase software before doing the installation. The default setting is recommended unless there is a reason for not placing the PRIMEBASEHOME directory in /usr/local/primebase.
To install this package execute the file "Install_PrimeBase". This will move the files to the correct locations inside of your PRIMEBASEHOME directory. The installer must be executed as the user 'root'.


About the PrimeBase ODBC Driver

This version of the PrimeBase odbc driver has no setup dialog. That means that for an application to make a connection via the PrimeBase ODBC driver it must supply all setup information including a user name and password. This can be done by calling SQLConnect() with a valid datasource name, user name password or calling SQLDriverConnect() with a full connection string containing all connection details.
For example to connect to the "daldemo" data source as setup in the example odbc.ini file you would call: SQLConnect(hdbc, "daldemo", SQL_NTS, "sa", SQL_NTS, "sa", SQL_NTS); where "sa" is both the user and password.
Also included with this package is an example odbc.ini file showing how to define a datasource called "daldemo". This will connect to a server called "soltest" via TCP at host ip 2312.1.32.198 and open the database daldemo.
You can use this as a template to setup a connection in your odbc.ini file which should be in the user's HOME directory or in /etc. If it is in your HOME directory then it must be called '.odbc.ini'.
 


Specifying Data Source Information

Data Source Name:The name that will be used to access this ODBC data source.
Database Name: The name of the PrimeBase database that will be accessed via this data source. The database must exist on the PrimeBase data server before you will be able to use this data source.

Client/Server Data Source Connection

This is the communication protocol setup to use if you are connecting to a PrimeBase database server running as a separate process.

Server Name: The name of the PrimeBase database server to connect to. This is the name that the PrimeBase database server publishes itself as. All PrimeBase servers come preinstalled with the published name "PrimeServer".

Communication Protocols: The following communication protocols are available:
 

TCP: Use the TCP protocol. (Available on all platforms.) This protocol requires the IP address of the host machine on which the PrimeBase database server is running such as "213.465.98.4".

Shared Memory: Connect to the PrimeBase database server using shared memory. (Available on Windows and Unix platforms.) To use this protocol the PrimeBase database server must be running on the same machine as the client application and the PrimeBase ODBC driver and PrimeBase database server must be using the same version of shared memory. Components from the same release will always have the same version of shared memory. If you are unsure about the shared memory versions, use TCP.

ADSP: Use the Apple Data Stream Protocol. (Available only on Mac platforms.) This protocol requires the Apple Talk zone in which the PrimeBase database server is running. The PrimeBase database server must also be published on ADSP.

Program Linking: Use Apple’s Program Linking protocol. . (Available only on Mac platforms.) This protocol requires that the PrimeBase database server is running on a Mac and is published over the Program Linking protocol.
 
 
 

 

Runtime Data Source Connection

This is the communication protocol setup to use if you want to access the PrimeBase database directly from your application. To do this you must specify the exact location of the PrimeBase data server’s root directory, or the application’s current working directory while running must be the same as the PrimeBase data server’s root directory.

The Server’s env root directory: The PrimeBase ODBC driver provides a file locator dialog that can be used to locate the runtime database server environment file "pbds.env". When located the data server’s root directory, which will be one directory above the location of the environment file, will be entered as the data server’s root directory. You can also enter this location by hand if desired. If the location entered is not an absalute path of the server’s root directory then the server’s root directory will be assumed to be relative to the working directory of your application.

Runtime data source advantages:

The advantage of using a runtime data source connection is speed and simplicity of installation. Everything is handled by the client application so there is no need to have a second process running somewhere to act as the database server.

Runtime data source disadvantages:

The disadvantage of a runtime data source is that only one process, be it a client application using a runtime connection or a PrimeBase database server, can access the database at any one time. This means that you can not access a database via a runtime connection that is already being accessed by a PrimeBase database server or some other application using a runtime connection. A single application can have multiple runtime connections to the same database though.
 
 


Options


Normally you will not have to use any of the optional settings, but if you are having problems will an application you may want to try activating some of the settings to see if things improve.

 
Disable Async mode:
This setting will prevent the PrimeBase ODBC driver from running in asynchronous mode. The result will be that the PrimeBase ODBC driver will behave as if it didn’t support asynchronous execution when a client application requests this behavior. Use this setting if you suspect that the application’s problems may be do to asynchronous execution.
Strict Conformance:
The PrimeBase ODBC driver supplies an option to enforce strict ODBC conformance. When this option is selected the ODBC driver will generate an error whenever it encounters an unsupported ODBC feature. When this option is not selected the ODBC driver will try and handle the unsupported features as best it can. For example when the "strict" option is not checked the ODBC driver will ignore unsupported qualifiers. The qualifiers that it is referring to are the qualifier parameters which can optionally be supplied to the ODBC API functions used to lookup database information such as SQLPrimaryKeys(). When strict conformance is requested the PrimeBase ODBC driver will return the error "Qualifiers not Supported".
You may want to activate this setting if the application is not working properly and you suspect that it may have something to do with PrimeBase ODBC driver incorrectly handling an unsupported feature.
API Logging:
When this setting is activated all calls to the PrimeBase ODBC driver and the translated statements that are passed to the PrimeBase virtual machine will be logged. Use this if you want to see what is going on inside of the PrimeBase ODBC driver or if you want to report a problem.
If you think that there is a problem in the PrimeBase ODBC driver send the log along with a description of what you think is the problem to "support@PrimeBase.net" and someone will look at it and get back to you as soon as possible.
NOTE: Turning on logging will have a very negative effect on performance. Only use it when required.
 
 


Performance

The PrimeBase ODBC driver is very tightly coupled with the PrimeBase virtual machine. As a result there is very little, if any, performance cost for using the ODBC interface as opposed to the native PrimeBase API. If you think there is a problem with performance please check to make sure that the PrimeBase ODBC driver API logging is not activated.


Trouble Shooting

If you are having problems setting up a connection to a PrimeBase server with ODBC here are some things to check.

Client/Server Data Source Connection


Runtime Data Source Connection
 


 

Suspected PrimeBase ODBC Driver Problems:
If you think that there is a problem in the PrimeBase ODBC driver with reguards to your application, do the following:


NOTE: Turning on logging will have a very negative effect on performance. Only use it when required.


 
 
 


PrimeBase ODBC Specifications

 

ODBC Conformance:

The PrimeBase ODBC driver conforms to the ODBC 2.1 specifications with a level 1 API and Core level SQL grammar with the following additions.
Functions
In addition to the level 1 functions the following level 2 API functions have been implemented :
SQLNumParams
SQLSetPos
SQLColumnPrivileges
SQLForeignKeys
SQLPrimaryKeys
SQLProcedureColumns
SQLProcedures
SQLTablePrivileges
 
Data types
The PrimeBase ODBC driver supports the Minimum and Core SQL data types as well as the following Extended SQL data types:
 
SQL_BIT
SQL_TINYINT
SQL_VARBINARY
SQL_BINARY
SQL_DATE
SQL_TIME
SQL_TIMESTAMP
SQL_LONGVARCHAR
SQL_LONGVARBINARY
SQL_UNICODE


 

Connection string keyword/attribute pairs:

For a more detailed description of these key/attribute pairs reffer to the section Specifying Data Source Information.
UID: The name of the user to use for making the connection. (required)
PWD: The user's password.
DATABASE: The name of the primebase database to be opened.(required)
SERVER: The name that the PrimeBase server is published under, for example "PrimeServer". (required for non runtime connections)
PROTOCOL: The communication protocol to use. (required)
Possible values are: "TCP", "IPC" (Unix and Windows only.), "ADSP" (Mac only.), "PPC" (Program linking, Mac only.), "MEM" (Runtime Connection).
PROT_OPTS: Protocol specific options, for TCP this is the IP address, For ADSP this is the Apple zone. (required for ADSP and TCP, for all other protocols this value is ignored.)
DATABASEROOT: The data server’s root directory used for a runtime connection. . (required for MEM protocol, for all other protocols this value is ignored.)
OPT_DISABLE_ASYNC: Option setting. Disables the use of asynchronous mode by the client. Possible settings: "YES", "NO". Default: "NO".
OPT_STRICT_CONFORMANCE: Option setting. When this option is set to "YES" the ODBC driver will generate an error whenever it encounters an unsupported ODBC feature. Possible settings: "YES", "NO". Default: "NO".
OPT_APILOG:Option setting. The name and path of the log into which the logging is to be written. If the file doesn't exist it will be created. API logging will be activated if a value is specified for this key.
 
Example settings:
PROTOCOL=TCP
PROT_OPTS=212.1.32.198
DATABASE=odbc_test
SERVER=PrimeServer
OPT_DISABLE_ASYNC=NO