Getting Started

Chapter Updated 1/29/99


Overview

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.

Xbase DBMS is a set of documentation and C++ routines for accessing Xbase style databases and indices from C/C++ programs on a variety of computing platforms.

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.



System Requirements

To use Xbase DBMS, the following items are needed:

A computer and C/C++ compiler.

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 www.isys.net/susehilf/index_e.html

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.

Xbase DBMS has been successfully ported and runs on Linux, Sun Solaris, OpenVMS, FreeBSD, OS2 and DOS/Windows (Using the large memory model).

Makefiles for Various Platforms


Classes and User Interface

There are six classes in the Xbase library which are available for use in a typical Xbase application program.




Xbase Classes - Version 1.8.0 and newer

ClassBasic DescriptionHow UsedOld Class
Name
xbXBaseBasic Xbase ClassEvery program gets one of theseXBASE
xbDbfDatabase and Field classNeed one of these for each open DBF fileDBF
xbNdxNdx index classNeed one of these for each open NDX indexNDX
xbNtxNtx index classNeed one of these for each open NTX index
xbStringString classUsed for handling strings
xbHtmlHtml generation classNeeded for creating HTML codeHTML


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.

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



Portability, Type Defs and Structures

To effectively make the Xbase library as portable across platforms as possible, three things occured.

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

  • Secondly, field types must be consistently defined in each environment. The types.h 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 types.h file for your site and recompile.

  • Thirdly, support for unix automake and autoconf has been added to provide support on a wide variety of unices.

    Field Types

    TypeDescriptionOld Type
    xbULongunsigned long intULONG
    xbUShortunsigned short intUSHORT
    xbShortshort int
    xbLonglongLONG
    xbFloatfloatFLOAT
    xbDoubledoubleDOUBLE
    charcharCHAR
    voidvoidVOID
    struct SCHEMAUsed for defining record structures


    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.


    Compilation Overview

    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.

    The source members you will need to compile into your library include:

    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.

    Before compiling the library, you may need to modify the options.h file for your environment.

    After you have it working, please consider contributing your make files to the xbase project.

    Installing the Xbase source code (for Unix environments)

    Instructions for 1.8.0a installation

    Dowload the file
    cp /home/of/xbase-1.8.0a.tar.gz /usr/local
    cd /usr/local
    gunzip xbase-1.8.0a.tar.gz
    tar -xvf xbase-1.8.0a.tar
    ln -s xbase-1.7.4c xbase


    Building the Xbase Library (for Unix environments)

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

    Execute the following commands to create the makefile for your environment.

  • cd /usr/local/xbase
  • make -f Makefile.cvs
  • ./configure - this step builds a makefile for your specific Unix environment optionally you could do ./configure --help to see the library build options ie; ./configure --enable-debug --disable-shared --enable-static - builds a static debug lib)
  • make - this step builds the actual xbase library
  • make install - this step copies the library and the header files into local bin and include directories

    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.

    In the Linux development environment, the script generates the following messages.

    To link against installed libraries in a given directory, LIBDIR, you must use the '-LLIBDIR' flag during linking.

    You will also need to do one of the following
    - add LIBDIR to the 'LD_LIBRARY_PATH environment variable during execution
    - add LIBDIR to the 'LD_RUN_PATH' environment during linking
    - use the -Wl, --rpath -Wl,LIBDIR linker flags
    - have your system administrator add LIBDIR to 'etc/ld.so.conf'

    On the Startech server, I had to:
  • Verify the library and associated links were copied from xbase/xbase/.libs into /usr/local/lib
  • Add /usr/local/lib is in /etc/ld.so.conf
  • execute program ldconfig to refresh the new libs

    Actual milage at your site may vary.



    Building a program with the Xbase library

    Create a directory for your project:

    cd /home/me
    mkdir MyProject
    cd MyProject
    vi MyProg.cpp

    To use the Xbase classes, include the following header file in the program:

    #include <xbase/xbase.h>

    If you are using the html interface, you will also need
    #include <xbase/html.h>
    in your program. For more details, check out the sample programs in the xbase/examples directory.

    Compiling and Linking Unix Application Program for v1.7.4c and later

    The install script should have provided specific instructions for your environment on how to link with the xbase library.

    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

    To Compile:
    g++ -c -Wall -I/usr/include -I/usr/src/linux/include-asm-i386 -I/usr/local/include -I/usr/local/xbase myprog.cpp

    To Link Edit:
    g++ -o myprog myprog.o libxbase.so

    Compiling an Application Program with Borland v4.5 C/C++compiler

    With Borland C compiler: bcc -Ic:\xbase\src myprog.cpp -Lc:\xbase\src\xbase.lib


    Getting the latest development version of XBase


    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.

    You will need:

  • 1 - A computer running Unix or Linux connected to the internet via TCP/IP
  • 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.
  • 3 - automake
  • 4 - autoconf

    Follow these steps:

  • 1 - connect to the Startech CVS server with the following command:
  • cvs -d :pserver:cvsguest@stargazer.startech.keller.tx.us:/usr/local/cvsroot login
  • 2 - The next prompt should be asking you for a password. Enter download
  • 3 - change directory to the location you want to load the Xbase library
    ie; cd /home/mydirectory
  • 4 - Download the archive
    cvs -d :pserver:cvsguest@stargazer.startech.keller.tx.us:/usr/local/cvsroot checkout xbase
  • 5 - make -f Makefile.cvs
  • 6 - Configure for your environment.
    ./configure - this will set up a basic build of a dynamic link library and put the resultant libraries in the xbase/xbase/.libs directory
    ./configure --enable-debug --disable-shared --enable-static This will build a static library with debug mode turned on.
    ./configure --help This will display all the configure options.
  • 7 - Build the core library, examples and utility programs enter
    make
  • 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.
  • 9 - Install the library and header files into the system libraries - make install
    This will typically copy the dynamic libraries into /usr/local/lib and copy the header files (.h files) into /usr/local/include
  • 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.

    Notes about using the current development library

  • 1 - Library functions may or may not be documented
  • 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 xbase@startech.keller.tx.us. 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.
  • 3 - If you have changes to contribute to the library, mail your updates to xbase@startech.keller.tx.us
    .

    System Limitations


    Maximum size of a database file is the size of LONG - 2,147,483,647 bytes
    Total number of fields in a database - 1024
    Total number of characters in all fields - 32767
    Maximum number of characters in a field - 254
    Total number of records in a file - 1 billion
    Maximum index key length - 100 bytes
    Maximum .DBT file memo block size - 32256
    Maximum expression result length - 100 bytes
    Maximum NDX index key length - 100 bytes



    Directory Structures

    The following is a proposed directory structure for loading the Xbase libraries at your site.

    Proposed Xbase Directory Structure for Unix
    Versions 1.7.4c and later

    DirectoryDescription
    /usr/local/xbaseXbase source code
    /usr/local/xbase/samplesX-Base samples
    /home/me/MyProject1Your first project
    /home/me/MyProject2Your second project


    Proposed Xbase Directory Structure for Dos/Windows/NT

    DirectoryDescription
    c:\xbaseBase Directory for Xbase
    c:\xbase\srcXbase source code
    c:\xbase\samplesX-Base samples
    c:\xbase\binXbase utility programs
    c:\xbase\MyProject1Your first project
    c:\xbase\MyProject2Your second project



    Compile Options

    The options.h header file contains compile options which impact how the Xbase library is built.

    Xbase Options - Non Unix Automake environment

    OPTIONDESCRIPTION
    XBASE_DEBUGXBASE_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.
    XB_HTMLTurns on the option for the HTML generation class.
    XB_INDEX_NDXThis define compiles in support for NDX indexes. Comment this line out to drop support for NDX indexes. This define automatically enables expression processing.
    XB_LOCKING_ONNeeded 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.
    XB_MEMO_FIELDSThis define compiles in support for memo (variable length) fields.
    XB_DBT_BLOCK_SIZEThis 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.
    XB_EXPRESSIONSUsed for expression logic, required for index keys.
    XB_CASTELLANODate routines return Spanish names for days,weeks and months




    Xbase Options - Unix Automake environment

    OPTIONDESCRIPTION
    --without-xbase-debugTurns off xbase debugging code
    --without-index-ndxTurns off NDX index options
    --without-memo-fieldsTurns off memo fields
    --without-expressionsTurns off expression processing
    --without-ui-htmlTurns off HTML user interface class
    --without-xbase-lockingTurns off xbase locking
    --without-xbase-debugTurns off debug logic
    --without-exceptionsTurns on exception processing
    --with-castellanoTurn on castellano date options


    Use these options on the command line when executing the ./configure command. Also, you can execute ./configure --help for a complete list of all unix configure options.

    Send me mail - xbase@startech.keller.tx.us

    (c)1997 StarTech