File: sesam.xml

package info (click to toggle)
phpdoc 20020310-1
links: PTS
area: main
in suites: woody
size: 35,272 kB
ctags: 354
sloc: xml: 799,767; php: 1,395; cpp: 500; makefile: 200; sh: 140; awk: 51
file content (1966 lines) | stat: -rw-r--r-- 75,603 bytes
<?xml version="1.0" encoding="utf-8"?>
 <reference id="ref.sesam">
  <title>SESAM データベース関数</title>
  <titleabbrev>SESAM</titleabbrev>

  <partintro>
   <para>
    SESAM/SQL-Server は、ドイツの Fujitsu Siemens コンピュータにより開
    発されたメインフレーム上のデータベースシステムです。このデータベー
    スは、ハイエンドのメインフレーム上でオペレーティングシステム
    BS2000/OSD を使用して動作します。
   </para>
   <para>
    数多くのBS2000システムにて実運用され、SESAM/SQL-Server は以下の事
    項を実証しています。
    <itemizedlist>
     <listitem>
      <simpara>
       Java、Web ベースのクライアント/サーバ接続が簡単に可能
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       99.99% 以上の確率で有効に動作する能力
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       数万から数十万のユーザを管理する能力
      </simpara>
     </listitem>
    </itemizedlist>
   </para>
   <para>
    PHPスクリプトによるデータベース処理を可能にする PHP3 SESAM インター
    フェースが利用可能です。
   </para>
   <note>
    <title>設定上の注意</title>
    <para>
     PHP SESAMインタフェースは、スタンドアロン版をサポートしていません。
     Apache モジュール版として組み込まれた場合のみ動作します。Apache
     PHP モジュールにおいて、<link linkend="ini.sect.sesam">SESAMイン
     タフェース</link> は、Apache 用ディレクティブにより設定されます。
     <table>
      <title>SESAM 設定用ディレクティブ</title>
      <tgroup cols="2">
       <thead>
        <row>
 	<entry>ディレクティブ</entry>
 	<entry>意味</entry>
        </row>
       </thead>
       <tbody>
        <row>
 	<entry><literal>php3_sesam_oml</literal></entry>
 	<entry>
	  ロード可能なSESAMドライバモジュールが含まれるBS2000 PLAM ラ
	  イブラリの名前。SESAM関数を使用するために必要。
	  <para>
	   例:
	   <informalexample>
	    <programlisting role="apache">
<![CDATA[
php3_sesam_oml $.SYSLNK.SESAM-SQL.030
]]>
            </programlisting>
	   </informalexample>
	  </para>
	 </entry>
        </row>
        <row>
	 <entry><literal>php3_sesam_configfile</literal></entry>
	 <entry>
	  SESAM
	  SESAMアプリケーション設定ファイルの名前。SESAM関数を使用する
	  際に必要。
	  <para>
	   例:
	   <informalexample>
	    <programlisting role="apache">
<![CDATA[
php3_sesam_configfile $SESAM.SESAM.CONF.AW
]]>
	    </programlisting>
	   </informalexample>
	   通常、次のような設定が含まれます。(SESAMリファレンスマニュ
	   アルを参照)
	   <informalexample>
	    <programlisting role="bs2000">
<![CDATA[
CNF=B
NAM=K
NOTYPE
]]>
	    </programlisting>
	   </informalexample>
	  </para>
	 </entry>
        </row>
        <row>
 	<entry><literal>php3_sesam_messagecatalog</literal></entry>
	 <entry>
	  SESAMメッセージカタログファイルの名前。多くの場合、このディ
	  レクティブは不要です。SESAMメッセージファイルがシステム
	  BS2000メッセージファイルてーぶりにインストールされていない場
	  合にのみ、このディレクティブを設定することが可能です。
	  <para>
	   例:
	   <informalexample>
	    <programlisting role="apache">
