# &proper-name; Driver Notes

## Preface

libdbi is a database abstraction layer written in C. It implements a framework that can utilize separate driver libraries for specific database servers. The libdbi-drivers project provides the drivers necessary to talk to the supported database servers.

This manual provides information about the &dbd-name; driver, which provides support for &proper-name; databases. The manual is intended for programmers who write applications linked against libdbi and who want their applications to use this database backend.

Questions and comments about this driver should be sent to the libdbi-drivers-devel mailing list (see the website). Questions and comments about the libdbi library should be sent to the appropriate libdbi mailing list.

This driver is maintained by &author-name;.

## Introduction

Ingres(R) is an advanced relational database management system from Ingres Corporation. Notable features include C2 security certification, clustering, partitioning, transaction journaling, query optimisation, diverse programming bindings and flexible licensing from GPL community through to 24/7 enterprise level support.

More information can be found from the &proper-name; website.

## Installation

This chapter describes the prerequisites and the procedures to build and install this driver from source code.

### Prerequisites

The following packages must be installed on your system:

libdbi

- This library implements the core database abstraction layer, which provides your application with database backend functionality when paired with this driver. More information about libdbi, including mailing lists, documentation, bug reports, and downloads, is available from the libdbi website.

libpq

- This is the C shared library to enable user programs to communicate with the Ingres(R) Community Edition RDBMS.

  The current version of the dbd_ingres driver was written and tested with the 32-bit NPTL version II 9.0.4 and 9.2 for Linux/x86, running on Gentoo (see my installation notes).

### Build and install the driver

First you have to unpack the libdbi-drivers archive in a suitable directory. Unpacking will create a new subdirectory with the version number, such as `libdbi-drivers-0.8.0`

    $ tar xfvz libdbi-drivers-0.8.0.tar.gz

The libdbi-drivers project consists of several drivers that use a common build system. Therefore you must explicitly tell the configuration script that you want to build the &dbd-name; driver (you can list as many drivers as you want to build):

    $ cd libdbi-drivers-0.8.0

    $ ./configure --with-&dbd-name;

Run `./configure --help` to find out about additional options and other available drivers.

Then build the driver with the command:

    $ make

Please note that you may have to invoke `gmake`, the GNU version of make, on some systems.

