XBSQL: An SQL wrapper for the XBase DBMS library

Next Previous Table of Contents

## 1. The XBaseSQL class

XBaseSQL is the root class for the XBSQL wrapper; an instance of this class represents a database. The class is in fact derived from the XBase xbXBase class.

A database is considered to be the set of .dbf and related files in a particular directory (but not in any subdirectory). The XBaseSQL constructor takes a single argument, which is the directory path.

Note that queries (select, ...) can use the ? character as place-holders, in which case values are substituted when the query is actually executed.

- XBSQLQuery *XBaseSQL::openQuery (const char *)
  This method takes an SQL statement. Unless there is an error (in which case the result is null), this returns a pointer at an instance of a class which represents the parsed and verified query. This result will actually be an instance of XBSQLSelect, XBSQLInsert, ...., as appropriate, but is returned as a pointer at a base class XBSQLQuery. See below for details of determining which applies.

- XBSQLSelect *XBaseSQL::openSelect (const char *), ...
  This, and the similar openInsert, openUpdate and openDelete methods take a select (or insert, ...) SQL query, and return a pointer at an object representing that particular type of query. They are essentially special cases of the openQuery method.

- bool XBaseSQL::execCommand (const char *)
  This method is used to execute SQL commands, such as create table and drop table which return either success or failure.

- bool XBaseSQL::dropTable (const char *)
  This is a shortcut to drop a named table. Any indexes which were created by the XBSQL wrapper will be deleted.

- bool XBaseSQL::renameTable (const char *)
  This is a shortcut to rename a table. Any indexes which were created by the XBSQL wrapper will be appropriately renamed.

- XBSQLTableSet *XBaseSQL::getTableSet()
  This method returns an object which contains a list of all tables in the database.

- XBSQLFieldSet *XBaseSQL::getFieldSet(const char *)
  This method returns an object which contains a list of all fields in a named table, plus information about those fields.

- const char *XBaseSQL::lastError()
  In the event of an error, this method returns a corresponding error message string.

In addition to the above, there are some addition methods which can be used to control the behaviour of the XBSQL library:

- void XBaseSQL::setClosePack(bool)
  This method is used to enable (or disable) packing of tables on close. Packing removes deleted records, which would otherwise remain and simply be flagged as deleted.
- void XBaseSQL::setCaseSensitive(bool)
  By default, string comparisom in query expressions (both for (in)equality and for like) are case insensitive. This method is used to enable (and disable) case sensitive comparisom.
- void XBaseSQL::setUseWildcard(bool)
  The defualt operation of the like operator is to use the % character to match arbitrary (possibly empty) strings. This method can be used to enable (and disable) wildcard matching, which uses UNIX shell-like wildcard characters.
- void XBaseSQL::setGoSlow(bool)
  This option affects select queries. When set, the data is handled in a manner which reduces the amount of memory used, at the expense of execution time. It is probably only useful where the query will return large amounts of data. Performance will be worst affected if the data (rows and columns) are accessed randomly.

Given an XBSQLQuery object, the particular type can be determined with the following set of methods. Each returns a null pointer if the object is not the corresponding type, or a safely type-cast pointer if it is.

- XBSQLSelect *XBSQLQuery::isSelect()
- XBSQLInsert *XBSQLQuery::isInsert()
- XBSQLUpdate *XBSQLQuery::isUpdate()
- XBSQLDelete *XBSQLQuery::isDelete()