<![CDATA[
php3_sesam_messagecatalog $.SYSMES.SESAM-SQL.030
]]>
	    </programlisting>
	   </informalexample>
	  </para>
	 </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>
    <para>
     PHP/SESAMインターフェースの設定に加えて、メインフレーム上のSESAM
     データベースサーバー自体を設定する必要があります。これは、次のよ
     うになります。
     <itemizedlist>
      <listitem>
       <simpara>
	SESAMデータベースハンドラ(DBH)を開始
       </simpara>
      </listitem>
      <listitem>
       <simpara>
	SESAMデータベースハンドラを指定して、データベースに接続
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     PHPスクリプトとデータベースハンドラの間の接続を得るには、選択した
     SESAM設定ファイルのパラメータ <literal>CNF</literal> および
     <literal>NAM</literal> が実行中のデータベースハンドラのIDに一致し
     ている必要があります。
    </para>
    <para>
     分散型データベースの場合、ホストおよびデータベース名を有する分配
     テーブルを指定してSESAM/SQL-DCNエージェントを開始する必要がありま
     す。
    </para>
    <para>
     (POSIXサブシステムで実行されている)PHPと(POSIXサブシステムの外で
     実行されている)データベースハンドラの間の通信は、SQLSCIという名前
     の特別なドライバモジュールと通常メモリを使用するSESAM接続モジュー
     ルで実現されます。通常メモリアクセスのため、そして、PHPはWebサー
     バの静的部分であるため、ODBC、JDBC、UTM経由のリモートアクセスは不
     要であり、データベースへのアクセスは非常に高速です。
    </para>
    <para>
     スモールスタブローダ(SESMOD)のみがPHPにリンクされており、SESAM接
     続モジュールはSESAMのOML PLAMライブラリからロードされます。
     <link linkend="ini.sect.sesam">設定</link>の際、このPLAMライブラ
     リの名前とSESAM設定ファイルを使用するためのファイルリンクをPHPに
     指定する必要があります。(SESAM V3.0 において、SQLSCI は標準配布の
     SESAMツールライブラリから入手可能です)
    </para>
    <para>
     SQLコマンドにおけるシングルクオートのクオートは、(シングルクオー
     トの前にバックスラッシュを付加するのではなく、)シングルクオートを
     2つ重ねて使用するため、SESAMインターフェースを使用する全てのPHPス
     クリプトについて、PHP設定ディレクティブで <link
     linkend="ini.magic-quotes-gpc"><literal>php3_magic_quotes_gpc</literal></link>
     および <link linkend="ini.magic-quotes-sybase">
      <literal>php3_magic_quotes_sybase</literal></link> を
     <literal>On</literal> にしておく方が賢明でしょう。
    </para>
   </note>
   <note>
    <title>実行時の考慮</title>
    <para>
     BS2000 モデルの制限のために、ドライバは、Apache サーバがそのサー
     バの子プロセスをフォークした後にのみロード可能となります。これは、
     各子プロセスの最初のSESAMリクエストを若干遅くしますが、その後のア
     クセスへの応答は最高速度となります。
    </para>
    <para>
     SESAM用の明示的にメッセージカタログを定義した場合、そのカタログは
     ドライバがロードされる度(すなわち、最初のSESAMリクエスト時に)にロー
     ドされます。BS2000 オペレーティングシステムはメッセージカタログの
     ロードに成功した後にメッセージを出力します。このメッセージは、
     Apacheのerror_logファイルに送信されます。BS2000は現在、このメッセー
     ジの出力を停止することができません。このため、ログを段々と埋めて
     いきます。
    </para>
    <para>
     SESAM OML PLAM ライブラリとSESAM設定ファイルは、Webサーバを実行し
     ているユーザIDから読み込み可能であることを確認して下さい。そうで
     ない場合、サーバはドライバをロードすることができず、SESAM関数をコー
     ルすることができません。また、Apacheサーバを実行しているユーザID
     にデータベースへのアクセスが許可されている必要があります。そうで
     ない場合、SESAMデータベースハンドラへの接続は失敗します。
    </para>
   </note>
   <note>
    <title>カーソル型</title>
    <para>
     SQL "select 型"クエリ用に確保された結果カーソルは、"sequential"ま
     たは"scrollable"のどちらかとすることが可能です。"scrollable"カー
     ソルで必要なメモリオーバヘッドはより大きいため、デフォルトは
     "sequential" です。
    </para>
    <para>
     "scrollable"カーソルを使用した場合、カーソルは結果集合の中で自由
     に移動可能です。各"scrollable"クエリについて、スクロール型のグロー
     バルなデフォルト値(<literal>SESAM_SEEK_NEXT</literal>に初期化され
     ます)があり、スクロールオフセットは、
     <function>sesam_seek_row</function> により一回設定されるか、
     <function>sesam_fetch_row</function> によりレコードを取得する度に
     設定されるかのどちらかです。"scrollable"カーソルを使用してレコー
     ドを取得する際に、スクロール型およびスクロールオフセットのグロー
     バルデフォルト値について次のようなポスト処理行われます。
     <table>
      <title>スクロール後のカーソルに関するポスト処理</title>
      <tgroup cols="2">
       <thead>
        <row>
 	<entry>スクロール型</entry>
 	<entry>動作</entry>
        </row>
       </thead>
       <tbody>
        <row>
	 <entry><literal>SESAM_SEEK_NEXT</literal></entry>
	 <entry>なし</entry>
        </row>
        <row>
	 <entry><literal>SESAM_SEEK_PRIOR</literal></entry>
	 <entry>なし</entry>
        </row>
        <row>
	 <entry><literal>SESAM_SEEK_FIRST</literal></entry>
	 <entry>
	  スクロール型を <literal>SESAM_SEEK_NEXT</literal> に設定
	 </entry>
        </row>
        <row>
	 <entry><literal>SESAM_SEEK_LAST</literal></entry>
	 <entry>
	  スクロール型を <literal>SESAM_SEEK_PRIOR</literal> に設定
	 </entry>
        </row>
        <row>
	 <entry><literal>SESAM_SEEK_ABSOLUTE</literal></entry>
	 <entry>
	  内部オフセット値を自動的に増加させる
	 </entry>
        </row>
        <row>
	 <entry><literal>SESAM_SEEK_RELATIVE</literal></entry>
	 <entry>
	  なし。(グローバルデフォルト値 <parameter>offset</parameter>
	  を保持する。これにより、例えば、10個前のレコードを取得すると
	  いったことが可能になります)
	 </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>
   </note>
   <note>
    <title>移植時の注意</title>
    <para>
     PHPでは、配列の添字は(1よりも)0から始まるのが普通なため、いくつか
     の調整がSESAMインターフェースで行われています。ある添字配列がネー
     ティブのSESAMインターフェースで添字1から始まる際には、PHPインター
     フェースでは最初の添字として0を使用します。例えば、
     <function>sesam_fetch_row</function> でカラムを取得する際に、最初
     のカラムの添字は0であり、その後のカラム番号はカラム数
     ($array["count"])に達するまで(カラム数は含まず)増えていきます。
     SESAMアプリケーションを他の高級言語からPHPに移植する際には、この
     インターフェース上の変更に留意する必要があります。各PHP sesam 関
     数の説明の適切な場所に添字が0から始まるという注意が含まれています。
    </para>
   </note>
   <note>
    <title>セキュリティの考慮</title>
    <para>
     SESAMデータベースへのアクセスが可能な場合、Webサーバのユーザは、
     可能な限り小さな権限のみを有している必要があります。多くのデータ
     ベースでは許可する必要があるのは読み込み権限のみです。使用する設
     定に応じて状況に見合ったアクセス権限を追加して下さい。決してネッ
     トからの全てのユーザに全てのデータベースへの完全な制御権を許可し
     ないで下さい! データベースを管理するPHPスクリプトへのアクセス制限
     は、パスワード制限またはSSLセキュリティにより制限して下さい。
    </para>
   </note>
   <note>
    <title>他のSQLデータベースからの移行</title>
    <para>
     SQLには方言があるため100%互換ではありません。他のデータベースイン
     ターフェースからSQLアプリケーションをSESAMに移植する際には、いく
     つかの修正が必要になる可能性があります。次のような典型的な差異に
     注意する必要があります。
     <itemizedlist>
      <listitem>
       <simpara>ベンダ固有のデータ型</simpara>
       <simpara>
	いくつかのベンダ固有のデータ型は、標準的なSQLデータ型で置換す
	る必要があります。(例えば、<literal>TEXT</literal> は
	<literal>VARCHAR(max. size)</literal>で置換可能です。)
     </simpara>
      </listitem>
      <listitem>
       <simpara>SQL IDと同じキーワード</simpara>
       <simpara>
	SESAM では(通常のSQLと同様に)このようなIDは2重引用付で括る(も
	しくは名前を変える)必要があります。
       </simpara>
      </listitem>
      <listitem>
       <simpara>データ型の表示長</simpara>
       <simpara>
	SESAM データ型は表示長ではなく、ある精度を有しています。
	
	<literal>int(4)</literal>(意図された使用法:'9999'までの整数)の
	代わりに、SESAM は単に31ビット長の<literal>int</literal>を要求
	します。また、SESAMで利用可能な日付時刻型は次のものだけです。
	<literal>DATE</literal>、 <literal>TIME(3)</literal>、
	<literal>TIMESTAMP(3)</literal>
       </simpara>
      </listitem>
      <listitem>
       <simpara>
	ベンダ固有のSQL型 <literal>unsigned</literal>、
	<literal>zerofill</literal>、<literal>auto_increment</literal> 
	属性
       </simpara>
       <simpara>
	<literal>unsigned</literal> と <literal>zerofill</literal> は
        サポートされません。<literal>auto_increment</literal> は自動で
        す。(SESAMに実装された自動インクリメントの利点を活かすために、
	<literal>"... VALUES(0,...)"</literal> の代わりに
	<literal>"INSERT ... VALUES(*, ...)"</literal> を使用して下さ
        い。)
       </simpara>
      </listitem>
      <listitem>
       <simpara><command>int ... DEFAULT '0000'</command></simpara>
       <simpara>
	数値変数は、文字列定数で初期化するべきではありません。代わりに
	<command>DEFAULT 0</command> を使用して下さい。SQLデータ型
	datetime の変数を初期化する際、初期化文字列には、次のように適
	当な型キーワードを前に付加する必要があります。
	<literal> CREATE TABLE exmpl (
                xtime timestamp(3) DEFAULT TIMESTAMP '1970-01-01 00:00:00.000' NOT &null;
                ); 
	</literal>
       </simpara>
      </listitem>
      <listitem>
       <simpara><command>$count = xxxx_num_rows();</command></simpara>
       <simpara>
	いくつかのデータベースは、返される値が著しく不正確であるとして
	も、クエリ結果のレコード数を推定または見積もろうとします。
	SESAM はクエリ結果のレコード数を実際に取得する前に知ることはあ
	りません。その数が実際に必要な場合には、
	<command>SELECT COUNT(...) WHERE ...</command> を試してみて下
	さい。このクエリは、ヒット数を取得します。2番目のクエリは(理想
	的には)結果を返します。
       </simpara>
      </listitem>
      <listitem>
       <simpara><command>DROP TABLE thename;</command></simpara>
       <simpara>
	SESAMでは、<command>DROP TABLE</command> においてテーブル名の
	後にキーワード <literal>RESTRICT</literal> または
	<literal>CASCADE</literal> のどちらかを後に付加する必要があり
	ます。<literal>RESTRICT</literal> を指定した場合、(VIEWのよう
	な)依存するオブジェクトがある場合にエラーが返されます。また、
	<literal>CASCADE</literal> を指定した場合、依存するオブジェク
	トは指定したテーブルから削除されます。
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
   </note>
   <note>
    <title>
     様々なSQL型を使用する場合の注意
    </title>
    <para>
     SESAM は現在BLOB型をサポートしていません。SESAMの将来のバージョン
     は、BLOBをサポートする予定です。
    </para>
    <para>
     PHP インターフェースでは、SQLフィールドを取得する際に次の型変換が
     自動的に適用されます。
     <table>
      <title>SQL から PHP への型変換</title>
      <tgroup cols="2">
       <thead>
        <row>
 	<entry>SQL 型</entry>
 	<entry>PHP 型</entry>
        </row>
       </thead>
       <tbody>
        <row>
 	<entry>SMALLINT, INTEGER</entry>
 	<entry>"integer"</entry>
        </row>
        <row>
 	<entry>NUMERIC, DECIMAL, FLOAT, REAL, DOUBLE</entry>
 	<entry>"double"</entry>
        </row>
        <row>
 	<entry>DATE, TIME, TIMESTAMP</entry>
 	<entry>"string"</entry>
        </row>
        <row>
 	<entry>VARCHAR, CHARACTER</entry>
 	<entry>"string"</entry>
        </row>
       </tbody>
      </tgroup>
     </table>
     レコード全体を取得する際、結果は配列として返されます。空のフィー
     ルドには値が入っていないため、個々のフィールド自体の存在を調べる
     必要があります(空のフィールドかどうか調べるには、
     <function>isset</function> または <function>empty</function> を使
     用して下さい) 。この手法は、(空のフィールドの表現として型の文字列
     を使用するよりも)空のフィールドの見え方をユーザが制御することが可
     能となります。
    </para>
   </note>
   <note>
    <title>SESAM の "複数フィールド" 機能のサポート</title>
    <para>
     SESAM特有の"複数フィールド"機能により複数のフィールドの配列からな
     るカラムを使用することが可能です。"複数フィールド"カラム亜は、次
     のように作成可能です。
     <example>
      <title>"複数フィールド"カラムを作成する</title>
      <programlisting role="sesam">
