# Informix Functions

## Introduction

The Informix driver for Informix (IDS) 7.x, SE 7.x, Universal Server (IUS) 9.x and IDS 2000 is implemented in "ifx.ec" and "php3_ifx.h" in the informix extension directory. IDS 7.x support is fairly complete, with full support for BYTE and TEXT columns. IUS 9.x support is partly finished: the new data types are there, but SLOB and CLOB support is still under construction.

> Note: This extension has been moved to the » PECL repository and is no longer bundled with PHP as of PHP 5.2.1.

## Requirements

> Note: Configuration notes You need a version of ESQL/C to compile the PHP Informix driver. ESQL/C versions from 7.2x on should be OK. ESQL/C is now part of the Informix Client SDK.
> Make sure that the "INFORMIXDIR" variable has been set, and that $INFORMIXDIR/bin is in your PATH before you run the "configure" script.

## Installation

To be able to use the functions defined in this module you must compile your PHP interpreter using the configure line --with-informix[=DIR], where DIR is the Informix base install directory, defaults to nothing.

## Runtime Configuration

The behaviour of these functions is affected by settings in php.ini.

> Note: Make sure that the Informix environment variables INFORMIXDIR and INFORMIXSERVER are available to the PHP ifx driver, and that the INFORMIX bin directory is in the PATH. Check this by running a script that contains a call to phpinfo() before you start testing. The phpinfo() output should list these environment variables. This is true for both CGI php and Apache mod_php. You may have to set these environment variables in your Apache startup script.
> The Informix shared libraries should also be available to the loader (check LD_LIBRARY_PATH or ld.so.conf/ldconfig).

