doc/client.xml

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