Database Tools Interface (DBTools)

SAP Sybase IQ includes Sybase Control Center and a set of utilities for managing databases. These database management utilities perform tasks such as backing up databases, creating databases, translating transaction logs to SQL, and so on.

Supported Platforms

All the database management utilities use a shared library called the database tools library. It is supplied for Windows operating systems and for Linux, and Unix. For Windows, the name of this library is dbtool16.dll. For Linux and Unix, the name of this library is libdbtool16_r.so.

You can develop your own database management utilities or incorporate database management features into your applications by calling the database tools library. This section describes the interface to the database tools library. This section assumes you are familiar with how to call library routines from the development environment you are using.

The database tools library has functions, or entry points, for each of the database management utilities. In addition, functions must be called before use of other database tools functions and when you have finished using other database tools functions.

The dbtools.h Header File

The dbtools header file lists the entry points to the DBTools library and also the structures used to pass information to and from the library. The dbtools.h file is installed into the SDK\Include subdirectory under your SAP Sybase IQ installation directory. You should consult the dbtools.h file for the latest information about the entry points and structure members.

The dbtools.h header file includes other files such as:

sqlca.h – This is included for resolution of various macros, not for the SQLCA itself.
dllapi.h – Defines preprocessor macros for operating-system dependent and language-dependent macros.
dbtlvers.h – Defines the DB_TOOLS_VERSION_NUMBER preprocessor macro and other version specific macros.

The sqldef.h Header File

The sqldef.h header file includes error return values.

The dbrmt.h Header File

The dbrmt.h header file included with SAP Sybase IQ describes the DBRemoteSQL entry point in the DBTools library and also the structure used to pass information to and from the DBRemoteSQL entry point. The dbrmt.h file is installed into the SDK\Include subdirectory under your SAP Sybase IQ installation directory. You should consult the dbrmt.h file for the latest information about the DBRemoteSQL entry point and structure members.

DBTools Import Libraries
To use the DBTools functions, you must link your application against a DBTools import library that contains the required function definitions.
DBTools Library Initialization and Finalization
Before using any other DBTools functions, you must call DBToolsInit. When you are finished using the DBTools library, you must call DBToolsFini.
DBTools Function Calls
All the tools are run by first filling out a structure, and then calling a function (or entry point) in the DBTools library. Each entry point takes a pointer to a single structure as argument.
Callback Functions
Several elements in DBTools structures are of type MSG_CALLBACK. These are pointers to callback functions.
Version Numbers and Compatibility
Each structure has a member that indicates the version number. You should set the version field to the version number of the DBTools library that your application was developed against before calling any DBTools function. The current version of the DBTools library is defined when you include the dbtools.h header file.
Bit Fields
Many of the DBTools structures use bit fields to hold Boolean information in a compact manner. For example, the backup structure includes the following bit fields:
A DBTools Example
You can find this sample and instructions for compiling it in the %ALLUSERSPROFILE%\SybaseIQ\samples\SQLAnywhere\DBTools directory. The sample program itself is in main.cpp. The sample illustrates how to use the DBTools library to perform a backup of a database.
Software Component Exit Codes
All database tools library entry points use the following exit codes. The SAP Sybase IQ utilities also use these exit codes.
Database Tools C API Reference
The header files are dbtools.h and dbrmt.h.