<!-- $Id: client.xml,v 1.4 2001/10/24 20:12:36 adam 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 client. It supports a fair amount
    of the functionality of the Z39.50-1995 standard, but some things you
    need to enable or disable by re-compilation.
    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>
   <screen>
     yaz-client [<replaceable>options</replaceable>] [<replaceable>zurl</replaceable>]
   </screen>
   <simpara>
    in a UNIX shell / WIN32 console. The <replaceable>zurl</replaceable>,
    specifies a Z39.50 host and, if specified, the client first tries to
    establish connection with the Z39.50 target on the host.
    Options are, as usual, 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>ISO2709 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>-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>all</literal>,
       <literal>none</literal>.
      </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 marc, one would have to type
   </para>
   <screen>
    yaz-client bagel.indexdata.dk:210/marc
   </screen>
   <para>
    In order to enable APDU log and connect to localhost, port 210 (default)
    and database Default (default) you'd write:
   </para>
   <screen>
    yaz-client -a - localhost
   </screen>
  </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 away 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>
   <variablelist>
    <varlistentry><term>
      <literal>open </literal><replaceable>zurl</replaceable>
     </term>
     <term><literal>o</literal></term>
     <listitem>
      <para>Opens a connection to a server. The syntax for
       <replaceable>zurl</replaceable> is the same as described
       above for connecting from the command line.
      </para>
      <para>
       Syntax:
      </para>
      <para>
       [<literal>(tcp|osi)':'</literal><[<replaceable>tsel/</replaceable>]]<replaceable>host</replaceable>[:<replaceable>port</replaceable>][/<replaceable>base&gt</replaceable>]
      </para>
     </listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>quit</literal>
     </term>
     <term><literal>q</literal></term>
     <listitem>
      <para>Ends YAZ client</para>
     </listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>f </literal><replaceable>query</replaceable></term>
     <term><literal>f</literal></term>
     <listitem>
      <para>Sends Search Request using the <replaceable>query</replaceable>
       given.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>delete</literal> <replaceable>setname</replaceable></term>
     <listitem>
      <para>Deletes result set with name <replaceable>setname</replaceable>
       on the server.</para>
     </listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>base </literal><replaceable>base1</replaceable>
      <replaceable>base2</replaceable> ...
      </term>
     <listitem>
      <para>Sets the name(s) of the database(s) to search. One or more
       databases may be specified separated by blanks. This commands overrides
       the database given in <replaceable>zurl</replaceable>.
       </para>
     </listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>show </literal> [<replaceable>start</replaceable>[+<replaceable>number</replaceable>]]
      </term>
     <term><literal>s</literal></term>
     <listitem>
      <para>Fetches records by sending a Present Request from the start
       position given by
       <replaceable>start</replaceable>
       a number of records given by <replaceable>number</replaceable>. If
       <replaceable>start</replaceable> is not given the client will 
       fetch from position of the last retrieved record plus 1. If
       <replaceable>number</replaceable> is not given one record will be
       fetched at a time.
      </para>
      </listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>scan</literal> <replaceable>term</replaceable>
     </term>
     <listitem>
      <simpara>Scans
       database index for a term. The syntax resembles the syntax
       for <literal>find</literal>.
       If you want to scan for the word <literal>water</literal> you could
       write
       </simpara>
      <screen>
       scan water
      </screen>
      <simpara>
       but if you want to scan only in, say the title field, you would write
       </simpara>
      <screen>
       scan @attr 1=4 water
      </screen>
     </listitem>
    </varlistentry>
    <varlistentry id="sortspec"><term>
      <literal>sort</literal> <replaceable>sortspecs</replaceable>
     </term>
     <listitem>
      <para>Sorts a result set. The sort command takes a
       sequence of sort specifications. A sort
       specification holds a field (sort criteria) and is followed by flags.
       If the sort criteria includes <literal>=</literal> it is assumed
       that the sort SortKey is of type sortAttributes using Bib-1.
       The integer before <literal>=</literal> is
       the attribute type and the integer following <literal>=</literal>
       is the attribute value.
       If no <literal>=</literal> is in the SortKey it is treated as a
       sortfield-type of type InternationalString.
       Flags observed are: <literal>s</literal>
       for case sensitive, <literal>i</literal> for case insensitive,
       <literal>&lt;</literal> for sort ascending and <literal>&gt;</literal>
       for sort descending.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>sort+</literal>
     </term>
     <listitem>
      <para>Same as <literal>sort</literal> but stores the sorted
       result set in a new result set.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>authentication</literal> <replaceable>openauth</replaceable>
      </term>
     <listitem>
      <para>Sets up a authentication string if a server requires
       authentication (v2 OpenStyle). The authentication string is first
       sent to the server when the <literal>open</literal> command is
       issued and the Z39.50 Initialize Request is sent, so this command
       must be used before <literal>open</literal> in order to be effective.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>lslb</literal> <replaceable>n</replaceable>
     </term>
     <listitem>
      <para>Sets the limit for when no records should be returned
       together with the search result.
       See the
       <ulink
	url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
	Z39.50 standard
       </ulink>
       for more details.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry><term>
      <literal>ssub</literal> <replaceable>n</replaceable>
     </term>
     <listitem>
      <para>Sets the limit for when all records should be returned with
       the search result.
       See the
       <ulink
	url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
	Z39.50 standard
       </ulink> for more details.
      </para>
     </listitem>
    </varlistentry>
    
    <varlistentry><term>
      <literal>mspn</literal> <replaceable>n</replaceable>
     </term>
     <listitem>
      <para>Sets the number of records should be returned if the
       number of records in the result set is between the values of
       <literal>lslb</literal> and <literal>ssub</literal>.
       See the
       <ulink
	url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
	Z39.50 standard
       </ulink>
       for more details.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>status</literal>
     </term>
     <listitem>
      <para>Displays the values of <literal>lslb</literal>,
       <literal>ssub</literal> and <literal>mspn</literal>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>setname</literal>
     </term>
     <listitem>
      <para>Switches named result sets on and off. Default is on.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>cancel</literal>
     </term>
     <listitem>
      <para>Sends a Trigger Resource Control Request to the target.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>format</literal> <replaceable>oid</replaceable>
     </term>
     <listitem>
      <para>Sets the preferred transfer syntax for retrieved records.
       yaz-client supports all the record syntaxes that currently
       are registered. See
       <ulink
	url="http://lcweb.loc.gov/z3950/agency/defns/oids.html#5">
	Z39.50 Standard
       </ulink>
       for more details. Commonly used records syntaxes include usmarc,
       sutrs, grs1 and xml.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>elements</literal> <replaceable>e</replaceable>
     </term>
     <listitem>
      <para>Sets the element set name for the records. Many targets support
       element sets are B (for brief) and F (for full).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>close</literal>
     </term>
     <listitem>
      <para>Sends a Z39.50 Close APDU and closes connection with the peer
      </para>
     </listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>querytype</literal> <replaceable>type</replaceable>
     </term>
     <listitem>
      <para>Sets the query type as used by command <literal>find</literal>.
       The following is supported: <literal>prefix</literal> for 
       <link linkend="PQF">Prefix Query Notation</link> (Type-1 Query);
       <literal>ccl</literal> for CCL search (Type-2
       Query) or <literal>ccl2rpn</literal> for
       <link linkend="CCL">CCL</link> to RPN conversion (Type-1 Query).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>attributeset</literal> <replaceable>set</replaceable>
     </term>
     <listitem>
      <para>
       Sets attribute set OID for prefix queries (RPN, Type-1).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>refid</literal> <replaceable>id</replaceable>
      </term>
     <listitem>
      <para>Sets reference ID for Z39.50 Request(s).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry><term>
     <literal>itemorder</literal>
      <replaceable>type</replaceable> <replaceable>no</replaceable>
     </term>
     <listitem>
      <para>Sends an Item Order Request using the ILL External. 
       <replaceable>type</replaceable> is either 1 or 2 which corresponds to
       ILL-Profile 1 and 2 respectively. The <replaceable>no</replaceable>
       is the Result Set position of the record to be ordered.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry><term>
      <literal>update</literal>
     </term>
     <listitem>
      <para>Sends Item Update Request. This command sends a "minimal"
       PDU to the target supplying the last received record from the target.
       If no record has been received from the target this command is ignored
       and nothing is sent to the target.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </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: "../../docbook/docbook.cat"
 sgml-namecase-general:t
 End:
 -->
