Ingres extension for PHP

1. Introduction
2. Platform support
3. Function support
4. Installing the extension
5. Known issues
6. Future direction
7. Comments/suggestions/credits

1. Introduction

This extension is designed to provide access to the Ingres Enterprise Relational Database Management System. Native or direct access is provided for Ingres II 2.0, Ingres II 2.5, Advantage Ingres 2.6 and Ingres r3. To access older versions, a supported client environment can be used with Ingres/NET.

In 2005, the Ingres extension was moved to the PHP extension community library (PECL) to resolve a build conflict with Windows and UNIX/Linux platforms. One advantage of this move is it allows the extension to be developed with its own release cycle. This permits new functionality to be released when possible instead of waiting for the next official PHP release. Rather than being available via the main PHP tarball/zip archive (http://www.php.net/downloads), an additional download is required.

2. Platform support

Ingres Releases

This extension has been written to support the following versions of Ingres:

Ingres II 2.0/OpenIngres 2.0
Ingres II 2.5
Advantage Ingres 2.6
Ingres r3
Ingres 2006

PHP Releases

This extension has been written against PHP 5.1 and PHP 5.2. Prior versions of PHP, i.e. 4.0.x - 5.0.x, contain an earlier version of the Ingres extension. Building the extension with earlier versions requires the deletion of the ingres_ii directory under ext.

Operating System Compatibility

The extension should work against any platform where the above Ingres releases are supported. In practice the extension has been developed on Windows XP using Visual Studio .Net 2003 (VC7) and SuSE 9.3/Fedora Core 3 using GCC 3.3.x. There has been limited testing on Solaris 9 Sparc. If you find the extension does not work, please log a bug via the project home page with the following information:

operating system and patches/service pack installed
compiler + version used to build the extension
version of PHP being used
version of Ingres being used
if you managed to get the extension built, the value of the constants INGRES_EXT_VERSION and INGRES_API_VERSION:
```
<?php
	echo INGRES_EXT_VERSION + " " + INGRES_API_VERSION;
?> 
```

3. Function support

The extension provides the following functionality:

Function	Description
ingres_autocommit	Switch autocommit on or off
ingres_close	Close an Ingres database connection
ingres_commit	Commit a transaction
ingres_connect	Open a connection to an Ingres database
ingres_cursor	Get the name of the cursor in use
ingres_error	Get the error text
ingres_errno	Get the error code
ingres_errsqlstate	Get the SQLState
ingres_execute	Execute a cursor prepared by `ingres_prepare`
ingres_fetch_array	Fetch a row of result into an array
ingres_fetch_object	Fetch a row of result into an object
ingres_fetch_proc_return	Get the return value from a procedure call
ingres_fetch_row	Fetch a row of result into an enumerated array
ingres_field_length	Get the length of a field
ingres_field_name	Get the name of a field in a query result
ingres_field_nullable	Test if a field is nullable
ingres_field_precision	Get the precision of a field
ingres_field_scale	Get the scale of a field
ingres_field_type	Get the type of a field in a query result
ingres_num_fields	Get the number of fields returned by the last query
ingres_num_rows	Get the number of rows affected or returned by the last query
ingres_pconnect	Open a persistent connection to an Ingres database
ingres_prepare	Prepares a query for execution by`ingres_execute`
ingres_query	Send a SQL query to Ingres
ingres_set_environment	Set one or more Ingres environment variables
ingres_rollback	Rollback a transaction

Project home page

The latest tar ball for this extension can be downloaded from http://pecl.php.net/project/ingres. At the moment only source code is available for download via this page. Development snapshot builds of the PECL extension for Windows can be downloaded from http://pecl4win.php.net/ext.php/php_ingres.dll. Binary releases for certain operating systems will be provided in due course.

Configuration Options

The following options configure the behaviour of the Ingres extension:

Setting	Description	Default	php.ini	ini_set()
ingres.allow_persistent	Allow persistent links	On	Yes	No
ingres.max_persistent	Maximum number of persistent links allowed	-1	Yes	No
ingres.max_links	Maximum number of links allowed	-1	Yes	No
ingres.default_database	Default database name		Yes	Yes
ingres.default_user	Default user name		Yes	Yes
ingres.default_password	Default password		Yes	Yes
ingres.report_db_warnings	Suppress DB warnings	On	Yes	Yes
ingres.blob_segment_length	Size of the memory buffer in bytes to be used when chunking BLOB data	4096	Yes	Yes
ingres.trace_connect	Trace the ingres_connect() / ingres_pconnect() functions	Off	Yes	Yes
ingres.timeout	Time in ms the OpenAPI IIapi_initialize function will wait before failing	-1	Yes	Yes
ingres.array_index_start	Start index from which arrays return by ingres_fetch_array() should use	1	Yes	Yes

4. Installing the extension

Windows Installation

The latest binaries for the Ingres extension can be downloaded from http://pecl4win.php.net/ext.php/php_ingres.dll. Direct links are provided below for different PHP releases:

To install the extension copy php_ingres.dll into the extension_dir configured in php.ini.

UNIX/Linux Installation

The installation of the extension on UNIX/Linux will require a C complilation environment.

The latest source code can be downloaded manually from http://pecl.php.net/get/ingres. Or by using the pecl command:

    pecl download ingres-1.4.2

Once you have the source archive run through the following steps to build and install, note that $II_SYSTEM needs to be defined beforehand:

Extract the archive, adapt the version number accordingly:
```
tar -zxvf ingres-1.4.2.tgz
```
Enter the newly created directory:
```
cd ingres-1.4.2
```
Generate the configuration file for the extension:
```
phpize
```
Generate the Makefile needed to build the extension:
```
./configure
```
Build the extension:
```
make
```
Install the extension, N.B. this may require root access :
```
make install
```

Ingres with the Apache web server on UNIX/Linux

This extension, like other Ingres applications, requires knowledge of a local Ingres installation. Providing Apache with this information can be done two ways both of which require mod_env. The following assumes Ingres was installed to /opt/Ingres/II:

Using PassEnv:

In the script that starts Apache add the following lines:

II_SYSTEM=/opt/Ingres/II
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$II_SYSTEM/ingres/lib
export II_SYSTEM LD_LIBRARY_PATH

Add the following lines to the apache configuration script httpd.conf (or equivalent):
```
PassEnv II_SYSTEM LD_LIBRARY_PATH
```

Using SetEnv:

Add the following lines to the apache configuration script httpd.conf (or equivalent):
```
SetEnv II_SYSTEM /opt/Ingres/II
SetEnv LD_LIBRARY_PATH /opt/Ingres/II/ingres/lib
```

Activating the Ingres PECL extension

Windows

Add the following line to the php.ini configuration file:

extension = php_ingres.dll

If a web server is being used to serve PHP scripts, restart it to activate the Ingres extension.

UNIX/Linux

Add the following line to the php.ini configuration file:

extension = ingres.so

If a web server is being used to serve PHP scripts, restart it to activate the Ingres extension.

5. Known issues

Bugs

For a list of known bugs go to pecl.php.net.

Multi-threaded web servers

When working with multi-threaded web servers certain considerations need to be made. Each server thread that can service an HTTP request could potentially connect to an Ingres server, either directly or via Ingres/NET. Depending on the number of server threads configured this could exceed the number of sessions allowed by Ingres. With Apache HTTPd's mpm-winnt module this is configured using ThreadsPerChild and with the worker module this is controlled using the MaxSpareThreads (with Apache HTTPd worker MaxSpareThreads controls the overall number threads across all child processes).

6. Future direction

Since the code has been relatively stable for a number of years, all current development efforts have tried to avoid, where possible, changing syntax of any existing function. The TODO file covers the items that are on the list to be implemented.

There are, however, some things that would be nice to have but might prove difficult to implement without breaking backwards compatibility, either with versions of Ingres or with existing Ingres based PHP code.

The current extension maintains a single statement handle. Whenever a query is executed via ingres_query() or ingres_prepare(), any existing statement is terminated/closed. For multiple resultsets to work, the ingres_fetch_*() statements will need to be able to accept a resource that represents an Ingres resultset. Such that:

  ingres_fetch_row( [resource link] )

would have to change to:

  ingres_fetch_row( resource result )

Note '[]' means anything contained within is optional. Apart from passing a result resource instead of a link resource, the main difference is the parameter passed would be a mandatory parameter rather than optional as it is at the moment. This is more in keeping with how other PHP database interfaces work. Link resource parameters that are currently optional would become mandatory. Implementing this would make the extension incompatible with existing scripts that use Ingres.

It is possible for the code to be branched such that any future versions that break backwards compatibility are clearly marked as doing so. This will be done according to demand.

7. Comments/suggestions/credits

The architecture for the Ingres extension is based on code written by David Hénot (henot@php.net) from 2000-2004. Since February 2005, Grant Croker, (grantc@php.net), took over the maintenance and development of the extension.

If you have any comments, features or if you wish to assist in some way with coding, testing or documentation please contact grantc@php.net.