<!DOCTYPE HTML PUBLIC> <HTML> <TITLE>Xbase DBMS Chapter 1</TITLE> <BODY BGCOLOR=#FFFFFF> <h1><p align="center">Getting Started</p></h1> <p align="center">Chapter Updated 1/29/99</p> <hr><h2>Overview</h2> The term Xbase is often used used to describe the format of the original DBase (.DBF) files. Many vendors support the industry standard Xbase file format and are committed to this technology for many years to come, thus insuring continued support.<br><br> Xbase DBMS is a set of documentation and C++ routines for accessing Xbase style databases and indicis from C/C++ programs on a variety of computing platforms. <br><br> The main purpose of the routines is to provide reliable and economical programming tools to programmers for reading, writing and updating DBF databases, indices and memo fields.<br><br><br> <hr><h2>System Requirements</h2> To use Xbase DBMS, the following items are needed:<br><br> A computer and C/C++ compiler.<br><br> The original source code is developed on a Linux platform with the GCC public domain C/C++ compiler. Documenation for GCC products and tools can be found at <A HREF="http://www.isys.net/susehilf/index_e.html"> www.isys.net/susehilf/index_e.html</A><br><br> The examples and steps here describe how to load this library in a Linux/Unix or Dos/Windows environment. If you would like to contribute specific steps for loading the Xbase DBMS in your environment, please send them to me and I will include them in the next release.<br><br> Xbase DBMS has been successfully ported and runs on Linux, Sun Solaris, OpenVMS, FreeBSD, OS2 and DOS/Windows (Using the large memory model).<br><br> <A HREF="xbase_port.html">Makefiles for Various Platforms</A><br><br> <hr><h2>Classes and User Interface</h2> There are six classes in the Xbase library which are available for use in a typical Xbase application program.<br><br><br> <br><br> <TABLE BORDER> <CAPTION ALIGN="TOP"><H3>Xbase Classes - Version 1.8.0 and newer</H3></CAPTION> <TR VALIGN="BASELINE"> <TR><TH ALIGN="LEFT">Class<TD>Basic Description<TD>How Used<TD>Old Class<br>Name <TR><TH ALIGN="LEFT">xbXBase<TD>Basic Xbase Class<TD>Every program gets one of these<TD>XBASE <TR><TH ALIGN="LEFT">xbDbf<TD>Database and Field class<TD>Need one of these for each open DBF file<TD>DBF <TR><TH ALIGN="LEFT">xbNdx<TD>Ndx index class<TD>Need one of these for each open NDX index<TD>NDX <TR><TH ALIGN="LEFT">xbNtx<TD>Ntx index class<TD>Need one of these for each open NTX index <TR><TH ALIGN="LEFT">xbString<TD>String class<TD>Used for handling strings <TR><TH ALIGN="LEFT">xbHtml<TD>Html generation class<TD>Needed for creating HTML code<TD>HTML </TABLE> <br><br> There are other classes used internally by these Xbase classes, but most application programs will not need to be concerned with them. These classes are xbStack - used for stack data structures, xbExpn - used for expression logic, and xbDate - used for date manipulation logic. <br><br> If you are upgrading from an earlier version of Xbase, there is a conversion utility in the xbase/bin. See shell script xbase_rename.sh and xbase_rename.txt for details (courtesy of Vitaly Fedrushkov). <br><br><br> <hr><h2>Portability, Type Defs and Structures</h2> To effectively make the Xbase library as portable across platforms as possible, three things occured. <br><br> <li>First, the software was developed to run and compile on either big endian or little endian computers and store all numeric data in little endian format. <br><br> <li>Secondly, field types must be consistently defined in each environment. The <em>types.h</em> file defines the xbase data types. To modify the Xbase code base to function in a different (non ported to yet) environment, start by modifying the <em>types.h</em> file for your site and recompile.<br><br> <li>Thirdly, support for unix automake and autoconf has been added to provide support on a wide variety of unices. <hr> <TABLE BORDER> <CAPTION ALIGN="TOP"><h3>Field Types</h3></CAPTION> <TR ALIGN="BASELINE"> <TR><TH ALIGN="LEFT">Type<TD>Description<TD>Old Type <TR><TH ALIGN="LEFT">xbULong<TD>unsigned long int<TD>ULONG <TR><TH ALIGN="LEFT">xbUShort<TD>unsigned short int<TD>USHORT <TR><TH ALIGN="LEFT">xbShort<TD>short int <TR><TH ALIGN="LEFT">xbLong<TD>long<TD>LONG <TR><TH ALIGN="LEFT">xbFloat<TD>floath<TD>FLOAT <TR><TH ALIGN="LEFT">xbDouble<TD>double<TD>DOUBLE <TR><TH ALIGN="LEFT">char<TD>char<TD>CHAR <TR><TH ALIGN="LEFT">void<TD>void<TD>VOID <TR><TH ALIGN="LEFT">struct SCHEMA<TD>Used for defining record structures </TABLE> <br><br> Xbase was designed for portability utilizing standard ANSI-C compliant code. If you decide to write updates to the Xbase project, please try to keep your work to standard generic ANSI-C (no special DOS/WINDOWS Calls). If you find find non compliant code, please let the Xbase team know by sending an email to xbase@startech.keller.tx.us. <br><br> <hr><h2>Compilation Overview</h2> The following sections document building the Xbase library. If none of the methods documented work for you, or are not what you need, then you will need to build some type of makefile or batch file to compile the source code and build a static or dynamic library for your OS environment.<br><br> The source members you will need to compile into your library include:<br><br> dbf.cpp, exp.cpp. expfunc.cpp. expproc.cpp, fields.cpp, html.cpp, lock.cpp, memo.cpp, ndx.cpp, stack.cpp, xbase.cpp, xdate.cpp and xbexcept.cpp. <br><br> Before compiling the library, you may need to modify the options.h file for your environment. <br><br> After you have it working, please consider contributing your make files to the xbase project.<br> <hr><h2>Installing the Xbase source code (for Unix environments)</h2> <h4>Instructions for 1.8.0a installation</h4> Dowload the file<br> cp /home/of/xbase-1.8.0a.tar.gz /usr/local<br> cd /usr/local<br> gunzip xbase-1.8.0a.tar.gz<br> tar -xvf xbase-1.8.0a.tar<br> ln -s xbase-1.7.4c xbase<br><br> <hr><h2>Building the Xbase Library (for Unix environments)</h2> Beginning with version 1.7.4c, there is an automake procedure which is designed to provide automatic makefile generation for a variety of Unix environments (courtesy of Denis Pershin). <br><br> Execute the following commands to create the makefile for your environment. <br><br> <li><em>cd /usr/local/xbase</em> <li><em>make -f Makefile.cvs</em> <li><em>./configure</em> - this step builds a makefile for your specific Unix environment optionally you could do <em>./configure --help</em> to see the library build options ie; <em>./configure --enable-debug --disable-shared --enable-static</em> - builds a static debug lib) <li><em>make</em> - this step builds the actual xbase library <li><em>make install</em> - this step copies the library and the header files into local bin and include directories<br> <br> Watch for any error messages. If you get errors and they scroll off the screen, rerun the command and append "| more" (make | more or make install | more) to the end of the command to stop the display. The most common errors are related to directory access rights. Read any instructions for your environment produced by this script and follow the printed directions. <br><br> In the Linux development environment, the script generates the following messages.<br><br> To link against installed libraries in a given directory, LIBDIR, you must use the '-LLIBDIR' flag during linking.<br><br> You will also need to do one of the following<br> - add LIBDIR to the 'LD_LIBRARY_PATH environment variable during execution<br> - add LIBDIR to the 'LD_RUN_PATH' environment during linking<br> - use the -Wl, --rpath -Wl,LIBDIR linker flags<br> - have your system administrator add LIBDIR to 'etc/ld.so.conf' <br><br> On the Startech server, I had to: <li>Verify the library and associated links were copied from xbase/xbase/.libs into /usr/local/lib <li>Add /usr/local/lib is in /etc/ld.so.conf <li>execute program <em>ldconfig</em> to refresh the new libs <br><br> Actual milage at your site may vary. <br><br><br> <hr><h2>Building a program with the Xbase library</H2> Create a directory for your project:<br><br> cd /home/me<br> mkdir MyProject<br> cd MyProject<br> vi MyProg.cpp<br><br> To use the Xbase classes, include the following header file in the program: <br><br> #include <xbase/xbase.h><br><br> If you are using the html interface, you will also need<br> #include <xbase/html.h><br> <!-- FIXME: this isn't true anymore, xbase.h is enough -- willy --> <!-- OTOH, xbstring.h is needed to use strings --> in your program. For more details, check out the sample programs in the xbase/examples directory. <hr><h2>Compiling and Linking Unix Application Program for v1.7.4c and later</h2> The install script should have provided specific instructions for your environment on how to link with the xbase library. <br><br> In the Linux environment, assuming that you are using shared libraries, and usr/local/lib has been added to the /etc/ld.so.conf file, and the ldconfig command was executed <br><br> To Compile:<br> g++ -c -Wall -I/usr/include -I/usr/src/linux/include-asm-i386 -I/usr/local/include -I/usr/local/xbase myprog.cpp<br><br> To Link Edit:<br> g++ -o myprog myprog.o libxbase.so<br> <hr><h2>Compiling an Application Program with Borland v4.5 C/C++compiler</h2> With Borland C compiler: bcc -Ic:\xbase\src myprog.cpp -Lc:\xbase\src\xbase.lib <br><br> <hr><h2>Getting the latest development version of XBase</h2> <br>The Xbase project is in an ongoing state of development with new enhancements being added regularly and bug fixes being applied as they are found. There are several programmers from various parts of the world working on Xbase. If you would like to get the latest version of the Xbase library for your project, then follow these steps. <br><br> <h3>You will need:</h3> <li>1 - A computer running Unix or Linux connected to the internet via TCP/IP <li>2 - CVS loaded and operational. CVS is a tool which maintains a repository of source code and supports the building of the Xbase library allowing simultaneous access and development by several programmers. <li>3 - automake <li>4 - autoconf <br><br> <h3>Follow these steps:</h3> <li>1 - connect to the Startech CVS server with the following command: <li><em>cvs -d :pserver:cvsguest@stargazer.startech.keller.tx.us:/usr/local/cvsroot login</em> <li>2 - The next prompt should be asking you for a password. Enter <em>download</em> <li>3 - change directory to the location you want to load the Xbase library <br><em>ie; cd /home/mydirectory</em> <li>4 - Download the archive <br><em>cvs -d :pserver:cvsguest@stargazer.startech.keller.tx.us:/usr/local/cvsroot checkout xbase</em> <li>5 - <em>make -f Makefile.cvs</em> <li>6 - Configure for your environment. <br><em>./configure</em> - this will set up a basic build of a dynamic link library and put the resultant libraries in the xbase/xbase/.libs directory <br><em>./configure --enable-debug --disable-shared --enable-static</em> This will build a static library with debug mode turned on. <br><em>./configure --help</em> This will display all the configure options. <li>7 - Build the core library, examples and utility programs enter <br><em>make</em> <li>8 - If you accepted the defaults, after the build is complete, you will end up with a set of dynamic link library files in the xbase/xbase/.libs directory. <li>9 - Install the library and header files into the system libraries - <em>make install</em><br> This will typically copy the dynamic libraries into /usr/local/lib and copy the header files (.h files) into /usr/local/include <li>10 - If you have got this far, the library is now operational. you can go into the examples directory, or the bin directory and execute some of the programs to verify all is working OK. For example, cd examples, then type sample1, this program should build a DBF,DBT and several NDX files. <br><h3>Notes about using the current development library</h3> <li>1 - Library functions may or may not be documented <li>2 - The library may or may not be stable. This is the development library and is being updated with current code changes. If you are using it, and it does not behave the way you think it should, you may want to drop a note to <A HREF="mailto:xbase@startech.keller.tx.us"> xbase@startech.keller.tx.us.</A> This may sound a little unsettling, but the library is generally stable. It goes through periods of time where it is in a state of flux when major changes are occurring, but for the most part it is probably OK to use. <li>3 - If you have changes to contribute to the library, mail your updates to<A HREF="mailto:xbase@startech.keller.tx.us"> xbase@startech.keller.tx.us</A><br>. <hr><br> <h2>System Limitations</h2> <br> Maximum size of a database file is the size of LONG - 2,147,483,647 bytes<br> Total number of fields in a database - 1024 <br> Total number of characters in all fields - 32767<br> Maximum number of characters in a field - 254<br> Total number of records in a file - 1 billion<br> Maximum index key length - 100 bytes<br> Maximum .DBT file memo block size - 32256<br> Maximum expression result length - 100 bytes<br> Maximum NDX index key length - 100 bytes<br><br> <br><hr> <h2>Directory Structures</h2> The following is a proposed directory structure for loading the Xbase libraries at your site.<br><br> <TABLE BORDER> <CAPTION ALIGN="TOP"><h3>Proposed Xbase Directory Structure for Unix <br>Versions 1.7.4c and later</h3></CAPTION> <TR ALIGN="BASELINE"> <TR><TH ALIGN="LEFT">Directory<TD>Description <TR><TH ALIGN="LEFT">/usr/local/xbase<TD>Xbase source code <TR><TH ALIGN="LEFT">/usr/local/xbase/samples<TD>X-Base samples <TR><TH ALIGN="LEFT">/home/me/MyProject1<TD>Your first project <TR><TH ALIGN="LEFT">/home/me/MyProject2<TD>Your second project </TABLE> <br><br> <TABLE BORDER> <CAPTION ALIGN="TOP"><h3>Proposed Xbase Directory Structure for Dos/Windows/NT</h3></CAPTION> <TR ALIGN="BASELINE"> <TR><TH ALIGN="LEFT">Directory<TD>Description <TR><TH ALIGN="LEFT">c:\xbase<TD>Base Directory for Xbase <TR><TH ALIGN="LEFT">c:\xbase\src<TD>Xbase source code <TR><TH ALIGN="LEFT">c:\xbase\samples<TD>X-Base samples <TR><TH ALIGN="LEFT">c:\xbase\bin<TD>Xbase utility programs <TR><TH ALIGN="LEFT">c:\xbase\MyProject1<TD>Your first project <TR><TH ALIGN="LEFT">c:\xbase\MyProject2<TD>Your second project </TABLE> <br><br> <hr> <h2>Compile Options</h2> The <em>options.h</em> header file contains compile options which impact how the Xbase library is built.<br><br> <TABLE BORDER> <CAPTION ALIGN="TOP"><H3>Xbase Options - Non Unix Automake environment</H3></CAPTION> <TR VALIGN="BASELINE"> <TR><TH ALIGN="LEFT">OPTION<TD>DESCRIPTION <TR><TH ALIGN="LEFT">XBASE_DEBUG<TD>XBASE_DEBUG can be used during application development. To generate smaller and faster production executable programs, comment this define out before building the Xbase library. This option generates debugging logic. <TR><TH ALIGN="LEFT">XB_HTML<TD>Turns on the option for the HTML generation class. <TR><TH ALIGN="LEFT">XB_INDEX_NDX<TD>This define compiles in support for NDX indexes. Comment this line out to drop support for NDX indexes. This define automatically enables expression processing. <TR><TH ALIGN="LEFT">XB_LOCKING_ON<TD>Needed for multi user configuration. It is safe to remove this option for single user environments. DOS/Windows support is at alpha level and needs a volunteer to test it. <TR><TH ALIGN="LEFT">XB_MEMO_FIELDS<TD>This define compiles in support for memo (variable length) fields. <TR><TH ALIGN="LEFT">XB_DBT_BLOCK_SIZE<TD>This defines the default block size to use when creating memo .DBT files. It must be an increment of 512 bytes. The maximum block size is 32256. <TR><TH ALIGN="LEFT">XB_EXPRESSIONS<TD>Used for expression logic, required for index keys. <TR><TH ALIGN="LEFT">XB_CASTELLANO<TD>Date routines return Spanish names for days,weeks and months </TABLE><br><br><br><hr> <TABLE BORDER> <CAPTION ALIGN="TOP"><H3>Xbase Options - Unix Automake environment</H3></CAPTION> <TR VALIGN="BASELINE"> <TR><TH ALIGN="LEFT">OPTION<TD>DESCRIPTION <TR><TH ALIGN="LEFT">--without-xbase-debug<TD>Turns off xbase debugging code <TR><TH ALIGN="LEFT">--without-index-ndx<TD>Turns off NDX index options <TR><TH ALIGN="LEFT">--without-memo-fields<TD>Turns off memo fields <TR><TH ALIGN="LEFT">--without-expressions<TD>Turns off expression processing <TR><TH ALIGN="LEFT">--without-ui-html<TD>Turns off HTML user interface class <TR><TH ALIGN="LEFT">--without-xbase-locking<TD>Turns off xbase locking <TR><TH ALIGN="LEFT">--without-xbase-debug<TD>Turns off debug logic <TR><TH ALIGN="LEFT">--without-exceptions<TD>Turns on exception processing <TR><TH ALIGN="LEFT">--with-castellano<TD>Turn on castellano date options </TABLE><br><br> Use these options on the command line when executing the <em>./configure</em> command. Also, you can execute <em>./configure --help</em> for a complete list of all unix configure options. <br><hr> <A HREF="mailto:xbase@startech.keller.tx.us"> Send me mail - xbase@startech.keller.tx.us</A><br> <p>(c)1997 StarTech <p><img src="xbase.jpg"><br><hr> </BODY> </HTML>
