Copyright © 2001, 2002
Harald Wabnig
email: wabnig@testready.net
homepage: www.testready.net
Test Environment Programmer Documentation
Test Environment Programmer Documentation
Special Installation under Windows
General Configurations for Development under Microsoft Visual-C++ 6.0
and Windows ME
Special Installation under Linux
C-Representation of Data-Types DATE, TIME and TIMESTAMP
Data-Types for Database-Structure-Definition
mymalloc, myrealloc, myfree, mystrdup:
Functions for Handling File-Extensions
Functions for Handling Directories
Functions for Reading/Writing Files
Test-Environment-Library-Functions
Hold_ValueStrings / Release_ValueStrings:
Fillup_String/Reduce_<*>String:
File_Read_Open / File_Write_Open / File_Append_Open:
Functions for Random Number Generation
Functions for Handling Virtual Time
Functions for Handling Data-Type DATE
Functions for Handling Data-Type TIME
Functions for Handling Data-Type TIMESTAMP
Functions for Handling Binary Large Objects
Functions for Storing/Loading Databases
Functions for Analysing and Changing Database-Rows
Functions for Comparing and Rounding Double Values
Functions for Accessing the Database
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.
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.
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”.
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
[…]
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>”.
In this
section you find library constants.
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.
SQL_DEFSHORT: The default-value is -32768.
SQL_MINSHORT: The minimum-value is –32768.
SQL_MAXSHORT: The maximum-value is 32767.
SQL_DEFLONG: The default-value is -2147483647.
SQL_MINLONG: The minimum-value is -2147483647.
SQL_MAXLONG: The maximum-value is 2147483647.
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.
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’.
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’.
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’.
DATE_YYYYMMDD: Defines format: 20020524
DATE_DDMMYYYY: Defines format: 24.05.2002
DATE_DEFAULT: Defines format: 2002.05.24
TIME_DEFAULT: Defines format: 22.25.17
DATI_DEFAULT
Defines format: 2002.05.24.22.25.17.123456
RND_FINANCE: Defines financial rounding
RND_UP: Defines upward rounding
RND_DOWN: Defines downward rounding
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
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;
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.
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.
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.
extern
void Close_Msglog(void);
If
message-logging is directed to a file the file is closed.
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.
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.
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’.
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.
The library
contains basic-functions which help you to handle data-structures and file-io.
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.
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.
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.
extern
int htsearch(char * key_string);
Searches
for a key-string in the hash-table. If the key is not found –1 is returned.
extern
int htinsert(char * key_string);
Inserts a
new item to the hash-table. The key for the new item is returned.
extern
int htdelete(int key);
Deletes a
key from the hash-table. If the key is not in the hash-table –1 is returned.
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’.
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.
extern void
lsinit(List * ls);
Initialises
a List-object.
extern
void Make_List(List ** ls);
Generates a
new List-object on the heap. The object is automatically initialised.
extern int
lsempty(List * ls);
Returns
TRUE if the list is empty.
extern
int lsnumber(List * ls);
Returns the
number of elements in the list.
extern void
lsinsert(List * ls, void * item);
Inserts a
new item to the beginning of the list.
extern
void lssortinsert(List * ls, void * item);
Inserts a
new item at the end of the list.
extern
int lsdelete(List * ls, void * item);
Deletes the
item from the list.
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’.
extern
int lsfind(List * ls, void * item);
Returns
TRUE if the item is in the list.
extern
int lschange(List * list, void * old, void * new);
Changes
item ‘old’ by item ‘new’ in the list.
extern
void lsfree(List * list);
Frees all
memory allocated internally for a list.
extern
void lsfreeall(List * list);
Frees all memory
allocated internally for a list and the memory of all items.
extern
void lsunify(List * list);
Convert a
list of lists into a single list.
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.
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.
extern
int lsreadfst(List * list, void ** item);
Returns the
first item from the list into the parameter ‘item’.
extern
int lsdelread(List * list, void ** item);
Returns the
next item from the list into the parameter ‘item’ and deletes it.
extern
void lsinitsortread(List * list);
Initialises
the read-pointer for access to the list-items in their reverse sequential
order.
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.
extern
void lscopy(List * ls1, List * ls2);
Assigns
list ls2 to list ls1.
Note: The data items will only exists
once!
extern
void lscat(List * ls1, List * ls2);
Adds all
items from list ls2 to list ls1.
Note: The data items will only exists
once!
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!
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.
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.
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.
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’.
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.
extern
void ltinit(Tree * tree);
Initialises
a List-object.
extern
void Make_Tree(Tree ** tree);
Generates a
new Tree-object on the heap. The object is automatically initialised.
extern
int ltempty(Tree);
Return TRUE
if the tree-object is empty.
extern
int ltnumber(Tree tree);
Return the
number of items in the tree-object.
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.
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.
extern
int ltdelete(Tree * tree, int key);
Deletes the
key from the tree. If the key does not exists FALSE is returned.
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.
extern
void ltfree(Tree * tree);
Frees all
internal memory of the given Tree-object.
extern
void ltfreeall(Tree * tree);
Frees all
internal memory of the given Tree-object and all memory of the referenced
items.
extern
void ltdump(Tree tree, List * list);
Dumps all
items to the list given in the parameter ‘list’. The items are sorted.
extern
void ltdumpunsort(Tree tree, List * list);
Dumps all
items unsorted to the list given in the parameter ‘list’.
extern
void ltdumpkeys(Tree tree, List * list);
Dumps all
keys to the list given in the parameter ‘list’.
extern
void ltdumpunsortkeys(Tree tree, List * list);
Dumps all
keys unsorted to the list given in the parameter ‘list’.
All functions
returns strings which are allocated on the heap. You must free the memory on
your own.
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’.
extern
char * clearsuffix(char * fn);
Removes the
file-extension.
extern
char * getsuffix(char * fn);
Reads the
file-extension; e.g. file ‘test.log’ will return ‘log’.
extern
int filesize(char * fn);
Returns the
size of the file.
extern
int filemodified(char * fn);
Returns
TRUE if the file has been modified.
extern
int validfilename(char * fn);
Returns
TRUE if the file-name is a valid filename; i.e. filename consists only of ‘_’,
letters, digits or ‘.’.
extern
int exists_file(char * fn);
Returns
TRUE if the file exists.
extern
int del_file(char * fn);
Deletes
file defined by ‘fn’. Returns TRUE if the file has been deleted.
extern
int exists_directory(char * dirname);
Returns
TRUE if directory exists.
extern
void make_directory(char * dirname);
Creates the
directory ‘dirname’.
extern
void remove_directory(char * dirname);
Removes the
directory with all files and sub-directories in the directory.
extern List genfnlist(char * pattern);
Creates a
list of filenames and directory-names which match the given patterns; e.g.
“*.log;*.ext”.
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.
extern void sortfnlist(List * ls);
The list is
sorted ascending.
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.
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.
extern
char * read_file(char * filename);
Reads the
text-file ‘filename’. You must take care to free the file-data returned.
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.
extern
int write_file(char * filename, char * data);
Creates the
text-file ‘filename’ with content ‘data’. If the file already exists it is
overwritten.
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.
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”.
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.
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.
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.
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.
extern
void Free_ValueStrings();
This
function is required to free all internal memory which has been allocated for
the generation of strings.
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);