<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.24 $ -->
 <reference id="ref.yaz">
  <title>YAZ functions</title>
  <titleabbrev>YAZ</titleabbrev>
  <partintro>
   <sect1 id="yaz.intro">
   <title>Introduction</title>
   <para>
    This extension offers a PHP interface to the
    <productname>YAZ</productname> toolkit that implements the Z39.50
    protocol for information retrieval. With this extension you can easily
    implement a Z39.50 origin (client) that searches or scans Z39.50
    targets (servers) in parallel.
   </para>
   <para>
    <productname>YAZ</productname> is available at <ulink
    url="&url.yaz;">&url.yaz;</ulink>. You can find news information,
    example scripts, etc. for this extension at <ulink
    url="&url.yaz-phpyaz;">&url.yaz-phpyaz;</ulink>.
   </para>
   <para>
    The module hides most of the complexity of Z39.50 so it should be
    fairly easy to use. It supports persistent stateless connections very
    similar to those offered by the various SQL APIs that are available
    for PHP. This means that sessions are stateless but shared amongst
    users, thus saving the connect and initialize phase steps in most
    cases.
   </para>
   </sect1>
   <sect1 id="yaz.install">
   <title>Installation</title>
   <para>
    Compile YAZ and install it. Build PHP with your favourite
    modules and add option 
    <link linkend="install.configure.with-yaz"><option role="configure">
    --with-yaz</option></link>.
    Your task is roughly the following:
   </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 keeps track of connections with targets
    (Z-Associations). A positive integer represents the ID of a
    particular association.
   </para>
   <para>
   <example>
    <title><function>Parallel searching using YAZ</function></title>
     <simpara>
      The script below demonstrates the parallel searching feature of
      the API. When invoked with no arguments it prints a query form; else
      (arguments are supplied) it searches the targets as given in in array
      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>Returns additional error information</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_addinfo</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns additional error message for target (last request). An
     empty string is returned if last operation was a success or if no
     additional information was provided by the target.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-close">
   <refnamediv>
    <refname>yaz_close</refname>
    <refpurpose>Closes a YAZ connection</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_close</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
     </methodsynopsis>
    <para>
     Closes the Z-association given by <parameter>id</parameter>.
     The <parameter>id</parameter> is a target ID as returned by a
     previous <function>yaz_connect</function> command.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-connect">
   <refnamediv>
    <refname>yaz_connect</refname>
    <refpurpose>
     Prepares for a connection and Z-association to a Z39.50 target.
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</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>
     This function returns a positive ID on success; zero on
     failure.
    </para>
    <para>
     <function>yaz_connect</function> prepares for a connection to a
     Z39.50 target. The zurl argument takes the form
     host[:port][/database]. If port is omitted 210 is used. If
     database is omitted Default is used. This function is
     non-blocking and doesn't attempt to establish a socket - it
     merely prepares a connect to be performed later when
     <function>yaz_wait</function> is called.
    </para>
    <para>
     If the second argument, <parameter>options</parameter>, is given as
     a string it is treated as the Z39.50 V2 authentication string
     (OpenAuth).
    </para>
    <para>
     If <parameter>options</parameter> is given as an array the contents
     of the array serves as options. Note that array options are only
     supported for PHP 4.1.0 and later.

    <variablelist>
     <title><function>yaz_connect</function> options</title>
     <varlistentry><term>user</term><listitem>
      <simpara>Username for authentication.
      </simpara></listitem>
     </varlistentry>
     <varlistentry><term>group</term><listitem>
      <simpara>Group for authentication.
      </simpara></listitem>
     </varlistentry>
     <varlistentry><term>password</term><listitem>
      <simpara>Password for authentication.
      </simpara></listitem>
     </varlistentry>
     <varlistentry><term>cookie</term><listitem>
      <simpara>Cookie for session (YAZ proxy).
      </simpara></listitem>
     </varlistentry>
     <varlistentry><term>proxy</term><listitem>
      <simpara>Proxy for connection (YAZ proxy).
      </simpara></listitem>
     </varlistentry>
     <varlistentry><term>persistent</term><listitem>
      <simpara>A boolean. If &true; the connection is persistent; If