<![CDATA[
CREATE TABLE multi_field_test (
    pkey CHAR(20) PRIMARY KEY,
    multi(3) CHAR(12)
)
]]>
      </programlisting>
     </example>
     上のレコードに次のように代入することができます。
     <example>
      <title>"複数フィールド"カラムに代入する</title>
      <programlisting role="sesam">
<![CDATA[
INSERT INTO multi_field_test (pkey, multi(2..3) )
    VALUES ('Second', <'first_val', 'second_val'>)
]]>
      </programlisting>
     </example>
     (この場合のように)先頭の空のサブフィールドは無視され、代入された
     値は詰められることに注意して下さい。このため、上記の例の結果は、
     multi(2..3) ではなく、multi(1..2) となります。
    </para>
    <para>
     結果レコードを取得する際、"複数カラム"は"インラインの"付加カラム
     のようにアクセスされます。上のにおいて、"pkey" は添字0を有し、3つ
     の"multi(1..3)" カラムは添字1から3でアクセス可能です。
    </para>
   </note>
   <para>
    SESAM固有の事項について詳細は、<ulink url="&url.sesam.en;">the
    SESAM/SQL-Serverドキュメント(英語)</ulink> または
    <ulink url="&url.sesam.de;">SESAM/SQL-Server ドキュメント(ドイツ語)
    </ulink> を参照下さい。共にオンラインで参照可能です。もしくは、適
    当なマニュアルを使用して下さい。
   </para>
  </partintro>

  <refentry id="function.sesam-connect">
   <refnamediv>
    <refname>sesam_connect</refname>
    <refpurpose>SESAM データベース接続をオープンする</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>bool</type><methodname>sesam_connect</methodname>
      <methodparam><type>string</type><parameter>catalog</parameter></methodparam>
      <methodparam><type>string</type><parameter>schema</parameter></methodparam>
      <methodparam><type>string</type><parameter>user</parameter></methodparam>
     </methodsynopsis>
    <para>
     SESAMデータベースへの接続が作成された場合に
     &true;、エラーの場合に &false;
     を返します。
    </para>
    <para>
     <function>sesam_connect</function> はSESAMデータベースハンドラタ
     スクへの接続を確立します。接続は、最初の起動時にのみ設定された
     SESAM OML PLAMライブラリから実際にドライバがロードされるという意
     味で常に"持続的"です。この後のコールでは、ドライバは再利用され、
     指定しカタログ、スキーマ、ユーザを直ちに使用されます。
    </para>
    <para>
     データベースを作成する際、<parameter>"catalog"</parameter> 名は、
     SESAM設定ディレクティブ <command>//ADD-SQL-DATABASE-CATALOG-LIST
     ENTRY-1 = *CATALOG(CATALOG-NAME = catalogname,...)</command> で指
     定します。
    </para>
    <para>
     <parameter>"schema"</parameter> には選択したデータベーススキーマ
     を指定します。(SESAMハンドブックを参照)
    </para>
    <para>
     <parameter>"user"</parameter> 引数には、この
     <parameter>"catalog"</parameter> /
     <parameter>"schema"</parameter> の組にアクセス可能なユーザの一人
     を指定します。<parameter>"user"</parameter>は、システムのユーザID
     とHTTPユーザ/パスワード保護から共に完全に独立していことに注意して
     下さい。SESAM設定にのみ使用されます。
    </para>
    <para>
     <function>sesam_disconnect</function>も参照下さい。
     <example>
      <title>SESAM データベースへの接続</title>
      <programlisting role="php">
