1c21bc585bbb9bbdc6c03229593b845f5c6c74d5
[yaz-moved-to-github.git] / doc / yaz-client-commands.xml
1 <!-- 
2    $Id: yaz-client-commands.xml,v 1.10 2005-06-23 13:09:42 adam Exp $
3    Commands for YAZ client.
4    Included in both manual and man page for yaz-client.
5 -->
6 <variablelist>
7  <varlistentry id="command-open"><term>
8    <literal>open </literal><replaceable>zurl</replaceable>
9   </term>
10   <listitem>
11    <para>Opens a connection to a server. The syntax for
12     <replaceable>zurl</replaceable> is the same as described
13     above for connecting from the command line.
14    </para>
15    <para>
16     Syntax:
17    </para>
18    <para>
19     [<literal>(tcp|ssl|unix|http)':'</literal>]<replaceable>host</replaceable>
20     [:<replaceable>port</replaceable>][/<replaceable>base</replaceable>]
21    </para>
22   </listitem>
23  </varlistentry>
24  <varlistentry><term>
25    <literal>quit</literal>
26   </term>
27   <listitem>
28    <para>Quits YAZ client</para>
29   </listitem>
30  </varlistentry>
31  <varlistentry id="command-find"><term>
32    <literal>find </literal><replaceable>query</replaceable></term>
33   <listitem>
34    <para>Sends a Search Request using the <replaceable>query</replaceable>
35     given. By default the query is assumed to be PQF. See command
36     <link linkend="command-querytype"><literal>querytype</literal></link>.
37    </para>
38   </listitem>
39  </varlistentry>
40  <varlistentry><term>
41    <literal>delete</literal> <replaceable>setname</replaceable></term>
42   <listitem>
43    <para>Deletes result set with name <replaceable>setname</replaceable>
44     on the server.</para>
45   </listitem>
46  </varlistentry>
47  <varlistentry><term>
48    <literal>base </literal><replaceable>base1</replaceable>
49    <replaceable>base2</replaceable> ...
50   </term>
51   <listitem>
52    <para>Sets the name(s) of the database(s) to search. One or more
53     databases may be specified separated by blanks. This commands overrides
54     the database given in <replaceable>zurl</replaceable>.
55    </para>
56   </listitem>
57  </varlistentry>
58  <varlistentry><term>
59    <literal>show </literal>
60    [<replaceable>start</replaceable>[+<replaceable>number</replaceable>]]
61   </term>
62   <listitem>
63    <para>Fetches records by sending a Present Request from the start
64     position given by
65     <replaceable>start</replaceable>
66     a number of records given by <replaceable>number</replaceable>. If
67     <replaceable>start</replaceable> is not given, then the client
68     will fetch from position of the last retrieved record plus 1. If
69     <replaceable>number</replaceable> is not given, then one record will
70     be fetched at a time.
71    </para>
72   </listitem>
73  </varlistentry>
74  <varlistentry><term>
75    <literal>scan</literal> <replaceable>term</replaceable>
76   </term>
77   <listitem>
78    <simpara>Scans
79     database index for a term. The syntax resembles the syntax
80     for <link linkend="command-find"><literal>find</literal></link>.
81     If you want to scan for the word <literal>water</literal> you could
82     write
83    </simpara>
84    <screen>
85     scan water
86    </screen>
87    <simpara>
88     but if you want to scan only in, say the title field, you would write
89    </simpara>
90    <screen>
91     scan @attr 1=4 water
92    </screen>
93   </listitem>
94  </varlistentry>
95  <varlistentry><term>
96    <literal>scanpos</literal> <replaceable>pos</replaceable>
97   </term>
98   <listitem>
99    <simpara>
100     Sets preferred position for scan. This value
101     is used in next scan. By default position is 1.
102    </simpara>
103   </listitem>
104  </varlistentry>
105  <varlistentry><term>
106    <literal>scansize</literal> <replaceable>size</replaceable>
107   </term>
108   <listitem>
109    <simpara>
110     Sets number of entries to be returned by scan. Default
111     number of entries is 20.
112    </simpara>
113   </listitem>
114  </varlistentry>
115  <varlistentry><term>
116    <literal>scanstep</literal> <replaceable>step</replaceable>
117   </term>
118   <listitem>
119    <simpara>
120     Set step-size for scan. This value is used in next scan
121     sent to the target. By default step-size is 0.
122    </simpara>
123   </listitem>
124  </varlistentry>
125  <varlistentry id="sortspec"><term>
126    <literal>sort</literal> <replaceable>sortspecs</replaceable>
127   </term>
128   <listitem>
129    <para>Sorts a result set. The sort command takes a
130     sequence of sort specifications. A sort
131     specification holds a field (sort criteria) and is followed by flags.
132     If the sort criteria includes <literal>=</literal> it is assumed
133     that the sort SortKey is of type sortAttributes using Bib-1.
134     The integer before <literal>=</literal> is
135     the attribute type and the integer following <literal>=</literal>
136     is the attribute value.
137     If no <literal>=</literal> is in the SortKey it is treated as a
138     sortfield-type of type InternationalString.
139     Flags observed are: <literal>s</literal>
140     for case sensitive, <literal>i</literal> for case insensitive,
141     <literal>&lt;</literal> for sort ascending and <literal>&gt;</literal>
142     for sort descending.
143    </para>
144   </listitem>
145  </varlistentry>
146  <varlistentry><term>
147    <literal>sort+</literal>
148   </term>
149   <listitem>
150    <para>Same as <literal>sort</literal> but stores the sorted
151     result set in a new result set.
152    </para>
153   </listitem>
154  </varlistentry>
155  <varlistentry><term>
156    <literal>authentication</literal> <replaceable>openauth</replaceable>
157   </term>
158   <listitem>
159    <para>Sets up a authentication string if a server requires
160     authentication (v2 OpenStyle). The authentication string is first
161     sent to the server when the 
162     <link linkend="command-open"><literal>open</literal></link> command is
163     issued and the Z39.50 Initialize Request is sent, so this command
164     must be used before <literal>open</literal> in order to be effective.
165     A common convention for the <replaceable>authopen</replaceable> string
166     is that the username - and password is separated by a slash, e.g.
167     <literal>myusername/mysecret</literal>.
168    </para>
169   </listitem>
170  </varlistentry>
171
172  <varlistentry><term>
173    <literal>list_all</literal>
174   </term>
175   <listitem>
176    <para>This command displays status and values for many settings.
177    </para>
178   </listitem>
179  </varlistentry>
180  
181  <varlistentry><term>
182    <literal>lslb</literal> <replaceable>n</replaceable>
183   </term>
184   <listitem>
185    <para>Sets the limit for when no records should be returned
186     together with the search result.
187     See the
188     <ulink
189            url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
190      Z39.50 standard
191     </ulink>
192     for more details.
193    </para>
194   </listitem>
195  </varlistentry>
196
197  <varlistentry><term>
198    <literal>ssub</literal> <replaceable>n</replaceable>
199   </term>
200   <listitem>
201    <para>Sets the limit for when all records should be returned with
202     the search result.
203     See the
204     <ulink
205            url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
206      Z39.50 standard
207     </ulink> for more details.
208    </para>
209   </listitem>
210  </varlistentry>
211  
212  <varlistentry><term>
213    <literal>mspn</literal> <replaceable>n</replaceable>
214   </term>
215   <listitem>
216    <para>Sets the number of records should be returned if the
217     number of records in the result set is between the values of
218     <literal>lslb</literal> and <literal>ssub</literal>.
219     See the
220     <ulink
221            url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
222      Z39.50 standard
223     </ulink>
224     for more details.
225    </para>
226   </listitem>
227  </varlistentry>
228  <varlistentry><term>
229    <literal>status</literal>
230   </term>
231   <listitem>
232    <para>Displays the values of <literal>lslb</literal>,
233     <literal>ssub</literal> and <literal>mspn</literal>.
234    </para>
235   </listitem>
236  </varlistentry>
237  <varlistentry><term>
238    <literal>setname</literal>
239   </term>
240   <listitem>
241    <para>Switches named result sets on and off. Default is on.
242    </para>
243   </listitem>
244  </varlistentry>
245  <varlistentry><term>
246    <literal>cancel</literal>
247   </term>
248   <listitem>
249    <para>Sends a Trigger Resource Control Request to the target.
250    </para>
251   </listitem>
252  </varlistentry>
253  <varlistentry><term>
254    <literal>format</literal> <replaceable>oid</replaceable>
255   </term>
256   <listitem>
257    <para>Sets the preferred transfer syntax for retrieved records.
258     yaz-client supports all the record syntaxes that currently
259     are registered. See
260     <ulink
261            url="http://lcweb.loc.gov/z3950/agency/defns/oids.html#5">
262      Z39.50 Standard
263     </ulink>
264     for more details. Commonly used records syntaxes include usmarc,
265     sutrs, grs1 and xml.
266    </para>
267   </listitem>
268  </varlistentry>
269  <varlistentry><term>
270    <literal>elements</literal> <replaceable>e</replaceable>
271   </term>
272   <listitem>
273    <para>Sets the element set name for the records. Many targets support
274     element sets are B (for brief) and F (for full).
275    </para>
276   </listitem>
277  </varlistentry>
278  <varlistentry><term>
279    <literal>close</literal>
280   </term>
281   <listitem>
282    <para>Sends a Z39.50 Close APDU and closes connection with the peer
283    </para>
284   </listitem>
285  </varlistentry>
286  <varlistentry id="command-querytype"><term>
287    <literal>querytype</literal> <replaceable>type</replaceable>
288   </term>
289   <listitem>
290    <para>Sets the query type as used by command 
291    <link linkend="command-find"><literal>find</literal></link>.
292     The following is supported:
293     <literal>prefix</literal> for
294         <link linkend="PQF">Prefix Query Notation</link> (Type-1 Query);
295     <literal>ccl</literal> for CCL search (Type-2 Query),
296     <literal>cql</literal> for CQL (Type-104 search with CQL OID),
297     <literal>ccl2rpn</literal> for
298         <link linkend="CCL">CCL</link> to RPN conversion (Type-1 Query).
299     <literal>cql2rpn</literal> for
300         CQL to RPN conversion (Type-1 Query).
301    </para>
302   </listitem>
303  </varlistentry>
304  <varlistentry><term>
305    <literal>attributeset</literal> <replaceable>set</replaceable>
306   </term>
307   <listitem>
308    <para>
309     Sets attribute set OID for prefix queries (RPN, Type-1).
310    </para>
311   </listitem>
312  </varlistentry>
313  <varlistentry><term>
314    <literal>refid</literal> <replaceable>id</replaceable>
315   </term>
316   <listitem>
317    <para>Sets reference ID for Z39.50 Request(s).
318    </para>
319   </listitem>
320  </varlistentry>
321  <varlistentry><term>
322    <literal>itemorder</literal>
323    <replaceable>type</replaceable> <replaceable>no</replaceable>
324   </term>
325   <listitem>
326    <para>Sends an Item Order Request using the ILL External. 
327     <replaceable>type</replaceable> is either 1 or 2 which corresponds to
328     ILL-Profile 1 and 2 respectively. The <replaceable>no</replaceable>
329     is the Result Set position of the record to be ordered.
330    </para>
331   </listitem>
332  </varlistentry>
333  <varlistentry><term>
334    <literal>update</literal>
335    <replaceable>action</replaceable>
336    <replaceable>recid</replaceable>
337    <replaceable>doc</replaceable>
338   </term>
339   <listitem>
340    <para>Sends Item Update Request. The <replaceable>action</replaceable>
341     argument must be the action type: one of <literal>insert</literal>,
342     <literal>replace</literal>, <literal>delete</literal> and
343     <literal>update</literal>. The second argument, 
344     <replaceable>recid</replaceable>, is the
345     record identifier (any string). Third argument which is optional is
346     the record document for the request. If doc is a quoted string
347     (double quotes) the string content is used verbatim. If doc is not
348     a quoted string, it is assumed to be a filename which is read, then
349     sent as the docuemnt content. If doc is omitted, the last received
350     record (as parf of present response or piggybacked search response) 
351     is used for the update.
352    </para>
353   </listitem>
354  </varlistentry>
355
356  <varlistentry><term>
357    <literal>.</literal>
358    <replaceable>filename</replaceable>
359   </term>
360   <listitem>
361    <para>Executes list of commands from
362     file <replaceable>filename</replaceable>, just like source on
363     most UNIX shells.
364    </para>
365   </listitem>
366  </varlistentry>
367
368  <varlistentry><term>
369    <literal>!</literal>
370    <replaceable>args</replaceable>
371   </term>
372   <listitem>
373    <para>Executes command <replaceable>args</replaceable> in subshell
374     using the <literal>system</literal> call.
375    </para>
376   </listitem>
377  </varlistentry>
378
379  <varlistentry><term>
380    <literal>push_command</literal>
381    <replaceable>command</replaceable>
382   </term>
383   <listitem>
384    <para>The push_command takes another command as its argument.
385     That command is then added to the history information (so
386     you can retrieve it later). The command itself is not
387     executed. This command only works if you have GNU readline/history
388     enabled.
389    </para>
390   </listitem>
391  </varlistentry>
392
393  <varlistentry><term>
394    <literal>set_apdufile</literal>
395    <replaceable>filename</replaceable>
396   </term>
397   <listitem>
398    <para>Sets that APDU should be logged to file
399     <replaceable>filename</replaceable>. Another way to achieve
400     APDU log is by using command-line option <literal>-a</literal>.
401    </para>
402   </listitem>
403  </varlistentry>
404
405  <varlistentry><term>
406    <literal>set_auto_reconnect</literal>
407    <replaceable>flag</replaceable>
408   </term>
409   <listitem>
410    <para>Specifies whether YAZ client automatically reconnect if
411     target closes connection (Z39.50 only).
412    </para>
413    <para>
414     <replaceable>flag</replaceable> must be either
415     <literal>on</literal> or <literal>off</literal>.
416    </para>
417   </listitem>
418  </varlistentry>
419
420  <varlistentry id="command-set-auto-wait"><term>
421    <literal>set_auto_wait</literal>
422    <replaceable>flag</replaceable>
423   </term>
424   <listitem>
425    <para>Specifies whether YAZ client should wait for
426    response protocol packages after a request.
427    By default YAZ client waits (on) for response packages immediately
428    after a command (find, show) has been issued. If <literal>off</literal>
429    is used, YAZ client does not attempt to receive packages automatically.
430    These will have to be manually received when command 
431    <link linkend="command-wait-response">
432     <literal>wait_response</literal>
433    </link> is used.
434    </para>
435    <para>
436    <replaceable>flag</replaceable> must be either
437    <literal>on</literal> or <literal>off</literal>.
438    </para>
439   </listitem>
440  </varlistentry>
441
442  <varlistentry><term>
443    <literal>set_marcdump</literal>
444    <replaceable>filename</replaceable>
445   </term>
446   <listitem>
447    <para>Specifies that all retrieved records should be appended to
448     file <replaceable>filename</replaceable>. This command does the
449     thing as option <literal>-m</literal>.
450    </para>
451   </listitem>
452  </varlistentry>
453
454  <varlistentry><term>
455    <literal>schema</literal>
456    <replaceable>schemaid</replaceable>
457   </term>
458   <listitem>
459    <para>Specifies schema for retrieval.
460     Schema may be specified as an OID for Z39.50.
461     For SRW, schema is a simple string URI.
462    </para>
463   </listitem>
464  </varlistentry>
465
466  <varlistentry id="command-charset"><term>
467    <literal>charset</literal>
468    <replaceable>negotiationcharset</replaceable>
469    [<replaceable>displaycharset</replaceable>]
470    [[<replaceable>marccharset</replaceable>]]
471   </term>
472   <listitem>
473    <para>Specifies character set (encoding) for Z39.50
474     negotiation / SRW encoding and/or character set for output (terminal).
475    </para>
476    <para>
477     <replaceable>negotiationcharset</replaceable> is the name
478     of the character set to be negotiated by the server. The special name
479     <literal>-</literal> for <replaceable>negotiationcharset</replaceable>
480     specifies <emphasis>no</emphasis> character set to be negotiated.
481    </para>
482    <para>
483     If <replaceable>displaycharset</replaceable> is given, it specifies name
484     of the character set of the output (on the terminal on which
485     YAZ client is running). To disable conversion of characters
486     to the output encoding, the special name <literal>-</literal> (dash)
487     can be used.
488     If the special name <literal>auto</literal> is given, YAZ client will
489     convert strings to the encoding of the
490     terminal as returned by <function>nl_langinfo</function> call.
491    </para>
492    <para>
493     If <replaceable>marcharset</replaceable> is given, it specifies name
494     of the character set of retrieved MARC records from server. See
495     also <literal>marcharset</literal> command.
496    </para>
497    <note>
498     <para>
499      Since character set negotation takes effect in the Z39.50
500      Initialize Request you should issue this command before
501      command <link linkend="command-open"><literal>open</literal></link>
502      is used.
503     </para>
504    </note>
505    <note>
506     <para>
507      MARC records are not covered by Z39.50 character set negotiation,
508      so that's why there is a separate character that must be known
509      in order to do meaningful converson(s).
510     </para>
511    </note>
512   </listitem>
513  </varlistentry>
514
515  <varlistentry><term>
516    <literal>negcharset</literal>
517    <replaceable>charset</replaceable>
518   </term>
519   <listitem>
520    <para>Specifies character set for negotiation (Z39.50). The
521     argument is the same as second argument for command
522     <link linkend="command-charset"><literal>charset</literal></link>.
523    </para>
524   </listitem>
525  </varlistentry>
526
527  <varlistentry><term>
528    <literal>displaycharset</literal>
529    <replaceable>charset</replaceable>
530   </term>
531   <listitem>
532    <para>Specifies character set for output (display). The
533     argument is the same as second argument for command 
534     <link linkend="command-charset"><literal>charset</literal></link>.
535    </para>
536   </listitem>
537  </varlistentry>
538
539  <varlistentry><term>
540    <literal>marccharset</literal>
541    <replaceable>charset</replaceable>
542   </term>
543   <listitem>
544    <para>Specifies character set for retrieved MARC records so
545     that YAZ client can display them in a character suitable
546     for your display. See <literal>charset</literal> command.
547     If <literal>auto</literal> is given, YAZ will assume
548     that MARC21/USMARC is using MARC8/UTF8 and ISO-8859-1
549     for all other MARC variants. The charset argument is the
550     same as third argument for command
551     <link linkend="command-charset"><literal>charset</literal></link>.
552    </para>
553   </listitem>
554  </varlistentry>
555
556  <varlistentry><term>
557    <literal>set_cclfile</literal>
558    <replaceable>filename</replaceable>
559   </term>
560   <listitem>
561    <para>Specifies that CCL fields should be read from file
562     file <replaceable>filename</replaceable>. This command does the
563     thing as option <literal>-c</literal>.
564    </para>
565   </listitem>
566  </varlistentry>
567
568  <varlistentry><term>
569    <literal>set_cqlfile</literal>
570    <replaceable>filename</replaceable>
571   </term>
572   <listitem>
573    <para>Specifies that CQL fields should be read from file
574     file <replaceable>filename</replaceable>. This command does the
575     thing as option <literal>-q</literal>.
576    </para>
577   </listitem>
578  </varlistentry>
579
580  <varlistentry><term>
581    <literal>register_oid</literal>
582    <replaceable>name</replaceable>
583    <replaceable>class</replaceable>
584    <replaceable>OID</replaceable>
585   </term>
586   <listitem>
587    <para>This command allows you to register your own object
588     identifier - so that instead of entering a long dot-notation
589     you can use a short name instead.
590     The <replaceable>name</replaceable> is your
591     name for the OID, <replaceable>class</replaceable> is the
592     class, and <replaceable>OID</replaceable> is the raw OID in
593     dot notation. Class is one <literal>appctx</literal>,
594     <literal>absyn</literal>, <literal>attet</literal>,
595     <literal>transyn</literal>, <literal>diagset</literal>,
596     <literal>recsyn</literal>, <literal>resform</literal>,
597     <literal>accform</literal>, <literal>extserv</literal>,
598     <literal>userinfo</literal>, <literal>elemspec</literal>,
599     <literal>varset</literal>, <literal>schema</literal>,
600     <literal>tagset</literal>, <literal>general</literal>.
601     If you're in doubt use the <literal>general</literal>
602     class.
603    </para>
604   </listitem>
605  </varlistentry>
606
607  <varlistentry><term>
608    <literal>register_tab</literal>
609    <replaceable>command</replaceable>
610    <replaceable>string</replaceable>
611   </term>
612   <listitem>
613    <para>This command registers a TAB completion string for
614     the command given.
615    </para>
616   </listitem>
617  </varlistentry>
618
619  <varlistentry><term>
620    <literal>sleep</literal>
621    <replaceable>seconds</replaceable>
622   </term>
623   <listitem>
624    <para>This command makes YAZ client sleep (be idle) for
625     the number of seconds given.
626    </para>
627   </listitem>
628  </varlistentry>
629
630  <varlistentry id="command-wait-response"><term>
631    <literal>wait_response</literal>
632    [ <replaceable>number</replaceable>]
633   </term>
634   <listitem>
635    <para>This command makes YAZ client wait for a number of
636     response packages from target. If <replaceable>number</replaceable> is
637     omitted, 1 is assumed. 
638    </para>
639    <para>This command is rarely used and is only useful if command
640     <link linkend="command-set-auto-wait">
641      <literal>set_auto_wait</literal>
642     </link> is set to off.
643    </para>
644   </listitem>
645  </varlistentry>
646
647  <varlistentry id="command-xmles"><term>
648    <literal>xmles</literal>
649    <replaceable>OID</replaceable>
650    <replaceable>doc</replaceable>
651   </term>
652   <listitem>
653    <para>Sends XML Extended Services request using the OID and doc given.
654    </para>
655   </listitem>
656  </varlistentry>
657
658  <varlistentry><term>
659    <literal>zversion</literal>
660    <replaceable>ver</replaceable>
661   </term>
662   <listitem>
663    <para>This command sets Z39.50 version for negotiation. 
664     Should be used before 
665     <link linkend="command-open"><literal>open</literal></link>.
666     By default 3 (version 3) is used.
667    </para>
668   </listitem>
669  </varlistentry>
670
671  <varlistentry><term>
672    <literal>options</literal>
673    <replaceable>op1 op2..</replaceable>
674   </term>
675   <listitem>
676    <para>This command sets Z39.50 options for negotiation. 
677     Should be used before 
678    <link linkend="command-open"><literal>open</literal></link>.
679    </para>
680    <para>
681     The following options are supported:
682     <literal>search</literal>,  
683     <literal>present</literal>,  
684     <literal>delSet</literal>,  
685     <literal>resourceReport</literal>,  
686     <literal>triggerResourceCtrl</literal>,  
687     <literal>resourceCtrl</literal>,  
688     <literal>accessCtrl</literal>,  
689     <literal>scan</literal>,  
690     <literal>sort</literal>,  
691     <literal>extendedServices</literal>,  
692     <literal>level_1Segmentation</literal>,  
693     <literal>level_2Segmentation</literal>,  
694     <literal>concurrentOperations</literal>,  
695     <literal>namedResultSets</literal>,  
696     <literal>encapsulation</literal>,  
697     <literal>resultCount</literal>,  
698     <literal>negotiationModel</literal>,  
699     <literal>duplicationDetection</literal>,  
700     <literal>queryType104</literal>,  
701     <literal>pQESCorrection</literal>,  
702     <literal>stringSchema</literal>.
703    </para>
704   </listitem>
705  </varlistentry>
706  
707 </variablelist>
708 <!-- Keep this comment at the end of the file
709 Local variables:
710 mode: sgml
711 sgml-omittag:t
712 sgml-shorttag:t
713 sgml-minimize-attributes:nil
714 sgml-always-quote-attributes:t
715 sgml-indent-step:1
716 sgml-indent-data:t
717 sgml-parent-document: "yaz.xml"
718 sgml-local-catalogs: nil
719 sgml-namecase-general:t
720 End:
721 -->