&false; the connection is not persistent. By default connections are
persistent.
      </simpara></listitem>
     </varlistentry>
     <varlistentry><term>piggyback</term><listitem>
      <simpara>A boolean. If &true; piggyback is enabled for
searches; If &false; piggyback is disabled.
By default piggyback is enabled. Enabling piggyback is more efficient
and usually saves a network-round-trip for first time fetches of records.
However, a few Z39.50 targets doesn't support piggyback or they ignore
element set names. For those, piggyback should be disabled.
      </simpara></listitem>
     </varlistentry>
    </variablelist>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-errno">
   <refnamediv>
    <refname>yaz_errno</refname>
    <refpurpose>Returns error number</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_errno</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns error for target (last request). A positive value is
     returned if the target returned a diagnostic code; a value of
     zero is returned if no errors occurred (success); negative value
     is returned for other errors (such as when the target
     closed connection, etc).
    </para>
    <para>
     <function>yaz_errno</function> should be called after network
     activity for each target - (after <function>yaz_wait</function>
     returns) to determine the success or failure of the last
     operation (e.g. search).
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-error">
   <refnamediv>
    <refname>yaz_error</refname>
    <refpurpose>Returns error description</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>yaz_error</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns error message for target (last request). An empty string
     is returned if last operation was a success.
    </para>
    <para>
     <function>yaz_error</function> returns an english text message
     corresponding to the last error number as returned by
     <function>yaz_errno</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-hits">
   <refnamediv>
    <refname>yaz_hits</refname>
    <refpurpose>Returns number of hits for last search</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_hits</methodname>
      <methodparam><type>int</type><parameter>id</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>yaz_hits</function> returns number of hits for last
     search.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-element">
   <refnamediv>
    <refname>yaz_element</refname>
    <refpurpose>
     Specifies Element-Set Name for retrieval
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</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>
     This function is used in conjunction with
     <function>yaz_search</function> and <function>yaz_present</function>
     to specify the element set name for records to be retrieved.
     Most servers support <literal>F</literal> (full) and
     <literal>B</literal> (brief).
    </para>
    <para>
     Returns &true; on success; &false; on error. 
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-database">
   <refnamediv>
    <refname>yaz_database</refname>
    <refpurpose>
     Specifies the databases within a session
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</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>
     This function specifies one or more databases to be used in search,
     retrieval, etc. - overriding databases specified in call to
     <function>yaz_connect</function>. Multiple databases are
     separated by a plus sign <literal>+</literal>.
    </para>
    <para>
     This function allows you to use different sets of databases within
     a session.
    </para>
    <para>
     Returns &true; on success; &false; on error. 
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-range">
   <refnamediv>
    <refname>yaz_range</refname>
    <refpurpose>
     Specifies the maximum number of records to retrieve
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</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>
     This function is used in conjunction with
     <function>yaz_search</function> to specify the maximum number of
     records to retrieve (number) and the first record position
     (start). If this function is not invoked (only
     <function>yaz_search</function>) start is set to 1 and number is
     set to 10.
    </para>
    <para>
     Returns &true; on success; &false; on error. 
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-record">
   <refnamediv>
    <refname>yaz_record</refname>
    <refpurpose>Returns a record</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</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>
     Returns record at position or empty string if no record exists at
     given position.
    </para>
    <para>
     The <function>yaz_record</function> function inspects a record in
     the current result set at the position specified. If no database
     record exists at the given position an empty string is
     returned. The argument, type, specifies the form of the returned
     record. If type is "string" the record is returned in a string
     representation suitable for printing (for XML and SUTRS). If type
     is "array" the record is returned as an array representation (for
     structured records).
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-search">
   <refnamediv>
    <refname>yaz_search</refname>
    <refpurpose>Prepares for a search</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</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> prepares for a search on the
     target with given id. The type represents the query type - only
     "rpn" is supported now in which case the third argument specifies
     a Type-1 query (RPN). Like <function>yaz_connect</function> this
     function is non-blocking and only prepares for a search to be
     executed later when <function>yaz_wait</function> is called.
    </para>
   </refsect1>
   <refsect1>
    <title>The RPN query</title>
    <para>
     The RPN query is a textual represenation of the Type-1 query as
     defined by the Z39.50 standard. However, in the text representation
     as used by YAZ a prefix notation is used, that is the operater
     precedes the operands. The query string is a sequence of tokens where
     white space is ignored is ignored unless surrounded by double
     quotes. Tokens beginning with an at-character (<literal>@</literal>)
     are considered operators, otherwise they are treated as search terms.
    </para>
    <table>
     <title>RPN Operators</title>
     <tgroup cols="2">
      <thead>
        <row>
          <entry>Syntax</entry>
          <entry>Description</entry>
        </row>
      </thead>
      <tbody>
        <row>
         <entry><literal>@and query1 query2</literal></entry>
         <entry>intersection of query1 and query2</entry>
        </row>
        <row>
         <entry><literal>@or query1 query2</literal></entry>
         <entry>union of query1 and query2</entry>
        </row>
        <row>
         <entry><literal>@not query1 query2</literal></entry>
         <entry>query1 and not query2</entry>
        </row>
        <row>
         <entry><literal>@set name</literal></entry>
         <entry>result set reference</entry>
        </row>
        <row>
         <entry><literal>@attrset set query</literal></entry>
         <entry>specifies attribute-set for query. This construction is only
                allowed once - in the beginning of the whole query</entry>
        </row>
        <row>
          <entry><literal>@attr set type=value query</literal></entry>
          <entry>applies attribute to query. The type and value are
                 integers specifying the attribute-type and attribute-value
                 respectively. The set, if given, specifies the
                 attribute-set.</entry>
        </row>
      </tbody>
     </tgroup>
    </table>     
    <example>
    <title>Query Examples</title>
    <para>
     Query
      <screen>computer</screen>
      matches documents where "computer" occur. No attributes are specified.
    </para>
     <para>
     The Query
      <screen>"donald knuth"</screen>
     matches documents where "donald knuth" occur.
     </para>
     <para>
     For the query
      <screen>@attr 1=4 art</screen>
     attribute type is 1 (Bib-1 use), attribute value is 4
     Title), so this should match documents where <literal>art</literal>
     occur in the title.
     </para>
     <para>
     Another more complex one:
