APIs

The APIs to Polyhedra fall into three main categories: Those that allow applications to act as clients to a Polyhedra database, those that allow control of a Polyhedra database server, and those that allow fine-tuning of the behaviour of a Polyhedra server.

Client APIs

ODBC

This is the main client API for Polyhedra, available on all supported platforms. It is based on the international standard, and allows access to Polyhedra features such as active queries, but there are some Polyhedra-specific extensions to support an event-driven model, and to allow the establishment and tuning of connections to a pair of servers running in a fault-tolerant configuration. Polyhedra recommend the use of this API rather than the older, Callback API, as it is standards-based; also, if use is made of the SQLPrepare/SQLExecute functions, then it imposes less load on the server.
 
On all platforms, ODBC client applications can be linked with the Polyhedra library directly, allowing them to make use of the Polyhedra-specific extensions to ODBC. Alternatively, on Windows and Linux/x86 the Polyhedra library is available as an ODBC driver - in this case, the client applications would be linked with the corresponding ODBC driver manager, and connection parameters can be used to specify that a fault-tolerant connection is required. If interfacing via a driver manager, the Polyhedra-specific API extensions for event handling are not available, but it is still possible to launch active queries, and it is possible to specify a connection is fault-tolerant when registering the Data Source Name (DSN). 

JDBC

released in Q4 2000, the Polyhedra JDBC driver allows the Java programmer to access a Polyhedra database. It is a Type 4 driver, written in Java, and so works with any Java engine that incorporates a JDBC driver manager. The release kit also contains a second set of class definitions, for use with Java engines such as CDLC that do not support JDBC. The driver supports JDBC 2.0 with some limitations. It uses the Polyhedra Native Protocol over TCP/IP to communicate with the Polyhedra database server, and has some support for fault-tolerant connections and active queries. The mapping between Polyhedra SQL data types and Java data types is described by the following table:
 

Polyhedra JDBC Type

Polyhedra SQL Type

Java Type

BINARY

binary

byte[]

BIT

bool

boolean

DOUBLE

float

double

BIGINT

integer64

long

INTEGER

integer

int

REAL

float32

float

SMALLINT

integer16

short

TIMESTAMP

datetime

java.sql.Timestamp

TINYINT

integer8

byte

VARCHAR

char, varchar

java.lang.String

(Alternatively, a Java client can use JDBC to access Polyhedra via a JDBC-ODBC bridge, and thus avoiding the use of the Polyhedra JDBC driver, but this requires the Polyhedra ODBC driver to be installed on the machine running the bridge.)

Callback Client API

This API contains all of the active query management to interface to any Polyhedra server. This API supports active and static queries for both SQL and direct object queries. It is based on the callback model of programming (hence its name) and so is well-suited to the event-driven nature of Polyhedra.

OLE DB

An OLE DB data provider is available for use by Windows programmers. This allows OLE DB applications, and applications using ADO objects, to access the Polyhedra database in an efficient fashion; good use is made of the Polyhedra active query mechanism to notify the user code of changes in the database as they occur.

Server management

In many cases, a Polyhedra server will be operating stand-alone, managing access to a single database. (If you want multiple independent databases available on the same machine, you would have a number of instances of the Polyhedra server executable running independently, each with a different server access point.) If you want to have a fault-tolerant configuration of two servers providing resilient access to a database, this is possible with most editions of Polyhedra; at any time, one server would be acting as master, and the other (if running) would be  a read-only hot standby. Tou would normally have the two servers running on separate machines to avoid, say, a faulty PSU bringing down both servers.
 
Of course, in such configurations there has to be some sort of arbitration mechanism to decide which server operates in which role, and to determine when failover is to occur. Polyhedra does not have an inbuilt mechanism for performing such arbitration, and instead relies on external control. This could be via a specially-configured database running on a third machine, but it is more normal to use an arbitration process running on each machine, with a trusted means of communication between these two processes to avoid the risk of both servers being told to be master at the same time. The server can use TCP to talk to its arbitration agent, via a protocol defined in the RTDB reference manual, and the release kits contain the source code of a sample applciation that can be used as a framework for the arbitration agent. Depending on the platform on which the servers are running, alternative transport protocols can be used for talking to the arbitrator; where available, this will be documented in the platform-specific reference manual, and sample code included in the release kit for the platform.

Embedded API

In addition to the APIs described above, there are a number of special-purpose APIs that are collectively referred to as the Polyhedra embedded API (and documented in the 'Polyhedra on embedded systems' reference manual). These APIs can be used to 'fine-tune' the functionality of the Polyhedra database server, by providing alternative definitions of certain functions (and thus allow file-system calls to be intercepted, for example) or to provide tuning parameters to the memory management system used within the Polyhedra server.

Comments