<!-- $Id: client.xml,v 1.16 2003/05/23 00:24:04 mike Exp $ -->
 <chapter id="client"><title>The YAZ client</title>
  <sect1 id="client.introduction"><title>Introduction</title>
   <para>
    yaz-client is a line-mode Z39.50/SRW client. It supports a fair amount
    of the functionality of the Z39.50v3 standard.
    Its primary purpose is to exercise the package, and verify that
    the protocol works OK.
    For the same reason some commands offers more functionality than others.
    Commands that exercises common Z39.50 services such as search and present
    have more features than less common supported services, such as Extended
    Services (ItemOrder, ItemUpdate,..).
   </para>
  </sect1>
  <sect1 id="client.invoking"><title>Invoking the YAZ client</title>
   <para>
    It can be started by typing
   </para>
   <cmdsynopsis>
    <command>yaz-client</command>
    <arg>-m <replaceable>fname</replaceable></arg>
    <arg>-a <replaceable>fname</replaceable></arg>
    <arg>-c <replaceable>fname</replaceable></arg>
    <arg>-q <replaceable>fname</replaceable></arg>
    <arg>-v <replaceable>level</replaceable></arg>
    <arg>-p <replaceable>target</replaceable></arg>
    <arg>-u <replaceable>auth</replaceable></arg>
    <arg>-k <replaceable>size</replaceable></arg>
    <arg>zurl</arg>
   </cmdsynopsis>
   
   <simpara>
    in a UNIX shell / WIN32 console. The <replaceable>zurl</replaceable>,
    specifies a Z39.50/SRW host and, if specified, the client first tries to
    establish connection with the Z39.50/SRW target.
   </simpara>
   <simpara>
    Options are prefixed by <literal>-</literal> followed by a
    particular letter.
    </simpara>
   <simpara>
    The following options are supported:
   </simpara>
   <variablelist>
    <varlistentry><term>
      <literal>-m</literal> <replaceable>fname</replaceable>
     </term><listitem>
      <simpara>All retrieved transfer records are appended to file
       <replaceable>fname</replaceable>. All records as returned by a
       target(s) in Search Responses and Present Responses are appended
       verbatim to the file.
      </simpara></listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>-a</literal> <replaceable>fname</replaceable>
     </term><listitem>
      <simpara>Pretty-print log of APDUs sent and received is appended
       to the file <replaceable>fname</replaceable>.
       If <replaceable>fname</replaceable> is <literal>-</literal> (minus)
       the APDU log is written to <literal>stderr</literal>.
      </simpara></listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>-c</literal> <replaceable>fname</replaceable>
     </term><listitem>
      <simpara>Sets the filename for CCL fields to
       <replaceable>fname</replaceable>. If this option is not given the
       YAZ client reads CCL fields from file <literal>default.bib</literal>.
      </simpara></listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>-q</literal> <replaceable>fname</replaceable>
     </term><listitem>
      <simpara>Sets the filename for CQL fields to
       <replaceable>fname</replaceable>. If this option is not given the
       YAZ client reads CQL fields from file
       <literal>/usr/local/share/yaz/etc/pqf.properties</literal>.
      </simpara></listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>-v</literal> <replaceable>level</replaceable>
     </term><listitem>
      <simpara>Sets the LOG level to <replaceable>level</replaceable>.
       Level is a sequence of tokens separated by comma. Each token
       is a integer or a named LOG item - one of 
       <literal>fatal</literal>,
       <literal>debug</literal>,
       <literal>warn</literal>,
       <literal>log</literal>,
       <literal>malloc</literal>,
       <literal>all</literal>,
       <literal>none</literal>.
      </simpara></listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>-p</literal> <replaceable>target</replaceable>
     </term><listitem>
      <simpara>Specifies proxy address. When set YAZ client will
       connect to a proxy on the address and port given. 
       The actual target will be specified as part of the InitRequest
       to inform the proxy about actual target.
      </simpara></listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>-u</literal> <replaceable>auth</replaceable>
     </term><listitem>
      <simpara>Specifies authentication. Usually the form
       <replaceable>user</replaceable>/<replaceable>password</replaceable>
       is used. This option does the same thing as the
       <literal>auth</literal> command.
      </simpara></listitem>
    </varlistentry>

    <varlistentry><term>
      <literal>-k</literal> <replaceable>size</replaceable>
     </term><listitem>
      <simpara>Specifies the maximum messages size in kilobytes.
       The default maximum message size for the YAZ client is 1024
       (1 MB).
      </simpara></listitem>
    </varlistentry>

   </variablelist>
   <para>
    In order to connect to Index Data's test Z39.50 server on
    <literal>bagel.indexdata.dk</literal>, port 210 and with the
    database name <literal>marc</literal>, one could type
    <screen>
     yaz-client bagel.indexdata.dk:210/marc
    </screen>
   </para>
   <para>
    The same server is also a SOAP SRW service. Connect to it via HTTP
    as follows:
    <screen>
     yaz-client http://bagel.indexdata.dk:210/marc
    </screen>
   </para>
   <para>
    In order to enable APDU log and connect to localhost, port 210 (default)
    and database Default (default) you'd write:
    <screen>
     yaz-client -a - localhost
    </screen>
   </para> 
   <para>
    The following command connects to a local server via UNIX
    socket <filename>/tmp/yaz</filename> and sets maximum message size to
    5 MB.
   <screen>
    yaz-client -k 5120 unix:/tmp/yaz
   </screen> 
   </para>
  </sect1>
  <sect1 id="client.commands"><title>Commands</title>
   <para>
    When the YAZ client has read options and connected to a target, if given,
    it will display <literal>Z&gt;</literal> and await your command.
    Commands are executed by hitting the return key.
    You can always issue the command <literal>?</literal> to see the list
    of available commands.
    </para>
   <para>
    The commands are (the letters in parenthesis are short
    names for the commands):
   </para>

   &yaz-client-commands;

  </sect1>
  <sect1 id="client.searching"><title>Searching</title>
   <para>
    The simplest example of a Prefix Query would be something like
    <screen>
     f knuth
    </screen>
    or
    <screen>
     f "donald knuth"
    </screen>
    In those queries no attributes was specified.
    This leaves it up to the server what fields to search but
    most servers will search in all fields. Some servers does not
    support this feature though, and require that some attributes
    are defined. To add one attribute you could do:
    <screen>
     f @attr 1=4 computer
    </screen>
    where we search in the title field, since the use(1) is title(4).
    If we want to search in the author field <emphasis>and</emphasis>
    in the title field, and in the title field using right truncation
    it could look something like this:
    <screen>
     f @and @attr 1=1003 knuth @attr 1=4 @attr 5=1 computer
    </screen>
    Finally using a mix of Bib-1 and GILS attributes could look
    something like this:
    <screen>
     f @attrset Bib-1 @and @attr GILS 1=2008 Washington @attr 1=21 weather
    </screen>
    For the full specification of the Prefix Query see the section
     <link linkend="PQF">Prefix Query Format</link>.
   </para>
  </sect1>
 </chapter>
 
 <!-- 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: "yaz.xml"
 sgml-local-catalogs: nil
 sgml-namecase-general:t
 End:
 -->
