Liren Large Software Subsidy 7

home *** CD-ROM | disk | FTP | other *** search

/ Liren Large Software Subsidy 7 / 07.iso / c / c001 / 1.ddi / READ.ME < prev next >

Wrap

Text File | 1990-06-25 | 28.8 KB | 694 lines

C/Database Toolchest This file contains the latest information about the C/Database Toolchest Diskette(s), and complete instructions for using the C/Database programs and libraries with various C compilers. ****************************************************************************** PLEASE READ THIS FILE COMPLETELY before you use the Distribution Diskettes. ****************************************************************************** The Distribution Diskettes contains these things: executable version of the LDM program (compiled with Power C) demo files for LDM executable version of 6 utility programs (compiled with Power C) (dbtodbf, dbftodb, pressdb, prlabels, dumpdata, dumptree) CBT library (medium memory model) for Power C 2.0+, Turbo C 2.0+, Quick C 2.0+, and Microsoft C 5.0+ ISAM library (medium memory model) for Power C 2.0+, Turbo C 2.0+, Quick C 2.0+, and Microsoft C 5.0+ source for LDM program, compatible with Power C 2.0+, Turbo C 2.0+, Quick C 2.0+, and Microsoft C 5.0+ source for 5 of the utility programs (dbtodbf, dbftodb, pressdb, prlabels, dumpdata) All programs and libraries were compiled using the medium memory model (1 meg code space, 64K data space). To use a different memory model, you need to purchase the C/Database Library Source and re-compile for the desired model. The source for the dumptree program is not on the Distribution Diskette; it is included with the C/Database Library Source (available separately) because it uses some source files from the CBT library. You can purchase the C/Database Library Source separately to get these options: Control files for building ISAM and CBT libraries using the small, medium, and large memory models Source for the ISAM and CBT libraries, compatible with Power C 2.0+, Turbo C 2.0+, Quick C 2.0+, Microsoft C 5.0+ Source for the dumptree tool program, compatible with Power C 2.0+, Turbo C 2.0+, Quick C 2.0+, Microsoft C 5.0+ Power C: If you have a version of Power C earlier than 2.0, you should order an update. Updates are $5.00 + $2.00 S&H. Other Compilers: If you do not have one of the compiler versions listed above, you should order an update from the appropriate vendor. ******************* Installing C/Database Toolchest ***************** Most of the files on the Distribution Diskette(s) are in "archive" form to pack more files on the disk. The "install" program (described in Chapter 1 of the C/Database manual) unpacks only the files required for a specific compiler. On a hard disk, you will need somewhere between 1 meg and 1.4 meg of free space to install the Distribution Diskette(s), depending on the compiler that you are using. You will need an additional 720K to 800K to compile the LDM and tools programs. You will not be able to compile the LDM program unless you have a hard disk. To install the database for either Power C, Turbo C, Quick C, or Microsoft C, insert the C/Database Toolchest disk (disk 1 of 2 for 5 1/4" disks) into one of your floppy drives. Then run the "install" program by typing X:install, where X is the name of the drive containing the floppy disk (for 5 1/4" disks, the install program will tell you when to insert disk 2 of 2). For example, type A:INSTALL if the disk is in drive A. The install program will ask you a series of questions. At the end of each question, the default answer is displayed inside square brackets (ie. [default answer]). If the default answer is suitable, you may select it by simply pressing the enter key. By default, it is assumed that you have placed the master disk in drive [A], that you wish to install the files on a hard disk [h], that the directory to contain the files is [c:\c\database] (note: the install program will create the directory if it does not already exist), and that you will be using the Power C compiler [P]. The install program creates sub-directories named LDM and TOOLS. The LDM sub-directory contains the C source code for the LDM program. The TOOLS directory contains the C source code for various utility programs supplied with the C/Database Toolchest. ********************* Running/Making the LDM Program ****************** The distribution disk contains a sample database management progam named LDM.EXE. To run a demonstration of this program, first change to the directory containing the installed files (eg. cd \c\database), then simply type DEMO. The LDM program itself may be executed by typing LDM [filename], where the optional [filename] is the name of a database file (such as DEMO.DB). C:>cd \c\database change to database directory C:\C\DATABASE>demo run LDM demonstration C:\C\DATABASE>ldm demo run LDM interactively The C source code for the LDM.EXE program is in the sub-directory named LDM. If you want to compile and link this program, first change directories so that the LDM sub-directory is the current directory, then type MAKELDM. Assuming that the database is installed in the directory named \c\database on drive C, type the following commands to compile and link the LDM program. C:>cd \c\database\ldm change to LDM sub-directory C:\C\DATABASE\LDM>makeldm make new LDM.EXE The MAKELDM.BAT file compiles the LDM program using the medium memory model. If the compilation is successful, the LDM.EXE file in the parent directory is replaced by a new version of the program. In the process of compiling, a directory named MEDIUM is created to store the medium memory model object files. After you finish making any changes to the LDM program, you may want to remove this directory to recover the disk space. A batch file named CLEAN.BAT is provided for this purpose. After executing MAKELDM, you can change back to the parent directory and type CLEAN to remove the MEDIUM object file directory. C:\C\DATABASE\LDM>cd .. C:\C\DATABASE>clean If you have trouble compiling and/or linking LDM: ------------------------------------------------ It is assumed that your compiler can be executed from any directory and that it can find its own header files and libraries. If you have trouble compiling and/or linking the LDM program, you should execute the following commands for your particular compiler. Power C: assuming Power C is in the directory c:\powerc set path=c:\powerc QuickC: assuming QuickC is in the directory c:\qc assuming QuickC header files (.h) are in the sub-directory include assuming QuickC library files (.lib) are in the sub-directory lib set path=c:\qc set include=c:\qc\include set lib=c:\qc\lib Note: By default, makeldm assumes that the NMAKE.EXE program is present in your compiler directory. If you have MAKE.EXE rather than NMAKE.EXE, type the following to instruct makeldm to use MAKE.EXE. makeldm make Microsoft C: same as QuickC (substitute appropriate directory names) Turbo C: assuming Turbo C is in the directory c:\tc assuming Turbo C header files (.h) are in the sub-directory include assuming Turbo C library files (.lib) are in the sub-directory lib assuming Turbo C startup files (.obj) are in the sub-directory lib set path=c:\tc or use: set path=c:\tc\bin if Turbo C executables are in sub-directory bin ------------------ Note: By default, makeldm assumes Turbo C is in the directory \tc on the current drive. If not, you should specify the appropriate directory on the makeldm command-line as shown in the example below. However, if your Turbo C header files are not in the sub-directory INCLUDE, or the Turbo C library and startup files are not in the sub-directory LIB, then you must change the directory names specified in the definitions of CLIB, COBJ, and CFLAGS at the beginning of the file named LDM.MAK. makeldm c:\turboc ******************** Running/Making the Tools Programs ***************** The six programs named DBFTODB, DBTODBF, PRESSDB, PRLABELS, DUMPDATA, and DUMPTREE are described in chapter 15 of the C/Database Toolchest manual. You can run any of these six programs by simply typing the name of the program followed by the appropriate command-line arguments. See the manual for details. The C source code for all of these programs except DUMPTREE is installed in the sub-directory named TOOLS. The source code for the DUMPTREE program is provided with the C/Database Library Source. You can make new versions of these programs by typing MAKE name, where name is the name of the program (eg. make dbtodbf). MAKE name Note: Some versions of Microsoft C are supplied with NMAKE.EXE rather than MAKE.EXE. If you have NMAKE, type the following: NMAKE name Note: If you have Turbo C, you must also specify the .EXE extension. MAKE name.EXE If you specify ALL (eg. make all), then all six programs will be compiled and linked. If you have trouble making the tools programs, follow the instructions below for your particular compiler, then try making the tools programs again. ***************** Compiling and Linking Your Own Programs **************** Before compiling and linking a C program, you must configure the environment so that your compiler can locate its own header files (ie. files specified by #include statements) and library files. Before compiling programs that use the C/Database Toolchest functions, you must also do the following two things. First, you must tell the compiler where to locate the database header files. If your compiler can't locate the header files, you will get compile errors. Second, you must tell the linker to search the database library files (ISAM.LIB and CBT.LIB). If your linker doesn't search the database libraries, you will get link errors. The only files that your linker searches automatically are the standard libraries distributed with your compiler. The database header files and library files are located in the directory that you specified during installation (eg. c:\c\database). Since the database libraries (ISAM.LIB and CBT.LIB) are medium memory model libraries, you must select the medium memory model when you compile programs that use any of the database functions. The Power C compiler uses the medium memory model by default. However, the Turbo C, QuickC, and Microsoft C compilers use the small memory model by default. We will assume that you have already listed the directory containing your C compiler in the DOS PATH= statement (eg. PATH=c:\powerc). If you specify a full path name to the compiler directory (including a drive prefix), then you will be able to execute your compiler from any drive or directory. Read the discussion that follows regarding compiling and linking for your particular compiler. After configuring the environment for your particular compiler, you should make a directory for storing your database programs, then change to that directory when working on your database programs. For example, the following two commands will make a directory named db, then change directories so that db is the current directory. md \db cd \db ******************* Compiling and Linking with Power C ******************* The following discussion assumes that the database is installed in the directory named c:\c\database. If not, you will need to substitute the appropriate directory name where this name appears below. Assume that your C program is stored in a file named TEST.C. Method 1 (Using a project file) ------------------------------- Create a project file named TEST.PRJ containing the following lines. test pc /mm /ic:\c\database test test.exe pcl test;c:\c\database\isam.lib;c:\c\database\cbt.lib Now you can compile and link the TEST.C program by simply typing: pc test Method 2 (Using the LIBNAMES environment variable) -------------------------------------------------- Create a batch file (eg. DATABASE.BAT) containing the following lines: set pcoption=/ic:\c\database set libnames=c:\c\database\isam*.lib;c:\c\database\cbt*.lib The PCOPTION environment variable tells the compiler where to locate header files. The LIBNAMES environment variable tells the linker to also search the ISAM.LIB and CBT.LIB database function libraries. With the * present, the Power C linker searches ISAM.LIB and CBT.LIB for medium memory model, ISAMS.LIB and CBTS.LIB for small memory model, or ISAML.LIB and CBTL.LIB for large memory model. However, the small and large memory model database libraries are not available unless you purchased the C/Database Library Source. You should store this batch file in a directory that is listed in your PATH= statement so that it can be executed from any drive or directory. Before compiling, simply type the name of the batch file (eg. DATABASE) to execute the two set commands. Now you can compile and link the TEST.C program by simply typing the following: pc/e test When you finish working on programs that use database functions, you won't want the linker to waste time searching the ISAM.LIB and CBT.LIB libraries. Therefore you may want to create another batch file (eg. NORMAL.BAT) that sets the PCOPTION and LIBNAMES variables back to some normal state. For example, you might want to set PCOPTION so that only the Power C directory is searched for include files, and you might want to set LIBNAMES so that no external libraries are searched as follows: set pcoption=/ic:\powerc set libnames= ******************* Compiling and Linking with Turbo C ******************* The following discussion assumes that the Turbo C compiler is installed in the directory named c:\tc and that the database is installed in the directory named c:\c\database. It is further assumed that the Turbo C header files are in the directory named c:\tc\include and the Turbo C library and startup files are in the directory named c:\tc\lib. If not, you will need to substitute the appropriate directory names where these names appear below. Assume that your C program is stored in a file named TEST.C. Method 1 (Using TCC.EXE) ------------------------ If you use the command-line compiler TCC.EXE, you should create a file named TURBOC.CFG containing the following lines: -mm -Ic:\tc\include -Ic:\c\database -Lc:\tc\lib -Lc:\c\database The -mm option tells the compiler to use the medium memory model. The -I options tell the compiler where to locate header files. The -L options tell the compiler where to locate library files. The TURBOC.CFG file may be stored in the Turbo C directory (eg. c:\tc or c:\tc\bin), or optionally in the directory where you will be working on your database programs. With TURBOC.CFG file present, the TEST.C program may be compiled and linked by typing the following: tcc test isam.lib cbt.lib Method 2 (Using TC.EXE) ----------------------- If you use the integrated environment TC.EXE, you should create a new configuration file named TCCONFIG.TC, which may be stored in the Turbo C directory, or optionally in the directory where you will be working on your database programs. Type TC to execute the compiler. Notice that the menu includes an item named Options. This item allows you to set various compiler and linker options. The Options menu is selected by pressing <Alt> O. You can then select submenus by pressing one of the highlighted characters in the menu. Type the following key sequences to set the appropriate options: Set the memory model to medium: <Alt> O CMM <enter> for Turbo C or <Alt> O CCM <enter> for Turbo C++ Add c:\c\database to the list of include directories: <Alt> O DI c:\tc\include;c:\c\database <enter> for Turbo C or <Alt> O D c:\tc\include;c:\c\database <enter> for Turbo C++ Add c:\c\database to the list of library directories: <Alt> O DL c:\tc\lib;c:\c\database <enter> for Turbo C or <Alt> O D <tab> c:\tc\lib;c:\c\database <enter> for Turbo C++ Save the new options in TCCONFIG.TC: <Alt> O S c:\tc\tcconfig.tc <enter> for Turbo C or <Alt> O S for Turbo C++ The only way to instruct the Turbo C environment to link external libraries is to specify the library names in a project file. Therefore, you must create a project file for any program that needs to be linked with the database libraries. For Turbo C: ----------- Create create a text file named TEST.PRJ containing the following lines (where test is the name of your C program, and isam.lib & cbt.lib are the names of the two external libraries): test isam.lib cbt.lib After creating the TEST.PRJ file, execute Turbo C by typing TC, then specify TEST.PRJ as the project file by typing the following key sequence: <Alt> P P test.prj Now you can compile and link the TEST.C program by typing the following key sequence. <Alt> C M For Turbo C++: ------------- Execute Turbo C++ by typing TC, then type the following key sequences to create the TEST.PRJ project file: <Alt> P O test.prj <enter> <Ins> test.c <enter> isam.lib <enter> cbt.lib <enter> <Esc> Now you can compile and link the TEST.C program by typing the following key sequence. <Alt> C M ******************* Compiling and Linking with QuickC ******************* The following discussion assumes that the QuickC compiler is installed in the directory named c:\qc and that the database is installed in the directory named c:\c\database. It is further assumed that the QuickC header files are in the directory named c:\qc\include and the QuickC library files are in the directory named c:\qc\lib. If not, you will need to substitute the appropriate directory names where these names appear below. Assume that your C program is stored in a file named TEST.C. Method 1 (Using QCL.EXE) ------------------------ If you use the command-line compiler QCL.EXE, you should set the following environment variables: set include=c:\qc\include;c:\c\database set lib=c:\qc\lib;c:\c\database The INCLUDE variable lists the names of directories to search for include files. The LIB variable lists the names of directories to search for library files. The above two commands should be placed in a batch file (eg. DATABASE.BAT). Before compiling, simply type the name of the batch file (eg. DATABASE) to execute the two set commands. Now you can compile and link the TEST.C program by simply typing the following: qcl /AM test.c isam.lib cbt.lib The /AM option is required to instruct the compiler to use the medium memory model. Method 2 (Using QC.EXE) ----------------------- If you use the integrated environment QC.EXE, you should create a new configuration file named QC.INI, which may be stored in the QuickC directory, or optionally in the directory where you will be working on your database programs. Type QC to execute the compiler. Notice that the menu includes an item named Options. This item allows you to set various compiler and linker options. The Options menu is selected by pressing <Alt> O. You can then select submenus by pressing one of the highlighted characters in the menu. Type the following key sequences to set the appropriate options: Set the option for full menus (but only if not already set): <Alt> O F Set the memory model to medium (for version 2.0 or later only): <Alt> O MCM <enter> <tab> <tab> <enter> Add c:\c\database to the list of include and library directories: <Alt> O E c:\qc\include;c:\c\database <tab> c:\qc\lib;c:\c\database <tab> <tab> <enter> When you exit the QuickC environment, the QC.INI file will contain these changes. If a QC.INI file already existed prior to typing QC, then the changes are stored in the existing QC.INI file, which may be in your QuickC directory. Otherwise a new QC.INI file is created in the current directory. Since the QC.INI file is automatically updated anytime you change an option, you may want to copy the new QC.INI file to the directory where you will be working on your database programs. The only way to instruct the QuickC environment to link external libraries is to specify the library names in a program list. Therefore, you must create a program list for any program that needs to be linked with the database libraries. Assume that your C program is stored in the file named TEST.C. Type QC to execute the QuickC compiler. Then type the following key sequences to create a program list. Create a program list file named test.mak: <Alt> M S test <enter> Y Enter the names of the files that make up the program: test.c <enter> isam.lib <enter> cbt.lib <enter> Save the program list in the file named test.mak: <Alt> S Now you can compile and link the TEST.C program by typing the following key sequence. <Alt> M B *************** Compiling and Linking with Microsoft C *************** Follow the instructions for QuickC, Method 1. Substitute an appropriate directory name (eg. \cl) everywhere \qc appears. Also substitute the compiler name cl where qcl appears. ************************************************************************ --------------- Storing binary data in an ISAM file --------------- ************************************************************************ All of the fields in a data file are stored as strings. A field can contain any arbitrary string of bytes, except the binary zero. A binary zero indicates the end of the field. Since no zero bytes can be stored within a field, we cannot store binary values directly. Fortunately, it is easy to transform the value so that it can be stored. The most obvious way to store numbers as a string is to use one of the C library functions (such as sprintf()) to convert it to ASCII or printable form. This will work, but the resulting string usually takes quite a bit more space than the original binary value. Conversion from binary to ASCII is also a relatively time consuming operation. The string that we want to store is not restricted to only printable characters. It can contain any byte value except zero. So another way to store the number as a legal string is to simply remove the zeros. One way to do this is to represent the zero bytes as an escape character followed by another character. The functions in the object file named CVT_BTOS perform this type of transformation. They efficiently convert binary values to strings or vice versa. You can add the CVT_BTOS object file to the CBT library as follows: Power C: C:\C\DATABASE>merge cbt.lib cvt_btos Turbo C: C:\C\DATABASE>tlib cbt.lib + cvt_btos QuickC: C:\C\DATABASE>lib cbt.lib + cvt_btos; Microsoft C: C:\C\DATABASE>lib cbt.lib + cvt_btos; The following example stores a person's age as an integer value and an account number as a double precision value. The function cvt_itos() is used to convert an integer value to a string and the function cvt_stoi() is used to convert the string back into an integer. The function cvt_dtos() is used to convert a double precision value to a string and the function cvt_stod() is used to convert the string back into a double. #include <stdio.h> #include "isam.h" #include "cvt_btos.h" char first[20], last[20], age[5], account[20]; char *record[5] = {first, last, age, account, NULL}; char *names[5] = {"first", "last", "age", "account", NULL}; char *lastname[2] = {"last", NULL}; char *fields[5]; main() { Db_Obj *age_db; Index_Obj *age_index; char buffer[50]; if ((age_db = icreate_db("agedata", 0, names)) == NULL) { puts("Error - could not create agedata"); exit(1); } imkindex(age_db, "lastname", lastname); age_index = ihandle(age_db, "lastname"); strcpy(first,"Joe"); strcpy(last,"Isuzu"); cvt_itos(40, age); cvt_dtos(1000999.999, account); if (iaddrec(age_db, NULL, record) == ERROR) { puts("Error adding record"); exit(1); } ifindhead(age_db, age_index); if (igetrec(age_db, age_index, fields, buffer, sizeof(buffer)) == OK) printf("Age of %s %s is %d, account = %.3f\n", fields[0], fields[1], cvt_stoi(fields[2]), cvt_stod(fields[3])); else printf("error reading record\n"); } You can also store an arbitrary array of binary data as a field in the database using the functions: cvt_btos() and cvt_stob(). These functions work on a block of any size. For example, you can store a structure with cvt_btos(). struct st { int value1; double value2; char c; } stru; char buffer[25]; cvt_btos(&stru, sizeof(stru), buffer); When storing structures in a database, you should not attempt to save pointers. The database will contain the value of the pointer but not the data pointed to. When you read the data, the value of the pointer will no longer be valid. The functions contained in the CVT_BTOS object file are: unsigned char *cvt_ctos(char value, char *string); convert a character to a string unsigned char *cvt_itos(int value, char *string); convert an int to a string unsigned char *cvt_ltos(long int value, char *string); convert a long int to a string unsigned char *cvt_ftos(float value, char *string); convert a float to a string unsigned char *cvt_dtos(double value, char *string); convert a double to a string unsigned char *cvt_btos(void *value, int length, char *string); convert a block of data (such as a structure) to a string unsigned char cvt_stoc(char *string); convert a string to a character int cvt_stoi(char *string); convert a string to an int long cvt_stol(char *string); convert a string to a long int float cvt_stof(char *string); convert a string to a float double cvt_stod(char *string); convert a string to a double void *cvt_stob(char *string, void *result); convert a string to a block of data Source to these conversion functions is in the file "cvt_btos.c" in the TOOLS sub-directory. You can create a new medium memory model object file as follows: Power C: C:\C\DATABASE\TOOLS>pc /mm cvt_btos Turbo C: C:\C\DATABASE\TOOLS>tcc -mm -c cvt_btos QuickC: C:\C\DATABASE\TOOLS>qcl /AM /c cvt_btos.c Microsoft C: C:\C\DATABASE\TOOLS>cl /AM /c cvt_btos.c ************************************************************************ ----------------------- Indexing using numbers ----------------------- ************************************************************************ When indexes are created, the fields are compared as strings. If you want to index on the value of a number, you should store the number in the database as a fixed length string. If int and long int values are stored in printable form and fixed width, the comparison will give the expected result. Float and double values should also be stored as fixed width using either fixed point or exponential notation. For example: itoa(9,buffer,10) gives "9" itoa(10,buffer,10) gives "10" "10" is less than "9" sprintf(buffer,"%5d",9) gives " 9" sprintf(buffer,"%5d",10) gives " 10" " 9" is less than " 10" ************************************************************************ --------------------- New features of LDM --------------------- ************************************************************************ 1. When editing a record or entering data in any form, you can use ctrl/enter (hold the control key down and press the enter key) or ctrl/j to accept the form. Previously, you had to move to the last field and press enter. 2. LDM has a new command: Remove Index. This will remove an index from an isam file. -- end of file --