Speedy User Documentation

The Speedy1-database can be accessed by usage of the C-API. You first have to install the Speedy1-database for development (see next section). The API allows you to access the Speedy1-database by sending SQL-commands in text-based manner. Although there is a binary access method this is not recommended. If you want fastest access you should use the program DB-Preparator which is a part of the test environment. This program automatically generates database-access-functions using the binary access-methods.

Installation

Please read the installation-instructions in the Speedy1-Database-User-Documentation.

Special Installation under Windows

General Configurations for Development under Microsoft Visual-C++ 6.0 and Windows ME

Required C/C++-Options (in “Project-Settings/C/C++”):

/Zp4 sets the correct alignment

/D _WIN32_WINNT=0x0400 defines that Windows is used

/D "SPEEDY1" must be defined to build with Speedy1-database (none defines Speedy-database)

Visual-C++ 6.0 project-files are included for all examples which allows you to build the binaries from the given source-codes.

You must add the paths for the include- and lib-directories (this is done in “Extras/Options/Directories”).

You can use a bat-file to start the VC++ environment setting the include- and lib-directories automatically.

The bat-file would look like:

SET PATH="c:\programme\microsoft visual studio\common\MSDev98\bin";"c:\programme\microsoft visual studio\VC98\bin"; C:\WINDOWS;C:\WINDOWS\COMMAND;

SET INCLUDE="C:\Programme\Microsoft Visual Studio\VC98\INCLUDE";"C:\Programme\Microsoft Visual Studio\VC98\MFC\INCLUDE";"C:\Programme\Microsoft Visual Studio\VC98\ATL\INCLUDE";d:\<Speedy1-path>\INCLUDE

SET LIB="C:\Programme\Microsoft Visual Studio\VC98\LIB";"C:\Programme\Microsoft Visual Studio\VC98\MFC\LIB";d:\<Speedy1-path>\LIB

SET DPATH=

start "C:\Programme\Microsoft Visual Studio\Common\MSDev98\Bin\MSDEV.EXE"

Of course, you must adjust the paths according to your local settings.

Note: You have to set up the MSDOS-program to use maximum possible environment space (4096). Furthermore you should set up the MSDOS-program to “close window on program termination”.

Special Installation under Linux

Make-files are include for all the applications and examples. If you have already installed the gcc-compiler you just have to type “make” in the directory of the application and the application is built. You can create a debug-version if you edit the “Makefile1” (“Makefile” for Speedy).

Change

[…]

#CFLAGS = -g

CFLAGS = -O2

[…]

CFLAGS = -g

#CFLAGS = -O2

[…]

and execute “make clean”. If you have installed the “ddd”-debugger you can then debug the application by typing “ddd <application>”.

API-Model

The C-API is very similar to the PostgreSQL C-API (i.e. libpq). So if you start with Speedy1 you can later on easily change to PostgresSQL and the other way round.

API-Constants

DB_ConnStatus:

DB_CONN_OK

Connection could be established.

DB_CONN_BAD

Connection could not be established.

DB_ExecStatus:

DB_EMPTY_QUERY

No result rows could be detected.

DB_COMMAND_OK

SQL-command could successfully be executed.

DB_TUPLES_OK

SQL-command evaluated all relevant data-rows.

DB_NOTALL_TUPLES_OK

SQL-command evaluated data-rows only partially.

DB_BAD_RESPONSE

SQL-command could not be executed successfully.

DB_NONFATAL_ERROR

SQL-command could not be executed successfully.

DB_FATAL_ERROR

SQL-command could not be executed successfully.

DB_FieldType:

DB_CHARACTER

Strings or character.

DB_BINARY

Binary value.

DB_SHORT

Small integer value.

DB_INT

Integer value.

DB_DOUBLE

Double value.

DB_TIME

Time value.

DB_DATE

Date value.

DB_TIMESTAMP

Timestamp value.

API-Datatypes

DBDATE:

short sYear

unsigned char sMonth

unsigned char sDay

DBTIME:

unsigned char sHour

unsigned char sMin

unsigned char sSec;

DBDATI:

short sYear

unsigned char sMonth

unsigned char sDay

unsigned char sHour

unsigned char sMin

unsigned char sSec

long lMicro

API-Functions

Here all relevant functions for using the C-API directly are listed.

Speedy1_Init

extern int Speedy1_Init(char * storage, char * dbname);

This function initialises the Speedy1-database. If the parameter “storage” is not empty it defines the directory-name where the Speedy1-database stores all required data to disk. If you provide an absolute path you can explicitly locate the place where the directory shall reside in your file system (Note: You must take care that the directory-path exists!). The parameter “dbname” defines the database which shall be used by the program. If the database does not exist it is automatically generated. If you do not give a “dbname” no database is initially selected. You have to create the database explicitly using the SQL-command “CREATE DATABASE <dbname>” or use the DBcreatedb command to connect to the database.

DBcreatedb

extern DBconn * DBcreatedb(const char * dbhost, const char * dbport,

const char * dboptions, char * dbname);

This function creates a new database named <dbname>, opens a connection to the new database and returns the created connector. Optional parameters are the host-name <dbhost>, the port-number <dbport>. The parameter <dboptions> is at the moment not used. Furthermore only the local host can be used.

DBdropdb

extern int DBdropdb(DBconn * conn);

This function destroys the database which is currently connected to by connector <conn>. The connector is freed.

DBsetdb

extern DBconn * DBsetdb(const char * dbhost, const char * dbport,

const char * dboptions, char * dbname);

This function opens a connection to an existing database named <dbname>, and returns the created connector. Optional parameters are the host-name <dbhost>, the port-number <dbport>. The parameter <dboptions> is at the moment not used. Furthermore only the local host can be used.

DBstatus

extern DB_ConnStatus DBstatus(DBconn * conn);

This function returns the current status of an opened connection. This function is mainly required when connections are established.

DBdisconnect

extern void DBdisconnect(DBconn * conn);

This function disconnects from the current database. You can reconnect to another database using the given connection.

DBfinish

extern void DBfinish(DBconn * conn);

This function closes the opened connection. You have to create a new database connection to access the database.

DBreset

extern int DBreset(DBconn * conn);

This function closes a opened connection and establishes a new connection. The status of the connection should be checked after a DBreset using DBstatus.

DBerrorMessage

extern const char * DBerrorMessage(DBconn * conn);

When a connector has status DB_CONN_BAD (see function DBstatus) this function returns a string which explains why no connection could be established.

DBexec

extern DBresult * DBexec(DBconn * conn, const char * query);

This function sends a query to the database-server and the result of the database request is returned. The format of the SQL-statements is as described in the separate document.

DBresultStatus

extern DB_ExecStatus DBresultStatus(DBresult * res);

This function returns the status of the query-result.