Speedy User Documentation

The test environment library contains many functions which allows you to access the Speedy/Speedy1-databases more comfortable from your C-application. Furthermore it allows you to use extended functionality like binary large objects, database saving and “tolerant” database loading and much more.

Installation

You must copy the “dbsys”-library for Speedy and the “dbsys1”-library for Speedy1 to a directory which is searched by your compiler.

If you want to use some of the test environment functions without the Speedy/Speedy1-database you must link your program to the “msglog”-library.

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:\<Speedy-path>\INCLUDE

SET LIB="C:\Programme\Microsoft Visual Studio\VC98\LIB";"C:\Programme\Microsoft Visual Studio\VC98\MFC\LIB";d:\<Speedy-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 “Makefile” (“Makefile1” for Speedy1).

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

Library-Constants

In this section you find library constants.

SQL-Codes

Each database-table-structure has an iDB-field. You can set this field to the given constant and perform an <TABLE>_Do command which invokes the selected command.

SQL_NONE (0): Do nothing.

SQL_SELECTPK (1): Select element by primary key.

SQL_SELECTLK (2): Select element by logical key.

SQL_INSERT (5): Insert the given database-table-structure.

SQL_UPDATE (6): Update the given database-table-structure.

SQL_DELETE (7): Delete the given database-table-structure.

Ranges of Data-Types

SMALLINT/FShort:

SQL_DEFSHORT: The default-value is -32768.

SQL_MINSHORT: The minimum-value is –32768.

SQL_MAXSHORT: The maximum-value is 32767.

INTEGER/FLong:

SQL_DEFLONG: The default-value is -2147483647.

SQL_MINLONG: The minimum-value is -2147483647.

SQL_MAXLONG: The maximum-value is 2147483647.

FLOAT/FDouble/FAmount:

SQL_DEFDOUBLE: The default-value is -1.E+20.

SQL_MINDOUBLE: The minimum-value is -1.E+20.

SQL_MAXDOUBLE: The maximum-value is 1.E+20.

DATE/FDate:

SQL_DEFDATE: The default-value is ‘1800-01-01’.

SQL_MINDATE: The minimum-value is ‘1800-01-01’.

SQL_MAXDATE: The maximum-value is ‘2800-12-31’.

TIME/FTime:

SQL_DEFTIME: The default-value is ’00:00:01’.

SQL_MINTIME: The minimum-value is ’00:00:01’.

SQL_MAXTIME: The maximum-value is ’23:59:59’.

TIMESTAMP/FTimestamp:

SQL_DEFDATI: The default-value is ‘1800-01-01-00.00.00.000000’.

SQL_MINDATI: The minimum-value is ‘1800-01-01-00.00.00.000000’.

SQL_MAXDATI: The maximum-value is ‘2800-12-31-23.59.59.000000’.

Enumerates

DateType:

DATE_YYYYMMDD: Defines format: 20020524

DATE_DDMMYYYY: Defines format: 24.05.2002

DATE_DEFAULT: Defines format: 2002.05.24

TimeType:

TIME_DEFAULT: Defines format: 22.25.17

DatiType:

DATI_DEFAULT Defines format: 2002.05.24.22.25.17.123456

RndType:

RND_FINANCE: Defines financial rounding

RND_UP: Defines upward rounding

RND_DOWN: Defines downward rounding

ModeType:

MODE_30: Defines 30 days a month

MODE_30F: Defines 30 days a month, February has 30 days at 28th or 29th

MODE_ACT: Defines month has actual number of days

Library-Datatypes

C-Representation of Data-Types DATE, TIME and TIMESTAMP

The data-type DATE is internally represented by the structure ADATE which is defined by:

short sYear;

unsigned char sMonth, sDay;

The data-type TIME is internally represented by the structure ATIME which is defined by:

unsigned char sHour, sMin, sSec ;

The data-type TIMESTAMP is internally represented by the structure ADATI which is defined by:

short sYear ;

unsigned char sMonth, sDay, sHour, sMin, sSec;

long lMicro;

Data-Types for Database-Structure-Definition

The available data-types are stored in the file “typename.dat”. This file must be either in the current directory or in the directory defined by the environment variable “DBDAT_PATH”.

