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.
This extension has been written to support the following versions of Ingres:
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 openSuSE 11 using GCC 4.3. There has been limited testing on Solaris 10 Sparc. If you find the extension does not work, please log a bug via the project home page with the following information:
<?php
echo INGRES_EXT_VERSION . " " . INGRES_API_VERSION;
?>
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_escape_string | Escape special characters for use in a query |
| 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 byingres_execute |
| ingres_query | Send a SQL query to Ingres |
| ingres_set_environment | Set one or more Ingres environment variables |
| ingres_rollback | Rollback a transaction |
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://esd.ingres.com/product/drivers/PHP. Binary releases for certain operating systems will be provided in due course.
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.array_index_start | Start index from which arrays return by ingres_fetch_array() should use | 1 | Yes | Yes |
| ingres.auto | Emulate AUTO COMMIT when working with cursors | 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.default_database | Default database name | Yes | Yes | |
| ingres.default_user | Default user name | Yes | Yes | |
| ingres.describe | Enable / Disable DESCRIBE INPUT | On | Yes | Yes |
| ingres.default_password | Default password | Yes | Yes | |
| ingres.fetch_buffer_size | The number of rows to pre-fetch | 100 | Yes | Yes |
| ingres.max_links | Maximum number of links allowed | -1 | Yes | No |
| ingres.max_persistent | Maximum number of persistent links allowed | -1 | Yes | No |
| ingres.reuse_connection | When connecting with ingres_connect()/ingres_pconnect(), use an active connection to the database if the username is the same | On | Yes | Yes |
| ingres.scrollable | Use scrollable cursors or not. With Ingres 9.2 this needs to be disable for queries that fetch LOB data | On | Yes | Yes |
| ingres.trace | Enable some basic query tracing in ingres_query() | Off | Yes | Yes |
| ingres.trace_connect | Trace the ingres_connect() / ingres_pconnect() functions | Off | Yes | Yes |
| ingres.utf8 | Assume all strings passed to NVARCHAR/NCHAR columns are in UTF-8 | On | Yes | Yes |
The latest binaries for the Ingres extension can be downloaded from http://esd.ingres.com/product/drivers/PHP. To install the extension copy php_ingres.dll into the extension_dir configured in php.ini.
The installation of the extension on UNIX/Linux will require a C complilation environment. If you have built and installed PHP from source code obtained via CVS or an archive, you will already have the necessary files. If however you are using Linux and have installed PHP using the operating system package manager (Synaptic, Package Kit, yum, aptitude or zypper) then it is probable you will also need to install the "development" package for PHP. This additional package contains the necessary files needed for building and installing PHP extensions, such as ingres. Below is a list of the PHP development packages for Redhat, SuSE and Ubuntu/Debian:
The Ingres extension can be downloaded an installed using just one command:
pecl install ingresWhen prompted:
The latest source code can be downloaded manually from http://pecl.php.net/get/ingres. Once you have the source archive run through the following steps to build and install, note that $II_SYSTEM needs to be defined beforehand:
tar -zxvf ingres-2.2.1.tgz
cd ingres-2.2.1
phpize
./configure
make
make install
cp -v modules/ingres.so `php -r 'echo ini_get("extension_dir");'`
Where php is the PHP executable for your target environment.
This extension, like other Ingres applications, requires knowledge of a local Ingres installation. The Apache extension, mod_env is required for this to work. The following assumes Ingres was installed to /opt/Ingres/II:
II_SYSTEM=/opt/Ingres/II LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$II_SYSTEM/ingres/lib export II_SYSTEM LD_LIBRARY_PATH
PassEnv II_SYSTEM LD_LIBRARY_PATH
Add the following line to the php.ini configuration file:
extension = php_ingres.dllIf a web server is being used to serve PHP scripts, restart it to activate the Ingres extension.
Add the following line to the php.ini configuration file:
extension = ingres.soIf a web server is being used to serve PHP scripts, restart it to activate the Ingres extension.
For a list of known bugs go to pecl.php.net.
When working with multi-threaded web servers certain considerations need to be made. Each HTTP server thread represents a single DBMS server connection, that 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). Verify that the number of threads in the HTTP server does not exceed the number of GCC sessions or DBMS server sessions.
Support for the PECL Ingres interface is available from a number of different sources. Users with a support contract can either raise an issue via https://servicedesk.ingres.com/ or through their local technical support department. See http://ingres.com/support for a complete list of locations, primary service hours, and telephone numbers. Users without a support contract can post questions or problems to the Ingres Community Forums (http://community.ingres.com/forum/php), to comp.databases.ingres (http://groups.google.com/group/comp.databases.ingres), or to the PECL developer mailing list (http://www.php.net/mailing-lists.php).
New features planned for the Ingres PECL
extension are documented in the TODO file that
is shipped with the source code or via PHP's CVS source
code repository.
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.