<![CDATA[
<?php
if (!sesam_connect ("mycatalog", "myschema", "otto")
    die("Unable to connect to SESAM");
?>
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.sesam-disconnect">
   <refnamediv>
    <refname>sesam_disconnect</refname>
    <refpurpose>SESAM接続から切り離す</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>bool</type><methodname>sesam_disconnect</methodname>
      <void/>
     </methodsynopsis>
    <para>
     返り値: 常に &true;。
    </para>
    <para>
     <function>sesam_disconnect</function> は(実際に接続を断にしたり、
     ドライバをアンロードすることなく)SESAMデータベースへの論理リンク
     を閉じます。
    </para>
    <para>
     オープンされた接続はスクリプトの実行終了時に閉じられるため、この
     関数は通常不要です。コミットされていないデータは、暗黙のうちに
     <function>sesam_rollback</function> が実行されるため、破棄されま
     す。
    </para>
    <para>
     <function>sesam_disconnect</function> は、持続的なリンクを閉じず、
     現在、定義されている <parameter>"catalog"</parameter>、
     <parameter>"schema"</parameter>、<parameter>"user"</parameter> の
     組を無効にするだけです。このため、
     <function>sesam_disconnect</function> の後でコールされた SESAM 関
     数は失敗します。
    </para>
    <para>
     <function>sesam_connect</function>も参照下さい。
     <example>
      <title>SESAM 接続を閉じる</title>
      <programlisting role="php">
<![CDATA[
if (sesam_connect ("mycatalog", "myschema", "otto")) {
    ... some queries and stuff ...
    sesam_disconnect(); 
}
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.sesam-settransaction">
   <refnamediv>
    <refname>sesam_settransaction</refname>
    <refpurpose>SESAM トランザクションパラメータ</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>bool</type><methodname>sesam_settransaction</methodname>
      <methodparam><type>int</type><parameter>isolation_level</parameter></methodparam>
      <methodparam><type>int</type><parameter>read_only</parameter></methodparam>
     </methodsynopsis>
    <para>
     返り値: <function>settransaction</function> 処理が成功して、
     有効な場合に &true;、その他の場合に
     &false;。
    </para>
    <para>
     <function>sesam_settransaction</function> は、(SESAM設定ファイル
     で設定される)トランザクションパラメータ "isolation level" と
     "read-only" のデフォルト値を上書きします。これは、連続するクエリ
     を最適化し、データベースの統一性を保証するためです。上書きされた
     値は、次のトランザクションでのみ使用されます。
    </para>
    <para>
     <function>sesam_settransaction</function> は、トランザクションを
     開始する前にのみコールすることが可能で、既にトランザクションが開
     始されている場合には、コールすることができません。
    </para>
    <para>
     PHPスクリプトの使用を簡単にするには、次の定数が、PHPで定義されて
     います。(意味の詳細についてはSESAMハンドブックを参照)
     <table>
      <title>
       <parameter>"Isolation_Level"</parameter>パラメータの有効な値
      </title>
      <tgroup cols="3">
       <thead>
        <row>
 	<entry>値</entry>
 	<entry>定数</entry>
 	<entry>意味</entry>
        </row>
       </thead>
       <tbody>
        <row>
 	<entry>1</entry>
 	<entry><literal>SESAM_TXISOL_READ_UNCOMMITTED</literal></entry>
 	<entry>Read Uncommitted</entry>
        </row>
        <row>
 	<entry>2</entry>
 	<entry><literal>SESAM_TXISOL_READ_COMMITTED</literal></entry>
 	<entry>Read Committed</entry>
        </row>
        <row>
 	<entry>3</entry>
 	<entry><literal>SESAM_TXISOL_REPEATABLE_READ</literal></entry>
 	<entry>Repeatable Read</entry>
        </row>
        <row>
 	<entry>4</entry>
 	<entry><literal>SESAM_TXISOL_SERIALIZABLE</literal></entry>
 	<entry>Serializable</entry>
        </row>
       </tbody>
      </tgroup>
     </table>
     <table>
      <title>
       <parameter>"Read_Only"</parameter> パラメータの有効な値
      </title>
      <tgroup cols="3">
       <thead>
        <row>
 	<entry>値</entry>
 	<entry>定数</entry>
 	<entry>意味</entry>
        </row>
       </thead>
       <tbody>
        <row>
 	<entry>0</entry>
 	<entry><literal>SESAM_TXREAD_READWRITE</literal></entry>
 	<entry>Read/Write</entry>
        </row>
        <row>
 	<entry>1</entry>
 	<entry><literal>SESAM_TXREAD_READONLY</literal></entry>
 	<entry>Read-Only</entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>
    <para>
     <function>sesam_settransaction</function> により設定された値は、
     <link linkend="ini.sesam-configfile">SESAM 設定ファイル</link>で
     指定されたデフォルト設定を上書きします。
    </para>
    <para>
     <example>
      <title>SESAM トランザクションパラメータを設定する</title>
      <programlisting role="php">
<![CDATA[
<?php
sesam_settransaction (SESAM_TXISOL_REPEATABLE_READ,
                     SESAM_TXREAD_READONLY);
?>
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.sesam-commit">
   <refnamediv>
    <refname>sesam_commit</refname>
    <refpurpose>
     SESAMデータベースへの待機中の更新処理をコミットする
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>bool</type><methodname>sesam_commit</methodname>
      <void/>
     </methodsynopsis>
    <para>
     返り値: 成功時に&true;、エラー時に
     &false;
    </para>
    <para>
     <function>sesam_commit</function> は、全ての待機中のデータベース
     への更新処理をコミットします。
    </para>
    <para>
     他のデータベースのように"自動コミット"機能がないため、事故により
     データが失われる可能性があることに注意して下さい。カレントのスク
     リプト実行終了時にコミットされていないデータは、暗黙の
     <function>sesam_rollback</function> コールにより破棄されます。
    </para>
    <para>
    </para>
    <para>
     <function>sesam_rollback</function>も参照下さい。
     <example>
      <title>SESAM データベースの更新をコミットする</title>
      <programlisting role="php">
<![CDATA[
<?php
if (sesam_connect ("mycatalog", "myschema", "otto")) {
    if (!sesam_execimm ("INSERT INTO mytable VALUES (*, 'Small Test', <0, 8, 15>)"))
        die("insert failed");
    if (!sesam_commit())
        die("commit failed");
}
?>
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.sesam-rollback">
   <refnamediv>
    <refname>sesam_rollback</refname>
    <refpurpose>
     SESAMデータベースに対する待機中の更新を破棄する
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>bool</type><methodname>sesam_rollback</methodname>
      <void/>
     </methodsynopsis>
    <para>
     返り値: 成功時に &true;、エラー時に
     &false;
    </para>
    <para>
     <function>sesam_rollback</function> は、データベースへの待機中の
     更新を破棄します。結果カーソルと結果記述子も変更されます。
    </para>
    <para>
     スクリプトの終了時に、<function>sesam_disconnect</function> 関数
     から暗黙のうちに <function>sesam_rollback</function>が実行され、
     データベースの待機中の全ての変更は破棄されます。
    </para>
    <para>
     <function>sesam_commit</function>も参照下さい。
     <example>
      <title>SESAM データベースへの更新を破棄する</title>
      <programlisting role="php">
<![CDATA[
<?php
if (sesam_connect ("mycatalog", "myschema", "otto")) {
    if (sesam_execimm ("INSERT INTO mytable VALUES (*, 'Small Test', <0, 8, 15>)")
        && sesam_execimm ("INSERT INTO othertable VALUES (*, 'Another Test', 1)"))
        sesam_commit();
    else
        sesam_rollback();
}
?>
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.sesam-execimm">
   <refnamediv>
    <refname>sesam_execimm</refname>
    <refpurpose>SQL命令を直ちに実行する</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>string</type><methodname>sesam_execimm</methodname>
      <methodparam><type>string</type><parameter>query</parameter></methodparam>
     </methodsynopsis>
    <para>
     返り値: 成功時にSESAM "結果ID"、エラー時に
     &false;
    </para>
    <para>
     <function>sesam_execimm</function> は命令(すなわち、UPDATE、
     INSERT、DELETEのような結果を返さない命令や入出力変数がない命令)を
     "直ちに"実行します。"select 型" クエリは、
     <function>sesam_execimm</function> で使用することはできません。
     <function>sesam_affected_rows</function> 関数により取得可能な
     <parameter>affected_rows</parameter> の値を設定します。
    </para>
    <para>
     <function>sesam_query</function> は、"即時型"および"select型"クエ
     リの両方を処理することができることに注意して下さい。実行される命
     令の型が事前に分かっている場合にのみ
     <function>sesam_execimm</function> を使用して下さい。SELECT型クエ
     リを使用しようとすると、<function>sesam_execimm</function>は
     <literal>$err["sqlstate"] == "42SBW"</literal>を返します。
    </para>
    <para>
     返される"結果ID"は、何かを取得する際に使用することはできず、
     <function>sesam_affected_rows</function> を実行する際に使用します。
     このIDは、<function>sesam_query</function> 関数と対称性を保つため
     にのみ返されます。
    </para>
    <para>
     <informalexample>
      <programlisting role="php">
<![CDATA[
$stmt = "INSERT INTO mytable VALUES ('one', 'two')";
$result = sesam_execimm ($stmt);
$err = sesam_diagnostic();
print ("sqlstate = ".$err["sqlstate"]."\n".
       "Affected rows = ".$err["rowcount"]." == ".
       sesam_affected_rows($result)."\n");
]]>
      </programlisting>
     </informalexample>
     <function>sesam_query</function> および
     <function>sesam_affected_rows</function>も参照下さい。
    </para>
   </refsect1>
  </refentry>
 
  <refentry id="function.sesam-query">
   <refnamediv>
    <refname>sesam_query</refname>
    <refpurpose>SESAM SQL クエリを実行し、結果を準備する</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>string</type><methodname>sesam_query</methodname>
      <methodparam><type>string</type><parameter>query</parameter></methodparam>
      <methodparam><type>bool</type><parameter>
	<replaceable><optional>scrollable</optional></replaceable>
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     返り値: 成功時にSESAM "結果ID" またはエラー時に
     &false;。
    </para>
    <para>
     "result_id"リソースは、クエリ結果を取得する際に他の関数で使用され
     ます。
    </para>
    <para>
     <function>sesam_query</function> は、クエリをサーバ上の現在アクティ
     ブなデータベースに送信します。この関数は、"即時"SQL命令および
     "select型"クエリの両方を実行可能です。"即時型"命令を実行した場合、
     カーソルは確保されず、この後に
     <function>sesam_fetch_row</function> または
     <function>sesam_fetch_result</function> をコールしても空の結果(結
     果の終端を示すカラム数0)が返されます。"select型"命令の場合、結果
     記述子および(オプションのパラメータ
     <parameter>scrollable</parameter>の設定によりスクロール型または連
     続型の)カーソルが確保されます。<parameter>scrollable</parameter>
     が省略された場合、カーソルは連続型となります。
    </para>
    <para>
     "スクロール型"カーソルを使用している場合、カーソルは結果集合上を
     自由に移動可能です。各"スクロール型"クエリに関して、スクロール型
     のグローバルデフォルト値(<literal>SESAM_SEEK_NEXT</literal>に初期
     化されています)と <function>sesam_seek_row</function> により一度
     設定するか、<function>sesam_fetch_row</function> を使用してレコー
     ドを取得する度に設定するスクロールオフセットがあります。
    </para>
    <para>
     "即時型"命令の場合、作用されたレコードの数が保存されます。この数
     は、<function>sesam_affected_rows</function> 関数で取得可能です。
    </para>
    <para>
     <function>sesam_fetch_row</function> および
     <function>sesam_fetch_result</function> も参照下さい。
     <example>
      <title>
       "phone"テーブルの全てのレコードをHTMLテーブルとして表示
      </title>
      <programlisting role="php">
<![CDATA[
<?php
if (!sesam_connect ("phonedb", "demo", "otto"))
    die ("cannot connect");
$result = sesam_query ("select * from phone");
if (!$result) {
    $err = sesam_diagnostic();
    die ($err["errmsg"]);
}
echo "<TABLE BORDER>\n";
// Add title header with column names above the result:
if ($cols = sesam_field_array ($result)) {
    echo " <TR><TH COLSPAN=".$cols["count"].">Result:</TH></TR>\n";
    echo " <TR>\n";
    for ($col = 0; $col < $cols["count"]; ++$col) {
        $colattr = $cols[$col];
        /* Span the table head over SESAM's "Multiple Fields": */
        if ($colattr["count"] > 1) {
            echo "  <TH COLSPAN=".$colattr["count"].">".$colattr["name"].
                "(1..".$colattr["count"].")</TH>\n";
            $col += $colattr["count"] - 1;
        } else
            echo "  <TH>" . $colattr["name"] . "</TH>\n";
    }
    echo " </TR>\n";
}

do {
    // Fetch the result in chunks of 100 rows max.
    $ok = sesam_fetch_result ($result, 100);
    for ($row=0; $row < $ok["rows"]; ++$row) {
        echo " <TR>\n";
        for ($col = 0; $col < $ok["cols"]; ++$col) {
            if (isset($ok[$col][$row]))
                echo "  <TD>" . $ok[$col][$row] . "</TD>\n";
            } else {
                echo "  <TD>-empty-</TD>\n";
            }
        }
        echo " </TR>\n";
    }
} 
while ($ok["truncated"]) { // while there may be more data
    echo "</TABLE>\n";
}
// free result id
sesam_free_result($result);
?>
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.sesam-num-fields">
   <refnamediv>
    <refname>sesam_num_fields</refname>
    <refpurpose>結果集合のフィールド/カラム数を返す</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>sesam_num_fields</methodname>
      <methodparam><type>string</type><parameter>result_id</parameter></methodparam>
     </methodsynopsis>
    <para>
     "select型"クエリで <function>sesam_query</function>をコールした後、
     この関数により結果のカラム数を得ることが可能です。全体のカラム(ま
     たはフィールド)の数を記述する整数を返します。
    </para>
    <para>
     "即時型"命令の場合、値0が返されます。SESAM"複数フィールド"カラム
     は、それぞれの次元毎に数えられます。すなわち、"複数フィールド"の3
     カラムはカラム3つとして数えられます。
    </para>
    <para>
     "複数フィールド"カラムよ標準カラムを区別するには、
     <function>sesam_query</function> および
     <function>sesam_field_array</function> も参照下さい。
    </para>
   </refsect1>
  </refentry>
 
  <refentry id="function.sesam-field-name">
   <refnamediv>
    <refname>sesam_field_name</refname>
    <refpurpose>
     結果集合のカラム名を返す
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>sesam_field_name</methodname>
      <methodparam><type>string</type><parameter>result_id</parameter></methodparam>
      <methodparam><type>int</type><parameter>index</parameter></methodparam>
     </methodsynopsis>
    <para>
     結果集合の中のフィールド名(すなわち、カラム名)またはエラーの際に
     &false; を返します。
    </para>
    <para>
     "即時型"クエリまたは動的なカラムの場合、空の文字列が返されます。
    </para>
    <note>
     <para>
      カラムの添字は、SESAMのように1から始まらず、0から始まります。
     </para>
    </note>
    <para>
     <function>sesam_field_array</function> も参照下さい。この関数は、
     カラム名および型により簡単にアクセスするインターフェースを提供し、
     "複数フィールド"の検出が可能になります。
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="function.sesam-diagnostic">
   <refnamediv>
    <refname>sesam_diagnostic</refname>
    <refpurpose>
     直近のSESAMコールに関するステータス情報を返す
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>array</type><methodname>sesam_diagnostic</methodname>
      <void/>
     </methodsynopsis>
    <para>
     直近のSQLクエリ/命令/コマンドに関するステータスおよびエラーコード
     を連想配列として返します。配列の要素は次のようになります。
     <table>
      <title>
       <function>sesam_diagnostic</function>により返されるステータス情報
      </title>
      <tgroup cols="2">
       <thead>
        <row>
 	<entry>要素</entry>
 	<entry>内容</entry>
        </row>
       </thead>
       <tbody>
        <row>
	 <entry>$array["sqlstate"]</entry>
	 <entry>
	  5 桁の SQL リターンコード (SQLSTATEの値の説明については、
	  SESAMマニュアル参照)
	 </entry>
        </row>
        <row>
	 <entry>$array["rowcount"]</entry>
	 <entry>
	  直近のupdate/insert/deleteクエリで作用されたレコードの数
	  ("即時型"命令の後でのみ設定されます)
        </entry>
        </row>
        <row>
 	<entry>$array["errmsg"]</entry>
 	<entry>
	  "可読な" エラーメッセージ文字列
	  (エラーの後でのみ設定されます)
        </entry>
        </row>
        <row>
 	<entry>$array["errcol"]</entry>
 	<entry>
	  以前のエラーのエラーカラム番号
	  (0から始まり、未定義の場合は-1。エラーの後でのみ設定されます)
        </entry>
        </row>
        <row>
 	<entry>$array["errlin"]</entry>
 	<entry>
	  前のエラーのエラー行番号
	  (0から始まり、未定義の場合は-1。エラーの後でのみ設定されます)
        </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>
    <para>
     次の例では、問題があるSQL命令を含み、エラー位置を指す構文エラー(E
     SEW42AE ILLEGAL CHARACTER)が表示されます。
     <example>
      <title>エラー位置を付けてSESAMエラーメッセージを表示</title>
      <programlisting role="php">
<![CDATA[
<?php
// フォーマットされたエラーメッセージを出力する関数
// SQL命令における構文エラーの場所を表示
function PrintReturncode($exec_str)
{
   $err = Sesam_Diagnostic();
   $colspan=4; // sqlstate, errlin, errcol, rowcount 用の4つのカラム
   if ($err["errlin"] == -1)
     --$colspan;
   if ($err["errcol"] == -1)
     --$colspan;
   if ($err["rowcount"] == 0)
     --$colspan;
    echo "<TABLE BORDER>\n";
    echo "<TR><TH COLSPAN=".$colspan."><FONT COLOR=red>ERROR:</FONT> ".
	  	htmlspecialchars($err["errmsg"])."</TH></TR>\n";
    if ($err["errcol"] >= 0) {
        echo "<TR><TD COLSPAN=".$colspan."><PRE>\n";
        $errstmt = $exec_str."\n";
        for ($lin=0; $errstmt != ""; ++$lin) {
            if ($lin != $err["errlin"]) { // $lin is less or greater than errlin
                if (!($i = strchr ($errstmt, "\n")))
                    $i = "";
                $line = substr ($errstmt, 0, strlen($errstmt)-strlen($i)+1);
                $errstmt = substr($i, 1);
                if ($line != "\n")
                    print htmlspecialchars ($line);
            } else {
                if (! ($i = strchr ($errstmt, "\n")))
                    $i = "";
                $line = substr ($errstmt, 0, strlen ($errstmt)-strlen($i)+1);
                $errstmt = substr($i, 1);
                for ($col=0; $col < $err["errcol"]; ++$col)
                    echo (substr($line, $col, 1) == "\t") ? "\t" : ".";
                echo "<FONT COLOR=RED><BLINK>\\</BLINK></FONT>\n";
                print "<FONT COLOR=\"#880000\">".htmlspecialchars($line)."</FONT>";
                for ($col=0; $col < $err["errcol"]; ++$col)
                    echo (substr ($line, $col, 1) == "\t") ? "\t" : ".";
                echo "<FONT COLOR=RED><BLINK>/</BLINK></FONT>\n";
            }
        }
        echo "</PRE></TD></TR>\n";
    }
    echo "<TR>\n";
    echo " <TD>sqlstate=" . $err["sqlstate"] . "</TD>\n";
    if ($err["errlin"] != -1)
        echo " <TD>errlin=" . $err["errlin"] . "</TD>\n";
    if ($err["errcol"] != -1)
        echo " <TD>errcol=" . $err["errcol"] . "</TD>\n";
    if ($err["rowcount"] != 0)
         echo " <TD>rowcount=" . $err["rowcount"] . "</TD>\n";
    echo "</TR>\n";
    echo "</TABLE>\n";
}

if (!sesam_connect ("mycatalog", "phoneno", "otto"))
  die ("cannot connect");

$stmt = "SELECT * FROM phone\n".
        " WHERE@ LASTNAME='KRAEMER'\n".
        " ORDER BY FIRSTNAME";
if (!($result = sesam_query ($stmt)))
    PrintReturncode ($stmt);
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     エラー文字列に簡単にアクセスするためには、
     <function>sesam_errormsg</function> も参照下さい。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.sesam-fetch-result">
   <refnamediv>
    <refname>sesam_fetch_result</refname>
    <refpurpose>クエリ結果の全てあるいは一部を返す</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>mixed</type><methodname>sesam_fetch_result</methodname>
      <methodparam><type>string</type><parameter>result_id</parameter></methodparam>
      <methodparam><type>int</type><parameter>
	<replaceable><optional>max_rows</optional></replaceable>
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     クエリ結果のエントリを種々の型の配列として返します。オプションで
     最大レコード数を <parameter>max_rows</parameter> に制限することが
     可能です。レコード番号およびカラム番号は共に0から始まることに注意
     して下さい。
     <table>
      <title>
       <function>sesam_fetch_result</function>により返された種々の結果集合
      </title>
      <tgroup cols="2">
       <thead>
        <row>
 	<entry>配列要素</entry>
 	<entry>定数</entry>
        </row>
       </thead>
       <tbody>
        <row>
 	<entry>int $arr["count"]</entry>
 	<entry>
	  結果集合のカラム数 ("即時型"クエリの場合に0)
	 </entry>
        </row>
        <row>
 	<entry>int $arr["rows"]</entry>
 	<entry>
	  結果集合のレコード数(0と<parameter>max_rows</parameter>の間)
	 </entry>
        </row>
        <row>
 	<entry>bool $arr["truncated"]</entry>
 	<entry>
	  レコード数が<parameter>max_rows</parameter>以上の場合に
	  &true;、そうでない場合に
	  &false;。これが &true;でな
	  い場合でも、結果エントリはもうないために次の
	  <function>sesam_fetch_result</function> はレコードを返さない
	  可能性があります。 
	 </entry>
        </row>
        <row>
 	<entry>mixed $arr[col][row]</entry>
 	<entry>
	  レコード(<literal>row</literal>) および
	  カラム(<literal>col</literal>)にある全てのフィールドの結果デー
	  タ、(整数のレコード番号<literal>row</literal>は0から
	  <literal>$arr["rows"]-1</literal>の間であり、
	  <literal>col</literal> は 0 から
	  <literal>$arr["count"]-1</literal>の間です)。フィールドは空
	  である可能性があり、このため、PHPの
	  <function>isset</function> 関数を使用してフィールドが存在す
	  るかどうか確認する必要があります。返されるフィールドの型は、
	  そのカラムのSQL型宣言(適用される変換については<link
	  linkend="ref.sesam">SESAM 概要</link>参照)に依存します。
	  SESAM "複数フィールド" は"インライン"であり、カラムの番号と
	  同様に処理されます。
        </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
     大きなクエリで使用されるメモリの最大値は、巨大なものになる可能性
     があることに注意して下さい。結果が利用可能な全メモリを消費しない
     ことが確実である場合以外は、返されるレコード数の最大値を制限する
     ために <parameter>max_rows</parameter> パラメータを使用して下さい。
    </para>
    <para>
     "複数フィールド"を確認するために
     <function>sesam_fetch_row</function>および
     <function>sesam_field_array</function> も参照下さい。
     <function>sesam_fetch_result</function>の完全な例については、
     <function>sesam_query</function> 関数の説明を参照下さい。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.sesam-affected-rows">
   <refnamediv>
    <refname>sesam_affected_rows</refname>
    <refpurpose>直近のクエリにより作用されたレコードの数を得る</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>sesam_affected_rows</methodname>
      <methodparam><type>string</type><parameter>result_id</parameter></methodparam>
     </methodsynopsis>
    <para>
     <parameter>result_id</parameter> は、
     <function>sesam_query</function> により返された有効な結果IDです。
    </para>
    <para>
     <parameter>result_id</parameter> に関連するクエリにより作用された
     レコード数を返します。
    </para>
    <para>
     <function>sesam_affected_rows</function> 関数は、"即時型"SQL命令
     (<literal>INSERT</literal>、<literal>UPDATE</literal>、
     <literal>DELETE</literal>のような更新処理)の組合せで使用された場
     合にのみ有用な値を返します。これは、SESAMが"select型"クエリに関し
     て"作用されたレコード"に関する情報を返さないためです。返される数
     は作用されたレコードの数です。
    </para>
    <para>
     <function>sesam_query</function> および
     <function>sesam_execimm</function> も参照下さい。
    </para>
     <informalexample>
      <programlisting role="php">
<![CDATA[
$result = sesam_execimm ("DELETE FROM PHONE WHERE LASTNAME = '".strtoupper ($name)."'");
if (!$result) {
    ... error ...
}
print sesam_affected_rows ($result).
    " entries with last name ".$name." deleted.\n"
]]>
     </programlisting>
    </informalexample>
   </refsect1>
  </refentry>

  <refentry id="function.sesam-errormsg">
   <refnamediv>
    <refname>sesam_errormsg</refname>
    <refpurpose>直近のSESAMコールのエラーメッセージを返す</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>string</type><methodname>sesam_errormsg</methodname>
      <void/>
     </methodsynopsis>
    <para>
     直近のSESAMエラーに関連する SESAMエラーメッセージを返します。
    </para>
    <informalexample>
     <programlisting role="php">
<![CDATA[
if (!sesam_execimm ($stmt))
  printf ("%s<br>\n", sesam_errormsg());
]]>
     </programlisting>
    </informalexample>
    <para>
     SESAM SQLステータス情報の完全な集合については、
     <function>sesam_diagnostic</function> も参照下さい。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.sesam-field-array">
   <refnamediv>
    <refname>sesam_field_array</refname>
    <refpurpose>
     結果の個々のカラムに関するメタ情報を返す
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>array</type><methodname>sesam_field_array</methodname>
      <methodparam><type>string</type><parameter>result_id</parameter></methodparam>
     </methodsynopsis>
    <para>
     <parameter>result_id</parameter> は、
     <function>sesam_query</function> により返された有効な結果IDです。
    </para>
    <para>
     <parameter>result_id</parameter>に関連したクエリの後で、結果の個々
     のカラムに関するメタ情報(カラム名、型、精度、...)を有する連想/添
     字配列を返します。
    </para>
    <para>
     <table>
      <title>
       <function>sesam_field_array</function> で返された結果集合
      </title>
      <tgroup cols="2">
       <thead>
        <row>
 	<entry>配列要素</entry>
 	<entry>定数</entry>
        </row>
       </thead>
       <tbody>
        <row>
 	<entry>int $arr["count"]</entry>
 	<entry>
	  結果集合におけるカラム数の合計 (または"即時型"クエリの場合に
	  0)。  SESAM "複数フィールド"はインライン化されており、対応す
	  るカラム番号と同様に処理されます。
	</entry>
        </row>
        <row>
 	<entry>string $arr[col]["name"]</entry>
 	<entry>
	  カラム(<literal>col</literal>)のカラム名、ただし、
	  <literal>col</literal> は、0 から
	  <literal>$arr["count"]-1</literal>の間です。返される値は、
	  (動的に計算されるカラムの場合、)空の文字列となる可能性があり
	  ます。SESAM "複数フィールド" は"インライン化"されており、カ
	  ラム番号と同様に同じカラム名で処理されます。
        </entry>
        </row>
        <row>
 	<entry>string $arr[col]["count"]</entry>
 	<entry>
	  属性 "count" は、カラムが"複数フィールド"として宣言された場
	  合の繰り返し数を記述します。通常、"count"属性は1です。しかし、
	  "複数フィールド"カラムの最初のカラムは繰返し数を有します。
	  ("複数フィールド"の2番目以降のカラムは1という"count"属性を有
	  します)この属性は、結果集合の中で"複数フィールド"を検出する
	  ために使用可能です。"count"属性の使用例については、
	  <function>sesam_query</function> の説明に示されている例を参
	  照下さい。
	 </entry>
        </row>
        <row>
 	<entry>string $arr[col]["type"]</entry>
 	<entry>
	  カラム(<literal>col</literal>)に関するデータのPHP 変数型、た
	  だし、<literal>col</literal> は 0 と
	  <literal>$arr["count"]-1</literal> の間です。値は、結果のSQL
	  型に基づき以下のどれかとなります。
	  <itemizedlist>
	   <listitem>
	    <simpara>"integer"</simpara>
	   </listitem>
	   <listitem>
	    <simpara>"double"</simpara>
	   </listitem>
	   <listitem>
	    <simpara>"string"</simpara>
	   </listitem>
	  </itemizedlist>
	  SESAM "複数フィールド"は"インライン化"されており、同じカラム
	  数を有し、同じPHP型の場合と同様に処理されます。
	 </entry>
        </row>
        <row>
	 <entry>string $arr[col]["sqltype"]</entry>
	 <entry>
	  SQL variable type of the column data for
	  カラム(<literal>col</literal>)に関するカラムデータのSQL変数
	  型。ただし、<literal>col</literal> は 0 から
	  and <literal>$arr["count"]-1</literal>の間になります。返され
	  る値は、結果のSQL型を記述する次のどれかとなります。
	  <itemizedlist>
	   <listitem>
	    <simpara>"CHARACTER"</simpara>
	   </listitem>
	   <listitem>
	    <simpara>"VARCHAR"</simpara>
	   </listitem>
	   <listitem>
	    <simpara>"NUMERIC"</simpara>
	   </listitem>
	   <listitem>
	    <simpara>"DECIMAL"</simpara>
	   </listitem>
	   <listitem>
	    <simpara>"INTEGER"</simpara>
	   </listitem>
	   <listitem>
	    <simpara>"SMALLINT"</simpara>
	   </listitem>
	   <listitem>
	    <simpara>"FLOAT"</simpara>
	   </listitem>
	   <listitem>
	    <simpara>"REAL"</simpara>
	   </listitem>
	   <listitem>
	    <simpara>"DOUBLE"</simpara>
	   </listitem>
	   <listitem>
	    <simpara>"DATE"</simpara>
	   </listitem>
	   <listitem>
	    <simpara>"TIME"</simpara>
	   </listitem>
	   <listitem>
	    <simpara>"TIMESTAMP"</simpara>
	   </listitem>
	  </itemizedlist>
	  SESAM "複数フィールド"は"インライン化"されており、同じカラム
	  数、同じPHP型の場合と同様に処理されます。
        </entry>
        </row>
        <row>
 	<entry>string $arr[col]["length"]</entry>
	 <entry>
	  カラム(<literal>col</literal>)のSQL変数のSQL "length" 属性。
	  ただし、<literal>col</literal> は、0 から
	  <literal>$arr["count"]-1</literal>の間です。"length"属性は、
	  文字列変数の(最大)長さを指定するために"CHARACTER" および
	  "VARCHAR" SQL型を指定して使用されます。
	  SESAM "複数フィールド"は"インライン化"されており、同じカラム
	  数、同じPHP型の場合と同様に処理されます。
	 </entry>
        </row>
        <row>
 	<entry>string $arr[col]["precision"]</entry>
 	<entry>
	  カラム(<literal>col</literal>にあるSQL変数,の
	  "precision" 属性。ただし、<literal>col</literal> は、0から
	  <literal>$arr["count"]-1</literal>の間です。"precision"属性
	  は、数値および時間データ型で使用されます。
	  SESAM "複数フィールド"は"インライン化"されており、同じカラム
	  数、同じPHP型の場合と同様に処理されます。
	 </entry>
        </row>
        <row>
 	<entry>string $arr[col]["scale"]</entry>
 	<entry>
	  カラム(<literal>col</literal>)にあるSQL変数の"scale" 属性。
	  ただし、<literal>col</literal> は、0 から
	  <literal>$arr["count"]-1</literal>の間です。"scale"属性は、
	  数値データ型で使用されます。
	  SESAM "複数フィールド"は"インライン化"されており、同じカラム
	  数、同じPHP型の場合と同様に処理されます。
	 </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>
    <para>
     <function>sesam_field_array</function> の使用例については、
     <function>sesam_query</function> 関数を参照下さい。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.sesam-fetch-row">
   <refnamediv>
    <refname>sesam_fetch_row</refname>
    <refpurpose>1件分のレコードを配列として取得</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>array</type><methodname>sesam_fetch_row</methodname>
      <methodparam><type>string</type><parameter>result_id</parameter></methodparam>
      <methodparam><type>int</type><parameter>
	<replaceable><optional>whence</optional></replaceable>
       </parameter></methodparam>
      <methodparam><type>int</type><parameter>
	<replaceable><optional>offset</optional></replaceable>
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     取得したレコードを含む配列またはもうレコードがない場合に
     &false; を返します。
    </para>
    <para>
     結果集合のカラム数が連想配列の要素 $array["count"] で返されます。
     いくつかのカラムは空である可能性があるため、
     <function>sesam_fetch_row</function> により返された結果レコードに
     対して <function>count</function> 関数を使用することはできません。
    </para>
    <para>
     <parameter>result_id</parameter> は、
     <function>sesam_query</function> (select 型クエリのみ!)により返さ
     れた有効な結果IDです。
    </para>
    <para>
     <parameter>whence</parameter>は、"スクロール型"カーソルで取得処理
     を行うためのオプションパラメータで、次のような定義済みの定数を設
     定することが可能です。
     <table>
      <title><parameter>"whence"</parameter> パラメータで有効な値</title>
      <tgroup cols="3">
       <thead>
        <row>
	 <entry>値</entry>
	 <entry>定数</entry>
	 <entry>意味</entry>
        </row>
       </thead>
       <tbody>
        <row>
	 <entry>0</entry>
	 <entry><literal>SESAM_SEEK_NEXT</literal></entry>
	 <entry>
	  連続的に読み込む(取得後、内部デフォルト値は
	  <literal>SESAM_SEEK_NEXT</literal>に設定されます)
	 </entry>
        </row>
        <row>
	 <entry>1</entry>
	 <entry><literal>SESAM_SEEK_PRIOR</literal></entry>
	 <entry>
	  連続的に後向きに読み込む (取得後、内部デフォルト値は
	  <literal>SESAM_SEEK_PRIOR</literal>に設定されます)
	 </entry>
        </row>
        <row>
	 <entry>2</entry>
	 <entry><literal>SESAM_SEEK_FIRST</literal></entry>
	 <entry>
	  最初のレコードに移動(取得後、デフォルト値は
	  <literal>SESAM_SEEK_NEXT</literal>に設定されます)
	 </entry>
        </row>
        <row>
	 <entry>3</entry>
	 <entry><literal>SESAM_SEEK_LAST</literal></entry>
	 <entry>
	  最後のレコードに移動 (取得後、デフォルト値は
	  <literal>SESAM_SEEK_PRIOR</literal>に設定されます)
	 </entry>
        </row>
        <row>
	 <entry>4</entry>
	 <entry><literal>SESAM_SEEK_ABSOLUTE</literal></entry>
	 <entry>
	  <parameter>offset</parameter> (0が先頭。取得後、内部デフォル
	  ト値は、<literal>SESAM_SEEK_ABSOLUTE</literal> に設定して下
	  さい。内部のオフセット値は、自動的に増加します)で指定した絶
	  対レコード番号に移動します。
	 </entry>
        </row>
        <row>
	 <entry>5</entry>
	 <entry><literal>SESAM_SEEK_RELATIVE</literal></entry>
	 <entry>
	  カレントのスクロール位置に対して相対位置に移動。ただし、
	  <parameter>offset</parameter> は正または負の値を指定可能です。
	 </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
     このパラメータは、"スクロール型"カーソルでのみ有効です。
    </para>
    <para>
     "スクロール型"カーソルを使用している場合、カーソルは結果集合を自
     由に移動可能です。<parameter>whence</parameter> パラメータが省略
     された場合、スクロールの型には、グローバルなデフォルト値
     (<literal>SESAM_SEEK_NEXT</literal>に初期化されており、
     <function>sesam_seek_row</function>で設定可能です) が使用されます。
     <parameter>whence</parameter> が指定された場合、その値はグローバ
     ルデフォルト値に置換されます。
    </para>
    <para>
     <parameter>offset</parameter> は、オプションのパラメータであり、
     <parameter>whence</parameter> が
     <literal>SESAM_SEEK_RELATIVE</literal> または
     <literal>SESAM_SEEK_ABSOLUTE</literal> のどちらかである場合にのみ
     評価されます(そして必要とされます)。このパラメータは、"スクロール
     型"カーソルでのみ有効です。
    </para>
    <para>
     <function>sesam_fetch_row</function> は、指定した結果IDが指す結果
     から1件分のレコードのデータを取得します。レコードは、(
     <literal>0</literal> から <literal>$array["count"]-1</literal> を
     添字とした)配列として返されます。フィールドは空である可能性がある
     ため、PHP の <function>isset</function> 関数を使用してフィールド
     の存在を確認する必要があります。返されるフィールドの型は、そのカ
     ラムを宣言したSQL型に依存します。(適用される変換については、<link
     linkend="ref.sesam">SESAMの概要</link> を参照下さい。 
     SESAM "複数フィールド" は "インライン化" されており、連続するカラ
     ムのように処理されます。
    </para>
    <para>
     <function>sesam_fetch_row</function> を連けてコールした場合、結果
     集合の次の(スクロール属性に応じて前またはn番目の前/後)レコードま
     たはレコードがもうない場合に &false;を返します。
    </para>
    <example>
     <title>SESAM レコードを取得</title>
     <programlisting role="php">
<![CDATA[
<?php
$result = sesam_query ("SELECT * FROM phone\n".
                       "  WHERE LASTNAME='".strtoupper($name)."'\n".
                       "  ORDER BY FIRSTNAME", 1);
if (!$result) {
    ... error ...
}
// print the table in backward order
print "<TABLE BORDER>\n";
$row = sesam_fetch_row ($result, SESAM_SEEK_LAST);
while (is_array ($row)) {
    print " <TR>\n";
    for ($col = 0; $col < $row["count"]; ++$col) {
        print "  <TD>".htmlspecialchars ($row[$col])."</TD>\n";
    }
    print " </TR>\n";
    // use implied SESAM_SEEK_PRIOR
    $row = sesam_fetch_row ($result);
}
print "</TABLE>\n";
sesam_free_result ($result);
?>
]]>
     </programlisting>
    </example>
    <para>
     連想配列を返す <function>sesam_fetch_array</function>、そして、
     一度に多くのレコードを返す
     <function>sesam_fetch_result</function> も参照下さい。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.sesam-fetch-array">
   <refnamediv>
    <refname>sesam_fetch_array</refname>
    <refpurpose>連想配列としてレコードを1件取得</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>array</type><methodname>sesam_fetch_array</methodname>
      <methodparam><type>string</type><parameter>result_id</parameter></methodparam>
      <methodparam><type>int</type><parameter>
	<replaceable><optional>whence</optional></replaceable>
       </parameter></methodparam>
      <methodparam><type>int</type><parameter>
	<replaceable><optional>offset</optional></replaceable>
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     取得したレコードに対応する配列またはレコードがもうない場合には
     &false; を返します。
    </para>
    <para>
     <function>sesam_fetch_array</function> は、
     <function>sesam_fetch_row</function> の連想配列版です。データを結
     果配列の数値添字に保存する代わりに、データをフィールド名をキーと
     して連想配列に保存します。
    </para>
    <para>
     <parameter>result_id</parameter> は、
     <function>sesam_query</function> (select 型クエリのみ!)により返さ
     れた有効な結果IDです。
    </para>
    <para>
     オプションの<parameter>whence</parameter>および
     <parameter>offset</parameter>パラメータの有効な値の詳細については、
     関数<function>sesam_fetch_row</function> を参照下さい。
    </para>
    <para>
     <function>sesam_fetch_array</function> は、
     指定した結果IDが指す結果から1件分のレコードを取得します。レコード
     は、連想配列として返されます。各結果カラムは、そのカラム(または
     フィールド)名に等しい連想配列の要素に保存されます。カラム名は、小
     文字に変換されます。
    </para>
    <para>
     フィールド名がないカラム(例えば、数値演算の結果)および空のフィー
     ルドは、配列に保存されません。また、2つ以上の結果がカラム名に同じ
     カラム名がある場合、最後のカラムが優先されます。この場合、
     <function>sesam_fetch_row</function>をコールするかそのカラムへの
     エイリアスを作成して下さい。
     <informalexample>
      <programlisting role="sesam">
<![CDATA[
SELECT TBL1.COL AS FOO, TBL2.COL AS BAR FROM TBL1, TBL2
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
     特別な処理により"複数フィールド"カラム(もしくは同じカラム名を有す
     るカラム)を取得することが可能になります。"複数フィールド"の各カラ
     ムに関して、添字名は、文字列"(n)"を付加することにより構築されます。
     ただし、n は複数フィールドのカラムの副添字であり、1から宣言済みの
     反復数までの範囲となります。クエリ構文で使用される表記に一致させ
     るために添字はゼロを基準にしていません。
     次のように宣言されているあるカラムの場合、
     <informalexample>
      <programlisting role="sesam">
<![CDATA[
CREATE TABLE ... ( ... MULTI(3) INT )
]]>
      </programlisting>
     </informalexample>
     個々の"複数フィールド"カラムに関して連想添字は、それぞれ
     <literal>"multi(1)"</literal>,<literal>"multi(2)"</literal>, 
     <literal>"multi(3)"</literal> になります。
    </para>
    <para>
     <function>sesam_fetch_array</function> を続けてコールした場合、結
     果集合の次の(スクロール属性に応じて前またはn番目の前/後)レコードま
     たはレコードがもうない場合に &false;を返します。
    </para>
    <example>
     <title>SESAM 取得配列</title>
     <programlisting role="php">
<![CDATA[
<?php
$result = sesam_query ("SELECT * FROM phone\n".
                       "  WHERE LASTNAME='".strtoupper($name)."'\n".
                       "  ORDER BY FIRSTNAME", 1);
if (!$result) {
    ... error ...
}
// print the table:
print "<TABLE BORDER>\n";
while (($row = sesam_fetch_array ($result)) && count ($row) > 0) {
    print " <TR>\n";
    print " <TD>".htmlspecialchars ($row["firstname"])."</TD>\n";
    print " <TD>".htmlspecialchars ($row["lastname"])."</TD>\n";
    print " <TD>".htmlspecialchars ($row["phoneno"])."</TD>\n";
    print " </TR>\n";
}
print "</TABLE>\n";
sesam_free_result ($result);
?>
]]>
     </programlisting>
    </example>
    <para>
     添字配列を返す <function>sesam_fetch_row</function> も参照下さい。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.sesam-seek-row">
   <refnamediv>
    <refname>sesam_seek_row</refname>
    <refpurpose>
     連続的に取得する際にスクロール可能なカーソルモードに設定する
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>bool</type><methodname>sesam_seek_row</methodname>
      <methodparam><type>string</type><parameter>result_id</parameter></methodparam>
      <methodparam><type>int</type><parameter>whence</parameter></methodparam>
      <methodparam><type>int</type><parameter>
	<replaceable><optional>offset</optional></replaceable>
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     <parameter>result_id</parameter> は有効な結果IDです。(select
     型のクエリで、かつ、<function>sesam_query</function>をコール
     した際に"スクロール可能な"カーソルが要求された場合のみ)
    </para>
    <para>
     <parameter>whence</parameter> は、この後の"スクロール型"カーソル
     の取得処理で使用されるスクロールの型を指定するスクロール型のグロー
     バルなデフォルト値を設定し、次のような定義済みの定数を設定します。
     <table>
      <title><parameter>"whence"</parameter> パラメータの有効な値</title>
      <tgroup cols="3">
       <thead>
        <row>
	 <entry>値</entry>
	 <entry>定数</entry>
	 <entry>意味</entry>
        </row>
       </thead>
       <tbody>
        <row>
	 <entry>0</entry>
	 <entry><literal>SESAM_SEEK_NEXT</literal></entry>
	 <entry>
	  連続的に読み込む
	 </entry>
        </row>
        <row>
	 <entry>1</entry>
	 <entry><literal>SESAM_SEEK_PRIOR</literal></entry>
	 <entry>
	  連続的に後向きに読む
	 </entry>
        </row>
        <row>
	 <entry>1</entry>
	 <entry><literal>SESAM_SEEK_PRIOR</literal></entry>
	 <entry>
	  連続的に後向きに読み込む (取得後、内部デフォルト値は
	  <literal>SESAM_SEEK_PRIOR</literal>に設定されます)
	 </entry>
        </row>
        <row>
	 <entry>2</entry>
	 <entry><literal>SESAM_SEEK_FIRST</literal></entry>
	 <entry>
	  最初のレコードに移動(取得後、デフォルト値は
	  <literal>SESAM_SEEK_NEXT</literal>に設定されます)
	 </entry>
        </row>
        <row>
	 <entry>3</entry>
	 <entry><literal>SESAM_SEEK_LAST</literal></entry>
	 <entry>
	  最後のレコードに移動 (取得後、デフォルト値は
	  <literal>SESAM_SEEK_PRIOR</literal>に設定されます)
	 </entry>
        </row>
        <row>
	 <entry>4</entry>
	 <entry><literal>SESAM_SEEK_ABSOLUTE</literal></entry>
	 <entry>
	  <parameter>offset</parameter> (0が先頭。取得後、内部デフォル
	  ト値は、<literal>SESAM_SEEK_ABSOLUTE</literal> に設定して下
	  さい。内部のオフセット値は、自動的に増加します)で指定した絶
	  対レコード番号に移動します。
	 </entry>
        </row>
        <row>
	 <entry>5</entry>
	 <entry><literal>SESAM_SEEK_RELATIVE</literal></entry>
	 <entry>
	  カレントのスクロール位置に対して相対位置に移動。ただし、
	  <parameter>offset</parameter> は正または負の値を指定可能です。
	 </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>
    <para>
     <parameter>offset</parameter>は、オプションのパラメータであり、
     <parameter>whence</parameter>が
     <literal>SESAM_SEEK_RELATIVE</literal>または
     <literal>SESAM_SEEK_ABSOLUTE</literal> のどちらかである場合にのみ
     評価されます(また必要とされます)。
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="function.sesam-free-result">
   <refnamediv>
    <refname>sesam_free_result</refname>
    <refpurpose>クエリに関するリソースを開放する</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>sesam_free_result</methodname>
      <methodparam><type>string</type><parameter>result_id</parameter></methodparam>
     </methodsynopsis>
    <para>
     <parameter>result_id</parameter> が指すクエリに関するリソースを開
     放します。エラーの場合に &false; を返します。
    </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:
-->