1 <!-- $Id: client.xml,v 1.13 2002-08-17 07:55:51 adam Exp $ -->
2 <chapter id="client"><title>The YAZ client</title>
3 <sect1 id="client.introduction"><title>Introduction</title>
5 yaz-client is a line-mode Z39.50 client. It supports a fair amount
6 of the functionality of the Z39.50-1995 standard
7 Its primary purpose is to exercise the package, and verify that
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,..).
15 <sect1 id="client.invoking"><title>Invoking the YAZ client</title>
17 It can be started by typing
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>
32 in a UNIX shell / WIN32 console. The <replaceable>zurl</replaceable>,
33 specifies a Z39.50 host and, if specified, the client first tries to
34 establish connection with the Z39.50 target on the host.
35 Options are prefixed by <literal>-</literal> followed by a
39 The following options are supported:
43 <literal>-m</literal> <replaceable>fname</replaceable>
45 <simpara>All retrieved transfer records are appended to file
46 <replaceable>fname</replaceable>. All records as returned by a
47 target(s) in Search Responses and Present Responses are appended
52 <literal>-a</literal> <replaceable>fname</replaceable>
54 <simpara>Pretty-print log of APDUs sent and received is appended
55 to the file <replaceable>fname</replaceable>.
56 If <replaceable>fname</replaceable> is <literal>-</literal> (minus)
57 the APDU log is written to <literal>stderr</literal>.
61 <literal>-c</literal> <replaceable>fname</replaceable>
63 <simpara>Sets the filename for CCL fields to
64 <replaceable>fname</replaceable>. If this option is not given the
65 YAZ client reads CCL fields from file <literal>default.bib</literal>.
69 <literal>-v</literal> <replaceable>level</replaceable>
71 <simpara>Sets the LOG level to <replaceable>level</replaceable>.
72 Level is a sequence of tokens separated by comma. Each token
73 is a integer or a named LOG item - one of
74 <literal>fatal</literal>,
75 <literal>debug</literal>,
76 <literal>warn</literal>,
77 <literal>log</literal>,
78 <literal>malloc</literal>,
79 <literal>all</literal>,
80 <literal>none</literal>.
84 <literal>-p</literal> <replaceable>target</replaceable>
86 <simpara>Specifies proxy address. When set YAZ client will
87 connect to a proxy on the address and port given.
88 The actual target will be specified as part of the InitRequest
89 to inform the proxy about actual target.
93 <literal>-u</literal> <replaceable>auth</replaceable>
95 <simpara>Specifies authentication. Usually the form
96 <replaceable>user</replaceable>/<replaceable>password</replaceable>
97 is used. This option does the same thing as the
98 <literal>auth</literal> command.
103 <literal>-k</literal> <replaceable>size</replaceable>
105 <simpara>Specifies the maximum messages size in kilobytes.
106 The default maximum messages for the YAZ client is 1024
108 </simpara></listitem>
113 In order to connect to Index Data's test Z39.50 server on
114 <literal>bagel.indexdata.dk</literal>, port 210 and with the
115 database name marc, one would have to type
118 yaz-client bagel.indexdata.dk:210/marc
121 In order to enable APDU log and connect to localhost, port 210 (default)
122 and database Default (default) you'd write:
125 yaz-client -a - localhost
128 The following command connects to a local server via UNIX
129 socket <filename>/tmp/yaz</filename> and sets maximum message size to
133 yaz-client -k 5120 unix:/tmp/yaz
136 <sect1 id="client.commands"><title>Commands</title>
138 When the YAZ client has read options and connected to a target, if given,
139 it will display <literal>Z></literal> and await your command.
140 Commands are executed by hitting the return key.
141 You can always issue the command <literal>?</literal> to see the list
142 of available commands.
145 The commands are (the letters in parenthesis are short
146 names for the commands):
150 <literal>open </literal><replaceable>zurl</replaceable>
153 <para>Opens a connection to a server. The syntax for
154 <replaceable>zurl</replaceable> is the same as described
155 above for connecting from the command line.
161 [<literal>(tcp|ssl|unix)':'</literal>]<replaceable>host</replaceable>
162 [:<replaceable>port</replaceable>][/<replaceable>base></replaceable>]
167 <literal>quit</literal>
170 <para>Ends YAZ client</para>
174 <literal>f </literal><replaceable>query</replaceable></term>
176 <para>Sends a Search Request using the <replaceable>query</replaceable>
182 <literal>delete</literal> <replaceable>setname</replaceable></term>
184 <para>Deletes result set with name <replaceable>setname</replaceable>
185 on the server.</para>
189 <literal>base </literal><replaceable>base1</replaceable>
190 <replaceable>base2</replaceable> ...
193 <para>Sets the name(s) of the database(s) to search. One or more
194 databases may be specified separated by blanks. This commands overrides
195 the database given in <replaceable>zurl</replaceable>.
200 <literal>show </literal>
201 [<replaceable>start</replaceable>[+<replaceable>number</replaceable>]]
203 <term><literal>s</literal></term>
205 <para>Fetches records by sending a Present Request from the start
207 <replaceable>start</replaceable>
208 a number of records given by <replaceable>number</replaceable>. If
209 <replaceable>start</replaceable> is not given, then the client
210 will fetch from position of the last retrieved record plus 1. If
211 <replaceable>number</replaceable> is not given, then one record will
212 be fetched at a time.
217 <literal>scan</literal> <replaceable>term</replaceable>
221 database index for a term. The syntax resembles the syntax
222 for <literal>find</literal>.
223 If you want to scan for the word <literal>water</literal> you could
230 but if you want to scan only in, say the title field, you would write
237 <varlistentry id="sortspec"><term>
238 <literal>sort</literal> <replaceable>sortspecs</replaceable>
241 <para>Sorts a result set. The sort command takes a
242 sequence of sort specifications. A sort
243 specification holds a field (sort criteria) and is followed by flags.
244 If the sort criteria includes <literal>=</literal> it is assumed
245 that the sort SortKey is of type sortAttributes using Bib-1.
246 The integer before <literal>=</literal> is
247 the attribute type and the integer following <literal>=</literal>
248 is the attribute value.
249 If no <literal>=</literal> is in the SortKey it is treated as a
250 sortfield-type of type InternationalString.
251 Flags observed are: <literal>s</literal>
252 for case sensitive, <literal>i</literal> for case insensitive,
253 <literal><</literal> for sort ascending and <literal>></literal>
259 <literal>sort+</literal>
262 <para>Same as <literal>sort</literal> but stores the sorted
263 result set in a new result set.
268 <literal>authentication</literal> <replaceable>openauth</replaceable>
271 <para>Sets up a authentication string if a server requires
272 authentication (v2 OpenStyle). The authentication string is first
273 sent to the server when the <literal>open</literal> command is
274 issued and the Z39.50 Initialize Request is sent, so this command
275 must be used before <literal>open</literal> in order to be effective.
276 A common convention for the <replaceable>authopen</replaceable> string
277 is that the username - and password is separated by a slash, e.g.
278 <literal>myusername/mysecret</literal>.
283 <literal>lslb</literal> <replaceable>n</replaceable>
286 <para>Sets the limit for when no records should be returned
287 together with the search result.
290 url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
299 <literal>ssub</literal> <replaceable>n</replaceable>
302 <para>Sets the limit for when all records should be returned with
306 url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
308 </ulink> for more details.
314 <literal>mspn</literal> <replaceable>n</replaceable>
317 <para>Sets the number of records should be returned if the
318 number of records in the result set is between the values of
319 <literal>lslb</literal> and <literal>ssub</literal>.
322 url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
330 <literal>status</literal>
333 <para>Displays the values of <literal>lslb</literal>,
334 <literal>ssub</literal> and <literal>mspn</literal>.
339 <literal>setname</literal>
342 <para>Switches named result sets on and off. Default is on.
347 <literal>cancel</literal>
350 <para>Sends a Trigger Resource Control Request to the target.
355 <literal>format</literal> <replaceable>oid</replaceable>
358 <para>Sets the preferred transfer syntax for retrieved records.
359 yaz-client supports all the record syntaxes that currently
362 url="http://lcweb.loc.gov/z3950/agency/defns/oids.html#5">
365 for more details. Commonly used records syntaxes include usmarc,
371 <literal>elements</literal> <replaceable>e</replaceable>
374 <para>Sets the element set name for the records. Many targets support
375 element sets are B (for brief) and F (for full).
380 <literal>close</literal>
383 <para>Sends a Z39.50 Close APDU and closes connection with the peer
388 <literal>querytype</literal> <replaceable>type</replaceable>
391 <para>Sets the query type as used by command <literal>find</literal>.
392 The following is supported: <literal>prefix</literal> for
393 <link linkend="PQF">Prefix Query Notation</link> (Type-1 Query);
394 <literal>ccl</literal> for CCL search (Type-2
395 Query) or <literal>ccl2rpn</literal> for
396 <link linkend="CCL">CCL</link> to RPN conversion (Type-1 Query).
401 <literal>attributeset</literal> <replaceable>set</replaceable>
405 Sets attribute set OID for prefix queries (RPN, Type-1).
410 <literal>refid</literal> <replaceable>id</replaceable>
413 <para>Sets reference ID for Z39.50 Request(s).
418 <literal>itemorder</literal>
419 <replaceable>type</replaceable> <replaceable>no</replaceable>
422 <para>Sends an Item Order Request using the ILL External.
423 <replaceable>type</replaceable> is either 1 or 2 which corresponds to
424 ILL-Profile 1 and 2 respectively. The <replaceable>no</replaceable>
425 is the Result Set position of the record to be ordered.
430 <literal>update</literal>
433 <para>Sends Item Update Request. This command sends a "minimal"
434 PDU Update to the target supplying the last received record from
436 If no record has been received from the target this command is ignored
437 and nothing is sent to the target.
444 <replaceable>filename</replaceable>
447 <para>Executes list of commands from
448 file <replaceable>filename</replaceable>, just like source on
456 <replaceable>args</replaceable>
459 <para>Executes command <replaceable>args</replaceable> in subshell
460 using the <literal>system</literal> call.
466 <literal>push_commande</literal>
467 <replaceable>command</replaceable>
470 <para>The push_command takes another command as its argument.
471 That command is then added to the history information (so
472 you can retrieve it later). The command itself is not
473 executed. This command only works if you have GNU readline/history
480 <literal>set_apdufile</literal>
481 <replaceable>filename</replaceable>
484 <para>Sets that APDU should be logged to file
485 <replaceable>filename</replaceable>. This command does the
486 thing as option <literal>-a</literal>.
492 <literal>set_marcdump</literal>
493 <replaceable>filename</replaceable>
496 <para>Specifies that all retrieved records should be appended ot
497 file <replaceable>filename</replaceable>. This command does the
498 thing as option <literal>-m</literal>.
504 <literal>set_cclfields</literal>
505 <replaceable>filename</replaceable>
508 <para>Specifies that CCL fields should be read from file
509 file <replaceable>filename</replaceable>. This command does the
510 thing as option <literal>-c</literal>.
516 <literal>register_oid</literal>
517 <replaceable>name</replaceable>
518 <replaceable>class</replaceable>
519 <replaceable>OID</replaceable>
522 <para>This command allows you to register your own object
523 identifier - so that instead of entering a long dot-notation
524 you can use a short name instead.
525 The <replaceable>name</replaceable> is your
526 name for the OID, <replaceable>class</replaceable> is the
527 class, and <replaceable>OID</replaceable> is the raw OID in
528 dot notation. Class is one <literal>appctx</literal>,
529 <literal>absyn</literal>, <literal>attet</literal>,
530 <literal>transyn</literal>, <literal>diagset</literal>,
531 <literal>recsyn</literal>, <literal>resform</literal>,
532 <literal>accform</literal>, <literal>extserv</literal>,
533 <literal>userinfo</literal>, <literal>elemspec</literal>,
534 <literal>varset</literal>, <literal>schema</literal>,
535 <literal>tagset</literal>, <literal>general</literal>.
536 If you're in doubt use the <literal>general</literal>
544 <sect1 id="client.searching"><title>Searching</title>
546 The simplest example of a Prefix Query would be something like
554 In those queries no attributes was specified.
555 This leaves it up to the server what fields to search but
556 most servers will search in all fields. Some servers does not
557 support this feature though, and require that some attributes
558 are defined. To add one attribute you could do:
562 where we search in the title field, since the use(1) is title(4).
563 If we want to search in the author field <emphasis>and</emphasis>
564 in the title field, and in the title field using right truncation
565 it could look something like this:
567 f @and @attr 1=1003 knuth @attr 1=4 @attr 5=1 computer
569 Finally using a mix of Bib-1 and GILS attributes could look
572 f @attrset Bib-1 @and @attr GILS 1=2008 Washington @attr 1=21 weather
574 For the full specification of the Prefix Query see the section
575 <link linkend="PQF">Prefix Query Format</link>.
580 <!-- Keep this comment at the end of the file
585 sgml-minimize-attributes:nil
586 sgml-always-quote-attributes:t
589 sgml-parent-document: "yaz.xml"
590 sgml-local-catalogs: nil
591 sgml-namecase-general:t