Copyright © 2001, 2002 Harald Wabnig

email: wabnig@testready.net    

homepage: www.testready.net  

 

 

Speedy1-Database Programmer Documentation

 

Speedy1-Database Programmer Documentation. 1

Introduction. 1

Installation. 1

Special Installation under Windows. 2

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

Special Installation under Linux. 2

API-Model 3

API-Constants. 3

API-Datatypes. 3

API-Functions. 4

Speedy1_Init 4

DBcreatedb. 4

DBdropdb. 4

DBsetdb. 4

DBstatus. 4

DBdisconnect 4

DBfinish. 5

DBreset 5

DBerrorMessage. 5

DBexec. 5

DBresultStatus. 5

DBresultErrorMessage. 5

DBntuples. 5

DBnfields. 5

DBfname. 5

DBfsize. 6

DBftype. 6

DBgetvalue. 6

DBgetbinary. 6

DBfillbinary. 6

DBclear 6

Examples. 6

 

Introduction

 

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

[…]

 

to

 

[…]

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.

DBresultErrorMessage

extern const char * DBresultErrorMessage(DBresult * res);

 

When a query-result has status

 DB_BAD_RESPONSE, DB_NONFATAL_ERROR, DB_FATAL_ERROR

(see function DBresultStatus) this function returns a string which explains why the query could not be successfully executed.

DBntuples

extern int DBntuples(DBresult * res);

 

When a query-result has status

 DB_TUPLES_OK, DB_NOTALL_TUPLES_OK

(see function DBresultStatus) this function returns the number of rows in the result-data.

DBnfields

extern int DBnfields(DBresult * res);

 

When a query-result has status

 DB_TUPLES_OK, DB_NOTALL_TUPLES_OK

(see function DBresultStatus) this function returns the number of columns in the result-data.

DBfname

extern const char * DBfname(DBresult * res, int field_num);

 

When a query-result has status

 DB_TUPLES_OK, DB_NOTALL_TUPLES_OK

(see function DBresultStatus) this function returns the column-name of column <field_num> in the result-data.

DBfsize

extern int DBfsize(DBresult * res, int field_num);

 

When a query-result has status

 DB_TUPLES_OK, DB_NOTALL_TUPLES_OK

(see function DBresultStatus) this function returns the size in character-bytes of column <field_num> in the result-data.

DBftype

extern DB_FieldType DBftype(DBresult * res1, int field_num);

 

When a query-result has status

 DB_TUPLES_OK, DB_NOTALL_TUPLES_OK

(see function DBresultStatus) this function returns the type of column <field_num> in the result-data.

DBgetvalue

extern char * DBgetvalue(DBresult * res, int tup_num, int field_num);

 

When a query-result has status

 DB_TUPLES_OK, DB_NOTALL_TUPLES_OK

(see function DBresultStatus) this function returns the value of column <field_num> in row <tup_num> as a string in the result-data.

DBgetbinary

extern char * DBgetbinary(DBresult * res, int tup_num, int field_num);

 

When a query-result has status

 DB_TUPLES_OK, DB_NOTALL_TUPLES_OK

(see function DBresultStatus) this function returns a character pointer to the binary value of column <field_num> in row <tup_num> in the result-data. You must copy the result-contents before you free the result-data.

DBfillbinary

extern void DBfillbinary(DBresult * res, void * data,

                         int tup_num, int field_num);

 

When a query-result has status

 DB_TUPLES_OK, DB_NOTALL_TUPLES_OK

(see function DBresultStatus) this function fills the binary value of column <field_num> in row <tup_num> in the result-data into the data-area pointed to by the pointer <data>.

DBclear

extern void DBclear(DBresult * res);

 

This function frees allocated memory to hold the data from the query-result.

 

Examples

 

See the source-code of the implementation of the Speedy1 shell interface (application “speedysh1”; it is included in the Speedy1-distribution).