<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.27 $ -->
 <reference id="ref.ifx">
  <title>Informix functions</title>
  <titleabbrev>Informix</titleabbrev>

  <partintro>
   <para>
    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.
   </para>
   <note>
    <title>Configuration notes</title>
    <para>
     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.
    </para>
    <para>
     Make sure that the "INFORMIXDIR" variable has been set, and that
     $INFORMIXDIR/bin is in your PATH before you run the "configure"
     script.
    </para>
    <para> 
     The configure script will autodetect the libraries and include
     directories, if you run "configure --with_informix=yes".  You can
     override this detection by specifying "IFX_LIBDIR", "IFX_LIBS" and
     "IFX_INCDIR" in the environment.  The configure script will also
     try to detect your Informix server version.  It will set the
     "HAVE_IFX_IUS" conditional compilation variable if your Informix
     version >= 9.00.
    </para>
   </note>
   <note>
    <title>Runtime considerations</title>
    <para>
     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 <function>phpinfo</function>
     before you start testing. The <function>phpinfo</function>
     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.
    </para>
    <para>
     The Informix shared libraries should also be available to the
     loader (check LD_LINBRARY_PATH or ld.so.conf/ldconfig).
    </para>
   </note>
   <note>
    <title>
     Some notes on the use of BLOBs (TEXT and BYTE columns)
    </title>
    <para>
     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.
    </para>
    <para>
     For insert/update queries you must create these "blob id's"
     yourself with "<function>ifx_create_blob</function>;". 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 <function>ifx_update_blob</function>.
    </para>
    <para>
     The behaviour of BLOB columns can be altered by configuration
     variables that also can be set at runtime :
    </para>
    <para>
     configuration variable : ifx.textasvarchar
    </para>
    <para>
     configuration variable : ifx.byteasvarchar
    </para>
    <para>
     runtime functions :
    </para>
    <para>
     ifx_textasvarchar(0) : use blob id's for select queries with TEXT
     columns
    </para>
    <para>
     ifx_byteasvarchar(0) : use blob id's for select queries with BYTE
     columns
    </para>
    <para>
     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.
    </para>
    <para>
     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.
    </para>
    <para>
     configuration variable : ifx.blobinfile
    </para>
    <para>
     runtime function :
    </para>
    <para>
     ifx_blobinfile_mode(0) : return BYTE columns in memory, the blob
     id lets you get at the contents.
    </para>
    <para>
     ifx_blobinfile_mode(1) : return BYTE columns in a file, the blob
     id lets you get at the file name.
    </para>
    <para>
     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.
    </para>
    <para>
     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.
    </para>
    <para>
     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").
    </para>
   </note>
   <note>
    <title>Automatically trimming "char" (SQLCHAR and SQLNCHAR) data</title>
    <para>
     This can be set with the configuration variable
    </para>
    <para>
     ifx.charasvarchar : if set to 1 trailing spaces will be
     automatically trimmed, to save you some "chopping".
    </para>
   </note>
   <note>
    <title>&null; values</title>
    <para>
     The configuration variable ifx.nullformat (and the runtime
     function <function>ifx_nullformat</function>) 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.
    </para>
   </note>
  </partintro>

  <refentry id="function.ifx-connect">
   <refnamediv>
    <refname>ifx_connect</refname>
    <refpurpose>Open Informix server connection</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifx_connect</methodname>
      <methodparam choice="opt"><type>string</type><parameter>database
                       </parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>userid
                       </parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>password
                       </parameter></methodparam>
     </methodsynopsis>
    <para> 
     Returns a connection identifier on success, or &false; on
     error.
    </para>
    <para> 
     <function>ifx_connect</function> establishes a connection to an
     Informix server.  All of the arguments are optional, and if
     they're missing, defaults are taken from values supplied in <link
     linkend="configuration.file">configuration file</link>
     (ifx.default_host for the host (Informix libraries will use
     <envar>INFORMIXSERVER</envar> environment value if not defined),
     ifx.default_user for user, ifx.default_password for the password
     (none if not defined).
    </para>
    <para> 
     In case a second call is made to
     <function>ifx_connect</function> with the same arguments, no
     new link will be established, but instead, the link identifier of
     the already opened link will be returned.
    </para>
    <para> 
     The link to the server will be closed as soon as the execution of
     the script ends, unless it's closed earlier by explicitly calling
     <function>ifx_close</function>.
    </para>
    <para> 
     See also <function>ifx_pconnect</function>, and
     <function>ifx_close</function>.
     <example>
      <title>Connect to a Informix database</title>
      <programlisting role="php">
<![CDATA[
$conn_id = ifx_connect ("mydb@ol_srv1", "imyself", "mypassword");
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-pconnect">
   <refnamediv>
    <refname>ifx_pconnect</refname>
    <refpurpose>Open persistent Informix connection</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifx_pconnect</methodname>
      <methodparam choice="opt"><type>string</type><parameter>database</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>userid</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>password</parameter></methodparam>
     </methodsynopsis>
    <para> 
     Returns: A positive Informix persistent link identifier on success,
     or &false; on error
    </para>
    <para>
     <function>ifx_pconnect</function> acts very much like
     <function>ifx_connect</function> with two major differences.
    </para>
    <para> 
     This function behaves exactly like <function>ifx_connect</function>
     when PHP is not running as an Apache module.
     First, when connecting, the function would first try to find a
     (persistent) link that's already open with the same host,
     username and password.  If one is found, an identifier for it
     will be returned instead of opening a new connection.
    </para>
    <para> 
     Second, the connection to the SQL server will not be closed when
     the execution of the script ends.  Instead, the link will remain
     open for future use (<function>ifx_close</function> will not
     close links established by <function>ifx_pconnect</function>).
    </para>
    <para> 
     This type of links is therefore called 'persistent'.
    </para>
    <para>
     See also: <function>ifx_connect</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-close">
   <refnamediv>
    <refname>ifx_close</refname>
    <refpurpose>Close Informix connection</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifx_close</methodname>
      <methodparam choice="opt"><type>int</type><parameter>link_identifier</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns: always &true;.
    </para>
    <para> 
     <function>ifx_close</function> closes the link to an Informix
     database that's associated with the specified link identifier.
     If the link identifier isn't specified, the last opened link is
     assumed.
    </para>
    <para> 
     Note that this isn't usually necessary, as non-persistent open
     links are automatically closed at the end of the script's
     execution.
    </para>
    <para> 
     <function>ifx_close</function> will not close persistent links
     generated by <function>ifx_pconnect</function>.
    </para>
    <para> 
     See also: <function>ifx_connect</function>, and
     <function>ifx_pconnect</function>.
     <example>
      <title>Closing a Informix connection</title>
      <programlisting role="php">
<![CDATA[
$conn_id = ifx_connect ("mydb@ol_srv", "itsme", "mypassword");
... some queries and stuff ...
ifx_close($conn_id);
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-query">
   <refnamediv>
    <refname>ifx_query</refname>
    <refpurpose>Send Informix query</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifx_query</methodname>
      <methodparam><type>string</type><parameter>query</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>link_identifier</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>cursor_type</parameter></methodparam>
      <methodparam choice="opt"><type>mixed</type><parameter>
        blobidarray
       </parameter></methodparam>
     </methodsynopsis>
    <para> 
     Returns: A positive Informix result identifier on success, or
     &false; on error.  
    </para>
    <para> 
     A "result_id" resource used by other functions to retrieve the
     query results.  Sets "affected_rows" for retrieval by the
     <function>ifx_affected_rows</function> function.
    </para>
    <para> 
     <function>ifx_query</function> sends a query to the currently
     active database on the server that's associated with the
     specified link identifier.  If the link identifier isn't
     specified, the last opened link is assumed.  If no link is open,
     the function tries to establish a link as if
     <function>ifx_connect</function> was called, and use it.
    </para>
    <para>
     Executes <parameter>query</parameter> on connection
     <parameter>conn_id</parameter>. For "select-type" queries a
     cursor is declared and opened. The optional
     <parameter>cursor_type</parameter> parameter allows you to make
     this a "scroll" and/or "hold" cursor.  It's a bitmask and can be
     either IFX_SCROLL, IFX_HOLD, or both or'ed together. Non-select
     queries are "execute immediate".  IFX_SCROLL and IFX_HOLD are
     symbolic constants and as such shouldn't be between quotes. I you
     omit this parameter the cursor is a normal sequential cursor.
    </para>
    <para>
     For either query type the number of (estimated or real) affected
     rows is saved for retrieval by
     <function>ifx_affected_rows</function>.
    </para>
    <para>
     If you have BLOB (BYTE or TEXT) columns in an update query, you
     can add a <parameter>blobidarray</parameter> parameter containing
     the corresponding "blob ids", and you should replace those
     columns with a "?" in the query text.
    </para>
    <para>
     If the contents of the TEXT (or BYTE) column allow it, you can
     also use "ifx_textasvarchar(1)" and "ifx_byteasvarchar(1)".  This
     allows you to treat TEXT (or BYTE) columns just as if they were
     ordinary (but long) VARCHAR columns for select queries, and you
     don't need to bother with blob id's.
    </para><para>
     With ifx_textasvarchar(0) or ifx_byteasvarchar(0) (the default
     situation), select queries will return BLOB columns as blob id's
     (integer value).  You can get the value of the blob as a string
     or file with the blob functions (see below).
    </para>
    <para>
     See also: <function>ifx_connect</function>.
     <example>
      <title>
       Show all rows of the "orders" table as a html table
      </title>
      <programlisting role="php">
<![CDATA[
ifx_textasvarchar(1);      // use "text mode" for blobs
$res_id = ifx_query("select * from orders", $conn_id);
if (! $res_id) {
    printf("Can't select orders : %s\n<br>%s<br>\n", ifx_error());
    ifx_errormsg();
    die;
}
ifx_htmltbl_result($res_id, "border=\"1\"");
ifx_free_result($res_id);
]]>
      </programlisting>
     </example>
     <example>
      <title>Insert some values into the "catalog" table</title>
      <programlisting role="php">
<![CDATA[   
                   // create blob id's for a byte and text column
$textid = ifx_create_blob(0, 0, "Text column in memory");
$byteid = ifx_create_blob(1, 0, "Byte column in memory");
                      // store blob id's in a blobid array
$blobidarray[] = $textid;
$blobidarray[] = $byteid;
                      // launch query
$query = "insert into catalog (stock_num, manu_code, " .
         "cat_descr,cat_picture) values(1,'HRO',?,?)";
$res_id = ifx_query($query, $conn_id, $blobidarray);
if (! $res_id) {
  ... error ...
}
                     // free result id
ifx_free_result($res_id);
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-prepare">
   <refnamediv>
    <refname>ifx_prepare</refname>
    <refpurpose>Prepare an SQL-statement for execution</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifx_prepare</methodname>
      <methodparam><type>string</type><parameter>query</parameter></methodparam>
      <methodparam><type>int</type><parameter>conn_id</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>cursor_def</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>blobidarray</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns a integer <parameter>result_id</parameter> for use by
     <function>ifx_do</function>.  Sets
     <parameter>affected_rows</parameter> for retrieval by the
     <function>ifx_affected_rows</function> function.  
    </para>
    <para>
     Prepares <parameter>query</parameter> on connection
     <parameter>conn_id</parameter>.  For "select-type" queries a
     cursor is declared and opened. The optional
     <parameter>cursor_type</parameter> parameter allows you to make
     this a "scroll" and/or "hold" cursor.  It's a bitmask and can be
     either IFX_SCROLL, IFX_HOLD, or both or'ed together.
    </para>
    <para> 
     For either query type the estimated number of affected rows is
     saved for retrieval by <function>ifx_affected_rows</function>.
    </para>
    <para>
     If you have BLOB (BYTE or TEXT) columns in the query, you can add
     a <parameter>blobidarray</parameter> parameter containing the
     corresponding "blob ids", and you should replace those columns
     with a "?" in the query text.
    </para>
    <para>
     If the contents of the TEXT (or BYTE) column allow it, you can
     also use "ifx_textasvarchar(1)" and "ifx_byteasvarchar(1)".  This
     allows you to treat TEXT (or BYTE) columns just as if they were
     ordinary (but long) VARCHAR columns for select queries, and you
     don't need to bother with blob id's.
    </para>
    <para>
     With ifx_textasvarchar(0) or ifx_byteasvarchar(0) (the default
     situation), select queries will return BLOB columns as blob id's
     (integer value).  You can get the value of the blob as a string
     or file with the blob functions (see below).
    </para>
    <para>
     See also: <function>ifx_do</function>.
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="function.ifx-do">
   <refnamediv>
    <refname>ifx_do</refname>
    <refpurpose>
     Execute a previously prepared SQL-statement
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifx_do</methodname>
      <methodparam><type>int</type><parameter>result_id</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns &true; on success, &false; on error.  
    </para>
    <para> 
     Executes a previously prepared query or opens a cursor for it.
    </para>
    <para> 
     Does NOT free <parameter>result_id</parameter> on error.
    </para>
    <para> 
     Also sets the real number of
     <function>ifx_affected_rows</function> for non-select statements
     for retrieval by <function>ifx_affected_rows</function>
    </para>
    <para>
     See also: <function>ifx_prepare</function>. There is a example.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-error">
   <refnamediv>
    <refname>ifx_error</refname>
    <refpurpose>Returns error code of last Informix call</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>ifx_error</methodname>
      <void/>
     </methodsynopsis>
    <para>
     The Informix error codes (SQLSTATE &amp; SQLCODE) formatted as
     follows :
    </para>
    <para>
     x [SQLSTATE = aa bbb SQLCODE=cccc]
    </para>
    <para>
     where x = space : no error
    </para>
    <para> 
     E : error
    </para>
    <para> 
     N : no more data
    </para>
    <para>        
     W : warning
    </para>
    <para>        
     ? : undefined
    </para>
    <para>
     If the "x" character is anything other than space, SQLSTATE and
     SQLCODE describe the error in more detail.
    </para>
    <para>
     See the Informix manual for the description of SQLSTATE and
     SQLCODE
    </para>
    <para>
     Returns in a string one character describing the general results
     of a statement and both SQLSTATE and SQLCODE associated with the
     most recent SQL statement executed. The format of the string is
     "(char) [SQLSTATE=(two digits) (three digits) SQLCODE=(one
     digit)]". The first character can be '<literal> </literal>'
     (space) (success), '<literal>W</literal>' (the statement caused
     some warning), '<literal>E</literal>' (an error happened when
     executing the statement) or '<literal>N</literal>' (the statement
     didn't return any data).  
    </para>
    <para> 
     See also: <function>ifx_errormsg</function>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-errormsg">
   <refnamediv>
    <refname>ifx_errormsg</refname>
    <refpurpose>Returns error message of last Informix call</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>ifx_errormsg</methodname>
      <methodparam choice="opt"><type>int</type><parameter>errorcode</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the Informix error message associated with the most
     recent Informix error, or, when the optional
     "<parameter>errorcode</parameter>" param is present, the error
     message corresponding to "<parameter>errorcode</parameter>".
    </para>
    <para> 
     See also: <function>ifx_error</function>
    </para>
    <informalexample>
     <programlisting role="php">
<![CDATA[
printf("%s\n&lt;br>", ifx_errormsg(-201));
]]>
     </programlisting>
    </informalexample>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-affected-rows">
   <refnamediv>
    <refname>ifx_affected_rows</refname>
    <refpurpose>Get number of rows affected by a query</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifx_affected_rows</methodname>
      <methodparam><type>int</type><parameter>result_id</parameter></methodparam>
     </methodsynopsis>
    <para>
     <parameter>result_id</parameter> is a valid result id returned by
     <function>ifx_query</function> or
     <function>ifx_prepare</function>. 
    </para>
    <para> 
     Returns the number of rows affected by a query associated with
     <parameter>result_id</parameter>.  
    </para>
    <para> 
     For inserts, updates and deletes the number is the real number
     (sqlerrd[2]) of affected rows. For selects it is an estimate
     (sqlerrd[0]). Don't rely on it. The database server can never
     return the actual number of rows that will be returned by a
     SELECT because it has not even begun fetching them at this stage
     (just after the "PREPARE" when the optimizer has determined the
     query plan).
    </para>
    <para> 
     Useful after <function>ifx_prepare</function> to limit queries to
     reasonable result sets.
    </para>
    <para>
     See also: <function>ifx_num_rows</function>
    </para>
     <example>
      <title>Informix affected rows</title>
      <programlisting role="php">
<![CDATA[
$rid = ifx_prepare ("select * from emp 
                     where name like " . $name, $connid);
if (! $rid) {
    ... error ...
}
$rowcount = ifx_affected_rows ($rid);
if ($rowcount > 1000) {
    printf ("Too many rows in result set (%d)\n<br>", $rowcount);
    die ("Please restrict your query<br>\n");
}
]]>
     </programlisting>
    </example>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-getsqlca">
   <refnamediv>
    <refname>ifx_getsqlca</refname>
    <refpurpose>
     Get the contents of sqlca.sqlerrd[0..5] after a query
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>ifx_getsqlca</methodname>
      <methodparam><type>int</type><parameter>result_id</parameter></methodparam>
     </methodsynopsis>
    <para>
     <parameter>result_id</parameter> is a valid result id returned by
     <function>ifx_query</function> or
     <function>ifx_prepare</function>. 
    </para>
    <para> 
     Returns a pseudo-row (associative array) with sqlca.sqlerrd[0]
     ... sqlca.sqlerrd[5] after the query associated with
     <parameter>result_id</parameter>.
    </para>
    <para> 
     For inserts, updates and deletes the values returned are those as
     set by the server after executing the query. This gives access to
     the number of affected rows and the serial insert value. For
     SELECTs the values are those saved after the PREPARE
     statement. This gives access to the *estimated* number of
     affected rows. The use of this function saves the overhead of
     executing a "select dbinfo('sqlca.sqlerrdx')" query, as it
     retrieves the values that were saved by the ifx driver at the
     appropriate moment.
    </para>
    <example>
     <title>Retrieve Informix sqlca.sqlerrd[x] values</title>
     <programlisting role="php">
<![CDATA[
/* assume the first column of 'sometable' is a serial */
$qid = ifx_query("insert into sometable 
                  values (0, '2nd column', 'another column') ", $connid);
if (! $qid) {
    ... error ...
}
$sqlca = ifx_getsqlca ($qid);
$serial_value = $sqlca["sqlerrd1"];
echo "The serial value of the inserted row is : " . $serial_value<br>\n"; 
]]>
     </programlisting>
    </example>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-fetch-row">
   <refnamediv>
    <refname>ifx_fetch_row</refname>
    <refpurpose>Get row as enumerated array</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>ifx_fetch_row</methodname>
      <methodparam><type>int</type><parameter>result_id</parameter></methodparam>
      <methodparam choice="opt"><type>mixed</type><parameter>position</parameter></methodparam>
     </methodsynopsis>
    <para> 
     Returns an associative array that corresponds to the fetched row,
     or &false; if there are no more rows.
    </para>
    <para>
     Blob columns are returned as integer blob id values for use in
     <function>ifx_get_blob</function> unless you have used
     ifx_textasvarchar(1) or ifx_byteasvarchar(1), in which case blobs
     are returned as string values.  Returns &false; on error
    </para>
    <para>
     <parameter>result_id</parameter> is a valid resultid returned by
     <function>ifx_query</function> or
     <function>ifx_prepare</function> (select type queries only!).
    </para>
    <para>
     <parameter>position</parameter> is an
     optional parameter for a "fetch" operation on "scroll" cursors:
     "NEXT", "PREVIOUS", "CURRENT", "FIRST", "LAST" or a number.  If
     you specify a number, an "absolute" row fetch is executed.  This
     parameter is optional, and only valid for SCROLL cursors.
    </para>
    <para>
     <function>ifx_fetch_row</function> fetches one row of data from
     the result associated with the specified result identifier.  The
     row is returned as an array.  Each result column is stored in an
     array offset, starting at offset 0, with the column name as key.
    </para>
    <para>
     Subsequent calls to <function>ifx_fetch_row</function> would
     return the next row in the result set, or &false; if there are no
     more rows.
    </para>
    <example>
     <title>Informix fetch rows</title>
     <programlisting role="php">
<![CDATA[
$rid = ifx_prepare ("select * from emp where name like " . $name,
                     $connid, IFX_SCROLL);
if (! $rid) {
    ... error ...
}
$rowcount = ifx_affected_rows($rid);
if ($rowcount > 1000) {
    printf ("Too many rows in result set (%d)\n<br>", $rowcount);
    die ("Please restrict your query<br>\n");
}
if (! ifx_do ($rid)) {
   ... error ...
}
$row = ifx_fetch_row ($rid, "NEXT");
while (is_array($row)) {
    for(reset($row); $fieldname=key($row); next($row)) {
        $fieldvalue = $row[$fieldname];
        printf ("%s = %s,", $fieldname, $fieldvalue);
    }
    printf("\n<br>");
    $row = ifx_fetch_row ($rid, "NEXT");
}
ifx_free_result ($rid);
]]>
     </programlisting>
    </example>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-htmltbl-result">
   <refnamediv>
    <refname>ifx_htmltbl_result</refname>
    <refpurpose>
     Formats all rows of a query into a HTML table
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifx_htmltbl_result</methodname>
      <methodparam><type>int</type><parameter>result_id</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>html_table_options</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the number of rows fetched or &false; on error.
    </para>
    <para>
     Formats all rows of the <parameter>result_id</parameter> query
     into a html table. The optional second argument is a string of
     &lt;table&gt; tag options
    </para>
    <example>
     <title>Informix results as HTML table</title>
     <programlisting role="php">
<![CDATA[
$rid = ifx_prepare ("select * from emp where name like " . $name,
                     $connid, IFX_SCROLL);
if (! $rid) {
   ... error ...
}
$rowcount = ifx_affected_rows ($rid);
if ($rowcount > 1000) {
    printf ("Too many rows in result set (%d)\n<br>", $rowcount);
    die ("Please restrict your query<br>\n");
}
if (! ifx_do($rid) {
  ... error ...
}

ifx_htmltbl_result ($rid, "border=\"2\"");

ifx_free_result($rid);
]]>
     </programlisting>
    </example>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-fieldtypes">
   <refnamediv>
    <refname>ifx_fieldtypes</refname>
    <refpurpose>List of Informix SQL fields</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>ifx_fieldtypes</methodname>
      <methodparam><type>int</type><parameter>result_id</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns an associative array with fieldnames as key and the SQL
     fieldtypes as data for query with
     <parameter>result_id</parameter>.  Returns &false; on error.
    </para>
    <example>
     <title>Fieldnames and SQL fieldtypes</title>
     <programlisting role="php">
<![CDATA[
$types = ifx_fieldtypes ($resultid);
if (! isset ($types)) {
  ... error ...
}
for ($i = 0; $i < count($types); $i++) {
    $fname = key($types);
    printf("%s :\t type =  %s\n", $fname, $types[$fname]);
    next($types);
}
]]>
     </programlisting>
    </example>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-fieldproperties">
   <refnamediv>
    <refname>ifx_fieldproperties</refname>
    <refpurpose>List of SQL fieldproperties</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>ifx_fieldproperties</methodname>
      <methodparam><type>int</type><parameter>result_id</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns an associative array with fieldnames as key and the SQL
     fieldproperties as data for a query with
     <parameter>result_id</parameter>.  Returns &false; on error.
    </para>
    <para>
     Returns the Informix SQL fieldproperties of every field in the
     query as an associative array.  Properties are encoded as:
     "SQLTYPE;length;precision;scale;ISNULLABLE" where SQLTYPE = the
     Informix type like "SQLVCHAR" etc. and ISNULLABLE = "Y" or "N".
    </para>
    <example>
     <title>Informix SQL fieldproperties</title>
     <programlisting role="php">
<![CDATA[
$properties = ifx_fieldproperties ($resultid);
if (! isset($properties)) {
  ... error ...
}
for ($i = 0; $i < count($properties); $i++) {
    $fname = key ($properties);
    printf ("%s:\t type =  %s\n", $fname, $properties[$fname]);
    next ($properties);
}
]]>
     </programlisting>
    </example>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-num-fields">
   <refnamediv>
    <refname>ifx_num_fields</refname>
    <refpurpose>Returns the number of columns in the query</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifx_num_fields</methodname>
      <methodparam><type>int</type><parameter>result_id</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the number of columns in query for
     <parameter>result_id</parameter> or &false; on error
    </para>
    <para>
     After preparing or executing a query, this call gives you the
     number of columns in the query.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-num-rows">
   <refnamediv>
    <refname>ifx_num_rows</refname>
    <refpurpose>Count the rows already fetched from a query</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifx_num_rows</methodname>
      <methodparam><type>int</type><parameter>result_id</parameter></methodparam>
     </methodsynopsis>
    <para>
     Gives the number of rows fetched so far for a query with
     <parameter>result_id</parameter> after a
     <function>ifx_query</function> or <function>ifx_do</function>
     query.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-free-result">
   <refnamediv>
    <refname>ifx_free_result</refname>
    <refpurpose>Releases resources for the query</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifx_free_result</methodname>
      <methodparam><type>int</type><parameter>result_id</parameter></methodparam>
     </methodsynopsis>
    <para>
     Releases resources for the query associated with
     <parameter>result_id</parameter>.  Returns &false; on error.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-create-char">
   <refnamediv>
    <refname>ifx_create_char</refname>
    <refpurpose>Creates an char object</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifx_create_char</methodname>
      <methodparam><type>string</type><parameter>param</parameter></methodparam>
     </methodsynopsis>
    <para>
     Creates an char object. <parameter>param</parameter> should
     be the char content.
    </para> 
   </refsect1>
  </refentry>

  <refentry id="function.ifx-free-char">
   <refnamediv>
    <refname>ifx_free_char</refname>
    <refpurpose>Deletes the char object</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifx_free_char</methodname>
      <methodparam><type>int</type><parameter>bid</parameter></methodparam>
     </methodsynopsis>
    <para>
     Deletes the charobject for the given char object-id
     <parameter>bid</parameter>. Returns &false; on error otherwise
     &true;.  
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-update-char">
   <refnamediv>
    <refname>ifx_update_char</refname>
    <refpurpose>Updates the content of the char object</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifx_update_char</methodname>
      <methodparam><type>int</type><parameter>bid</parameter></methodparam>
      <methodparam><type>string</type><parameter>content</parameter></methodparam>
     </methodsynopsis>
    <para>
     Updates the content of the char object for the given char object
     <parameter>bid</parameter>. <parameter>content</parameter> is a
     string with new data. Returns &false; on error otherwise &true;.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-get-char">
   <refnamediv>
    <refname>ifx_get_char</refname>
    <refpurpose>Return the content of the char object</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifx_get_char</methodname>
      <methodparam><type>int</type><parameter>bid</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the content of the char object for the given char
     object-id <parameter>bid</parameter>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-create-blob">
   <refnamediv>
    <refname>ifx_create_blob</refname>
    <refpurpose>Creates an blob object</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifx_create_blob</methodname>
      <methodparam><type>int</type><parameter>type</parameter></methodparam>
      <methodparam><type>int</type><parameter>mode</parameter></methodparam>
      <methodparam><type>string</type><parameter>param</parameter></methodparam>
     </methodsynopsis>
    <para>
     Creates an blob object.
    </para>
    <para>
     type: 1 = TEXT, 0 = BYTE
    </para>
    <para>
     mode: 0 = blob-object holds the content in memory, 
           1 = blob-object holds the content in file.
    </para>
    <para>
     param: if mode = 0: pointer to the content,
            if mode = 1: pointer to the filestring.
    </para>
    <para>
     Return &false; on error, otherwise the new blob object-id.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-copy-blob">
   <refnamediv>
    <refname>ifx_copy_blob</refname>
    <refpurpose>Duplicates the given blob object</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifx_copy_blob</methodname>
      <methodparam><type>int</type><parameter>bid</parameter></methodparam>
     </methodsynopsis>
    <para>
     Duplicates the given blob object. <parameter>bid</parameter> is
     the ID of the blob object.
    </para>
    <para>
     Returns &false; on error otherwise the new blob object-id.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-free-blob">
   <refnamediv>
    <refname>ifx_free_blob</refname>
    <refpurpose>Deletes the blob object</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifx_free_blob</methodname>
      <methodparam><type>int</type><parameter>bid</parameter></methodparam>
     </methodsynopsis>
    <para>
     Deletes the blobobject for the given blob object-id
     <parameter>bid</parameter>.  Returns &false; on error otherwise
     &true;.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-get-blob">
   <refnamediv>
    <refname>ifx_get_blob</refname>
    <refpurpose>Return the content of a blob object</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifx_get_blob</methodname>
      <methodparam><type>int</type><parameter>bid</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the content of the blob object for the given blob
     object-id <parameter>bid</parameter>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-update-blob">
   <refnamediv>
    <refname>ifx_update_blob</refname>
    <refpurpose>Updates the content of the blob object</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <methodname>ifx_update_blob</methodname>
      <methodparam><type>int</type><parameter>bid</parameter></methodparam>
      <methodparam><type>string</type><parameter>content</parameter></methodparam>
     </methodsynopsis>
    <para>
     Updates the content of the blob object for the given blob object
     <parameter>bid</parameter>. <parameter>content</parameter> is a
     string with new data.  Returns &false; on error otherwise &true;.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-blobinfile-mode">
   <refnamediv>
    <refname>ifx_blobinfile_mode</refname>
    <refpurpose>Set the default blob mode for all select queries</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>ifx_blobinfile_mode</methodname>
      <methodparam><type>int</type><parameter>mode</parameter></methodparam>
     </methodsynopsis>
    <para>
     Set the default blob mode for all select queries. Mode "0" means
     save Byte-Blobs in memory, and mode "1" means save Byte-Blobs in
     a file.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-textasvarchar">
   <refnamediv>
    <refname>ifx_textasvarchar</refname>
    <refpurpose>Set the default text mode</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>ifx_textasvarchar</methodname>
      <methodparam><type>int</type><parameter>mode</parameter></methodparam>
     </methodsynopsis>
    <para>
     Sets the default text mode for all select-queries.  Mode "0" will
     return a blob id, and mode "1" will return a varchar with text
     content.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-byteasvarchar">
   <refnamediv>
    <refname>ifx_byteasvarchar</refname>
    <refpurpose>Set the default byte mode</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>ifx_byteasvarchar</methodname>
      <methodparam><type>int</type><parameter>mode</parameter></methodparam>
     </methodsynopsis>
    <para>
     Sets the default byte mode for all select-queries.  Mode "0" will
     return a blob id, and mode "1" will return a varchar with text
     content.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifx-nullformat">
   <refnamediv>
    <refname>ifx_nullformat</refname>
    <refpurpose>
     Sets the default return value on a fetch row
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>ifx_nullformat</methodname>
      <methodparam><type>int</type><parameter>mode</parameter></methodparam>
     </methodsynopsis>
    <para>
     Sets the default return value of a NULL-value on a fetch row.
     Mode "0" returns "", and mode "1" returns "&null;".
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifxus-create-slob">
   <refnamediv>
    <refname>ifxus_create_slob</refname>
    <refpurpose>Creates an slob object and opens it</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifxus_create_slob</methodname>
      <methodparam><type>int</type><parameter>mode</parameter></methodparam>
     </methodsynopsis>
    <para>
     Creates an slob object and opens it.  Modes: 1 = LO_RDONLY, 2 =
     LO_WRONLY, 4 = LO_APPEND, 8 = LO_RDWR, 16 = LO_BUFFER, 32 =
     LO_NOBUFFER -> or-mask. You can also use constants named
     IFX_LO_RDONLY, IFX_LO_WRONLY etc.  Return &false; on error otherwise
     the new slob object-id.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifxus-free-slob">
   <refnamediv>
    <refname>ifxus_free_slob</refname>
    <refpurpose>Deletes the slob object</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifxus_free_slob</methodname>
      <methodparam><type>int</type><parameter>bid</parameter></methodparam>
     </methodsynopsis>
    <para>
     Deletes the slob object. <parameter>bid</parameter> is the Id of
     the slob object.  Returns &false; on error otherwise &true;.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifxus-close-slob">
   <refnamediv>
    <refname>ifxus_close_slob</refname>
    <refpurpose>Deletes the slob object</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifxus_close_slob</methodname>
      <methodparam><type>int</type><parameter>bid</parameter></methodparam>
     </methodsynopsis>
    <para>
     Deletes the slob object on the given slob object-id
     <parameter>bid</parameter>.  Return &false; on error otherwise
     &true;.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifxus-open-slob">
   <refnamediv>
    <refname>ifxus_open_slob</refname>
    <refpurpose>Opens an slob object</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifxus_open_slob</methodname>
      <methodparam><type>long</type><parameter>bid</parameter></methodparam>
      <methodparam><type>int</type><parameter>mode</parameter></methodparam>
     </methodsynopsis>
    <para>
     Opens an slob object. <parameter>bid</parameter> should be an
     existing slob id.  Modes: 1 = LO_RDONLY, 2 = LO_WRONLY, 4 =
     LO_APPEND, 8 = LO_RDWR, 16 = LO_BUFFER, 32 = LO_NOBUFFER ->
     or-mask.  Returns &false; on error otherwise the new slob
     object-id.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifxus-tell-slob">
   <refnamediv>
    <refname>ifxus_tell_slob</refname>
    <refpurpose>Returns the current file or seek position</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifxus_tell_slob</methodname>
      <methodparam><type>long</type><parameter>bid</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the current file or seek position of an open slob object
     <parameter>bid</parameter> should be an existing slob id.  Return
     &false; on error otherwise the seek position.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifxus-seek-slob">
   <refnamediv>
    <refname>ifxus_seek_slob</refname>
    <refpurpose>Sets the current file or seek position</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifxus_seek_slob</methodname>
      <methodparam><type>long</type><parameter>bid</parameter></methodparam>
      <methodparam><type>int</type><parameter>mode</parameter></methodparam>
      <methodparam><type>long</type><parameter>offset</parameter></methodparam>
     </methodsynopsis>
    <para>
     Sets the current file or seek position of an open slob object.
     <parameter>bid</parameter> should be an existing slob id.  Modes:
     0 = LO_SEEK_SET, 1 = LO_SEEK_CUR, 2 = LO_SEEK_END and
     <parameter>offset</parameter> is an byte offset.  Return &false; on
     error otherwise the seek position.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifxus-read-slob">
   <refnamediv>
    <refname>ifxus_read_slob</refname>
    <refpurpose>Reads nbytes of the slob object</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifxus_read_slob</methodname>
      <methodparam><type>long</type><parameter>bid</parameter></methodparam>
      <methodparam><type>long</type><parameter>nbytes</parameter></methodparam>
     </methodsynopsis>
    <para>
     Reads nbytes of the slob object.  <parameter>bid</parameter> is a
     existing slob id and <parameter>nbytes</parameter> is the number
     of bytes read.  Return &false; on error otherwise the string.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ifxus-write-slob">
   <refnamediv>
    <refname>ifxus_write_slob</refname>
    <refpurpose>Writes a string into the slob object</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ifxus_write_slob</methodname>
      <methodparam><type>long</type><parameter>bid</parameter></methodparam>
      <methodparam><type>string</type><parameter>content</parameter></methodparam>
     </methodsynopsis>
    <para>
     Writes a string into the slob object.  <parameter>bid</parameter>
     is a existing slob id and <parameter>content</parameter> the
     content to write.  Return &false; on error otherwise bytes written.
    </para>
   </refsect1>
  </refentry>

 </reference>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->