<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.11 $ -->
 <reference id="ref.dbx">
  <title>dbx 関数</title>
  <titleabbrev>dbx</titleabbrev>
  <partintro>
   &warn.experimental;
   <simpara>
    dbx モジュールは、データベース抽象化レイヤ (db 'X'、ただし 'X' は
    サポートされるデータベースの一つを意味します)のことです。dbx 関数
    により、サポートされる全てのデータベースを単一の呼出表記によりアク
    セスすることが可能になります。これらの関数を利用可能にするには、
    <option role="configure">--enable-dbx</option> オプションを使用し
    てdbxサポートを有効にし、また、使用するデータベースに関するオプショ
    ン、例えば、MySQL の場合は <option
    role="configure">--with-mysql</option> も指定して PHPをコンパイル
    する必要があります。dbx 関数自体は、データベースへの直接のインター
    フェイスを有しませんが、それらのデータベースをサポートするために使
    用されるモジュールへのインターフェイスを有します。dbxモジュールで
    データベースを使用可能とするには、そのモジュールが PHPにリンクされ
    るかロードされる必要があり、そのデータベースのモジュールは、dbxモ
    ジュールにサポートされている必要があります。現在、MySQL、
    PostgreSQL、Microsoft SQL Server、FrontBase、ODBCがサポートされて
    おり、その他についても(希望的観測だとまもなく)追加される予定です。
   </simpara>
   <simpara>
    dbx にデータベースのサポートを追加するためのドキュメントは、
    <ulink url="&url.dbx.docs;">&url.dbx.docs;</ulink> にあります。
   </simpara>
  </partintro>
 
  <refentry id="function.dbx-close">
   <refnamediv>
    <refname>dbx_close</refname>
    <refpurpose>オープンされた接続/データベースを閉じる</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>boolean</type><methodname>dbx_close</methodname>
      <methodparam><type>dbx_link_object</type><parameter>link_identifier</parameter></methodparam>
     </methodsynopsis>
     &warn.experimental;
    <para>
     成功時に&true;、エラーの際に&false;を返します。
    </para>
    <example>
     <title><function>dbx_close</function> の例</title>
     <programlisting role="php">
<![CDATA[
<?php
$link = dbx_connect ("mysql", "localhost", "db", "username", "password")
    or die ("Could not connect");
print("Connected successfully");
dbx_close($link);
?>
]]>
     </programlisting>
    </example>
    <note>
     <para>
      モジュール毎のドキュメントも参照下さい。
     </para>
    </note>
    <para>
     <function>dbx_connect</function>も参照下さい。
    </para>
   </refsect1>
  </refentry>
 
  <refentry id="function.dbx-connect">
   <refnamediv>
    <refname>dbx_connect</refname>
    <refpurpose>接続/データベースをオープンする</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>dbx_link_object</type><methodname>dbx_connect</methodname>
      <methodparam><type>string</type><parameter>module</parameter></methodparam>
      <methodparam><type>string</type><parameter>host</parameter></methodparam>
      <methodparam><type>string</type><parameter>database</parameter></methodparam>
      <methodparam><type>string</type><parameter>username</parameter></methodparam>
      <methodparam><type>string</type><parameter>password</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>persistent</parameter></methodparam>
     </methodsynopsis>
     &warn.experimental;
    <para>
     返り値: 成功時にdbx_link_object、エラー時に
     &false;。接続が確立されたが、データベースが選択
     できない場合でも、この関数は dbx_link_object を返します。パラメー
     タ<parameter>persistent</parameter>にDBX_PERSISTENTを設定すること
     ができ、この場合には、持続的接続が作成されます。
    </para>
    <para>
     パラメータ <parameter>module</parameter> は、文字列または定数とす
     ることが可能です。以下に指定した可能な値を示しますが、そのモジュー
     ルが実際にロードされている場合にのみ動作することに注意して下さい。
    </para>
    <para>
     <itemizedlist>
      <listitem>
       <simpara>
	モジュール DBX_MYSQL: "mysql"
       </simpara>
      </listitem>
      <listitem>
       <simpara>
	モジュール DBX_ODBC: "odbc"
       </simpara>
      </listitem>
      <listitem>
       <simpara>
	モジュール DBX_PGSQL: "pgsql"
       </simpara>
      </listitem>
      <listitem>
       <simpara>
	モジュール DBX_MSSQL: "mssql"
       </simpara>
      </listitem>
      <listitem>
       <simpara>
	モジュール DBX_FBSQL: "fbsql" (CVSのみ)
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     dbx_link_object は、3つのメンバ 'handle'、'module'、'database' を
     有します。メンバ 'database'は、現在選択されているデータベースの名
     前です。メンバ'module'は、dbxの内部のみで使用され、上記の有効なモ
     ジュール番号です。メンバ 'handle' は、データベース接続に関する有
     効なハンドルで、(必要に応じて)モジュール専用関数で使用されます。
     例えば、
    </para>
    <para>
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
$link = dbx_connect ("mysql", "localhost", "db", "username", "password");
mysql_close ($link->handle); // dbx_close($link) の方が良いかもしれません
?>
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
     パラメータhost、database、username、passwordが必要ですが、常に抽
     象化モジュールで使用されるわけではありません。
    </para>
    <para>
     <example>
      <title><function>dbx_connect</function> の例</title>
      <programlisting role="php">