FSurrogat STRING [8]

FLogical LOGICAL

FChar_1 CHAR

FChar_2 STRING [2]

FChar_3 STRING [3]

FChar_4 STRING [4]

FChar_5 STRING [5]

FChar_6 STRING [6]

FChar_7 STRING [7]

FChar_8 STRING [8]

FChar_10 STRING [10]

FChar_12 STRING [12]

FChar_15 STRING [15]

FChar_16 STRING [16]

FChar_19 STRING [19]

FChar_20 STRING [20]

FChar_21 STRING [21]

FChar_24 STRING [24]

FChar_25 STRING [25]

FChar_30 STRING [30]

FChar_32 STRING [32]

FChar_35 STRING [35]

FChar_40 STRING [40]

FChar_46 STRING [46]

FChar_55 STRING [55]

FChar_58 STRING [58]

FChar_60 STRING [60]

FChar_68 STRING [68]

FChar_80 STRING [80]

FChar_120 STRING [120]

FChar_132 STRING [123]

FChar_140 STRING [140]

FChar_146 STRING [146]

FChar_160 STRING [160]

FChar_254 STRING [254]

FChar_255 STRING [255]

FChar_4000 STRING [4000]

FBinary_255 BINARY [255]

FBinary BINARY [4000]

FShort SHORT

FInt INT

FLong LONG

FAmount DOUBLE

FDouble DOUBLE

FDay SHORT

FMonth SHORT

FYear SHORT

FDate DATE

FTime TIME

FTimestamp DATI

Note: If you want to use the data-types in your program you must add a leading ‘T’ to the data-type-name; e.g. FTime will name TFTime. You can initialise variables by the INIT_<type-name> macro; e.g. INIT_FDate(a). You can assign values by the COPY_<type-name> macro; e.g. COPY_FDate(a,b). The default-value for each data-type can be named by DEF_<type-name>; e.g. DEF_FDate.

Msglog-Library-Functions

The library contains functions to handle error-output. If you are using the Speedy/Speedy1-library you must not link with the msglog-library because this functionality is already included in the Speedy/Speedy1-library.

Init_Msglog:

extern int Init_Msglog(char * filename, int kz_empty);

Initialises the message-logging functionality. If a file-name is given the messages are logged to this file. The file will get the extension “.log”. If the parameter ‘kz_empty’ is TRUE the log-file will be overwritten if it already exists; else new data will be added.

Note: You can specify an absolute path for the log-file. If you want to do so you must not use the “.log”-extension. The extension will be added automatically.

Close_Msglog:

extern void Close_Msglog(void);

If message-logging is directed to a file the file is closed.

Set_Msglog_Callback:

extern void Set_Msglog_Callback(void (* cb_func)(char*));

Defines a callback-function which shall be called every time an insert into the log happens.

Set_Msglog_Close_Callback:

extern void Set_Msglog_Close_Callback(void (* cb_func)(char*));

Defines a callback-function which shall be called when the Close_Msglog-function is invoked.

Log_Msg:

extern void Log_Msg(char * fmt, ...);

Adds data to the log. The function can be used very similar to the printf-function. The parameter ‘fmt’ is capable of the following variables: ‘%s’, ‘%d’, ‘%f’, ‘%ld’, ‘%lf’.

Msglog_Exit:

extern void Msglog_Exit(int rcode);

This function can be called to exit a program with the exit-code given by ‘rcode’. The function calls Close_Msglog and terminates the program.

Basis-Library-Functions

The library contains basic-functions which help you to handle data-structures and file-io.

Memory-Handling

mymalloc, myrealloc, myfree, mystrdup:

extern void * mymalloc(int size);

extern void * myrealloc(void * ptr, int size);

extern char * mystrdup(char * strg);

extern void myfree(void * ptr);

These functions check “out-of-memory”-errors and exit with return-code 1 in this case.

Hash-Tables

htinit:

extern void htinit(int max, int size);

Initialises the hash-table. The parameter ‘max’ defines the maximum number of characters to hold the identifiers in the hash-table. The parameter ‘size’ defines the maximum number of entries in the hash-table. The parameter must be a prime-number (e.g. 3001,5003,10007,15013,20011,30011,50021,100003,150001,200003,250007,300017). The function checks that the given size is a prime-number.

