php-doc-en/reference/maxdb/reference.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.12 $ -->
<!-- Purpose: database.vendors -->
<!-- Membership: pecl, external -->

 <reference xml:id="ref.maxdb" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>MaxDB PHP Extension</title>
  <titleabbrev>MaxDB</titleabbrev>

  <partintro>
   <section xml:id="maxdb.intro">
    &reftitle.intro;
    <para>
     The MaxDB PHP extension allows you to access the functionality provided by
     MaxDB 7.5.0 and above. More information about the MaxDB Database server
     can be found at <link xlink:href="&url.maxdb;">&url.maxdb;</link>.
    </para>
    <para>
     The MaxDB PHP extension is compatible to the MySQL mysqli extension. There are only
     minor differences in the behaviour of some functions due to the differences of the
     underlying database servers, MaxDB and MySQL.
    </para>
    <para>
     The main differences to mysqli are in the following functions:
    </para>
    <simplelist>
    <member><function>maxdb_character_set_name</function> - Returns only ascii or unicode.</member>
    <member><function>maxdb_get_client_info</function> - Returns a different version string.</member>
    <member><function>maxdb_get_client_version</function> - Returns a different version string.</member>
    <member><function>maxdb_get_host_info</function> - Returns localhost or hostname.</member>
    <member><function>maxdb_get_server_info</function> - Returns a different version string.</member>
    <member><function>maxdb_get_server_version</function> - Returns a different version string.</member>
    <member><function>maxdb_kill</function> - Only disconnects the session.</member>
    <member><function>maxdb_multi_query</function> - Can not handle multiple SQL statements.</member>
    <member><function>maxdb_next_result</function> - Function returns always false.</member>
    <member><function>maxdb_options</function> - Supports a different set of options.</member>
    <member><function>maxdb_report</function> - Supports a different report mode.</member>
    <member><function>maxdb_stat</function> - Returns a different system status string.</member>
    <member><function>maxdb_stmt_store_result</function> - Is not necessary for MaxDB.</member>
    <member><function>maxdb_store_result</function> - Is not necessary for MaxDB.</member>
    </simplelist>
    <para>
     Documentation for MaxDB can be found at
     <link xlink:href="&url.maxdb.doc;">&url.maxdb.doc;</link>.
    </para>
   </section>

   <section xml:id="maxdb.requirements">
    &reftitle.required;
    <para>
     In order to have these functions available, you must compile PHP with
     MaxDB support. Additionally, you must have the MaxDB SQLDBC runtime library
     available to access the MaxDB server. 
    </para>
    <para>
     Documentation for MaxDB SQLDBC can be found at
     <link xlink:href="&url.maxdb.doc;">&url.maxdb.doc;</link>.
    </para>
    <para>
     Download the MaxDB SQLDBC package from 
     <link xlink:href="&url.maxdb.sdbc;">&url.maxdb.sdbc;</link>.
     
    </para>
   </section>
    
    &reference.maxdb.configure;

    &reference.maxdb.ini;

   <section xml:id='maxdb.classes'>
    &reftitle.classes;

    <section xml:id='maxdb.class.maxdb'>
     <title><classname>maxdb</classname></title>
     <para>
      Represents a connection between PHP and a MaxDB database.
     </para>
     <section xml:id='maxdb.class.maxdb.constructor'>
      &reftitle.constructor;
      <itemizedlist>
       <listitem>
        <para><link linkend='function.maxdb-connect'>maxdb</link> - construct a new maxdb object</para>
       </listitem>
      </itemizedlist>
     </section>
     <section xml:id='maxdb.class.maxdb.methods'>
      &reftitle.methods;
      <itemizedlist>
       <listitem>
        <para><link linkend='function.maxdb-autocommit'>autocommit</link> - turns on or off auto-commiting database modifications</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-change-user'>change_user</link> - changes the user of the specified database connection</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-character-set-name'>character_set_name</link> - returns the default character set for the database connection</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-close'>close</link> - closes a previously opened connection</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-commit'>commit</link> - commits the current transaction</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-connect'>connect</link> - opens a new connection to MaxDB database server</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-debug'>debug</link> - performs debugging operations</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-dump-debug-info'>dump_debug_info</link> - dumps debug information</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-get-client-info'>get_client_info</link> - returns client version</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-get-host-info'>get_host_info</link> - returns type of connection used</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-get-server-info'>get_server_info</link> - returns version of the MaxDB server</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-get-server-version'>get_server_version</link> - returns version of the MaxDB server</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-init'>init</link> - initializes maxdb object</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-info'>info</link> - retrieves information about the most recently executed query</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-kill'>kill</link> - asks the server to kill a MaxDB thread</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-multi-query'>multi_query</link> - performs multiple queries</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-more-results'>more_results</link> - check if more results exist from currently executed multi-query</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-next-result'>next_result</link> - reads next result from currently executed multi-query</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-options'>options</link> - set options</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-ping'>ping</link> - pings a server connection or reconnects if there is no connection</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-prepare'>prepare</link> - prepares a SQL query</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-query'>query</link> - performs a query</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-real-connect'>real_connect</link> - attempts to open a connection to MaxDB database server</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-real-escape-string'>escape_string</link> - escapes special characters in a string for use in a SQL statement, taking into account the current charset of the connection</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-rollback'>rollback</link> - rolls back the current transaction</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-select-db'>select_db</link> - selects the default database</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-ssl-set'>ssl_set</link> - sets ssl parameters</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-stat'>stat</link> - gets the current system status</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-stmt-init'>stmt_init</link>- initializes a statement for use with <link linkend='function.maxdb-stmt-prepare'>maxdb_stmt_prepare</link></para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-store-result'>store_result</link> - transfers a resultset from last query</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-use-result'>use_result</link> - transfers an unbuffered resultset from last query</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-thread-safe'>thread-safe</link> - returns whether thread safety is given or not</para>
       </listitem>
      </itemizedlist>
     </section>
     <section xml:id='maxdb.class.maxdb.properties'>
      &reftitle.properties;
      <itemizedlist>
       <listitem>
        <para><link linkend='function.maxdb-affected-rows'>affected_rows</link> - gets the number of affected rows in a previous MaxDB operation</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-get-client-info'>client_info</link> - returns the MaxDB client version as a string</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-get-client-version'>client_version</link> - returns the MaxDB client version as an integer</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-errno'>errno</link> - returns the error code for the most recent function call</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-error'>error</link> - returns the error string for the most recent function call</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-field-count'>field_count</link> - returns the number of columns for the most recent query</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-get-host-info'>host_info</link> - returns a string representing the type of connection used</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-info'>info</link> - retrieves information about the most recently executed query</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-insert-id'>insert_id</link> - returns the auto generated id used in the last query</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-get-proto-info'>protocol_version</link> - returns the version of the MaxDB protocol used</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-sqlstate'>sqlstate</link> - returns a string containing the SQLSTATE error code for the last error</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-thread-id'>thread_id</link> - returns the thread ID for the current connection</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-warning-count'>warning_count</link> - returns the number of warnings generated during execution of the previous SQL statement</para>
       </listitem>

      </itemizedlist>
     </section>
    </section>

    <section xml:id='maxdb.classes.stmt'>
     <title><classname>maxdb_stmt</classname></title>
     <para>
      Represents a prepared statement.
     </para>
     <section xml:id='maxdb.class.stmt.methods'>
      &reftitle.methods;
      <itemizedlist>
       <listitem>
        <para><link linkend='function.maxdb-bind-param'>bind_param</link> - binds variables to a prepared statement</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-bind-result'>bind_result</link> - binds variables to a prepared statement for result storage</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-stmt-close'>close</link> - closes a prepared statement</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-stmt-data-seek'>data-seek</link> - seeks to an arbitrary row in a statement result set</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-execute'>execute</link> - executes a prepared statement</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-fetch'>fetch</link> - fetches result from a prepared statement into bound variables</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-stmt-free-result'>free_result</link> - frees stored result memory for the given statement handle</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-stmt-result-metadata'>result_metadata</link> - retrieves a resultset from a prepared statement for metadata information</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-stmt-prepare'>prepare</link> - prepares a SQL query</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-send-long-data'>send_long_data</link> - sends data in chunks</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-stmt-close-long-data'>close_long_data</link> - end sending long data</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-stmt-reset'>reset</link> - resets a prepared statement</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-stmt-store-result'>store_result</link> - buffers complete resultset from a prepared statement</para>
       </listitem>
      </itemizedlist>
     </section>
     <section xml:id='maxdb.class.stmt.properties'>
      &reftitle.properties;
      <itemizedlist>
       <listitem>
        <para><link linkend='function.maxdb-stmt-affected-rows'>affected_rows</link> - returns affected rows from last statement execution</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-stmt-errno'>errno</link> - returns errorcode for last statement function</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-stmt-error'>errno</link> - returns errormessage for last statement function</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-stmt-param-count'>param_count</link> - returns number of parameter for a given prepare statement</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-stmt-sqlstate'>sqlstate</link> - returns a string containing the SQLSTATE error code for the last statement function</para>
       </listitem>
      </itemizedlist>
     </section>
    </section>

    <section xml:id='maxdb.classes.result'>
     <title><classname>maxdb_result</classname></title>
     <para>
      Represents the result set obtained from a query against the database.
     </para>
     <section xml:id='maxdb.class.result.methods'>
      &reftitle.methods;
      <itemizedlist>
       <listitem>
        <para><link linkend='function.maxdb-free-result'>close</link> - closes resultset</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-data-seek'>data_seek</link> - moves internal result pointer</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-fetch-field'>fetch_field</link> - gets column information from a resultset</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-fetch-fields'>fetch_fields</link> - gets information for all columns from a resulset</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-fetch-field-direct'>fetch_field_direct</link> - gets column information for specified column</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-fetch-array'>fetch_array</link> - fetches a result row as an associative array, a numeric array, or both.</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-fetch-assoc'>fetch_assoc</link> - fetches a result row as an associative array</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-fetch-object'>fetch_object</link> - fetches a result row as an object</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-fetch-row'>fetch_row</link> - gets a result row as an enumerated array</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-free-result'>close</link> - frees result memory</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-field-seek'>field_seek</link> - set result pointer to a specified field offset</para>
       </listitem>
      </itemizedlist>
     </section>
     <section xml:id='maxdb.class.result.properties'>
      &reftitle.properties;
      <itemizedlist>
       <listitem>
        <para><link linkend='function.maxdb-field-tell'>current_field</link> - returns offset of current fieldpointer</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-field-count'>field_count</link> - returns number of fields in resultset</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-fetch-lengths'>lengths</link> - returns an array of columnlengths</para>
       </listitem>
       <listitem>
        <para><link linkend='function.maxdb-num-rows'>num_rows</link> - returns number of rows in resultset</para>
       </listitem>
      </itemizedlist>
     </section>
    </section>
   </section>

   <section xml:id="maxdb.resources">
    &reftitle.resources;
    <para>
     This extension defines resources.
    </para>
   </section>

   &reference.maxdb.constants;
    
   <section xml:id="maxdb.examples">
   &reftitle.examples;
    <para>
     All examples in the MaxDB PHP documentation use the HOTELDB demo database from MaxDB. More about this
     database can be found at <link xlink:href="&url.maxdb.sampledb;">&url.maxdb.sampledb;</link>.
    </para>
    <para>
     To use the examples in the MaxDB PHP documentation, you have to load the tutorial data into your database.
     Then you have to set maxdb.default_db in &php.ini; to the database that contains the tutorial data.
    </para>
    <para>
     This simple example shows how to connect, execute a query, print
     resulting rows and disconnect from a MaxDB database.
     <example>
      <title>MaxDB extension overview example</title>
      <programlisting role="php">