<![CDATA[
<?php
$link = dbx_connect ("odbc", "", "db", "username", "password", DBX_PERSISTENT)
    or die ("Could not connect");
print ("Connected successfully");
dbx_close ($link);
?>
]]>
      </programlisting>
     </example>
     <note>
      <para>
       モジュール毎のドキュメントも参照下さい。
      </para>
     </note>
    </para>
    <para>
     <function>dbx_close</function>も参照下さい。
    </para>
   </refsect1>
  </refentry>
 
  <refentry id="function.dbx-error">
   <refnamediv>
    <refname>dbx_error</refname>
    <refpurpose>
     (接続時だけでなく)使用するモジュールの最新の関数コールにおけるエ
     ラーメッセージを出力する
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>string</type><methodname>dbx_error</methodname>
      <methodparam><type>dbx_link_object</type><parameter>link_identifier</parameter></methodparam>
     </methodsynopsis>
     &warn.experimental;
    <para>
     モジュール(例えば mysql-module)の直近の関数コールからエラーメッセー
     ジを有する文字列を返します。同じモジュールに複数の接続がある場合、
     最後のエラーのみが取得されます。別のモジュールに接続がある場合、
     (リンクパラメータで)指定したモジュールに関する直近のエラーのみが
     返されます。ODBCモジュールは現在エラー出力関数をサポートしていな
     いことに注意して下さい。
    </para>
    <example>
     <title><function>dbx_error</function>の例</title>
     <programlisting role="php">
<![CDATA[
<?php
$link = dbx_connect ("mysql", "localhost", "db", "username", "password")
    or die ("Could not connect");
$result = dbx_query ($link, "select id from nonexistingtbl");
if ($result==0) {
    echo dbx_error ($link);
}
dbx_close ($link);
?>
]]>
     </programlisting>
    </example>
    <note>
     <para>
      必ずモジュール毎のドキュメントも参照下さい。
     </para>
     <para>
      Microsoft SQL Serverに関するエラーメッセージは、実際には
      <function>mssql_get_last_message</function> 関数の結果となります。
     </para>
    </note>
   </refsect1>
  </refentry>
 
  <refentry id="function.dbx-query">
   <refnamediv>
    <refname>dbx_query</refname>
    <refpurpose>クエリを送信し、(ある場合には)結果を全て取得する</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>dbx_result_object</type><methodname>dbx_query</methodname>
      <methodparam><type>dbx_link_object</type><parameter>link_identifier</parameter></methodparam>
      <methodparam><type>string</type><parameter>sql_statement</parameter></methodparam>
      <methodparam choice="opt"><type>long</type><parameter>flags</parameter></methodparam>
     </methodsynopsis>
   &warn.experimental;
    <para>
     成功時にdbx_result_objectまたは1を返します。結果オブジェクトは、
     SQL命令が結果を返す場合にのみ返されます。エラーの場合には、0を返
     します。パラメータ <parameter>flags</parameter> は、返される情報
     の量を制御するために使用されます。定数 DBX_RESULT_INFO,
     DBX_RESULT_INDEX, DBX_RESULT_ASSOC またはこれらの論理和を組み合わ
     せることが可能です。DBX_RESULT_INFO を指定するとフィールド名およ
     びフィールド型のようなカラムに関する情報が提供されます。
     DBX_RESULT_INDEX により、結果は(data[2][3]のような、ただし、2はレ
     コード番号、3はカラム番号)2次元の配列で返されます。ただし、最初の
     レコードおよびカラム番号は0から始まります。
     DBX_RESULT_ASSOC により、フィールド名にカラム添字が関連付けられま
     す。パラメータ<parameter>flags</parameter> によらず
     DBX_RESULT_INDEXは常に返されることに注意して下さい。
     DBX_RESULT_ASSOC が指定された場合、DBX_RESULT_INFOは指定されない
     場合でも返されます。これは、DBX_RESULT_INDEX,DBX_RESULT_INDEX |
     DBX_RESULT_INFO および DBX_RESULT_INDEX | DBX_RESULT_INFO |
     DBX_RESULT_ASSOC の組み合わせのみが結果的に使用可能であることを意
     味します。 <parameter>flags</parameter> が指定されない場合、この
     最後の組み合わせがデフォルトです。連想配列で参照される結果は、添
     字番号の結果へのリファレンスです。このため、
     <literal>data[0][0]</literal> を修正した場合、
     <literal>data[0]['fieldnameforfirstcolumn']</literal> も同時に修
     正されます。
    </para>
    <para>
     dbx_result_object には、5つのメンバがあります。
     (<parameter>flags</parameter>によっては4つの場合もあります)これら
     は、'handle', 'cols', 'rows', 'info'(オプション), 'data'です。
     handle は、指定したモジュールに関する有効な結果IDであり、次のよう
     にモジュール専用関数で使用可能です。
    </para>
    <para>
     <informalexample role="php">
      <programlisting>