idstring:

extern char * idstring(int key);

Retrieves the key-string for a given key from the hash-table. The function returns NULL if the key is not found.

htinsert:

extern int htsearch(char * key_string);

Searches for a key-string in the hash-table. If the key is not found –1 is returned.

htinsert:

extern int htinsert(char * key_string);

Inserts a new item to the hash-table. The key for the new item is returned.

htinsert:

extern int htdelete(int key);

Deletes a key from the hash-table. If the key is not in the hash-table –1 is returned.

Lists

These functions defines access-methods for the List-data-type. You must initialise the list-functionality by calling ‘lsmeminit’ at program startup. Then you can allocate List-objects by declaring them (e.g. “List ls;”). You must initialise each List-object by calling ‘lsinit’.

lsmeminit:

extern void lsmeminit(int max);

Initialises the global cache memory for lists. The parameter ‘max’ defines the number of list elements which will be allocated and managed in a cache-function internally.

lsinit:

extern void lsinit(List * ls);

Initialises a List-object.

Make_List:

extern void Make_List(List ** ls);

Generates a new List-object on the heap. The object is automatically initialised.

lsempty:

extern int lsempty(List * ls);

Returns TRUE if the list is empty.

lsnumber:

extern int lsnumber(List * ls);

Returns the number of elements in the list.

lsinsert:

extern void lsinsert(List * ls, void * item);

Inserts a new item to the beginning of the list.

lssortinsert:

extern void lssortinsert(List * ls, void * item);

Inserts a new item at the end of the list.

lsdelete:

extern int lsdelete(List * ls, void * item);

Deletes the item from the list.

lsdelfst:

extern int lsdelfst(List * ls, void ** item);

Deletes the first item of the list. The pointer to the first item is returned in the parameter ‘item’.

lsfind:

extern int lsfind(List * ls, void * item);

Returns TRUE if the item is in the list.

lschange:

extern int lschange(List * list, void * old, void * new);

Changes item ‘old’ by item ‘new’ in the list.

lsfree:

extern void lsfree(List * list);

Frees all memory allocated internally for a list.

lsfreeall:

extern void lsfreeall(List * list);

Frees all memory allocated internally for a list and the memory of all items.

lsunify:

extern void lsunify(List * list);

Convert a list of lists into a single list.

lsinitread:

extern void lsinitread(List * list);

Initialises the read-pointer for sequential access to the list-items. The items in the list are returned from the start to the list to the end of the list.

lsinitread:

extern int lsread(List * list, void ** item);

Returns the next item from the list and sets the list-pointer to the next item in the list.

lsreadfst:

extern int lsreadfst(List * list, void ** item);

Returns the first item from the list into the parameter ‘item’.

lsdelread:

extern int lsdelread(List * list, void ** item);

Returns the next item from the list into the parameter ‘item’ and deletes it.

lsinitsortread:

extern void lsinitsortread(List * list);

Initialises the read-pointer for access to the list-items in their reverse sequential order.

lssortread:

extern int lssortread(List * list, void ** item);

Returns the next item from the list and sets the list-pointer to the next item in the list in the reverse sequential order.

lscopy:

extern void lscopy(List * ls1, List * ls2);

Assigns list ls2 to list ls1.

Note: The data items will only exists once!

lscat:

extern void lscat(List * ls1, List * ls2);

Adds all items from list ls2 to list ls1.

Note: The data items will only exists once!

lssortcat:

extern void lssortcat(List * ls1, List * ls2);

Adds all items from list ls2 to list ls1. The items in list ls2 will be read in the reverse order.

Note: The data items will only exists once!

lssort:

extern void lssort(List * ls, void * sortfunc);

Sorts all items in the list using the sort-function given by ‘sortfunc’. The sort function takes two item-objects as arguments. It must return –1 if the left item is smaller than the right item, 0 if they are equal and 1 if the left item is greater than the right item. Sorting is only possible it the list has less than 10000 items.

lsmoveleft:

extern void lsmoveleft(List * list, void * item);

Moves the item one item towards the beginning of the list. If it is already the first item no moving occurs.

lsmoveright:

