-<!-- $Id: client.xml,v 1.11 2002-02-24 12:23:43 adam Exp $ -->
+<!-- $Id: client.xml,v 1.14 2002-09-16 14:16:31 adam Exp $ -->
<chapter id="client"><title>The YAZ client</title>
<sect1 id="client.introduction"><title>Introduction</title>
<para>
<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>-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.
+ Options are prefixed by <literal>-</literal> followed by a
+ particular letter.
</simpara>
<simpara>
The following options are supported:
<literal>debug</literal>,
<literal>warn</literal>,
<literal>log</literal>,
+ <literal>malloc</literal>,
<literal>all</literal>,
<literal>none</literal>.
</simpara></listitem>
</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 specifed as part of the InitRequest
+ 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>authentication</replaceable>
+ <literal>-u</literal> <replaceable>auth</replaceable>
</term><listitem>
<simpara>Specifies authentication. Usually the form
<replaceable>user</replaceable>/<replaceable>password</replaceable>
</varlistentry>
<varlistentry><term>
- <literal>-k</literal> <replaceable>kilobytes</replaceable>
+ <literal>-k</literal> <replaceable>size</replaceable>
</term><listitem>
<simpara>Specifies the maximum messages size in kilobytes.
- The default maxium messages for the YAZ client is 1024
+ The default maximum message size for the YAZ client is 1024
(1 MB).
</simpara></listitem>
</varlistentry>
<screen>
yaz-client -a - localhost
</screen>
+ <para>
+ The following command connects to a local server via UNIX
+ socket <filename>/tmp/yaz</filename> and sets maximum message size to
+ 5 MB.
+ </para>
+ <screen>
+ yaz-client -k 5120 unix:/tmp/yaz
+ </screen>
</sect1>
<sect1 id="client.commands"><title>Commands</title>
<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>
- <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|ssl)':'</literal>]<replaceable>host</replaceable>
- [:<replaceable>port</replaceable>][/<replaceable>base></replaceable>]
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>
- <literal>quit</literal>
- </term>
- <listitem>
- <para>Ends YAZ client</para>
- </listitem>
- </varlistentry>
- <varlistentry><term>
- <literal>f </literal><replaceable>query</replaceable></term>
- <listitem>
- <para>Sends a 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, then the client
- will fetch from position of the last retrieved record plus 1. If
- <replaceable>number</replaceable> is not given, then 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.
- A common convention for the <replaceable>authopen</replaceable> string
- is that the username - and password is separated by a slash, e.g.
- <literal>myusername/mysecret</literal>.
- </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 Update 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>
-
- <varlistentry><term>
- <literal>.</literal>
- <replaceable>filename</replaceable>
- </term>
- <listitem>
- <para>Executes list of commands from
- file <replaceable>filename</replaceable>, just like source on
- most UNIX shells.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term>
- <literal>!</literal>
- <replaceable>args</replaceable>
- </term>
- <listitem>
- <para>Executes command <replaceable>args</replaceable> in subshell
- using the <literal>system</literal> call.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term>
- <literal>push_commande</literal>
- <replaceable>command</replaceable>
- </term>
- <listitem>
- <para>The push_command takes another command as its argument.
- That command is then added to the history information (so
- you can retrieve it later). The command itself is not
- executed. This command only works if you have GNU readline/history
- enabled.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry><term>
- <literal>set_apdufile</literal>
- <replaceable>filename</replaceable>
- </term>
- <listitem>
- <para>Sets that APDU should be logged to file
- <replaceable>filename</replaceable>. This command does the
- thing as option <literal>-a</literal>.
- </para>
- </listitem>
- </varlistentry>
+ &yaz-client-commands;
- <varlistentry><term>
- <literal>set_marcdump</literal>
- <replaceable>filename</replaceable>
- </term>
- <listitem>
- <para>Specifies that all retrieved records should be appended ot
- file <replaceable>filename</replaceable>. This command does the
- thing as option <literal>-m</literal>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term>
- <literal>set_cclfields</literal>
- <replaceable>filename</replaceable>
- </term>
- <listitem>
- <para>Specifies that CCL fields should be read from file
- file <replaceable>filename</replaceable>. This command does the
- thing as option <literal>-c</literal>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry><term>
- <literal>register_oid</literal>
- <replaceable>name</replaceable>
- <replaceable>class</replaceable>
- <replaceable>OID</replaceable>
- </term>
- <listitem>
- <para>This command allows you to register your own object
- identifier - so that instead of entering a long dot-notation
- you can use a short name instead.
- The <replaceable>name</replaceable> is your
- name for the OID, <replaceable>class</replaceable> is the
- class, and <replaceable>OID</replaceable> is the raw OID in
- dot notation. Class is one <literal>appctx</literal>,
- <literal>absyn</literal>, <literal>attet</literal>,
- <literal>transyn</literal>, <literal>diagset</literal>,
- <literal>recsyn</literal>, <literal>resform</literal>,
- <literal>accform</literal>, <literal>extserv</literal>,
- <literal>userinfo</literal>, <literal>elemspec</literal>,
- <literal>varset</literal>, <literal>schema</literal>,
- <literal>tagset</literal>, <literal>general</literal>.
- If you're in doubt use the <literal>general</literal>
- class.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
</sect1>
<sect1 id="client.searching"><title>Searching</title>
<para>
projects / yaz-moved-to-github.git / blobdiff