2 $Id: yaz-client-commands.xml,v 1.8 2005-06-08 11:22:15 adam Exp $
3 Commands for YAZ client.
4 Included in both manual and man page for yaz-client.
7 <varlistentry id="command-open"><term>
8 <literal>open </literal><replaceable>zurl</replaceable>
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.
19 [<literal>(tcp|ssl|unix|http)':'</literal>]<replaceable>host</replaceable>
20 [:<replaceable>port</replaceable>][/<replaceable>base</replaceable>]
25 <literal>quit</literal>
28 <para>Quits YAZ client</para>
31 <varlistentry id="command-find"><term>
32 <literal>find </literal><replaceable>query</replaceable></term>
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>.
41 <literal>delete</literal> <replaceable>setname</replaceable></term>
43 <para>Deletes result set with name <replaceable>setname</replaceable>
48 <literal>base </literal><replaceable>base1</replaceable>
49 <replaceable>base2</replaceable> ...
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>.
59 <literal>show </literal>
60 [<replaceable>start</replaceable>[+<replaceable>number</replaceable>]]
63 <para>Fetches records by sending a Present Request from the start
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
75 <literal>scan</literal> <replaceable>term</replaceable>
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
88 but if you want to scan only in, say the title field, you would write
96 <literal>scanpos</literal> <replaceable>pos</replaceable>
100 Sets preferred position for scan. This value
101 is used in next scan. By default position is 1.
106 <literal>scansize</literal> <replaceable>size</replaceable>
110 Sets number of entries to be returned by scan. Default
111 number of entries is 20.
116 <literal>scanstep</literal> <replaceable>step</replaceable>
120 Set step-size for scan. This value is used in next scan
121 sent to the target. By default step-size is 0.
125 <varlistentry id="sortspec"><term>
126 <literal>sort</literal> <replaceable>sortspecs</replaceable>
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><</literal> for sort ascending and <literal>></literal>
147 <literal>sort+</literal>
150 <para>Same as <literal>sort</literal> but stores the sorted
151 result set in a new result set.
156 <literal>authentication</literal> <replaceable>openauth</replaceable>
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>.
173 <literal>list_all</literal>
176 <para>This command displays status and values for many settings.
182 <literal>lslb</literal> <replaceable>n</replaceable>
185 <para>Sets the limit for when no records should be returned
186 together with the search result.
189 url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
198 <literal>ssub</literal> <replaceable>n</replaceable>
201 <para>Sets the limit for when all records should be returned with
205 url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
207 </ulink> for more details.
213 <literal>mspn</literal> <replaceable>n</replaceable>
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>.
221 url="http://lcweb.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6">
229 <literal>status</literal>
232 <para>Displays the values of <literal>lslb</literal>,
233 <literal>ssub</literal> and <literal>mspn</literal>.
238 <literal>setname</literal>
241 <para>Switches named result sets on and off. Default is on.
246 <literal>cancel</literal>
249 <para>Sends a Trigger Resource Control Request to the target.
254 <literal>format</literal> <replaceable>oid</replaceable>
257 <para>Sets the preferred transfer syntax for retrieved records.
258 yaz-client supports all the record syntaxes that currently
261 url="http://lcweb.loc.gov/z3950/agency/defns/oids.html#5">
264 for more details. Commonly used records syntaxes include usmarc,
270 <literal>elements</literal> <replaceable>e</replaceable>
273 <para>Sets the element set name for the records. Many targets support
274 element sets are B (for brief) and F (for full).
279 <literal>close</literal>
282 <para>Sends a Z39.50 Close APDU and closes connection with the peer
286 <varlistentry id="command-querytype"><term>
287 <literal>querytype</literal> <replaceable>type</replaceable>
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).
305 <literal>attributeset</literal> <replaceable>set</replaceable>
309 Sets attribute set OID for prefix queries (RPN, Type-1).
314 <literal>refid</literal> <replaceable>id</replaceable>
317 <para>Sets reference ID for Z39.50 Request(s).
322 <literal>itemorder</literal>
323 <replaceable>type</replaceable> <replaceable>no</replaceable>
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.
334 <literal>update</literal>
337 <para>Sends Item Update Request. This command sends a "minimal"
338 PDU Update to the target supplying the last received record from
340 If no record has been received from the target this command is ignored
341 and nothing is sent to the target.
348 <replaceable>filename</replaceable>
351 <para>Executes list of commands from
352 file <replaceable>filename</replaceable>, just like source on
360 <replaceable>args</replaceable>
363 <para>Executes command <replaceable>args</replaceable> in subshell
364 using the <literal>system</literal> call.
370 <literal>push_command</literal>
371 <replaceable>command</replaceable>
374 <para>The push_command takes another command as its argument.
375 That command is then added to the history information (so
376 you can retrieve it later). The command itself is not
377 executed. This command only works if you have GNU readline/history
384 <literal>set_apdufile</literal>
385 <replaceable>filename</replaceable>
388 <para>Sets that APDU should be logged to file
389 <replaceable>filename</replaceable>. Another way to achieve
390 APDU log is by using command-line option <literal>-a</literal>.
396 <literal>set_auto_reconnect</literal>
397 <replaceable>flag</replaceable>
400 <para>Specifies whether YAZ client automatically reconnect if
401 target closes connection (Z39.50 only).
404 <replaceable>flag</replaceable> must be either
405 <literal>on</literal> or <literal>off</literal>.
410 <varlistentry id="command-set-auto-wait"><term>
411 <literal>set_auto_wait</literal>
412 <replaceable>flag</replaceable>
415 <para>Specifies whether YAZ client should wait for
416 response protocol packages after a request.
417 By default YAZ client waits (on) for response packages immediately
418 after a command (find, show) has been issued. If <literal>off</literal>
419 is used, YAZ client does not attempt to receive packages automatically.
420 These will have to be manually received when command
421 <link linkend="command-wait-response">
422 <literal>wait_response</literal>
426 <replaceable>flag</replaceable> must be either
427 <literal>on</literal> or <literal>off</literal>.
433 <literal>set_marcdump</literal>
434 <replaceable>filename</replaceable>
437 <para>Specifies that all retrieved records should be appended to
438 file <replaceable>filename</replaceable>. This command does the
439 thing as option <literal>-m</literal>.
445 <literal>schema</literal>
446 <replaceable>schemaid</replaceable>
449 <para>Specifies schema for retrieval.
450 Schema may be specified as an OID for Z39.50.
451 For SRW, schema is a simple string URI.
456 <varlistentry id="command-charset"><term>
457 <literal>charset</literal>
458 <replaceable>negotiationcharset</replaceable>
459 [<replaceable>displaycharset</replaceable>]
460 [[<replaceable>marccharset</replaceable>]]
463 <para>Specifies character set (encoding) for Z39.50
464 negotiation / SRW encoding and/or character set for output (terminal).
467 <replaceable>negotiationcharset</replaceable> is the name
468 of the character set to be negotiated by the server. The special name
469 <literal>-</literal> for <replaceable>negotiationcharset</replaceable>
470 specifies <emphasis>no</emphasis> character set to be negotiated.
473 If <replaceable>displaycharset</replaceable> is given, it specifies name
474 of the character set of the output (on the terminal on which
475 YAZ client is running). To disable conversion of characters
476 to the output encoding, the special name <literal>-</literal> (dash)
478 If the special name <literal>auto</literal> is given, YAZ client will
479 convert strings to the encoding of the
480 terminal as returned by <function>nl_langinfo</function> call.
483 If <replaceable>marcharset</replaceable> is given, it specifies name
484 of the character set of retrieved MARC records from server. See
485 also <literal>marcharset</literal> command.
489 Since character set negotation takes effect in the Z39.50
490 Initialize Request you should issue this command before
491 command <link linkend="command-open"><literal>open</literal></link>
497 MARC records are not covered by Z39.50 character set negotiation,
498 so that's why there is a separate character that must be known
499 in order to do meaningful converson(s).
506 <literal>negcharset</literal>
507 <replaceable>charset</replaceable>
510 <para>Specifies character set for negotiation (Z39.50). The
511 argument is the same as second argument for command
512 <link linkend="command-charset"><literal>charset</literal></link>.
518 <literal>displaycharset</literal>
519 <replaceable>charset</replaceable>
522 <para>Specifies character set for output (display). The
523 argument is the same as second argument for command
524 <link linkend="command-charset"><literal>charset</literal></link>.
530 <literal>marccharset</literal>
531 <replaceable>charset</replaceable>
534 <para>Specifies character set for retrieved MARC records so
535 that YAZ client can display them in a character suitable
536 for your display. See <literal>charset</literal> command.
537 If <literal>auto</literal> is given, YAZ will assume
538 that MARC21/USMARC is using MARC8/UTF8 and ISO-8859-1
539 for all other MARC variants. The charset argument is the
540 same as third argument for command
541 <link linkend="command-charset"><literal>charset</literal></link>.
547 <literal>set_cclfile</literal>
548 <replaceable>filename</replaceable>
551 <para>Specifies that CCL fields should be read from file
552 file <replaceable>filename</replaceable>. This command does the
553 thing as option <literal>-c</literal>.
559 <literal>set_cqlfile</literal>
560 <replaceable>filename</replaceable>
563 <para>Specifies that CQL fields should be read from file
564 file <replaceable>filename</replaceable>. This command does the
565 thing as option <literal>-q</literal>.
571 <literal>register_oid</literal>
572 <replaceable>name</replaceable>
573 <replaceable>class</replaceable>
574 <replaceable>OID</replaceable>
577 <para>This command allows you to register your own object
578 identifier - so that instead of entering a long dot-notation
579 you can use a short name instead.
580 The <replaceable>name</replaceable> is your
581 name for the OID, <replaceable>class</replaceable> is the
582 class, and <replaceable>OID</replaceable> is the raw OID in
583 dot notation. Class is one <literal>appctx</literal>,
584 <literal>absyn</literal>, <literal>attet</literal>,
585 <literal>transyn</literal>, <literal>diagset</literal>,
586 <literal>recsyn</literal>, <literal>resform</literal>,
587 <literal>accform</literal>, <literal>extserv</literal>,
588 <literal>userinfo</literal>, <literal>elemspec</literal>,
589 <literal>varset</literal>, <literal>schema</literal>,
590 <literal>tagset</literal>, <literal>general</literal>.
591 If you're in doubt use the <literal>general</literal>
598 <literal>register_tab</literal>
599 <replaceable>command</replaceable>
600 <replaceable>string</replaceable>
603 <para>This command registers a TAB completion string for
610 <literal>sleep</literal>
611 <replaceable>seconds</replaceable>
614 <para>This command makes YAZ client sleep (be idle) for
615 the number of seconds given.
620 <varlistentry id="command-wait-response"><term>
621 <literal>wait_response</literal>
622 [ <replaceable>number</replaceable>]
625 <para>This command makes YAZ client wait for a number of
626 response packages from target. If <literal>number</literal> is
627 omitted, 1 is assumed.
629 <para>This command is rarely used and is only useful if command
630 <link linkend="command-set-auto-wait">
631 <literal>set_auto_wait</literal>
632 </link> is set to off.
638 <literal>zversion</literal>
639 <replaceable>ver</replaceable>
642 <para>This command sets Z39.50 version for negotiation.
643 Should be used before
644 <link linkend="command-open"><literal>open</literal></link>.
645 By default 3 (version 3) is used.
651 <literal>options</literal>
652 <replaceable>op1 op2..</replaceable>
655 <para>This command sets Z39.50 options for negotiation.
656 Should be used before
657 <link linkend="command-open"><literal>open</literal></link>.
660 The following options are supported:
661 <literal>search</literal>,
662 <literal>present</literal>,
663 <literal>delSet</literal>,
664 <literal>resourceReport</literal>,
665 <literal>triggerResourceCtrl</literal>,
666 <literal>resourceCtrl</literal>,
667 <literal>accessCtrl</literal>,
668 <literal>scan</literal>,
669 <literal>sort</literal>,
670 <literal>extendedServices</literal>,
671 <literal>level_1Segmentation</literal>,
672 <literal>level_2Segmentation</literal>,
673 <literal>concurrentOperations</literal>,
674 <literal>namedResultSets</literal>,
675 <literal>encapsulation</literal>,
676 <literal>resultCount</literal>,
677 <literal>negotiationModel</literal>,
678 <literal>duplicationDetection</literal>,
679 <literal>queryType104</literal>,
680 <literal>pQESCorrection</literal>,
681 <literal>stringSchema</literal>.
687 <!-- Keep this comment at the end of the file
692 sgml-minimize-attributes:nil
693 sgml-always-quote-attributes:t
696 sgml-parent-document: "yaz.xml"
697 sgml-local-catalogs: nil
698 sgml-namecase-general:t