doc/client.xml

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