php-doc-en/functions/yaz.xml

 <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 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 --with-yaz. Your task is roughly the
    following:
   </para>
   <para>
   <informalexample>
    <programlisting>
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>
    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.
   </para>
   <para>
   <example>
    <title><function>YAZ</function></title>
    <programlisting role="php">
$num_hosts = count ($host);
if (empty($term) || count($host) == 0) {
    echo '&lt;form method="get"&gt;
    &lt;input type="checkbox"
    name="host[]" value="bagel.indexdata.dk/gils"&gt;
        GILS test
    &lt;input type="checkbox"
    name="host[]" value="localhost:9999/Default"&gt;
        local test
    &lt;input type="checkbox" checked="1"
    name="host[]" value="z3950.bell-labs.com/books"&gt;
        BELL Labs Library
    &lt;br>
    RPN Query:
    &lt;input type="text" size="30" name="term"&gt;
    &lt;input type="submit" name="action" value="Search"&gt;
    ';        
} else {
    echo 'You searced for ' . htmlspecialchars($term) . '&lt;br&gt;';
    for ($i = 0; $i &lt; $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 &lt; $num_hosts; $i++) {
        echo '&lt;hr&gt;' . $host[$i] . ":";
        $error = yaz_error($id[$i]);
        if (!empty($error)) {
            echo "Error: $error";
        } else {
            $hits = yaz_hits($id[$i]);
            echo "Result Count $hits";
        }
        echo '&lt;dl&gt;';
        for ($p = 1; $p &lt;= 10; $p++) {
            $rec = yaz_record($id[$i],$p,"string");
            if (empty($rec)) continue;
            echo "&lt;dt&gt;&lt;b&gt;$p&lt;/b&gt;&lt;/dt&gt;&lt;dd&gt;";
            echo ereg_replace("\n", "&lt;br&gt;\n",$rec);
            echo "&lt;/dd&gt;";
        }
        echo '&lt;/dl&gt;';
    }
}
    </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>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>yaz_addinfo</function></funcdef>
      <paramdef>int <parameter>id</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <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>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>yaz_close</function></funcdef>
      <paramdef>int <parameter>id</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     Closes a connection to a target. The application can no longer
     refer to the target with the given ID.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-connect">
   <refnamediv>
    <refname>yaz_connect</refname>
    <refpurpose>
     Returns a positive association ID on success; zero on failure
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>yaz_connect</function></funcdef>
      <paramdef>string <parameter>zurl</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <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>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-errno">
   <refnamediv>
    <refname>yaz_errno</refname>
    <refpurpose>Returns error number</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>yaz_errno</function></funcdef>
      <paramdef>int <parameter>id</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <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 targets didn't indicate the error in
     question.
    </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>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>yaz_error</function></funcdef>
      <paramdef>int <parameter>id</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <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 a english 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>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>yaz_hits</function></funcdef>
      <paramdef>int <parameter>id</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <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>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>yaz_range</function></funcdef>
      <paramdef>int <parameter>id</parameter></paramdef>
      <paramdef>string <parameter>elementset</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     This function is used in conjunction with
     <function>yaz_search</function> to specify the element set name
     for records to be retrieved. Most servers support F (full) and
     B (brief).
    </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>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>yaz_range</function></funcdef>
      <paramdef>int <parameter>id</parameter></paramdef>
      <paramdef>int <parameter>start</parameter></paramdef>
      <paramdef>int <parameter>number</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <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>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>yaz_record</function></funcdef>
      <paramdef>int <parameter>id</parameter></paramdef>
      <paramdef>int <parameter>pos</parameter></paramdef>
      <paramdef>string <parameter>type</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <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>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>yaz_search</function></funcdef>
      <paramdef>int <parameter>id</parameter></paramdef>
      <paramdef>string <parameter>type</parameter></paramdef>
      <paramdef>string <parameter>query</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <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>     
    <para>
     The following illustrates valid query constructions:
     <informalexample>
      <screen>computer</screen>
     </informalexample>
      Matches documents where "computer" occur. No attributes are specified.
    </para>
    <para>
     <informalexample>
      <screen>"donald knuth"</screen>
     </informalexample>
     Matches documents where "donald knuth" occur.
    </para>
    <para>
     <informalexample>
      <screen>@attr 1=4 art</screen>
     </informalexample>
     Attribute type is 1 (Bib-1 use), attribute value is 4
     Title), so this should match documents where "art" occur
     in the title.
    </para>
    <para>
     <informalexample>
<screen>@attrset gils @and @attr 1=4 art @attr 1=1003 "donald knuth"</screen>
     </informalexample>
     The query as a whole uses the GILS attributeset. The query matches
     documents where "art" occur in the title and in which "donald knuth"
     occur in the author.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-syntax">
   <refnamediv>
    <refname>yaz_syntax</refname>
    <refpurpose>
     Specifies the object identifier (OID) for the preferred record syntax
     for retrieval.
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>yaz_syntax</function></funcdef>
      <paramdef>int <parameter>id</parameter></paramdef>
      <paramdef>string <parameter>syntax</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     The syntax may be specified in a raw dot-notation (like
     <literal>1.2.840.10003.5.10</literal>) or as one of the known
     record syntaxes (sutrs, usmarc, grs1, xml, etc.).
     This function is used in conjunction with
     <function>yaz_search</function> to specify the preferred record
     syntax for retrieval.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.yaz-wait">
   <refnamediv>
    <refname>yaz_wait</refname>
    <refpurpose>Executes queries</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>yaz_wait</function></funcdef>
      <paramdef>int <parameter>id</parameter></paramdef>
      <paramdef>string <parameter>syntax</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <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_wait</function>
     returns when all targets have either completed all requests or
     otherwise completed (in case of errors).
    </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
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->