<![CDATA[
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");
   
/* check connection */
if (maxdb_connect_errno()) {
   printf("Connect failed: %s\n", maxdb_connect_error());
   exit();
}

/* Performing SQL query */
$query = "SELECT * FROM hotel.city";
$result = maxdb_query($link, $query) or die("Query failed : " . maxdb_error());

/* Printing results in HTML */
echo "<table>\n";
while ($line = maxdb_fetch_array($result, MAXDB_ASSOC)) {
    echo "  <tr>\n";
    foreach ($line as $col_value) {
        echo "    <td>$col_value</td>\n";
    }
    echo "  </tr>\n";
}
echo "</table>\n";

/* Free resultset */
maxdb_free_result($result);

/* Closing connection */
maxdb_close($link);
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     The following example shows how to bind variables to a SELECT INTO statement.
     <example>
      <title>Example for use of SELECT INTO statements</title>
      <programlisting role="php">
<![CDATA[
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");

/* check connection */
if (!$link) {
   printf("Connect failed: %s\n", maxdb_connect_error());
   exit();
}
   
/* Performing SQL query */
$stmt = maxdb_prepare ($link, "SELECT percentage INTO ? FROM hotel.countrylanguage where language = ?");
if (!$stmt) {
  printf ("Prepare failed: %s\n", maxdb_error($link));
}

$name = "Mbundu";

maxdb_stmt_bind_param($stmt, 'ds', $percentage, $name);
maxdb_stmt_execute($stmt);

printf ("%f\n", $percentage);

maxdb_stmt_close ($stmt);
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     The following example shows how to use MaxDB database procedures.
     <example>
      <title>Example fore using database procedures</title>
      <programlisting role="php">
<![CDATA[
<?php
$link = maxdb_connect("localhost", "MONA", "RED", "DEMODB");

/* check connection */
if (!$link) {
   printf("Connect failed: %s\n", maxdb_connect_error());
   exit();
}

maxdb_report (MAXDB_REPORT_OFF);
maxdb_query($link,"DROP DBPROC test_proc");
maxdb_report (MAXDB_REPORT_ERROR);

$query = "create dbproc test_proc (INOUT e_text char(72)) AS select * from SYSDBA.DUAL; fetch into :e_text;";

maxdb_query($link, $query);

/* Performing SQL query */
$stmt = maxdb_prepare ($link, "CALL test_proc (?)");
if (!$stmt) {
  printf ("Prepare failed: %s\n", maxdb_error($link));
}

maxdb_stmt_bind_param($stmt, 's', $result);
maxdb_stmt_execute($stmt);

printf ("%s\n", $result);

maxdb_stmt_close ($stmt);
?>
]]>
      </programlisting>
     </example>
    </para>
   </section>

  </partintro>

  &reference.maxdb.functions;

 </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
-->