Then install the driver with the command (you'll need root permissions to do this):

    $ make install

To test the operation of the newly installed driver, use the command:

    $ make check

This command creates and runs a test program that performs a few basic input and output tests.

If for some reason you need to re-create the autoconf/automake-related files, try running `./autogen.sh`. In some situations, the current stable autoconf/automake/libtool versions (as found in FreeBSD 4.7 and Debian 3.0) do not cooperate well, so it may be necessary to run the older autoconf 2.13. If necessary, edit `autogen.sh` so that it will catch the older autoconf version on your system.

## Driver options

Before you can initiate a connection, you must usually specify options that tell the database driver what to connect to. This driver supports the standard options of `username`, `password` and `dbname`. The latter parameter is in Ingres syntax, `[node_id::]dbname[/svr_class]` - see Ingres documentation for details. (When running as the Ingres admin user on the same host as the DBMS, only the `dbname` is normally required.) Sensible defaults will be used for all unspecified options.

This driver also offers the following non-standard options, and/or redefines the meaning of the following standard options:

ingres_autocommit

- Set this option to string value "0" to disable Ingres autocommit mode for the connection (it is enabled by default).

## &proper-name;-specific Peculiarities

This chapter lists known peculiarities of the &dbd-name; driver. Wherever possible, nonstandard driver behavior is hidden by libdbi's abstractions, but occasionally special considerations must be taken or extra functionality may be utilized for particular drivers.

Ingres environment variables must be set

- The driver will not be loaded at all by `dbi_initialize()` if the Ingres environment variables are not set (e.g. by `~/.ingIIbash`). If the current user or specified user does not have appropriate Ingres privileges, the connection will fail ("User authorization check failed" or similar).

  When connecting, the driver uses the values of the `dbname`, `username` and `password` options, if set.

Autocommit

- 'Autocommit' mode is enabled by default for the DBMS connection. In this mode, every query is committed as an individual transaction.

  With autocommit disabled (see `ingres_autocommit` connection option), a transaction is begun by the first query statement after connection, commit or rollback. The transaction remains open until the next explicit commit, rollback or disconnection (which implies commit). Commit and rollback cannot be done using an OpenAPI query, but must use separate API functions. To work around this, the Ingres driver makes a specific check for COMMIT and ROLLBACK queries and calls the appropriate API function instead of issuing the query.

  See Ingres OpenAPI and SQL documentation for more information.

Handling of result sets

- In the Ingres OpenAPI, result sets must be accessed sequentially. Furthermore, Ingres does not provide the row count; this must be determined by fetching rows until no more is available. For this reason, the driver must fetch all result data into memory immediately after a query. Then libdbi functions can be used to get random access to rows as usual.

  A workaround, for example if your result sets are very large, would be to use SELECT for random access; for example, query once to get a set of key values, then issue SELECTs on individual rows or smaller subsets of rows.

  If your result set or BLOB data is likely to exhaust memory, and workarounds such as the above are not appropriate, then you will need to use OpenAPI directly to access them sequentially or by segments, instead of using libdbi and this driver.

SEQUENCE functions and autocommit

- `dbi_conn_sequence_last()` is not usable in Ingres' autocommit mode (the default). To use sequences to identify INSERTed rows, first obtain the NEXT VALUE using `dbi_conn_sequence_next()` then use that sequence value directly in a separate INSERT transaction.

DATE parsing

- Parsing DATE columns into timestamp values will only work correctly when returned values are in the default (US) date format; i.e. `dd-mmm-yyyy [hh:mm:ss]` where `mmm` is a partial month name. The parsing routine will accept any separators and either a numeric or named month, but the D-M-Y ordering is required. If needed, a workaround for date format incompatibility is to format into a string using a SQL function such as `date_gmt(date)`.

Version string format

- `dbi_conn_get_engine_version_string()` returns a string like `II 9.0.4 (int.lnx/104)NPTL` (internally this is implemented as `SELECT dbmsinfo('_version')`.

Getting database and table lists

- `dbi_conn_get_table_list()` returns matching objects of all types - tables, views, indexes and partitions - in the `iitables` catalog for the named database (except those beginning with `ii`, which are reserved for Ingres). These names are space padded fixed width fields.

Logging verbosity

- The driver respects `dbd_set_verbosity()` level in reporting messages. At verbosity 1, only errors and abnormalities are reported; at 2, more information is shown; at 3, detailed debugging information is shown.

Blank handling

- Blanks are preserved in column values (except that DECIMAL and MONEY columns are converted to strings, and then stripped of trailing blanks). Note that names returned by `dbi_conn_get_table_list()` and `dbi_conn_get_db_list()` are padded with blanks to a fixed width.

Error messages

- The Ingres OpenAPI may return multiple error messages for a given query/operation. The `dbi_conn_error()` returns the error code only for the last error message, but the message text will include all relevant messages. At verbosity level 2, errors directly relating to libdbi function calls are logged. At verbosity 3, all errors are logged including those caused by API calls made internally by the driver.

  Environment variables `II_API_TRACE` and `II_API_LOG` control logging by the API itself. See Chapter 6 of the Ingres OpenAPI User Guide for details.

Connection options

- All Ingres option values are specified as strings (using `dbi_conn_set_option()`).

`ingres_blobsegment` option

- This option specifies the size of individual segments returned for BLOB columns (by default this is approx 2000 bytes). If your BLOBs are large, increasing this value reduces the number of API calls required by the Ingres driver.

&freedoc-license;