<![CDATA[
$result = dbx_query ($link, "SELECT id FROM tbl");
mysql_field_len ($result->handle, 0);
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
     メンバ cols および rows は、それぞれカラム(またはフィールド)番号
     および行(またはレコード)番号です。例えば、
    </para>
    <para>
     <informalexample>
      <programlisting role="php">
<![CDATA[
$result = dbx_query ($link, "SELECT id FROM tbl");
echo "result size: " . $result->rows . " x " . $result->cols . "<br>\n";
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
     メンバinfoは、DBX_RESULT_INFOまたはDBX_RESULT_ASSOCが
     <parameter>flags</parameter>パラメータで指定された場合のみ返され
     ます。このメンバは2次元配列で、カラム情報を取得するために二つのレ
     コード("name"と"type")を有しています。例えば、
    </para>
    <para>
     <informalexample>
      <programlisting role="php">
<![CDATA[
$result = dbx_query ($link, "SELECT id FROM tbl");
echo "column name: " . $result->info["name"][0] . "<br>\n";
echo "column type: " . $result->info["type"][0] . "<br>\n";
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
     メンバdataには、実際の結果が含まれます。そして、カラム名も同様に
     関連しています。DBX_RESULT_ASSOCが設定された場合、
     <literal>$result->data[2]["fieldname"]</literal>を使用することが
     可能です。
    </para>
    <example>
     <title><function>dbx_query</function> の例</title>
     <programlisting role="php">
<![CDATA[
<?php
$link = dbx_connect ("odbc", "", "db", "username", "password")
    or die ("Could not connect");
$result = dbx_query ($link, "SELECT id, parentid, description FROM tbl");
if ($result==0) echo "Query failed\n<br>";
elseif ($result==1) {
    echo "Query executed successfully\n<br>";
} else {
    $rows=$result->rows;
    $cols=$result->cols;
    echo "<p>table dimension: {$result->rows} x {$result->cols}<br><table border=1>\n";
    echo "<tr>";
    for ($col=0; $col<$cols; ++$col) {
        echo "<td>-{$result->info["name"][$col]}-<br>-{$result->info["type"][$col]}-</td>";
    }
    echo "</tr>\n";
    for ($row=0; $row<$rows; ++$row){
        echo "<tr>";
        for ($col=0; $col<$cols; ++$col) {
            echo "<td>-{$result->data[$row][$col]}-</td>";
        }
        echo "</tr>\n";
    }
    echo "</table><p>\n";
    echo "table dimension: {$result->rows} x id, parentid, description<br><table border=1>\n";
    for ($row=0; $row<$rows; ++$row) {
        echo "<tr>";
        echo "<td>-{$result->data[$row]["id"]}-</td>";
        echo "<td>-{$result->data[$row]["parentid"]}-</td>";
        echo "<td>-{$result->data[$row]["description"]}-</td>";
        echo "</tr>\n";
    }
    echo "</table><p>\n";
}
dbx_close($link);
?>
]]>
     </programlisting>
    </example>
    <note>
     <para>
      モジュール毎のドキュメントも参照下さい。
     </para>
    </note>
    <para>
     <function>dbx_connect</function>も参照下さい。
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="function.dbx-sort">
   <refnamediv>
    <refname>dbx_sort</refname>
    <refpurpose>
     カスタマイズされたsort関数により、dbx_queryから結果をソートする
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>boolean</type><methodname>dbx_sort</methodname>
      <methodparam><type>dbx_result_object</type><parameter>result</parameter></methodparam>
      <methodparam><type>string</type><parameter>user_compare_function</parameter></methodparam>
     </methodsynopsis>
   &warn.experimental;
    <para>
     成功時に&true;、エラー時に&false;を返します。
    </para>
    <example>
     <title><function>dbx_sort</function>の例</title>
     <programlisting role="php">
<![CDATA[
<?php
function user_re_order ($a, $b) {
    $rv = dbx_cmp_desc ($a, $b, "parentid");
    if (!$rv) $rv = dbx_cmp_asc ($a, $b, "id");
    return $rv;
}

$link = dbx_connect ("odbc", "", "db", "username", "password")
    or die ("接続できません");
$result = dbx_query ($link, "SELECT id, parentid, description FROM tbl ORDER BY id");
echo "結果は、idでソートされています<br>";
dbx_sort ($result, "user_re_order");
echo "結果はparentidで(降順に)ソートされ、続いて、idでソートされます<br>";
dbx_close ($link);
?>
]]>
     </programlisting>
    </example>
    <para>
     <function>dbx_compare</function>も参照下さい。
    </para>
   </refsect1>
  </refentry>
 
  <refentry id="function.dbx-cmp-asc">
   <refnamediv>
    <refname>dbx_cmp_asc</refname>
    <refpurpose>
     昇順にソートするために二つのレコードを比較する
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>dbx_cmp_asc</methodname>
      <methodparam><type>array</type><parameter>row_a</parameter></methodparam>
      <methodparam><type>array</type><parameter>row_b</parameter></methodparam>
      <methodparam><type>string</type><parameter>columnname_or_index</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>comparison_type</parameter></methodparam>
     </methodsynopsis>
   &warn.experimental;
    <para>
     row_a[$columnname_or_index] が row_b[$columnname_or_index] に等し
     い場合に 0、より大きい場合に 1、より小さい場合に -1 を返します。
    </para>
    <para>
     パラメータ <parameter>comparison_type</parameter> は、
     (DBX_CMP_NUMBERに設定することにより、)強制的に数値として比較を行
     うために使用されます。デフォルトの比較は、テキストとして行われま
     す。(例えば、"20"は、"100"よりも大きくなります。)
    </para>
    <example>
     <title><function>dbx_cmp_asc</function>の例</title>
     <programlisting role="php">
&lt;?php
function user_re_order ($a, $b) {
    $rv = dbx_cmp_desc ($a, $b, "parentid");
    if (!$rv) { 
        $rv = dbx_cmp_asc ($a, $b, "id");
        return $rv;
    }
}

$link = dbx_connect ("odbc", "", "db", "username", "password")
    or die ("接続できません");
$result = dbx_query ($link, "SELECT id, parentid, description FROM tbl ORDER BY id");
echo "結果はidでソートされました&lt;br>";
dbx_sort ($result, "user_re_order");
echo "結果はparentidで(降順に)ソートされた後、idでソートされました&lt;br>";
dbx_close ($link);
?&gt;
     </programlisting>
    </example>
    <para>
     <function>dbx_sort</function>および
     <function>dbx_cmp_desc</function>も参照下さい。
    </para>
   </refsect1>
  </refentry>
 
  <refentry id="function.dbx-compare">
   <refnamediv>
    <refname>dbx_compare</refname>
    <refpurpose>
     ソートするために二つのレコードを比較する
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>dbx_compare</methodname>
      <methodparam><type>array</type><parameter>row_a</parameter></methodparam>
      <methodparam><type>array</type><parameter>row_b</parameter></methodparam>
      <methodparam><type>string</type><parameter>columnname_or_index</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
     </methodsynopsis>
     &warn.experimental;
    <para>
     row_a[$columnname_or_index] が row_b[$columnname_or_index] に等し
     い場合に 0、より大きい場合に-1、より小さい場合に1を返します。
     (DBX_CMP_DESCフラグが指定されている場合には逆となります)
    </para>
    <para>
     <parameter>flags</parameter>により比較の方向(昇順または降順のソー
     トのどちらか)と比較の型(データ変換により強制的に文字列または数値
     として比較する)を設定することが可能です。比較用定数は、
     DBX_CMP_ASC及びDBX_CMP_DESCです。比較用定数は、DBX_CMP_NATIVE(比
     較無し)、DBX_CMP_TEXT、DBX_CMP_NUMBERです。これらの定数は、論理和
     をとることができます。<parameter>flags</parameter>パラメータのデ
     フォルト値は、DBX_CMP_ASC | DBX_CMP_NATIVEです。
    </para>
    <example>
     <title><function>dbx_compare</function>の例</title>
     <programlisting role="php">
<![CDATA[
<?php
function user_re_order ($a, $b) {
    $rv = dbx_compare ($a, $b, "parentid", DBX_CMP_DESC);
    if (!$rv) { 
        $rv = dbx_compare ($a, $b, "id");
        return $rv;
    }
}

$link = dbx_connect ("odbc", "", "db", "username", "password")
    or die ("Could not connect");
$result = dbx_query ($link, "SELECT id, parentid, description FROM tbl ORDER BY id");
echo "resulting data is now ordered by id<br>";
dbx_sort ($result, "user_re_order");
echo "resulting data is now ordered by parentid (descending), then by id<br>";
dbx_close ($link);
?>
]]>
     </programlisting>
    </example>
    <para>
     <function>dbx_sort</function>も参照下さい。
    </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:
-->