doc/client.xml

   1 <!-- $Id: client.xml,v 1.14 2002-09-16 14:16:31 adam Exp $ -->
   2  <chapter id="client"><title>The YAZ client</title>
   3   <sect1 id="client.introduction"><title>Introduction</title>
   4    <para>
   5     yaz-client is a line-mode Z39.50 client. It supports a fair amount
   6     of the functionality of the Z39.50-1995 standard
   7     Its primary purpose is to exercise the package, and verify that
   8     the protocol works OK.
   9     For the same reason some commands offers more functionality than others.
  10     Commands that exercises common Z39.50 services such as search and present
  11     have more features than less common supported services, such as Extended
  12     Services (ItemOrder, ItemUpdate,..).
  13    </para>
  14   </sect1>
  15   <sect1 id="client.invoking"><title>Invoking the YAZ client</title>
  16    <para>
  17     It can be started by typing
  18    </para>
  19    <cmdsynopsis>
  20     <command>yaz-client</command>
  21     <arg>-m <replaceable>fname</replaceable></arg>
  22     <arg>-a <replaceable>fname</replaceable></arg>
  23     <arg>-c <replaceable>fname</replaceable></arg>
  24     <arg>-v <replaceable>level</replaceable></arg>
  25     <arg>-p <replaceable>target</replaceable></arg>
  26     <arg>-u <replaceable>auth</replaceable></arg>
  27     <arg>-k <replaceable>size</replaceable></arg>
  28     <arg>zurl</arg>
  29    </cmdsynopsis>
  30
  31    <simpara>
  32     in a UNIX shell / WIN32 console. The <replaceable>zurl</replaceable>,
  33     specifies a Z39.50 host and, if specified, the client first tries to
  34     establish connection with the Z39.50 target on the host.
  35     Options are prefixed by <literal>-</literal> followed by a
  36     particular letter.
  37     </simpara>
  38    <simpara>
  39     The following options are supported:
  40    </simpara>
  41    <variablelist>
  42     <varlistentry><term>
  43       <literal>-m</literal> <replaceable>fname</replaceable>
  44      </term><listitem>
  45       <simpara>All retrieved transfer records are appended to file
  46        <replaceable>fname</replaceable>. All records as returned by a
  47        target(s) in Search Responses and Present Responses are appended
  48        verbatim to the file.
  49       </simpara></listitem>
  50     </varlistentry>
  51     <varlistentry><term>
  52       <literal>-a</literal> <replaceable>fname</replaceable>
  53      </term><listitem>
  54       <simpara>Pretty-print log of APDUs sent and received is appended
  55        to the file <replaceable>fname</replaceable>.
  56        If <replaceable>fname</replaceable> is <literal>-</literal> (minus)
  57        the APDU log is written to <literal>stderr</literal>.
  58       </simpara></listitem>
  59     </varlistentry>
  60     <varlistentry><term>
  61       <literal>-c</literal> <replaceable>fname</replaceable>
  62      </term><listitem>
  63       <simpara>Sets the filename for CCL fields to
  64        <replaceable>fname</replaceable>. If this option is not given the
  65        YAZ client reads CCL fields from file <literal>default.bib</literal>.
  66       </simpara></listitem>
  67     </varlistentry>
  68     <varlistentry><term>
  69       <literal>-v</literal> <replaceable>level</replaceable>
  70      </term><listitem>
  71       <simpara>Sets the LOG level to <replaceable>level</replaceable>.
  72        Level is a sequence of tokens separated by comma. Each token
  73        is a integer or a named LOG item - one of
  74        <literal>fatal</literal>,
  75        <literal>debug</literal>,
  76        <literal>warn</literal>,
  77        <literal>log</literal>,
  78        <literal>malloc</literal>,
  79        <literal>all</literal>,
  80        <literal>none</literal>.
  81       </simpara></listitem>
  82     </varlistentry>
  83     <varlistentry><term>
  84       <literal>-p</literal> <replaceable>target</replaceable>
  85      </term><listitem>
  86       <simpara>Specifies proxy address. When set YAZ client will
  87        connect to a proxy on the address and port given.
  88        The actual target will be specified as part of the InitRequest
  89        to inform the proxy about actual target.
  90       </simpara></listitem>
  91     </varlistentry>
  92     <varlistentry><term>
  93       <literal>-u</literal> <replaceable>auth</replaceable>
  94      </term><listitem>
  95       <simpara>Specifies authentication. Usually the form
  96        <replaceable>user</replaceable>/<replaceable>password</replaceable>
  97        is used. This option does the same thing as the
  98        <literal>auth</literal> command.
  99       </simpara></listitem>
 100     </varlistentry>
 101
 102     <varlistentry><term>
 103       <literal>-k</literal> <replaceable>size</replaceable>
 104      </term><listitem>
 105       <simpara>Specifies the maximum messages size in kilobytes.
 106        The default maximum message size for the YAZ client is 1024
 107        (1 MB).
 108       </simpara></listitem>
 109     </varlistentry>
 110
 111    </variablelist>
 112    <para>
 113     In order to connect to Index Data's test Z39.50 server on
 114     <literal>bagel.indexdata.dk</literal>, port 210 and with the
 115     database name marc, one would have to type
 116    </para>
 117    <screen>
 118     yaz-client bagel.indexdata.dk:210/marc
 119    </screen>
 120    <para>
 121     In order to enable APDU log and connect to localhost, port 210 (default)
 122     and database Default (default) you'd write:
 123    </para>
 124    <screen>
 125     yaz-client -a - localhost
 126    </screen>
 127    <para>
 128     The following command connects to a local server via UNIX
 129     socket <filename>/tmp/yaz</filename> and sets maximum message size to
 130     5 MB.
 131     </para>
 132    <screen>
 133     yaz-client -k 5120 unix:/tmp/yaz
 134     </screen>
 135   </sect1>
 136   <sect1 id="client.commands"><title>Commands</title>
 137    <para>
 138     When the YAZ client has read options and connected to a target, if given,
 139     it will display <literal>Z&gt;</literal> and await your command.
 140     Commands are executed by hitting the return key.
 141     You can always issue the command <literal>?</literal> to see the list
 142     of available commands.
 143     </para>
 144    <para>
 145     The commands are (the letters in parenthesis are short
 146     names for the commands):
 147    </para>
 148
 149    &yaz-client-commands;
 150
 151   </sect1>
 152   <sect1 id="client.searching"><title>Searching</title>
 153    <para>
 154     The simplest example of a Prefix Query would be something like
 155     <screen>
 156      f knuth
 157     </screen>
 158     or
 159     <screen>
 160      f "donald knuth"
 161     </screen>
 162     In those queries no attributes was specified.
 163     This leaves it up to the server what fields to search but
 164     most servers will search in all fields. Some servers does not
 165     support this feature though, and require that some attributes
 166     are defined. To add one attribute you could do:
 167     <screen>
 168      f @attr 1=4 computer
 169     </screen>
 170     where we search in the title field, since the use(1) is title(4).
 171     If we want to search in the author field <emphasis>and</emphasis>
 172     in the title field, and in the title field using right truncation
 173     it could look something like this:
 174     <screen>
 175      f @and @attr 1=1003 knuth @attr 1=4 @attr 5=1 computer
 176     </screen>
 177     Finally using a mix of Bib-1 and GILS attributes could look
 178     something like this:
 179     <screen>
 180      f @attrset Bib-1 @and @attr GILS 1=2008 Washington @attr 1=21 weather
 181     </screen>
 182     For the full specification of the Prefix Query see the section
 183      <link linkend="PQF">Prefix Query Format</link>.
 184    </para>
 185   </sect1>
 186  </chapter>
 187
 188  <!-- Keep this comment at the end of the file
 189  Local variables:
 190  mode: sgml
 191  sgml-omittag:t
 192  sgml-shorttag:t
 193  sgml-minimize-attributes:nil
 194  sgml-always-quote-attributes:t
 195  sgml-indent-step:1
 196  sgml-indent-data:t
 197  sgml-parent-document: "yaz.xml"
 198  sgml-local-catalogs: nil
 199  sgml-namecase-general:t
 200  End:
 201  -->