1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
2 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
4 <!ENTITY % local SYSTEM "local.ent">
6 <!ENTITY % entities SYSTEM "entities.ent">
8 <!ENTITY % idcommon SYSTEM "common/common.ent">
11 <refentry id="yaz-client">
13 <productname>YAZ</productname>
14 <productnumber>&version;</productnumber>
15 <info><orgname>Index Data</orgname></info>
19 <refentrytitle>yaz-client</refentrytitle>
20 <manvolnum>1</manvolnum>
21 <refmiscinfo class="manual">Commands</refmiscinfo>
25 <refname>yaz-client</refname>
26 <refpurpose>Z39.50/SRU client for implementors</refpurpose>
31 <command>yaz-client</command>
32 <arg choice="opt"><option>-a <replaceable>apdulog</replaceable></option></arg>
33 <arg choice="opt"><option>-b <replaceable>berdump</replaceable></option></arg>
34 <arg choice="opt"><option>-c <replaceable>cclfile</replaceable></option></arg>
35 <arg choice="opt"><option>-d <replaceable>dump</replaceable></option></arg>
36 <arg choice="opt"><option>-f <replaceable>cmdfile</replaceable></option></arg>
37 <arg choice="opt"><option>-k <replaceable>size</replaceable></option></arg>
38 <arg choice="opt"><option>-m <replaceable>marclog</replaceable></option></arg>
39 <arg choice="opt"><option>-p <replaceable>proxy-addr</replaceable></option></arg>
40 <arg choice="opt"><option>-q <replaceable>cqlfile</replaceable></option></arg>
41 <arg choice="opt"><option>-t <replaceable>dispcharset</replaceable></option></arg>
42 <arg choice="opt"><option>-u <replaceable>auth</replaceable></option></arg>
43 <arg choice="opt"><option>-v <replaceable>loglevel</replaceable></option></arg>
44 <arg choice="opt"><option>-V</option></arg>
45 <arg choice="opt"><option>-x</option></arg>
46 <arg choice="opt">server-addr</arg>
51 <refsect1><title>DESCRIPTION</title>
53 <command>yaz-client</command> is a
54 <ulink url="&url.z39.50;">Z39.50</ulink>/<ulink url="&url.sru;">SRU</ulink>
55 client (origin) with a simple command line interface that allows
56 you to test behavior and performance of Z39.50 targets and SRU servers.
59 From YAZ version 4.1.0 <command>yaz-client</command> may also operate as a
60 <ulink url="&url.solr;">Solr</ulink> Web Service
64 If the <replaceable>server-addr</replaceable> is specified, the client creates
65 a connection to the Z39.50/SRU target at the address given.
68 When <command>yaz-client</command> is started it tries to read
69 commands from one of the following files:
72 Command file if it is given by option -f.
75 <filename>.yazclientrc</filename> in current working directory.
78 <filename>.yazclientrc</filename> in the user's home directory.
79 The value of the <literal>HOME</literal> is used to determine
80 the home directory. Normally, <literal>HOME</literal> is only set
81 on POSIX systems such as Linux, FreeBSD, Solaris.
87 <title>OPTIONS</title>
90 <term>-a <replaceable>filename</replaceable></term>
92 If specified, logging of protocol packages will be appended
93 file given. If <replaceable>filename</replaceable> is
94 specified as <literal>-</literal>, the output is written
95 to <literal>stdout</literal>.
99 <term>-b <replaceable>filename</replaceable></term>
101 If specified, YAZ will dump BER data in readable notation
102 to the file specified. If <replaceable>filename</replaceable>
103 is specified as <literal>-</literal> the output is written
104 to <literal>stdout</literal>.
108 <term>-c <replaceable>filename</replaceable></term>
110 If specified, CCL configuration will be read from
115 <term>-d <replaceable>dump</replaceable></term>
117 If specified, YAZ will dump BER data for all PDUs sent and received
118 to individual files, named
119 <replaceable>dump</replaceable>.DDD.<literal>raw</literal>,
120 where DDD is 001, 002, 003, ..
125 <term>-f <replaceable>cmdfile</replaceable></term>
127 Reads commands from <replaceable>cmdfile</replaceable>. When
128 this option is used, YAZ client does not read .yazclientrc
129 from current directory or home directory.
134 <term>-k <replaceable>size</replaceable></term>
136 Sets preferred messages and maximum record size for Initialize
137 Request in kilobytes. Default value is 65536 (64 MB).
141 <term>-m <replaceable>filename</replaceable></term>
143 If specified, retrieved records will be appended to the file given.
147 <term>-p <replaceable>proxy-addr</replaceable></term>
149 If specified, the client will use the proxy at the address
150 given. YAZ client will
151 connect to a proxy on the address and port given.
152 The actual target will be specified as part of the InitRequest
153 to inform the proxy about actual target.
157 <term>-q <replaceable>filename</replaceable></term>
159 If specified, CQL configuration will be read from
164 <term>-t <replaceable>displaycharset</replaceable></term>
166 If displaycharset is given, it specifies name of the character set of the
167 output (on the terminal on which YAZ client is running).
171 <term>-u <replaceable>auth</replaceable></term>
173 If specified, the <replaceable>auth</replaceable> string
174 will be used for authentication.
178 <literal>-v</literal> <replaceable>level</replaceable>
180 <simpara>Sets the LOG level to <replaceable>level</replaceable>.
181 Level is a sequence of tokens separated by comma. Each token
182 is a integer or a named LOG item - one of
183 <literal>fatal</literal>,
184 <literal>debug</literal>,
185 <literal>warn</literal>,
186 <literal>log</literal>,
187 <literal>malloc</literal>,
188 <literal>all</literal>,
189 <literal>none</literal>.
190 </simpara></listitem>
201 Makes the YAZ client print hex dumps of packages sent and received
208 <title>COMMANDS</title>
210 The YAZ client accepts the following commands.
213 <varlistentry id="command-open"><term>
214 <literal>open </literal><replaceable>zurl</replaceable>
217 <para>Opens a connection to a server. The syntax for
218 <replaceable>zurl</replaceable> is the same as described
219 above for connecting from the command line.
225 [<literal>(tcp|ssl|unix|http)':'</literal>]<replaceable>host</replaceable>
226 [:<replaceable>port</replaceable>][/<replaceable>base</replaceable>]
231 <literal>quit</literal>
234 <para>Quits YAZ client</para>
237 <varlistentry id="command-find"><term>
238 <literal>find </literal><replaceable>query</replaceable></term>
240 <para>Sends a Search Request using the <replaceable>query</replaceable>
241 given. By default the query is assumed to be PQF. See command
242 <link linkend="command-querytype">querytype</link> for more information.
247 <literal>delete</literal> <replaceable>setname</replaceable></term>
249 <para>Deletes result set with name <replaceable>setname</replaceable>
250 on the server.</para>
254 <literal>base </literal><replaceable>base1</replaceable>
255 <replaceable>base2</replaceable> ...
258 <para>Sets the name(s) of the database(s) to search. One or more
259 databases may be specified separated by blanks. This commands overrides
260 the database given in <replaceable>zurl</replaceable>.
265 <literal>show </literal>
266 [<replaceable>start</replaceable>[+<replaceable>number</replaceable>]]
269 <para>Fetches records by sending a Present Request from the start
271 <replaceable>start</replaceable>
272 a number of records given by <replaceable>number</replaceable>. If
273 <replaceable>start</replaceable> is not given, then the client
274 will fetch from position of the last retrieved record plus 1. If
275 <replaceable>number</replaceable> is not given, then one record will
276 be fetched at a time.
281 <literal>scan</literal> <replaceable>term</replaceable>
285 database index for a term. The syntax resembles the syntax
286 for <link linkend="command-find"><literal>find</literal></link>.
287 If you want to scan for the word <literal>water</literal> you could
294 but if you want to scan only in, say the title field, you would write
302 <literal>setscan</literal> <replaceable>set</replaceable> <replaceable>term</replaceable>
305 <simpara>Scans database index for a term within a result set. This
306 is similar to the scan command but has a result set as its first argument.
311 <literal>scanpos</literal> <replaceable>pos</replaceable>
315 Sets preferred position for scan. This value
316 is used in next scan. By default position is 1.
321 <literal>scansize</literal> <replaceable>size</replaceable>
325 Sets number of entries to be returned by scan. Default
326 number of entries is 20.
331 <literal>scanstep</literal> <replaceable>step</replaceable>
335 Set step-size for scan. This value is used in next scan
336 sent to the target. By default step-size is 0.
340 <varlistentry id="sortspec"><term>
341 <literal>sort</literal> <replaceable>sortspecs</replaceable>
344 <para>Sorts a result set. The sort command takes a
345 sequence of space-separated sort specifications, with each sort
346 specification consisting of two space-separated words (so that the
347 whole specification list is made up of an even number of words).
348 The first word of each specification
349 holds a field (sort criterion) and the second holds flags.
350 If the sort criterion includes <literal>=</literal> it is assumed
351 that the <literal>SortKey</literal> is of type
352 <literal>sortAttributes</literal> using Bib-1: in this case
353 the integer before <literal>=</literal> is
354 the attribute type and the integer following <literal>=</literal>
355 is the attribute value.
356 If no <literal>=</literal> character is in the criterion, it is treated
357 as a sortfield of type InternationalString.
358 The flags word of each sort specification must consist of
360 for case sensitive or <literal>i</literal> for case insensitive, and
361 <literal><</literal> for ascending order or <literal>></literal>
362 for descending order.
367 <literal>sort+</literal>
370 <para>Same as <literal>sort</literal> but stores the sorted
371 result set in a new result set.
376 <literal>authentication</literal> <replaceable>openauth</replaceable>
379 <para>Sets up a authentication string if a server requires
380 authentication (v2 OpenStyle). The authentication string is first
381 sent to the server when the
382 <link linkend="command-open"><literal>open</literal></link> command is
383 issued and the Z39.50 Initialize Request is sent, so this command
384 must be used before <literal>open</literal> in order to be effective.
385 A common convention for the <replaceable>authopen</replaceable> string
386 is that the username - and password is separated by a slash, e.g.
387 <literal>myusername/mysecret</literal>.
393 <literal>sru</literal> <replaceable>method</replaceable> <replaceable>version</replaceable>
396 <para>Selects Web Service method and version.
397 Must be one of <literal>post</literal>,
398 <literal>get</literal>, <literal>soap</literal> (default)
399 or <literal>solr</literal>. Version
400 should be either 1.1, 1.2 or 2.0 for SRU.
401 Other versions are allowed - for testing
402 purposes (version negotiation with SRU server).
403 The version is currently not used for Solr Web Services
409 <literal>list_all</literal>
412 <para>This command displays status and values for many settings.
418 <literal>lslb</literal> <replaceable>n</replaceable>
421 <para>Sets the limit for when no records should be returned
422 together with the search result.
425 url="http://www.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
426 Z39.50 standard on set bounds
434 <literal>ssub</literal> <replaceable>n</replaceable>
437 <para>Sets the limit for when all records should be returned with
441 url="http://www.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
442 Z39.50 standard on set bounds
443 </ulink> for more details.
449 <literal>mspn</literal> <replaceable>n</replaceable>
452 <para>Sets the number of records should be returned if the
453 number of records in the result set is between the values of
454 <literal>lslb</literal> and <literal>ssub</literal>.
457 url="http://www.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
458 Z39.50 standard on set bounds
465 <literal>status</literal>
468 <para>Displays the values of <literal>lslb</literal>,
469 <literal>ssub</literal> and <literal>mspn</literal>.
474 <literal>setname</literal>
477 <para>Switches named result sets on and off. Default is on.
482 <literal>cancel</literal>
485 <para>Sends a Trigger Resource Control Request to the target.
490 <literal>format</literal> <replaceable>oid</replaceable>
493 <para>Sets the preferred transfer syntax for retrieved records.
494 yaz-client supports all the record syntaxes that currently
497 url="http://www.loc.gov/z3950/agency/defns/oids.html#5">
498 Z39.50 Record Syntax Identifiers
500 for more details. Commonly used records syntaxes include usmarc,
506 <literal>elements</literal> <replaceable>e</replaceable>
509 <para>Sets the element set name for the records. Many targets support
510 element sets are B (for brief) and F (for full).
515 <literal>close</literal>
518 <para>Sends a Z39.50 Close APDU and closes connection with the peer
522 <varlistentry id="command-querytype"><term>
523 <literal>querytype</literal> <replaceable>type</replaceable>
526 <para>Sets the query type as used by command
527 <link linkend="command-find"><literal>find</literal></link>.
528 The following is supported:
529 <literal>prefix</literal> for
530 <link linkend="PQF">Prefix Query Notation</link> (Type-1 Query);
531 <literal>ccl</literal> for CCL search (Type-2 Query),
532 <literal>cql</literal> for CQL (Type-104 search with CQL OID),
533 <literal>ccl2rpn</literal> for
534 <link linkend="CCL">CCL</link> to RPN conversion (Type-1 Query).
535 <literal>cql2rpn</literal> for
536 CQL to RPN conversion (Type-1 Query).
541 <literal>attributeset</literal> <replaceable>set</replaceable>
545 Sets attribute set OID for prefix queries (RPN, Type-1).
550 <literal>refid</literal> <replaceable>id</replaceable>
553 <para>Sets reference ID for Z39.50 Request(s).
558 <literal>itemorder</literal>
559 <replaceable>type</replaceable> <replaceable>no</replaceable>
562 <para>Sends an Item Order Request using the ILL External.
563 <replaceable>type</replaceable> is either 1 or 2 which corresponds to
564 ILL-Profile 1 and 2 respectively. The <replaceable>no</replaceable>
565 is the Result Set position of the record to be ordered.
570 <literal>update</literal>
571 <replaceable>action</replaceable>
572 <replaceable>recid</replaceable>
573 <replaceable>doc</replaceable>
576 <para>Sends Item Update Request. The <replaceable>action</replaceable>
577 argument must be the action type: one of <literal>insert</literal>,
578 <literal>replace</literal>, <literal>delete</literal> and
579 <literal>update</literal>. The second argument,
580 <replaceable>recid</replaceable>, is the
581 record identifier (any string). Third argument which is optional is
582 the record document for the request. If doc is preceded with
583 "<", then the following characters are treated as a filename
584 with the records to be updated. Otherwise doc is treated as
585 a document itself. The doc may also be quited in double quotes.
586 If doc is omitted, the last received record (as part of present
587 response or piggybacked search response) is used for the update.
593 <literal>source</literal>
594 <replaceable>filename</replaceable>
597 <para>Executes list of commands from
598 file <replaceable>filename</replaceable>, just like source on
599 most UNIX shells. A single dot (<literal>.</literal>) can be used
607 <replaceable>args</replaceable>
610 <para>Executes command <replaceable>args</replaceable> in subshell
611 using the <literal>system</literal> call.
617 <literal>push_command</literal>
618 <replaceable>command</replaceable>
621 <para>The push_command takes another command as its argument.
622 That command is then added to the history information (so
623 you can retrieve it later). The command itself is not
624 executed. This command only works if you have GNU readline/history
631 <literal>set_apdufile</literal>
632 <replaceable>filename</replaceable>
635 <para>Sets that APDU should be logged to file
636 <replaceable>filename</replaceable>. Another way to achieve
637 APDU log is by using command-line option <literal>-a</literal>.
643 <literal>set_auto_reconnect</literal>
644 <replaceable>flag</replaceable>
647 <para>Specifies whether YAZ client automatically reconnect if
648 target closes connection (Z39.50 only).
651 <replaceable>flag</replaceable> must be either
652 <literal>on</literal> or <literal>off</literal>.
657 <varlistentry id="command-set-auto-wait"><term>
658 <literal>set_auto_wait</literal>
659 <replaceable>flag</replaceable>
662 <para>Specifies whether YAZ client should wait for
663 response protocol packages after a request.
664 By default YAZ client waits (on) for response packages immediately
665 after a command (find, show) has been issued. If <literal>off</literal>
666 is used, YAZ client does not attempt to receive packages automatically.
667 These will have to be manually received when command
668 <link linkend="command-wait-response">
669 <literal>wait_response</literal>
673 <replaceable>flag</replaceable> must be either
674 <literal>on</literal> or <literal>off</literal>.
680 <literal>set_marcdump</literal>
681 <replaceable>filename</replaceable>
684 <para>Specifies that all retrieved records should be appended to
685 file <replaceable>filename</replaceable>. This command does the
686 thing as option <literal>-m</literal>.
692 <literal>schema</literal>
693 <replaceable>schemaid</replaceable>
696 <para>Specifies schema for retrieval.
697 Schema may be specified as an OID for Z39.50.
698 For SRU, schema is a simple string URI.
703 <varlistentry id="command-charset"><term>
704 <literal>charset</literal>
705 <replaceable>negotiationcharset</replaceable>
706 [<replaceable>displaycharset</replaceable>]
707 [[<replaceable>marccharset</replaceable>]]
710 <para>Specifies character set (encoding) for Z39.50
711 negotiation / SRU encoding and/or character set for output (terminal).
714 <replaceable>negotiationcharset</replaceable> is the name
715 of the character set to be negotiated by the server. The special name
716 <literal>-</literal> for <replaceable>negotiationcharset</replaceable>
717 specifies <emphasis>no</emphasis> character set to be negotiated.
720 If <replaceable>displaycharset</replaceable> is given, it specifies name
721 of the character set of the output (on the terminal on which
722 YAZ client is running). To disable conversion of characters
723 to the output encoding, the special name <literal>-</literal> (dash)
725 If the special name <literal>auto</literal> is given, YAZ client will
726 convert strings to the encoding of the
727 terminal as returned by <function>nl_langinfo</function> call.
730 If <replaceable>marcharset</replaceable> is given, it specifies name
731 of the character set of retrieved MARC records from server. See
732 also <literal>marcharset</literal> command.
736 Since character set negotiation takes effect in the Z39.50
737 Initialize Request you should issue this command before
738 command <link linkend="command-open"><literal>open</literal></link>
744 MARC records are not covered by Z39.50 character set negotiation,
745 so that's why there is a separate character that must be known
746 in order to do meaningful conversion(s).
753 <literal>negcharset</literal>
754 <replaceable>charset</replaceable>
757 <para>Specifies character set for negotiation (Z39.50). The
758 argument is the same as second argument for command
759 <link linkend="command-charset"><literal>charset</literal></link>.
765 <literal>displaycharset</literal>
766 <replaceable>charset</replaceable>
769 <para>Specifies character set for output (display). The
770 argument is the same as second argument for command
771 <link linkend="command-charset"><literal>charset</literal></link>.
777 <literal>marccharset</literal>
778 <replaceable>charset</replaceable>
781 <para>Specifies character set for retrieved MARC records so
782 that YAZ client can display them in a character suitable
783 for your display. See <literal>charset</literal> command.
784 If <literal>auto</literal> is given, YAZ will assume
785 that MARC21/USMARC is using MARC8/UTF8 and ISO-8859-1
786 for all other MARC variants. The charset argument is the
787 same as third argument for command
788 <link linkend="command-charset"><literal>charset</literal></link>.
794 <literal>querycharset</literal>
795 <replaceable>charset</replaceable>
798 <para>Specifies character set for query terms for Z39.50 RPN
799 queries and Z39.50 Scan Requests (termListAndStartPoint).
800 This is a pure client-side conversion which converts from
801 displayCharset to queryCharset.
807 <literal>set_cclfile</literal>
808 <replaceable>filename</replaceable>
811 <para>Specifies that CCL fields should be read from file
812 file <replaceable>filename</replaceable>. This command does the
813 thing as option <literal>-c</literal>.
819 <literal>set_cqlfile</literal>
820 <replaceable>filename</replaceable>
823 <para>Specifies that CQL fields should be read from file
824 file <replaceable>filename</replaceable>. This command does the
825 thing as option <literal>-q</literal>.
831 <literal>register_oid</literal>
832 <replaceable>name</replaceable>
833 <replaceable>class</replaceable>
834 <replaceable>OID</replaceable>
837 <para>This command allows you to register your own object
838 identifier - so that instead of entering a long dot-notation
839 you can use a short name instead.
840 The <replaceable>name</replaceable> is your
841 name for the OID, <replaceable>class</replaceable> is the
842 class, and <replaceable>OID</replaceable> is the raw OID in
843 dot notation. Class is one <literal>appctx</literal>,
844 <literal>absyn</literal>, <literal>attet</literal>,
845 <literal>transyn</literal>, <literal>diagset</literal>,
846 <literal>recsyn</literal>, <literal>resform</literal>,
847 <literal>accform</literal>, <literal>extserv</literal>,
848 <literal>userinfo</literal>, <literal>elemspec</literal>,
849 <literal>varset</literal>, <literal>schema</literal>,
850 <literal>tagset</literal>, <literal>general</literal>.
851 If you're in doubt use the <literal>general</literal>
858 <literal>register_tab</literal>
859 <replaceable>command</replaceable>
860 <replaceable>string</replaceable>
863 <para>This command registers a TAB completion string for
870 <literal>sleep</literal>
871 <replaceable>seconds</replaceable>
874 <para>This command makes YAZ client sleep (be idle) for
875 the number of seconds given.
880 <varlistentry id="command-wait-response"><term>
881 <literal>wait_response</literal>
882 [ <replaceable>number</replaceable>]
885 <para>This command makes YAZ client wait for a number of
886 response packages from target. If <replaceable>number</replaceable> is
887 omitted, 1 is assumed.
889 <para>This command is rarely used and is only useful if command
890 <link linkend="command-set-auto-wait">
891 <literal>set_auto_wait</literal>
892 </link> is set to off.
897 <varlistentry id="command-xmles"><term>
898 <literal>xmles</literal>
899 <replaceable>OID</replaceable>
900 <replaceable>doc</replaceable>
903 <para>Sends XML Extended Services request using the OID and doc given.
909 <literal>zversion</literal>
910 <replaceable>ver</replaceable>
913 <para>This command sets Z39.50 version for negotiation.
914 Should be used before
915 <link linkend="command-open"><literal>open</literal></link>.
916 By default 3 (version 3) is used.
922 <literal>options</literal>
923 <replaceable>op1 op2..</replaceable>
926 <para>This command sets Z39.50 options for negotiation.
927 Should be used before
928 <link linkend="command-open"><literal>open</literal></link>.
931 The following options are supported:
932 <literal>search</literal>,
933 <literal>present</literal>,
934 <literal>delSet</literal>,
935 <literal>resourceReport</literal>,
936 <literal>triggerResourceCtrl</literal>,
937 <literal>resourceCtrl</literal>,
938 <literal>accessCtrl</literal>,
939 <literal>scan</literal>,
940 <literal>sort</literal>,
941 <literal>extendedServices</literal>,
942 <literal>level_1Segmentation</literal>,
943 <literal>level_2Segmentation</literal>,
944 <literal>concurrentOperations</literal>,
945 <literal>namedResultSets</literal>,
946 <literal>encapsulation</literal>,
947 <literal>resultCount</literal>,
948 <literal>negotiationModel</literal>,
949 <literal>duplicationDetection</literal>,
950 <literal>queryType104</literal>,
951 <literal>pQESCorrection</literal>,
952 <literal>stringSchema</literal>.
959 <refsect1><title>EXAMPLE</title>
961 The simplest example of a Prefix Query would be something like
969 In those queries no attributes was specified.
970 This leaves it up to the server what fields to search but
971 most servers will search in all fields. Some servers does not
972 support this feature though, and require that some attributes
973 are defined. To add one attribute you could do:
977 where we search in the title field, since the use(1) is title(4).
978 If we want to search in the author field <emphasis>and</emphasis>
979 in the title field, and in the title field using right truncation
980 it could look something like this:
982 f @and @attr 1=1003 knuth @attr 1=4 @attr 5=1 computer
984 Finally using a mix of Bib-1 and GILS attributes could look
987 f @attrset Bib-1 @and @attr GILS 1=2008 Washington @attr 1=21 weather
991 <refsect1><title>FILES</title>
993 <filename>yaz-<version>/client/client.c</filename>
996 <filename>$HOME/.yazclientrc</filename>
999 <filename>$HOME/.yazclient.history</filename>
1002 <refsect1><title>SEE ALSO</title>
1005 <refentrytitle>yaz</refentrytitle>
1006 <manvolnum>7</manvolnum>
1009 <refentrytitle>bib1-attr</refentrytitle>
1010 <manvolnum>7</manvolnum>
1016 <!-- Keep this comment at the end of the file
1019 nxml-child-indent: 1