php-doc-en/functions/yaz.xml

 <reference id="ref.yaz">
  <title>YAZ</title>
  <titleabbrev>YAZ</titleabbrev>

  <partintro>
   <simpara>
    The <function>yaz</function> functions wrap the YAZ API.  The home page
    of the project is <ulink url="&url.yaz;">&url.yaz;</ulink>.  Information
    about the phpyaz module can be found at 
    <ulink url="&url.yaz-phpyaz;">&url.yaz-phpyaz;</ulink>.
   </simpara>
   <simpara>
    PHP/YAZ is much simpler to use than the C API for YAZ but less flexible. The 
    intent is to make it easy to build basic client functions. 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 INIT steps 
    in many cases. 
   </simpara>
   <simpara>
    Before compiling PHP with the PHP/YAZ module you'll need the YAZ toolkit. 
    Build YAZ and install it. Build PHP with your favourite modules and add 
    option --with-yaz. Your task is roughly the following: 
   </simpara>
   <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>
   <simpara>
    PHP/YAZ keeps track of connections with targets (Z-Associations). A positive 
    integer represents the ID of a particular association. 
   </simpara>
   <simpara>
    The script below demonstrates the parallel searching feature of the API. 
    When invoked it either prints a query form (if no arguments are supplied) or 
    if there are arguments (term and one or more hosts) it searches the targets 
    in array host. 
   </simpara>
   <example>
    <title><function>readline</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 &gt; $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>
  </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-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 is a prefix notation query as used by 
      YAZ. 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>
  </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>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>yaz_syntax</function></funcdef>
      <paramdef>int <parameter>id</parameter></paramdef>
      <paramdef>string <parameter>syntax</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     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:
-->