extern void lsmoveright(List *, void *);

Moves the item one item towards the end of the list. If it is already the last item no moving occurs.

Trees

These functions defines access-methods for the Tree-data-type. You must initialise the list-functionality by calling ‘ltmeminit’ at program startup. Then you can allocate Tree-objects by declaring them (e.g. “Tree lt;”). You must initialise each Tree-object by calling ‘ltinit’.

ltmeminit:

extern void ltmeminit(int max);

Initialises the global cache memory for tree-objects. The parameter ‘max’ defines the number of tree elements which will be allocated and managed in a cache-function internally.

ltinit:

extern void ltinit(Tree * tree);

Initialises a List-object.

Make_Tree:

extern void Make_Tree(Tree ** tree);

Generates a new Tree-object on the heap. The object is automatically initialised.

ltempty:

extern int ltempty(Tree);

Return TRUE if the tree-object is empty.

ltnumber:

extern int ltnumber(Tree tree);

Return the number of items in the tree-object.

ltsearch:

extern int ltsearch(Tree tree, int key, void ** item);

Searches for the item in the tree. The item is identified by the given key. If the item is found it is returned in the parameter ‘item’. The function returns TRUE if the item is found; else FALSE.

ltinsert:

extern int ltinsert(Tree * tree, int key, void * item);

Inserts the item with its key into the tree. If the key is already defined FALSE is returned and no insert occurs.

ltdelete:

extern int ltdelete(Tree * tree, int key);

Deletes the key from the tree. If the key does not exists FALSE is returned.

ltchange:

extern int ltchange(Tree * tree, int key, void * item);

Changes the item with the given key to the new value given in parameter ‘item’. If the key is not found FALSE is returned.

ltfree:

extern void ltfree(Tree * tree);

Frees all internal memory of the given Tree-object.

ltfreeall:

extern void ltfreeall(Tree * tree);

Frees all internal memory of the given Tree-object and all memory of the referenced items.

ltdump:

extern void ltdump(Tree tree, List * list);

Dumps all items to the list given in the parameter ‘list’. The items are sorted.

ltdumpunsort:

extern void ltdumpunsort(Tree tree, List * list);

Dumps all items unsorted to the list given in the parameter ‘list’.

ltdumpkeys:

extern void ltdumpkeys(Tree tree, List * list);

Dumps all keys to the list given in the parameter ‘list’.

ltdumpsortkeys:

extern void ltdumpunsortkeys(Tree tree, List * list);

Dumps all keys unsorted to the list given in the parameter ‘list’.

Functions for Handling File-Extensions

All functions returns strings which are allocated on the heap. You must free the memory on your own.

setsuffix:

extern char * setsuffix(char * fn, char * suffix);

Sets the file-extension to ‘suffix’; e.g. file-name ‘test’ will get ‘test.log’ with suffix = ‘log’.

clearsuffix:

extern char * clearsuffix(char * fn);

Removes the file-extension.

getsuffix:

extern char * getsuffix(char * fn);

Reads the file-extension; e.g. file ‘test.log’ will return ‘log’.

Functions for Handling Files

filesize:

extern int filesize(char * fn);

Returns the size of the file.

filemodified:

extern int filemodified(char * fn);

Returns TRUE if the file has been modified.

validfilename:

extern int validfilename(char * fn);

Returns TRUE if the file-name is a valid filename; i.e. filename consists only of ‘_’, letters, digits or ‘.’.

exists_file:

extern int exists_file(char * fn);

Returns TRUE if the file exists.

del_file:

extern int del_file(char * fn);

Deletes file defined by ‘fn’. Returns TRUE if the file has been deleted.

Functions for Handling Directories

exists_directory:

extern int exists_directory(char * dirname);

Returns TRUE if directory exists.

make_directory:

extern void make_directory(char * dirname);

Creates the directory ‘dirname’.

remove_directory:

extern void remove_directory(char * dirname);

Removes the directory with all files and sub-directories in the directory.

genfnlist:

extern List genfnlist(char * pattern);

Creates a list of filenames and directory-names which match the given patterns; e.g. “*.log;*.ext”.

extractfnlist:

extern List extractfnlist(List * ls, char * pattern);

