<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.12 $ -->
 <reference id="ref.yaz">
  <title>YAZ 関数</title>
  <titleabbrev>YAZ</titleabbrev>
  
  <partintro>
   <sect1 id="yaz.intro">
    <title>導入</title>
    <para>
     この拡張モジュールは、情報取得用のZ39.50プロトコルを実装する
     <productname>YAZ</productname>ツールキットへのPHPインターフェース
     を提供するものです。この拡張モジュールにより、Z39.50ターゲット(サー
     バー)を並列に検索またはスキャンするZ39.50オリジン(クライアント)を
     容易に実装することが可能になります。
    </para>
    <para>
     <productname>YAZ</productname> は、<ulink
     url="&url.yaz;">&url.yaz;</ulink>で取得可能です。この拡張モジュー
     ルに関する新しい情報、スクリプトの例等を
     <ulink url="&url.yaz-phpyaz;">&url.yaz-phpyaz;</ulink>にて
     参照可能です。
    </para>
    <para>
     このモジュールはZ39.50 の複雑さを隠蔽するため、使用法がかなり容
     易になります。PHPで利用可能な様々なSQL APIにより提供されているも
     のに非常によく似たステートレスな持続的接続がサポートされています。
     これにより、セッションはステートレスですが、ユーザ間で共有され、
     これにより多くの場合に接続および初期化手順が保存されます。
    </para>
   </sect1>

   <sect1 id="yaz.install">
   <title>インストール</title>
    <para>
     YAZをコンパイルし、インストールして下さい。PHPをオプション
     <literal>--with-yaz</literal>を付けて他の任意のモジュールと
     コンパイルして下さい。この手順の概要を以下に示します。
    </para>
    <para>
     <informalexample>
    <programlisting role="shell">
<![CDATA[
gunzip -c yaz-1.6.tar.gz|tar xf -
gunzip -c php-4.0.X.tar.gz|tar xf -
cd yaz-1.6
./configure --prefix=/usr
make
make install
cd ../php-4.0.X
./configure --with-yaz=/usr/bin
make
make install
]]>
      </programlisting>
     </informalexample>
    </para>
   </sect1>

   <sect1 id="yaz.example">
    <title>Example</title>
    <para>
     PHP/YAZ はターゲット(Z-Associations)との接続を保持し続けます。
     正の整数で特定の接続のIDを表します。
    </para>
    <para>
     以下のスクリプトは、APIのパラレルサーチ機能のデモです。
     このスクリプトは起動された際に(引数が指定されない場合は)クエリフォー
     ムを表示し、引数(termおよび一つ以上のhost)がある場合には、配列host
     にあるターゲットを検索します。
    </para>
    <para>
     <example>
      <title>YAZによる並列検索</title>
      <simpara>
       以下のスクリプトは、APIの並列検索機能のデモです。引数を指定せず
       にコールした場合、この関数は、クエリフォームを出力します。そう
       でない場合(引数を指定した場合)は、配列hostにあるターゲットを検
       索します。
      </simpara>
      <programlisting role="php">
