-<!-- $Id: client.xml,v 1.3 2001-10-24 09:27:59 adam Exp $ -->
+<!-- $Id: client.xml,v 1.18 2006-04-25 11:25:08 marc 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.
+ yaz-client is a line-mode Z39.50/SRW client. It supports a fair amount
+ of the functionality of the Z39.50v3 standard.
+ 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
<para>
It can be started by typing
</para>
- <screen>
- yaz-client [<replaceable>options</replaceable>] [<replaceable>zurl</replaceable>]
- </screen>
+ <cmdsynopsis>
+ <command>yaz-client</command>
+ <arg>-m <replaceable>fname</replaceable></arg>
+ <arg>-a <replaceable>fname</replaceable></arg>
+ <arg>-c <replaceable>fname</replaceable></arg>
+ <arg>-q <replaceable>fname</replaceable></arg>
+ <arg>-v <replaceable>level</replaceable></arg>
+ <arg>-p <replaceable>target</replaceable></arg>
+ <arg>-u <replaceable>auth</replaceable></arg>
+ <arg>-k <replaceable>size</replaceable></arg>
+ <arg>zurl</arg>
+ </cmdsynopsis>
+
<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.
+ specifies a Z39.50/SRW host and, if specified, the client first tries to
+ establish connection with the Z39.50/SRW target.
+ </simpara>
+ <simpara>
+ Options are prefixed by <literal>-</literal> followed by a
+ particular letter.
</simpara>
<simpara>
The following options are supported:
<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>All retrieved transfer 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>
</simpara></listitem>
</varlistentry>
<varlistentry><term>
+ <literal>-q</literal> <replaceable>fname</replaceable>
+ </term><listitem>
+ <simpara>Sets the filename for CQL fields to
+ <replaceable>fname</replaceable>. If this option is not given the
+ YAZ client reads CQL fields from file
+ <literal>/usr/local/share/yaz/etc/pqf.properties</literal>.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry><term>
<literal>-v</literal> <replaceable>level</replaceable>
</term><listitem>
<simpara>Sets the LOG level to <replaceable>level</replaceable>.
<literal>debug</literal>,
<literal>warn</literal>,
<literal>log</literal>,
+ <literal>malloc</literal>,
<literal>all</literal>,
<literal>none</literal>.
</simpara></listitem>
</varlistentry>
+ <varlistentry><term>
+ <literal>-p</literal> <replaceable>target</replaceable>
+ </term><listitem>
+ <simpara>Specifies proxy address. When set YAZ client will
+ connect to a proxy on the address and port given.
+ The actual target will be specified as part of the InitRequest
+ to inform the proxy about actual target.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry><term>
+ <literal>-u</literal> <replaceable>auth</replaceable>
+ </term><listitem>
+ <simpara>Specifies authentication. Usually the form
+ <replaceable>user</replaceable>/<replaceable>password</replaceable>
+ is used. This option does the same thing as the
+ <literal>auth</literal> command.
+ </simpara></listitem>
+ </varlistentry>
+
+ <varlistentry><term>
+ <literal>-k</literal> <replaceable>size</replaceable>
+ </term><listitem>
+ <simpara>Specifies the maximum messages size in kilobytes.
+ The default maximum message size for the YAZ client is 1024
+ (1 MB).
+ </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
+ database name <literal>marc</literal>, one could type
+ <screen>
+ yaz-client bagel.indexdata.dk:210/marc
+ </screen>
+ </para>
+ <para>
+ The same server is also a SOAP SRW service. Connect to it via HTTP
+ as follows:
+ <screen>
+ yaz-client http://bagel.indexdata.dk:210/marc
+ </screen>
</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>
+ </para>
+ <para>
+ The following command connects to a local server via UNIX
+ socket <filename>/tmp/yaz</filename> and sets maximum message size to
+ 5 MB.
<screen>
- yaz-client -a - localhost
- </screen>
+ yaz-client -k 5120 unix:/tmp/yaz
+ </screen>
+ </para>
</sect1>
- <sect1 id="client.commands"><title>YAZ client commands</title>
+ <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 ></literal> and away your command.
+ it will display <literal>Z></literal> and await 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.
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 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><</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 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>
+ &yaz-client-commands;
+
</sect1>
<sect1 id="client.searching"><title>Searching</title>
<para>
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document: "yaz.xml"
- sgml-local-catalogs: "../../docbook/docbook.cat"
+ sgml-local-catalogs: nil
sgml-namecase-general:t
End:
-->
projects / yaz-moved-to-github.git / blobdiff