grantc / pecl-ingres Goto Github PK

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 ([email protected]) from 2000-2004. Since February 2005, Grant Croker,
([email protected]), 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 [email protected].