<![CDATA[
$num_hosts = count ($host);
if (empty($term) || count($host) == 0) {
    echo '<form method="get">
    <input type="checkbox"
    name="host[]" value="bagel.indexdata.dk/gils">
        GILS test
    <input type="checkbox"
    name="host[]" value="localhost:9999/Default">
        local test
    <input type="checkbox" checked="1"
    name="host[]" value="z3950.bell-labs.com/books">
        BELL Labs Library
    <br>
    RPN Query:
    <input type="text" size="30" name="term">
    <input type="submit" name="action" value="Search">
    ';        
} else {
    echo 'You searced for ' . htmlspecialchars($term) . '<br>';
    for ($i = 0; $i < $num_hosts; $i++) {
        $id[] = yaz_connect($host[$i]);
        yaz_syntax($id[$i],"sutrs");
        yaz_search($id[$i],"rpn",$term);
    }
    yaz_wait();
    for ($i = 0; $i < $num_hosts; $i++) {
        echo '<hr>' . $host[$i] . ":";
        $error = yaz_error($id[$i]);
        if (!empty($error)) {
            echo "Error: $error";
        } else {
            $hits = yaz_hits($id[$i]);
            echo "Result Count $hits";
        }
        echo '<dl>';
        for ($p = 1; $p <= 10; $p++) {
            $rec = yaz_record($id[$i],$p,"string");
            if (empty($rec)) continue;
            echo "<dt><b>$p</b></dt><dd>";
            echo ereg_replace("\n", "<br>\n",$rec);
            echo "</dd>";
        }
        echo '</dl>';
    }
}
]]>
      </programlisting>
     </example>
    </para>
   </sect1>
  </partintro>

  <refentry id="function.yaz-addinfo">
   <refnamediv>
    <refname>yaz_addinfo</refname>
    <refpurpose>詳細なエラー情報を返す</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_addinfo</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
     </methodsynopsis>
    <para>
     (直近のリクエストの)ターゲットに関する詳細なエラーメッセージを返
     します。直近の処理が成功したかターゲットにより詳細な情報が提供さ
     れていない場合には、空の文字列が返されます。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-close">
   <refnamediv>
    <refname>yaz_close</refname>
    <refpurpose>YAZ接続をクローズする</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_close</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
     </methodsynopsis>
    <para>
     <parameter>id</parameter>で指定したZ接続(Z-association)をクローズ
     します。<parameter>id</parameter> は、コマンド
     <function>yaz_connect</function> の返り値であるターゲットIDです。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-connect">
   <refnamediv>
    <refname>yaz_connect</refname>
    <refpurpose>
     ターゲットへの接続およびZ接続を準備する。
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_connect</methodname>
      <methodparam><type>string</type><parameter>zurl</parameter></methodparam>
      <methodparam choice="opt"><type>mixed</type><parameter>options</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>yaz_connect</function> は、Z39.50 ターゲットへの接続を
     準備します。引数 zurl はhost[:port][/database]という形式です。
     port が省略された場合、210が使用されます。databaseが省略された場
     合 Default が使用されます。この関数は、非ブロックモードで動作し、
     ソケットを作成しようとしません。単に後で
     <function>yaz_wait</function>がコールされた際に接続を実行する準備
     を行うだけです。
    </para>
    <para>
     2番目の引数、<parameter>options</parameter>に文字列が指定された場合、
     Z39.50 V2認証文字列(OpenAuth)として処理されます。
    </para>
    <para>
     <parameter>options</parameter> に配列が指定された場合、その配列の内
     容はオプションとして処理されます。配列オプションは、PHP 4.1.0以降
     でのみサポートされることに注意して下さい。

     <variablelist>
      <title><function>yaz_connect</function> オプション</title>
      <varlistentry><term>user</term><listitem>
	<simpara>認証用のユーザ名
	</simpara></listitem>
      </varlistentry>
      <varlistentry><term>group</term><listitem>
	<simpara>認証用のグループ
	</simpara></listitem>
      </varlistentry>
      <varlistentry><term>password</term><listitem>
	<simpara>認証用のパスワード
	</simpara></listitem>
      </varlistentry>
      <varlistentry><term>cookie</term><listitem>
	<simpara>セッションクッキー (YAZ proxy).
	</simpara></listitem>
      </varlistentry>
      <varlistentry><term>proxy</term><listitem>
	<simpara>接続用プロキシ (YAZ proxy).
	</simpara></listitem>
      </varlistentry>
      <varlistentry><term>persistent</term><listitem>
	<simpara>
	 論理値。&true; の場合、接続は持続的となります。&false; の
	 場合、接続は持続的ではありません。デフォルトで、接続は
	 持続的です。
	</simpara>
       </listitem>
      </varlistentry>
      <varlistentry><term>piggyback</term><listitem>
	<simpara>
	 論理値。&true; の場合、検索時のpiggybackが有効になります。
	 &false; の場合、piggybackが無効になります。デフォルトでは、
	 piggyback は有効です。piggybackを有効にするとより効率的となり、
	 通常、レコードを最初に取得する際のネットワーク往復時間を節約
	 することが可能です。しかし、少数の Z39.50ターゲットは
	 piggybackをサポートしていないか、エレメント集合名を無視します。
	 この場合、piggybackを無効とする必要があります。
	</simpara>
       </listitem>
      </varlistentry>
     </variablelist>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-errno">
   <refnamediv>
    <refname>yaz_errno</refname>
    <refpurpose>エラー番号を返す</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_errno</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
     </methodsynopsis>
    <para>
     (直近のリクエストの)ターゲットのエラーを返します。ターゲットが原
     因コードを返した場合には、正の値が返されます。エラーが発生してい
     ない場合(成功時)は値ゼロが返されます。ターゲットが問題のあるエラー
     ではないと判定したその他のエラーの場合は、負の値が返されます。
    </para>
    <para>
     <function>yaz_errno</function> は、各ターゲットへのネットワーク接
     続が確立された後(つまり、<function>yaz_wait</function>の後)に
     コールされる必要があり、直近の操作(例えば検索)が成功したか失敗し
     たかを判定します。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-error">
   <refnamediv>
    <refname>yaz_error</refname>
    <refpurpose>エラーの内容を返す</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_error</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
     </methodsynopsis>
    <para>
     (直近のリクエストの)ターゲットに関するエラーメッセージを返します。
     直近の操作が成功した場合には空の文字列が返されます。
    </para>
    <para>
     <function>yaz_error</function> は、<function>yaz_errno</function>
     で返された直近のエラー番号に対応する英語のメッセージを返します。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-hits">
   <refnamediv>
    <refname>yaz_hits</refname>
    <refpurpose>直近の検索に関するヒット数を返す</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_hits</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>yaz_hits</function> は、直近の検索に関するヒット数を返
     します。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-element">
   <refnamediv>
    <refname>yaz_element</refname>
    <refpurpose>
     取得時に要素集合の名前を指定する
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_element</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
      <methodparam><type>string</type><parameter>elementset</parameter></methodparam>
     </methodsynopsis>
    <para>
     この関数は、<function>yaz_search</function> および
     <function>yaz_present</function>と共に使用され、取得するレコード
     の要素集合の名前を指定します。多くのサーバは、
     <literal>F</literal> (完全版)および<literal>B</literal> (短縮版)
     の名前をサポートします。
    </para>
    <para>
     成功時に&true;、エラー時に&false;を返します。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-database">
   <refnamediv>
    <refname>yaz_database</refname>
    <refpurpose>
     セッション内のデータベースを指定する
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_database</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
      <methodparam><type>string</type><parameter>databases</parameter></methodparam>
     </methodsynopsis>
    <para>
     この関数は、検索、取得等で使用する１つまたは複数のデータベースを
     指定します。<function>yaz_connect</function>をコールする際に指定
     したデータベースを上書きします。複数のデータベースは、可算記号
     <literal>+</literal>で区切ります。
    </para>
    <para>
     この関数は、あるセッションの中で異なるデータベースの集合を使用す
     ることを可能にします。
    </para>
    <para>
     成功時に&true;、エラー時に&false;を返します。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-range">
   <refnamediv>
    <refname>yaz_range</refname>
    <refpurpose>
     取得するレコードの最大数を指定する
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_range</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
      <methodparam><type>int</type><parameter>start</parameter></methodparam>
      <methodparam><type>int</type><parameter>number</parameter></methodparam>
     </methodsynopsis>
    <para>
     この関数は、<function>yaz_search</function>と共に使用され、取得す
     るレコードの最大数と、最初のレコードの位置(start)を指定します。
     この関数を使用しない場合(<function>yaz_search</function>のみの場
     合)、startは1に、numberは10に設定されます。
    </para>
    <para>
     成功時に&true;、エラー時に&false;を返します。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-record">
   <refnamediv>
    <refname>yaz_record</refname>
    <refpurpose>レコードを返す</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_record</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
      <methodparam><type>int</type><parameter>pos</parameter></methodparam>
      <methodparam><type>string</type><parameter>type</parameter></methodparam>
     </methodsynopsis>
    <para>
     指定した位置のレコードまたはレコードが指定位置に存在しない場合に
     空の文字列を返します。
    </para>
    <para>
     <function>yaz_record</function> 関数は、カレントの結果セット指定
     した位置にあるレコードを調べます。指定した位置にデータベースレコー
     ドが存在しない場合には、空の文字列が返されます。引数 type は返さ
     れるレコードの形式を指定します。
     type が "string" の場合、(XMLおよびSUTRS用に)出力可能な文字列表現
     でレコードが返されます。typeが"array"の場合、(構造化されたレコー
     ド用に)配列表現でレコードが返されます。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-search">
   <refnamediv>
    <refname>yaz_search</refname>
    <refpurpose>検索を準備する</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_search</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
      <methodparam><type>string</type><parameter>type</parameter></methodparam>
      <methodparam><type>string</type><parameter>query</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>yaz_search</function> は、指定したidを有するターゲット
     で検索を行う準備をします。type は、クエリの型を表します。現在、
     "rpn" のみがサポートされており、この場合、3番目の引数はType-1クエ
     リ(RPN)を指定します。<function>yaz_connect</function> と同じく、
     この関数は、非ブロックモードで動作し、後で
     <function>yaz_wait</function> がコールされた際に実行される検索の
     準備をするだけです。
    </para>
   </refsect1>
   <refsect1>
    <title>RPNクエリ</title>
    <para>
     RPNクエリは、Z39.50規格により定義されたType-1 クエリのテキスト表
     現です。しかし、YAZにより使用されるテキスト表現では、演算子がオペ
     ランドの前にある前置表記が使用されます。クエリ文字列はトークンの
     並びであり、このトークンでは2重引用符で括られない限り空白文字は無
     視されます。トークンは、アットマーク(<literal>@</literal>)で始ま
     り、演算子とみなされるか、そうでない場合は検索項目として処理され
     ます。
    </para>
    <table>
     <title>RPN 演算子</title>
     <tgroup cols="2">
      <thead>
       <row>
	<entry>構文</entry>
	<entry>説明</entry>
       </row>
      </thead>
      <tbody>
       <row>
	<entry><literal>@and query1 query2</literal></entry>
	<entry>
	 query1 および query2の積集合
	</entry>
       </row>
       <row>
	<entry><literal>@or query1 query2</literal></entry>
	<entry>
	 query1 および query2の和集合
	</entry>
       </row>
       <row>
	<entry><literal>@not query1 query2</literal></entry>
	<entry>
	 query1 であり、query2でない
	</entry>
       </row>
       <row>
	<entry><literal>@set name</literal></entry>
	<entry>
	 結果セットへのリファレンス
	</entry>
       </row>
       <row>
	<entry><literal>@attrset set query</literal></entry>
	<entry>
	 クエリの属性セットを指定します。この構造が使用できるの
         は全てのクエリの始めに一回だけです。
	</entry>
        </row>
        <row>
	<entry><literal>@attr set type=value query</literal></entry>
	<entry>
	 クエリに属性を適用します。型と値は属性型と属性値をそれぞれ指
	 定する整数です。この組みが指定された場合、属性の組を指定しま
	 す。
	</entry>
        </row>
      </tbody>
     </tgroup>
    </table> 
    <example>
     <title>クエリの例</title>
     <para>
      クエリ
      <screen>computer</screen>
      は、"computer"を含む文書にマッチします。属性は指定されていません。
     </para>
     <para>
      クエリ
      <screen>"donald knuth"</screen>
      は、"donald knuth" がある文書にマッチします。
     </para>
     <para>
      クエリ
      <screen>@attr 1=4 art</screen>の場合、
      属性型は1 (Bib-1 use)、属性の値は4 (Title)となります。このため、
      titleに<literal>art</literal>が現れる文書にマッチします。
     </para>
     <para>
      その他のより複雑なクエリの例:
      <screen>@attrset gils @and @attr 1=4 art @attr 1=1003 "donald knuth"</screen>
      このクエリは、GILS属性集合を使用しています。クエリはtitleに
      <literal>art</literal>が現れ、authorに<literal>donald knuth</literal>
      が現れる文書にマッチします。
     </para>
    </example>
   </refsect1>
  </refentry>
  
  <refentry id="function.yaz-present">
   <refnamediv>
    <refname>yaz_present</refname>
    <refpurpose>
     (Z39.50による)取得の準備を行う
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_present</methodname>
      <void/>
     </methodsynopsis>
    <para>
     この関数は、検索に成功した後、レコードを取得するための準備を行い
     ます。この関数をコールする前に取得するレコードの範囲を指定するた
     めに<function>yaz_range</function>をコールしておく必要があります。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-syntax">
   <refnamediv>
    <refname>yaz_syntax</refname>
    <refpurpose>
     取得用に適当なレコード構文を指定する
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_syntax</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
      <methodparam><type>string</type><parameter>syntax</parameter></methodparam>
     </methodsynopsis>
    <para>
     syntaxには、(<literal>1.2.840.10003.5.10</literal>のような)ドット
     表記のOIDまたは既知の登録されたレコード構文の一つ(sutrs, usmarc,
     grs1, xml,等)を指定します。この関数は
     <function>yaz_search</function> および
     <function>yaz_present</function>と共に使用され、取得時のレコード
     構文を指定します。
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-scan">
   <refnamediv>
    <refname>yaz_scan</refname>
    <refpurpose>スキャンの準備をする</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_scan</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
      <methodparam><type>string</type><parameter>type</parameter></methodparam>
      <methodparam><type>string</type><parameter>startterm</parameter></methodparam>
      <methodparam choice="opt"><type>array</type><parameter>flags</parameter></methodparam>
     </methodsynopsis>
    <para>
     この関数は、Z39.50スキャンリクエストの準備をします。引数
     <parameter>id</parameter> はターゲットIDです。スキャンを開始する
     言葉の場所は、<parameter>startterm</parameter>で指定します。
     開始語を指定する形式は、<parameter>type</parameter>で指定します。
     現在、<literal>rpn</literal>型がサポートされています。
     オプションの<parameter>flags</parameter>によりスキャンリクエスト
     の動作を制御する追加情報を指定します。現在、次の3つの添字が、現在、
     flagsから読み込まれます。
     <literal>number</literal> (リクエストされた語の数)、
     <literal>position</literal> (要求された語の位置)、
     <literal>stepSize</literal> (要求されたステップ数)。
     実際にスキャンリクエストをターゲットに送信し、スキャンレスポンス
     を受信する際には、<function>yaz_wait</function>をコールする必要が
     あります。<function>yaz_wait</function>が完了した後、応答を処理す
     るために、<function>yaz_error</function> および
     <function>yaz_scan_result</function>をコールします。
    </para>
    <para>
     <parameter>startterm</parameter>の構文は、
     <function>yaz_search</function>で説明いたRPNクエリに似ています。
     starttermは、ゼロ以上の<literal>@attr</literal>演算子の後にトーク
     ンが一つだけ続く形式となります。
    </para>
    <para>
    <example>
    <title>タイトルをスキャンするPHP関数</title>
    <programlisting>