Creates a list of filenames from a list of filenames which match the given pattern. You can use ‘*’ for any characters or ‘$’ for a single character.

sortfnlist:

extern void sortfnlist(List * ls);

The list is sorted ascending.

genfnpatternlist:

extern List genfnpatternlist(char * path, char * pattern);

Creates a list of filenames and directories which match the given patterns; e.g. “*.log;*.ext”. You can specify the path to look for filenames.

genfilelist:

extern List genfilelist(char * path, char * pattern);

Creates a list of filenames which includes the directory-path and match the given patterns; e.g. “*.log;*.ext”. You can specify the path to look for filenames. Directories are ignored.

Functions for Reading/Writing Files

read_file:

extern char * read_file(char * filename);

Reads the text-file ‘filename’. You must take care to free the file-data returned.

read_binfile:

extern void * read_binfile(char * filename, int * fsize);

Reads the binary file ‘filename’. The size of the file is returned in ‘fsize’. You must take care to free the file-data returned.

write_file:

extern int write_file(char * filename, char * data);

Creates the text-file ‘filename’ with content ‘data’. If the file already exists it is overwritten.

write_binfile:

extern int write_binfile(char * filename, char * data, int size);

Creates the binary file ‘filename’ with content ‘data’ of size given by the parameter ‘size’. If the file already exists it is overwritten.

Test-Environment-Library-Functions

The library contains a rich set of functions which helps you develop Speedy/Speedy1 applications. The library-name for Speedy is “dbsys”, the library-name for Speedy1 is “dbsys1”.

String Manipulation Functions

These functions are mainly internally used by the DB-Preparator to generate the database-access-functions. Nevertheless you can use them in your applications to print data.

Hold_ValueStrings / Release_ValueStrings:

extern int Hold_ValueStrings();

extern int Release_ValueStrings();

These functions are required to manage the memory used by the string functions. The hold-function is required if you use the string manipulation functions. Otherwise internal used memory may be reused and the result string can be damaged. The hold-function must be always followed by a release-function-call.

Set_DigitsAfterComma:

extern void Set_DigitsAfterComma(int comma);

This function can be used to set the number of digits after the comma for FDouble- and FAmount-data-types.

Make_<Type>String:

extern char * Make_ValueString(char *strg, int size);

extern char * Make_DbValueString(char *strg, int size);

extern char * Make_String(char * strg);

extern char * Make_BinaryString(char * strg, int size);

extern char * Make_TimeString(ATIME * time);

extern char * Make_DateString(ADATE * dat);

extern char * Make_DatiString(ADATI * dati);

extern char * Make_FETimeString(ATIME * time);

extern char * Make_FEDateString(ADATE * dat);

extern char * Make_FETimestampString(ADATI * dati);

extern char * Make_CharString(char ch);

extern char * Make_LogicalString(char ch);

extern char * Make_AmountString(double btrg);

extern char * Make_ShortString(short int sval);

extern char * Make_LongString(long int lval);

extern char * Make_DoubleString(double dval);

extern char * Make_DoubleIntString(double dval);

extern char * Make_Reduce_String(char * strg);

extern char * Make_Reduce_NumString(char * strg);

extern char * Make_Reduce_HTML_String(char * strg);

extern char * Make_Reduce_HTML_NumString(char * strg);

extern char * Make_Reduce_HTML_Leading_Zeros(char * strg);

extern char * Make_HTML_DateString(ADATE * dat);

extern char * Make_HTML_TimestampString(ADATI * dati);

extern char Make_CharValue(char ch);

These functions are used to generate string-representations for data-types. The FE-functions do not show the default-values but an empty string. The HTML-functions generate html-code. Please see the code generated by DB-Preparator as examples for the usage of these functions.

Note: The default-number of digits after the comma is 2 for FAmount and 6 for FDouble; the digits are only shown if they are required.

Free_ValueStrings:

extern void Free_ValueStrings();

This function is required to free all internal memory which has been allocated for the generation of strings.

Fillup_String/Reduce_<*>String:

extern char * Reduce_String(char * strg);

extern char * Reduce_NumString(char * strg);

extern char * Reduce_Leading_Zeros(char * strg);

extern char * Reduce_HTML_String(char * strg);