#

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 indicis 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

Class | Basic Description | How Used | Old Class Name
xbXBase | Basic Xbase Class | Every program gets one of these | XBASE
xbDbf | Database and Field class | Need one of these for each open DBF file | DBF
xbNdx | Ndx index class | Need one of these for each open NDX index | NDX
xbNtx | Ntx index class | Need one of these for each open NTX index
xbString | String class | Used for handling strings
xbHtml | Html generation class | Needed for creating HTML code | HTML

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

  Type | Description | Old Type
  xbULong | unsigned long int | ULONG
  xbUShort | unsigned short int | USHORT
  xbShort | short int
  xbLong | long | LONG
  xbFloat | floath | FLOAT
  xbDouble | double | DOUBLE
  char | char | CHAR
  void | void | VOID
  struct SCHEMA | Used 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

  Directory | Description
  /usr/local/xbase | Xbase source code
  /usr/local/xbase/samples | X-Base samples
  /home/me/MyProject1 | Your first project
  /home/me/MyProject2 | Your second project

  ### Proposed Xbase Directory Structure for Dos/Windows/NT

  Directory | Description
  c:\xbase | Base Directory for Xbase
  c:\xbase\src | Xbase source code
  c:\xbase\samples | X-Base samples
  c:\xbase\bin | Xbase utility programs
  c:\xbase\MyProject1 | Your first project
  c:\xbase\MyProject2 | Your 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

  OPTION | DESCRIPTION
  XBASE_DEBUG | 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.
  XB_HTML | Turns on the option for the HTML generation class.
  XB_INDEX_NDX | This 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_ON | 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.
  XB_MEMO_FIELDS | This define compiles in support for memo (variable length) fields.
  XB_DBT_BLOCK_SIZE | 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.
  XB_EXPRESSIONS | Used for expression logic, required for index keys.
  XB_CASTELLANO | Date routines return Spanish names for days,weeks and months

  ### Xbase Options - Unix Automake environment

  OPTION | DESCRIPTION
  --without-xbase-debug | Turns off xbase debugging code
  --without-index-ndx | Turns off NDX index options
  --without-memo-fields | Turns off memo fields
  --without-expressions | Turns off expression processing
  --without-ui-html | Turns off HTML user interface class
  --without-xbase-locking | Turns off xbase locking
  --without-xbase-debug | Turns off debug logic
  --without-exceptions | Turns on exception processing
  --with-castellano | Turn 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