<![CDATA[
      function scan_titles($id, $starterm) {
        yaz_scan($id,"rpn", "@attr 1=4 " . $starterm);
        yaz_wait();
        $errno = yaz_errno($id);
        if ($errno == 0) {
          $ar = yaz_scan_result($id,&$options);
          echo 'Scan ok; ';
          $ar = yaz_scan_result($id, &$options);
          while(list($key,$val)=each($options)) {
             echo "$key = $val &nbsp;";
          }
          echo '<br><table><tr><td>';
          while(list($key,list($k, $term, $tcount))=each($ar)) {
            if (empty($k)) continue;
            echo "<tr><td>$term</td><td>";
            echo $tcount;
            echo "</td></tr>";
          }
          echo '</table>';
        } else {
          echo "Scan failed. Error: " . yaz_error($id) . "<br>";
        }
      }
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>
 
  <refentry id="function.yaz-scan-result">
   <refnamediv>
    <refname>yaz_scan_result</refname>
    <refpurpose>スキャンリクエストの結果を返す</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>array</type><methodname>yaz_scan_result</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
      <methodparam choice="opt"><type>array &amp;</type><parameter>result</parameter></methodparam>
     </methodsynopsis>
    <para>
     ターゲットIDを指定するすると、この関数は直近のスキャン時のレスポ
     ンスとしてターゲットから受信した項目を配列として返します。この関
     数は、配列(0..n-1)を返します。ただし、nは返された項目の数です。各
     値は、最初の値が項目で、2番目の値が結果の数という組になっています。
     <parameter>result</parameter>が指定された場合、この変数にはスキャ
     ン時の応答からとりこまれた次のような追加情報が代入されます。
     <literal>number</literal> (返されたエントリの数),
     <literal>stepsize</literal> (ステップサイズ),
     <literal>position</literal> (項目の位置),
     <literal>status</literal> (スキャンステータス)
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-ccl-conf">
   <refnamediv>
    <refname>yaz_ccl_conf</refname>
    <refpurpose>CCLパーサを設定する</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_ccl_conf</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
      <methodparam><type>array</type><parameter>config</parameter></methodparam>
     </methodsynopsis>
    <para>
     この関数は、アクセスポイント(CCL限定辞)が定義するターゲットに関し
     てCCLクエリパーサとRPNへのマッピングを設定します。特定のCCLクエリ
     を後でRPNにマップするには、<function>yaz_ccl_parse</function>関数
     をコールして下さい。配列<parameter>config</parameter>の各添字は、
     CCLフィールドの名前であり、対応する値はRPNへのマッピングを指定す
     る文字列を保持します。マッピングは属性型および属性値の組が並んだ
     ものです。属性型と属性値は、等号 (<literal>=</literal>)で区切られ
     ます。各組は、空白で区切られます。
    </para>
    <para>
     <example>
      <title>CCL 設定</title>
      <simpara>
       以下の例では、CCLパーサは<literal>ti</literal>、
       <literal>au</literal>、<literal>isbn</literal>という3つのCCLフィー
       ルドをサポートするように設定されます。各フィールドは、等価な
       BIB-1へマップされます。 この例では、<literal>$id</literal>がター
       ゲットIDであることを仮定しています。
      </simpara>
      <programlisting>
<![CDATA[
      $field["ti"] = "1=4";
      $field["au"] = "1=1";
      $field["isbn"] = "1=7";
      yaz_ccl_conf($id,$field);
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="function.yaz-ccl-parse">
   <refnamediv>
    <refname>yaz_ccl_parse</refname>
    <refpurpose>CCLパーサを起動する</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_ccl_parse</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
      <methodparam><type>string</type><parameter>query</parameter></methodparam>
      <methodparam><type>array &amp;</type><parameter>result</parameter></methodparam>
     </methodsynopsis>
    <para>
     この関数は、CCLパーサを起動します。パーサは、指定したCCL FINDクエ
     リを検索を実行する<function>yaz_search</function>関数に指定可能な
     RPNクエリに変換します。有効なCCLフィールドの組を定義するには、こ
     の関数の前に<function>yaz_ccl_conf</function>をコールします。指定
     した<parameter>query</parameter>のRPNへの変換が成功した場合、この
     関数は&true;を返し、指定した配列<parameter>result</parameter>の添字
     <literal>rpn</literal>は、有効なRPNクエリを保持します。(構文が無
     効であったり、存在しないフィールドである等の理由により、)クエリが
     変換できなかった場合、この関数は&false;を返し、失敗の原因を示すため
     に返される配列に次のような3つの添字が設定されます。
     <literal>errorcode</literal>CCL エラーコード (整数)、
     <literal>errorstring</literal>CCLエラー文字列、
     <literal>errorpos</literal> エラーを発生したクエリのおおよその位
     置(整数は文字の位置を整数で表したもの)
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-itemorder">
   <refnamediv>
    <refname>yaz_itemorder</refname>
    <refpurpose>
     ILLリクエストパッケージを関してZ39.50 Item Orderを準備する
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_itemorder</methodname>
      <methodparam><type>array</type><parameter>args</parameter></methodparam>
     </methodsynopsis>
    <para>
     この関数は、Transport ILL (Profile/1)へのZ39.50 Item Order
     Extended Service用のプロファイルを使用するExtended Servicesリクエ
     ストを準備します。
     <ulink url="http://www.nlc-bnc.ca/iso/ill/stanprf.htm">このページ
     </ulink>および
     <ulink url="http://www.nlc-bnc.ca/iso/ill/document/standard/z-ill-1a.pdf">
     仕様</ulink>を参照下さい。パラメータargsは、送信するItem Orderリ
     クエストに関する情報を有するハッシュ配列とする必要があります。こ
     のハッシュ配列のキーは、対応するASN.1タグのパス名です。例えば、
     Item-ID以下にISBNがある場合のキーはitem-id,ISBNとなります。
    </para>
    <para>
     ILL-Request パラメータは次のようになります。
    </para>
    <literallayout>
protocol-version-num
transaction-id,initial-requester-id,person-or-institution-symbol,person
transaction-id,initial-requester-id,person-or-institution-symbol,institution
transaction-id,initial-requester-id,name-of-person-or-institution,name-of-person
transaction-id,initial-requester-id,name-of-person-or-institution,name-of-institution
transaction-id,transaction-group-qualifier
transaction-id,transaction-qualifier
transaction-id,sub-transaction-qualifier
service-date-time,this,date
service-date-time,this,time
service-date-time,original,date
service-date-time,original,time
requester-id,person-or-institution-symbol,person
requester-id,person-or-institution-symbol,institution
requester-id,name-of-person-or-institution,name-of-person
requester-id,name-of-person-or-institution,name-of-institution
responder-id,person-or-institution-symbol,person
responder-id,person-or-institution-symbol,institution
responder-id,name-of-person-or-institution,name-of-person
responder-id,name-of-person-or-institution,name-of-institution
transaction-type
delivery-address,postal-address,name-of-person-or-institution,name-of-person
delivery-address,postal-address,name-of-person-or-institution,name-of-institution
delivery-address,postal-address,extended-postal-delivery-address
delivery-address,postal-address,street-and-number
delivery-address,postal-address,post-office-box
delivery-address,postal-address,city
delivery-address,postal-address,region
delivery-address,postal-address,country
delivery-address,postal-address,postal-code
delivery-address,electronic-address,telecom-service-identifier
delivery-address,electronic-address,telecom-service-addreess
billing-address,postal-address,name-of-person-or-institution,name-of-person
billing-address,postal-address,name-of-person-or-institution,name-of-institution
billing-address,postal-address,extended-postal-delivery-address
billing-address,postal-address,street-and-number
billing-address,postal-address,post-office-box
billing-address,postal-address,city
billing-address,postal-address,region
billing-address,postal-address,country
billing-address,postal-address,postal-code
billing-address,electronic-address,telecom-service-identifier
billing-address,electronic-address,telecom-service-addreess
ill-service-type
requester-optional-messages,can-send-RECEIVED
requester-optional-messages,can-send-RETURNED
requester-optional-messages,requester-SHIPPED
requester-optional-messages,requester-CHECKED-IN
search-type,level-of-service
search-type,need-before-date
search-type,expiry-date
search-type,expiry-flag
place-on-hold
client-id,client-name
client-id,client-status
client-id,client-identifier
item-id,item-type
item-id,call-number
item-id,author
item-id,title
item-id,sub-title
item-id,sponsoring-body
item-id,place-of-publication
item-id,publisher
item-id,series-title-number
item-id,volume-issue
item-id,edition
item-id,publication-date
item-id,publication-date-of-component
item-id,author-of-article
item-id,title-of-article
item-id,pagination
item-id,ISBN
item-id,ISSN
item-id,additional-no-letters
item-id,verification-reference-source
copyright-complicance
retry-flag
forward-flag
requester-note
forward-note
    </literallayout>
    <para>
     Extended Services RequestパッケージおよびItemOrderパッケージにも
    次のような小数のパラメータがあります。
    </para>
    <literallayout>
package-name
user-id
contact-name
contact-phone
contact-email
itemorder-item
    </literallayout>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-wait">
   <refnamediv>
    <refname>yaz_wait</refname>
    <refpurpose>Z39.50リクエストが完了するまで待つ</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_wait</methodname>
      <methodparam choice="opt"><type></type><parameter>array options</parameter></methodparam>
     </methodsynopsis>
    <para>
     この関数は、関数<function>yaz_connect</function>、
     <function>yaz_search</function>、<function>yaz_present</function>,
     <function>yaz_scan</function>、<function>yaz_itemorder</function>
     により準備された発行済のリクエストをネットワーク経由で(ブロックモー
     ドで)伝送します。<function>yaz_wait</function>は、全てのターゲッ
     トが全てのリクエストを完了したか、(エラーの場合には)中断された場
     合に処理を戻します。
    </para>
    <para>
     配列 <parameter>options</parameter> が指定された場合、
     <function>yaz_wait</function>の動作を変更するオプションとなります。
    </para>
    <variablelist>
     <varlistentry><term><literal>timeout</literal></term>
      <listitem>
       <para>
	時間のタイムアウトを設定します。ターゲットが時間内に応答しなかっ
	た場合、動作していないとみなされ、<function>yaz_wait</function>
	は帰ります。タイムアウトのデフォルト値は15sです。
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-sort">
   <refnamediv>
    <refname>yaz_sort</refname>
    <refpurpose>ソートの基準を設定する</refpurpose>
   </refnamediv>
   <refsect1>
    <title>説明</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_sort</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
      <methodparam><type>string</type><parameter>criteria</parameter></methodparam>
     </methodsynopsis>
    <para>
     この関数は、ソートの基準を設定し、Z39.50 Sortを有効にします。
     この関数は、<function>yaz_search</function>または
     <function>yaz_present</function>と共に使用して下さい。この関数の
     みを使用しても何も意味はありません。
     <function>yaz_search</function>と組み合わせて使用した場合、
     検索応答が受信され、全てのZ39.50 Presentで取得される前にZ39.50
     Sortが送信されます。
    </para>
    <para>
      <replaceable>field1 flags1 field2 flags2</replaceable> ...
    </para>
    <para>
     ただし、field1は最初の属性でのソートを指定し、2番目にfield2といっ
     たように指定します。フィールドは、カンマで区切られた 型=値 の組か
     らなる数値属性の組み合わせ(例 <literal>1=4,2=1</literal>)、または、
     文字列の方法を指定することも可能です。
     (例 <literal>title</literal>) 
     フラグは、次の文字の並びからなり、空白により区切ることはありません。
    </para>
    <variablelist>
      <title>ソートフラグ</title>
      <varlistentry><term><literal>a</literal></term><listitem>
       <simpara>昇順ソート</simpara></listitem>
      </varlistentry>
      <varlistentry><term><literal>d</literal></term><listitem>
       <simpara>降順ソート</simpara></listitem>
      </varlistentry>
      <varlistentry><term><literal>i</literal></term><listitem>
       <simpara>大文字小文字を区別しないソート</simpara></listitem>
      </varlistentry>
      <varlistentry><term><literal>s</literal></term><listitem>
       <simpara>文字小文字を区別するソート</simpara></listitem>
      </varlistentry>
    </variablelist>
    <example>
    <title>ソート方法</title>
    <para>
      Bib1属性タイトルで大文字小文字を区別しない昇順のソートを行うには、
      以下のソート方法を使用して下さい。
      <screen>
       1=4 ia
      </screen>
     </para>
     <para>
      2番目のソート方法をauthorとし、大文字小文字を区別する昇順のソー
      トを行うには、以下のようにします。
      <screen>
       1=4 ia 1=1003 sa
      </screen>
     </para>
    </example>
   </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:
-->