> Note: Some notes on the use of BLOBs (TEXT and BYTE columns) BLOBs are normally addressed by BLOB identifiers. Select queries return a "blob id" for every BYTE and TEXT column. You can get at the contents with "string_var = ifx_get_blob($blob_id);" if you choose to get the BLOBs in memory (with: "ifx_blobinfile(0);"). If you prefer to receive the content of BLOB columns in a file, use "ifx_blobinfile(1);", and "ifx_get_blob($blob_id);" will get you the filename. Use normal file I/O to get at the blob contents.
> For insert/update queries you must create these "blob id's" yourself with "ifx_create_blob();". You then plug the blob id's into an array, and replace the blob columns with a question mark (?) in the query string. For updates/inserts, you are responsible for setting the blob contents with ifx_update_blob().
> The behaviour of BLOB columns can be altered by configuration variables that also can be set at runtime:
> configuration variable: ifx.textasvarchar
> configuration variable: ifx.byteasvarchar
> runtime functions:
> ifx_textasvarchar(0): use blob id's for select queries with TEXT columns
> ifx_byteasvarchar(0): use blob id's for select queries with BYTE columns
> ifx_textasvarchar(1): return TEXT columns as if they were VARCHAR columns, so that you don't need to use blob id's for select queries.
> ifx_byteasvarchar(1): return BYTE columns as if they were VARCHAR columns, so that you don't need to use blob id's for select queries.
> configuration variable: ifx.blobinfile
> runtime function:
> ifx_blobinfile_mode(0): return BYTE columns in memory, the blob id lets you get at the contents.
> ifx_blobinfile_mode(1): return BYTE columns in a file, the blob id lets you get at the file name.
> If you set ifx_text/byteasvarchar to 1, you can use TEXT and BYTE columns in select queries just like normal (but rather long) VARCHAR fields. Since all strings are "counted" in PHP, this remains "binary safe". It is up to you to handle this correctly. The returned data can contain anything, you are responsible for the contents.
> If you set ifx_blobinfile to 1, use the file name returned by ifx_get_blob(..) to get at the blob contents. Note that in this case YOU ARE RESPONSIBLE FOR DELETING THE TEMPORARY FILES CREATED BY INFORMIX when fetching the row. Every new row fetched will create new temporary files for every BYTE column.
> The location of the temporary files can be influenced by the environment variable "blobdir", default is "." (the current directory). Something like: putenv(blobdir=tmpblob"); will ease the cleaning up of temp files accidentally left behind (their names all start with "blb").

> Note: Automatically trimming "char" (SQLCHAR and SQLNCHAR) data This can be set with the configuration variable
> ifx.charasvarchar: if set to 1 trailing spaces will be automatically trimmed, to save you some "chopping".

> Note: `NULL` values The configuration variable ifx.nullformat (and the runtime function ifx_nullformat()) when set to `TRUE` will return `NULL` columns as the string "`NULL`", when set to `FALSE` they return the empty string. This allows you to discriminate between `NULL` columns and empty columns.

Informix configuration options
Name | Default | Changeable | Changelog
--- | --- | --- | ---
ifx.allow_persistent | "1" | PHP_INI_SYSTEM | Removed in PHP 5.2.1.
ifx.max_persistent | "-1" | PHP_INI_SYSTEM | Removed in PHP 5.2.1.
ifx.max_links | "-1" | PHP_INI_SYSTEM | Removed in PHP 5.2.1.
ifx.default_host | NULL | PHP_INI_SYSTEM | Removed in PHP 5.2.1.
ifx.default_user | NULL | PHP_INI_SYSTEM | Removed in PHP 5.2.1.
ifx.default_password | NULL | PHP_INI_SYSTEM | Removed in PHP 5.2.1.
ifx.blobinfile | "1" | PHP_INI_ALL | Removed in PHP 5.2.1.
ifx.textasvarchar | "0" | PHP_INI_ALL | Removed in PHP 5.2.1.
ifx.byteasvarchar | "0" | PHP_INI_ALL | Removed in PHP 5.2.1.
ifx.charasvarchar | "0" | PHP_INI_ALL | Removed in PHP 5.2.1.
ifx.nullformat | "0" | PHP_INI_ALL | Removed in PHP 5.2.1.

For further details and definitions of the PHP_INI_* constants, see the php.ini directives.

Here's a short explanation of the configuration directives.

`ifx.allow_persistent` boolean

  Whether to allow persistent Informix connections.

`ifx.max_persistent` integer

  The maximum number of persistent Informix connections per process.

`ifx.max_links` integer

  The maximum number of Informix connections per process, including persistent connections.

`ifx.default_host` string

  The default host to connect to when no host is specified in ifx_connect() or ifx_pconnect(). Doesn't apply in safe mode.

`ifx.default_user` string

  The default user id to use when none is specified in ifx_connect() or ifx_pconnect(). Doesn't apply in safe mode.

`ifx.default_password` string

  The default password to use when none is specified in ifx_connect() or ifx_pconnect(). Doesn't apply in safe mode.

`ifx.blobinfile` boolean

  Set to `TRUE` if you want to return blob columns in a file, `FALSE` if you want them in memory. You can override the setting at runtime with ifx_blobinfile_mode().

`ifx.textasvarchar` boolean

  Set to `TRUE` if you want to return TEXT columns as normal strings in select statements, `FALSE` if you want to use blob id parameters. You can override the setting at runtime with ifx_textasvarchar().

`ifx.byteasvarchar` boolean

  Set to `TRUE` if you want to return BYTE columns as normal strings in select queries, `FALSE` if you want to use blob id parameters. You can override the setting at runtime with ifx_textasvarchar().

`ifx.charasvarchar` boolean

  Set to `TRUE` if you want to trim trailing spaces from CHAR columns when fetching them.

`ifx.nullformat` boolean

  Set to `TRUE` if you want to return `NULL` columns as the literal string "`NULL`", `FALSE` if you want them returned as the empty string "". You can override this setting at runtime with ifx_nullformat().

## Resource Types

## Predefined Constants

The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.

`IFX_SCROLL` (integer)
`IFX_HOLD` (integer)
`IFX_LO_RDONLY` (integer)
`IFX_LO_WRONLY` (integer)
`IFX_LO_APPEND` (integer)
`IFX_LO_RDWR` (integer)
`IFX_LO_BUFFER` (integer)
`IFX_LO_NOBUFFER` (integer)

## Table of Contents

- ifx_affected_rows — Get number of rows affected by a query
- ifx_blobinfile_mode — Set the default blob mode for all select queries
- ifx_byteasvarchar — Set the default byte mode
- ifx_close — Close Informix connection
- ifx_connect — Open Informix server connection
- ifx_copy_blob — Duplicates the given blob object
- ifx_create_blob — Creates an blob object
- ifx_create_char — Creates an char object
- ifx_do — Execute a previously prepared SQL-statement
- ifx_error — Returns error code of last Informix call
- ifx_errormsg — Returns error message of last Informix call
- ifx_fetch_row — Get row as an associative array
- ifx_fieldproperties — List of SQL fieldproperties
- ifx_fieldtypes — List of Informix SQL fields
- ifx_free_blob — Deletes the blob object
- ifx_free_char — Deletes the char object
- ifx_free_result — Releases resources for the query
- ifx_get_blob — Return the content of a blob object
- ifx_get_char — Return the content of the char object
- ifx_getsqlca — Get the contents of sqlca.sqlerrd[0..5] after a query
- ifx_htmltbl_result — Formats all rows of a query into a HTML table
- ifx_nullformat — Sets the default return value on a fetch row
- ifx_num_fields — Returns the number of columns in the query
- ifx_num_rows — Count the rows already fetched from a query
- ifx_pconnect — Open persistent Informix connection
- ifx_prepare — Prepare an SQL-statement for execution
- ifx_query — Send Informix query
- ifx_textasvarchar — Set the default text mode
- ifx_update_blob — Updates the content of the blob object
- ifx_update_char — Updates the content of the char object
- ifxus_close_slob — Deletes the slob object
- ifxus_create_slob — Creates an slob object and opens it
- ifxus_free_slob — Deletes the slob object
- ifxus_open_slob — Opens an slob object
- ifxus_read_slob — Reads nbytes of the slob object
- ifxus_seek_slob — Sets the current file or seek position
- ifxus_tell_slob — Returns the current file or seek position
- ifxus_write_slob — Writes a string into the slob object