<screen>@attrset gils @and @attr 1=4 art @attr 1=1003 "donald knuth"</screen>
     The query as a whole uses the GILS attributeset. The query matches
     documents where <literal>art</literal> occur in the title and in which
     <literal>donald knuth</literal> occur in the author.
     </para>
    </example>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-present">
   <refnamediv>
    <refname>yaz_present</refname>
    <refpurpose>
     Prepares for retrieval (Z39.50 present).
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_present</methodname>
      <void/>
     </methodsynopsis>
    <para>
     This function prepares for retrieval of records after
     a successful search. The <function>yaz_range</function> should
     be called prior to this function to specify the range of
     records to be retrieved. 
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-syntax">
   <refnamediv>
    <refname>yaz_syntax</refname>
    <refpurpose>
     Specifies the preferred record syntax for retrieval.
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</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>
     The syntax is specified as an OID (Object Identifier) in a
     raw dot-notation (like <literal>1.2.840.10003.5.10</literal>) or
     as one of the known registered record syntaxes (sutrs, usmarc, grs1,
     xml, etc.). This function is used in conjunction with
     <function>yaz_search</function> and <function>yaz_present</function>
     to specify the preferred record syntax for retrieval.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-scan">
   <refnamediv>
    <refname>yaz_scan</refname>
    <refpurpose>Prepares for a scan</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</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>
     This function prepares for a Z39.50 Scan Request. Argument
     <parameter>id</parameter> specifies target ID. Starting term
     point for the scan is given by <parameter>startterm</parameter>.
     The form in which is the starting term is specified is given by
     <parameter>type</parameter>. Currently type <literal>rpn</literal>
     is supported. The optional <parameter>flags</parameter>
     specifies additional information to control the behaviour of the
     scan request. Three indexes are currently read from the flags:
     <literal>number</literal> (number of terms requested),
     <literal>position</literal> (preferred position of term) and
     <literal>stepSize</literal> (preferred step size).
     To actually tranfer the Scan Request to the target and receive the
     Scan Response, <function>yaz_wait</function> must be called. Upon
     completion of <function>yaz_wait</function> call
     <function>yaz_error</function> and
     <function>yaz_scan_result</function> to handle the response.
    </para>
    <para>
      The syntax of <parameter>startterm</parameter> is similar to the
      RPN query as described in <function>yaz_search</function>. The
      startterm consists of zero or more  <literal>@attr</literal>-operator 
      specifications, then followed by exactly one token.
    </para>
    <para>
    <example>
    <title>PHP function that scans titles</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>Returns Scan Response result</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</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>
     Given a target ID this function returns and array with terms as received
     from the target in the last Scan Response.
     This function returns an array (0..n-1) where n is the number
     of terms returned. Each value is a pair where first item is
     term, second item is result-count.
     If the <parameter>result</parameter> is given it will be modified to hold
     additional information taken from the Scan Response:
     <literal>number</literal> (number of entries returned),
     <literal>stepsize</literal> (Step-size),
     <literal>position</literal> (position of term),
     <literal>status</literal> (Scan Status).
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-ccl-conf">
   <refnamediv>
    <refname>yaz_ccl_conf</refname>
    <refpurpose>Configure CCL parser</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</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>
     This function configures the CCL query parser for a target
     with definitions of access points (CCL qualifiers) and their
     mapping to RPN. To map a specific CCL query to RPN afterwards
     call the <function>yaz_ccl_parse</function> function.
     Each index of the array <parameter>config</parameter> is the
     name of a CCL field and the corresponding value holds a string
     that specifies a mapping to RPN.
     The mapping is a sequence of attribute-type, attribute-value
     pairs. Attribute-type and attribute-value is separated by an equal
     sign (<literal>=</literal>). Each pair is separated by white space.
    </para>
    <para>
    <example>
    <title>CCL configuration</title>
    <simpara>
     In the example below, the CCL parser is configured to support
     three CCL fields: <literal>ti</literal>, <literal>au</literal> and
     <literal>isbn</literal>. Each field is mapped to their BIB-1
     equivalent. It is assumed that variable <literal>$id</literal> is a
     target 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>Invoke CCL Parser</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</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>
     This function invokes the CCL parser. It converts a given
     CCL FIND query to an RPN query which may be passed to the
     <function>yaz_search</function> function to perform a search.
     To define a set of valid CCL fields call
     <function>yaz_ccl_conf</function> prior to this function.
     If the supplied <parameter>query</parameter> was successfully
     converted to RPN, this function returns &true;, and the index
     <literal>rpn</literal> of the supplied array
     <parameter>result</parameter> holds a valid RPN query.
     If the query could not be converted (because of invalid syntax,
     unknown field, etc.) this function returns &false; and three
     indexes are set in the resulting array to indicate the cause
     of failure: <literal>errorcode</literal>CCL error code (integer),
     <literal>errorstring</literal>CCL error string, and 
     <literal>errorpos</literal>approximate position in query of failure
     (integer is character position).
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-itemorder">
   <refnamediv>
    <refname>yaz_itemorder</refname>
    <refpurpose>
     Prepares for Z39.50 Item Order with an ILL-Request package
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_itemorder</methodname>
      <methodparam><type>array</type><parameter>args</parameter></methodparam>
     </methodsynopsis>
    <para>
     This function prepares for an Extended Services request using the
     Profile for the Use of Z39.50 Item Order Extended Service to
     Transport ILL (Profile/1). See
     <ulink url="http://www.nlc-bnc.ca/iso/ill/stanprf.htm">this</ulink>
     and the
     <ulink url="http://www.nlc-bnc.ca/iso/ill/document/standard/z-ill-1a.pdf">
     specification</ulink>.
     The args parameter must be a hash array with information about the
     Item Order request to be sent. The key of the hash is the name
     of the corresponding ASN.1 tag path. For example, the ISBN below
     the Item-ID has the key item-id,ISBN. 
    </para>
    <para>
    The ILL-Request parameters are:
    </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>
    There are also a few parameters that are part of the Extended
    Services Request package and the ItemOrder package:
    </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>Wait for Z39.50 requests to complete</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>yaz_wait</methodname>
       <methodparam choice="opt"><type></type><parameter>array options</parameter></methodparam>
     </methodsynopsis>
    <para>
     This function carries out networked (blocked) activity for
     outstanding requests which have been prepared by the functions
     <function>yaz_connect</function>,
     <function>yaz_search</function>, <function>yaz_present</function>,
     <function>yaz_scan</function> and <function>yaz_itemorder</function>.
     <function>yaz_wait</function> returns when all targets have either
     completed all requests or aborted (in case of errors).
    </para>
    <para>
      If the <parameter>options</parameter> array is given that holds
      options that change the behaviour of <function>yaz_wait</function>.
    </para>
    <variablelist>
     <varlistentry><term><literal>timeout</literal></term><listitem>
      <para>Sets timeout in seconds. If a target hasn't responded within
      the timeout it is considered dead and <function>yaz_wait</function>
      returns. The default value for timeout is 15 seconds.
      </para></listitem>
     </varlistentry>
    </variablelist>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-sort">
   <refnamediv>
    <refname>yaz_sort</refname>
    <refpurpose>Sets sorting criteria</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</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>
     This function sets sorting criteria and enables Z39.50 Sort.
     Use this function together with <function>yaz_search</function>
     or <function>yaz_present</function>. Using this function alone
     doesn't have any effect. If used in conjunction with
     <function>yaz_search</function> a Z39.50 Sort will be sent after
     a search response has been received and before any records are
     retrieved with Z39.50 Present. The <parameter>criteria</parameter>
     takes the form
    </para>
    <para>
      <replaceable>field1 flags1 field2 flags2</replaceable> ...
    </para>
    <para>
     where field1 specifies primary attributes for sort, field2 seconds,
     etc.. The field specifies either numerical attribute combinations consisting
     of type=value pairs separated by comma (e.g. <literal>1=4,2=1</literal>)
     ; or the field may specify a plain string criteria
     (e.g. <literal>title</literal>. The flags is a sequnce of the
     following characters which may not be separated by any white space.
    </para>
    <variablelist>
      <title>Sort Flags</title>
      <varlistentry><term><literal>a</literal></term><listitem>
       <simpara>Sort ascending</simpara></listitem>
      </varlistentry>
      <varlistentry><term><literal>d</literal></term><listitem>
       <simpara>Sort descending</simpara></listitem>
      </varlistentry>
      <varlistentry><term><literal>i</literal></term><listitem>
       <simpara>Case insensitive sorting</simpara></listitem>
      </varlistentry>
      <varlistentry><term><literal>s</literal></term><listitem>
       <simpara>Case sensitive sorting</simpara></listitem>
      </varlistentry>
    </variablelist>
    <example>
    <title>Sort Criterias</title>
    <para>
       To sort on Bib1 attribute title, case insensitive,
       and ascending you'd use the following sort criteria:
     <screen>
       1=4 ia
     </screen>
    </para>
    <para>
       If the secondary sorting criteria should be author, case sensitive
       and ascending you'd use:
     <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:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->