--- /dev/null
+<!-- $Id: client.xml,v 1.1 2001-08-08 19:33:21 adam Exp $ -->
+ <chapter><title>The YAZ client</title>
+ <sect1><title>Introduction</title>
+ <para>
+ yaz-client is a linemode 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 recompilation.
+ 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 exercies 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><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 comman. 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><title>YAZ client commands</title>
+ <para>
+ When the YAZ client has read options and connected to a target, if given,
+ it will display <literal>Z ></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></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><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><</literal> for sort ascending and <literal>></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 correponds 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><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 specifiction 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:
+ -->
projects / yaz-moved-to-github.git / blobdiff