Ingres extension for PHP
-------------------------------------------------------------------------------
1. Introduction
2. Platform_support
1. Ingres_Releases
2. PHP_Releases
3. Operating_System_Compatibility
3. Function_support
1. Project_home_page
2. Configuration_Options
4. Installing_the_extension
1. Windows_Installation
2. UNIX/Linux_Installation
3. Ingres_with_the_Apache_web_server_on_UNIX/Linux
4. Activating_the_Ingres_PECL_extension
5. Known_issues
1. Bugs
2. Multi-threaded_web_servers
6. Future_direction
7. Support
8. Comments/suggestions/credits
-------------------------------------------------------------------------------
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.
-------------------------------------------------------------------------------
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 / 3.0.x
* Ingres 2006 / 9.0.0
* Ingres 2006 Release 2 / 9.1.0
* Ingres 2006 Release 2 Service Pack 1 / 9.1.1
* Ingres 9.2.0
* Ingres 9.3.0
* Ingres 10.0.0
PHP Releases
This extension has been written against PHP 5.1, PHP 5.2 and PHP 5.3. 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 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:
* 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;
?>
-------------------------------------------------------------------------------
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_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_assoc Fetch a row of result into an associative 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
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://esd.ingres.com/product/drivers/PHP.
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_______|
| |Start index from which | | | |
|ingres.array_index_start |arrays return by |1 |Yes |Yes |
| |ingres_fetch_array() | | | |
|__________________________|should_use______________|_______|_______|_________|
|ingres.auto |Emulate AUTO COMMIT when|On |Yes |Yes |
|__________________________|working_with_cursors____|_______|_______|_________|
| |Size of the memory | | | |
|ingres.blob_segment_length|buffer in bytes to be |4096 |Yes |Yes |
| |used when chunking BLOB | | | |
|__________________________|data____________________|_______|_______|_________|
|ingres.default_database___|Default_database_name___| _____|Yes____|Yes______|
|ingres.default_user_______|Default_user_name_______| _____|Yes____|Yes______|
|ingres.describe |Enable / Disable |On |Yes |Yes |
|__________________________|DESCRIBE_INPUT__________|_______|_______|_________|
|ingres.default_password___|Default_password________| _____|Yes____|Yes______|
|ingres.fetch_buffer_size |The number of rows to |100 |Yes |Yes |
|__________________________|pre-fetch_______________|_______|_______|_________|
|ingres.max_links |Maximum number of links |-1 |Yes |No |
|__________________________|allowed_________________|_______|_______|_________|
|ingres.max_persistent |Maximum number of |-1 |Yes |No |
|__________________________|persistent_links_allowed|_______|_______|_________|
| |When connecting with | | | |
| |ingres_connect()/ | | | |
|ingres.reuse_connection |ingres_pconnect(), use |On |Yes |Yes |
| |an active connection to | | | |
| |the database if the | | | |
|__________________________|username_is_the_same____|_______|_______|_________|
| |Use scrollable cursors | | | |
| |or not. With Ingres 9.2 | | | |
|ingres.scrollable |this needs to be disable|On |Yes |Yes |
| |for queries that fetch | | | |
|__________________________|LOB_data________________|_______|_______|_________|
| |Enable some basic query | | | |
|ingres.trace |tracing in ingres_query |Off |Yes |Yes |
|__________________________|()______________________|_______|_______|_________|
| |Trace the ingres_connect| | | |
|ingres.trace_connect |() / ingres_pconnect() |Off |Yes |Yes |
|__________________________|functions_______________|_______|_______|_________|
| |Assume all strings | | | |
|ingres.utf8 |passed to NVARCHAR/NCHAR|On |Yes |Yes |
|__________________________|columns_are_in_UTF-8____|_______|_______|_________|
-------------------------------------------------------------------------------
Installing the extension
Windows Installation
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.
UNIX/Linux Installation
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:
* SuSE Linux Enterprise Server / openSuSE - php4-devel - for PHP 4.x
* SuSE Linux Enterprise Server / openSuSE - php5-devel - for PHP 5.x
* Redhat Enterprise Linux/Centos/Fedora - php-devel
* Debian/Ubuntu Linux - php-dev
Please refer to the operating system documentation for more information on how
to install the necessary packages.
Installing with pecl
The Ingres extension can be downloaded an installed using just one command:
pecl install ingres
When prompted:
1. Enter 'all'
2. Provide the value for $II_SYSTEM
3. Press enter
4. Follow the instructions at the end of the build for activating the
extension
Installing from source
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:
1. Extract the archive, adapt the version number accordingly:
tar -zxvf ingres-2.2.2.tgz
2. Enter the newly created directory:
cd ingres-2.2.2
3. Generate the configuration file for the extension:
phpize
4. Generate the Makefile needed to build the extension:
./configure
5. Build the extension:
make
6. Install the extension, N.B. this may require root access :
make install
7. If your PHP build environment is not the same as the target PHP
environment then use the following command, N.B. this may require root
access :
cp -v modules/ingres.so `php -r 'echo ini_get("extension_dir");'`
Where php is the PHP executable for your target environment.
Ingres with the Apache web server on UNIX/Linux
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:
* 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
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.
-------------------------------------------------------------------------------
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 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
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).
-------------------------------------------------------------------------------
Future direction
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.
-------------------------------------------------------------------------------
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.