1YAZ-CLIENT(1) Commands YAZ-CLIENT(1)
2
6 yaz-client - Z39.50/SRU client for implementors
7
9 yaz-client [-a apdulog] [-b berdump] [-c cclfile] [-d dump]
10 [-f cmdfile] [-k size] [-m marclog] [-p proxy-addr]
11 [-q cqlfile] [-t dispcharset] [-u auth] [-v loglevel] [-V]
12 [-x] [server-addr]
13
15 yaz-client is a Z39.50[1]/SRU[2] client (origin) with a simple command
16 line interface that allows you to test behavior and performance of
17 Z39.50 targets and SRU servers.
18 From YAZ version 4.1.0 yaz-client may also operate as a Solr[3] Web
20 Service client.
21 If the server-addr is specified, the client creates a connection to the
23 Z39.50/SRU target at the address given.
24 When yaz-client is started it tries to read commands from one of the
26 following files:
27 · Command file if it is given by option -f.
29 · .yazclientrc in current working directory.
31 · .yazclientrc in the user's home directory. The value of the HOME is
33 used to determine the home directory. Normally, HOME is only set on
34 POSIX systems such as Linux, FreeBSD, Solaris.
35
38 -a filename
39 If specified, logging of protocol packages will be appended to the
40 file given. If filename is specified as -, the output is written to
41 stdout.
42 -b filename
44 If specified, YAZ will dump BER data in readable notation to the
45 file specified. If filename is specified as - the output is written
46 to stdout.
47 -c filename
49 If specified, CCL configuration will be read from the file given.
50 -d dump
52 If specified, YAZ will dump BER data for all PDUs sent and received
53 to individual files, named dump.DDD.raw, where DDD is 001, 002,
54 003, ..
55 -f cmdfile
57 Reads commands from cmdfile. When this option is used, YAZ client
58 does not read .yazclientrc from current directory or home
59 directory.
60 -k size
62 Sets preferred messages and maximum record size for Initialize
63 Request in kilobytes. Default value is 65536 (64 MB).
64 -m filename
66 If specified, retrieved records will be appended to the file given.
67 -p proxy-addr
69 If specified, the client will use the proxy at the address given.
70 YAZ client will connect to a proxy on the address and port given.
71 The actual target will be specified as part of the InitRequest to
72 inform the proxy about the actual target.
73 -q filename
75 If specified, CQL configuration will be read from the file given.
76 -t displaycharset
78 If displaycharset is given, it specifies name of the character set
79 of the output (on the terminal on which YAZ client is running).
80 -u auth
82 If specified, the auth string will be used for authentication.
83 -v level
85 Sets the LOG level to level. Level is a sequence of tokens
86 separated by comma. Each token is a integer or a named LOG item -
87 one of fatal, debug, warn, log, malloc, all, none.
88 -V
90 Prints YAZ version.
91 -x
93 Makes the YAZ client print hex dumps of packages sent and received
94 on standard output.
95
97 The YAZ client accepts the following commands.
98 open zurl
100 Opens a connection to a server. The syntax for zurl is the same as
101 described above for connecting from the command line.
102 Syntax:
104 [(tcp|ssl|unix|http)':']host [:port][/base]
106 quit
108 Quits YAZ client
109 find query
111 Sends a Search Request using the query given. By default the query
112 is assumed to be PQF. See command querytype for more information.
113 delete setname
115 Deletes result set with name setname on the server.
116 base base1 base2 ...
118 Sets the name(s) of the database(s) to search. One or more
119 databases may be specified, separated by blanks. This command
120 overrides the database given in zurl.
121 show [start[+number]]
123 Fetches records by sending a Present Request from the start
124 position given by start and a number of records given by number. If
125 start is not given, then the client will fetch from the position of
126 the last retrieved record plus 1. If number is not given, then one
127 record will be fetched at a time.
128 scan term
130 Scans database index for a term. The syntax resembles the syntax
131 for find. If you want to scan for the word water you could write
132 scan water
134 but if you want to scan only in, say the title field, you would
137 write
138 scan @attr 1=4 water
140 setscan set term
143 Scans database index for a term within a result set. This is
144 similar to the scan command but has a result set as its first
145 argument.
146 scanpos pos
148 Sets preferred position for scan. This value is used in the next
149 scan. By default, position is 1.
150 scansize size
152 Sets number of entries to be returned by scan. Default number of
153 entries is 20.
154 scanstep step
156 Set step-size for scan. This value is used in the next scan sent to
157 the target. By default step-size is 0.
158 sort sortspecs
160 Sorts a result set. The sort command takes a sequence of
161 space-separated sort specifications, with each sort specification
162 consisting of two space-separated words (so that the whole
163 specification list is made up of an even number of words). The
164 first word of each specification holds a field (sort criterion) and
165 the second holds flags. If the sort criterion includes = it is
166 assumed that the SortKey is of type sortAttributes using Bib-1: in
167 this case the integer before = is the attribute type and the
168 integer following = is the attribute value. If no = character is in
169 the criterion, it is treated as a sortfield of type
170 InternationalString. The flags word of each sort specification must
171 consist of s for case sensitive or i for case insensitive, and <
172 for ascending order or > for descending order.
173 sort+
175 Same as sort but stores the sorted result set in a new result set.
176 authentication openauth
178 Sets up an authentication string if a server requires
179 authentication (v2 OpenStyle). The authentication string is first
180 sent to the server when the open command is issued and the Z39.50
181 Initialize Request is sent, so this command must be used before
182 open in order to be effective. A common convention for the authopen
183 string is that the username - and password is separated by a slash,
184 e.g. myusername/mysecret.
185 sru method version
187 Selects Web Service method and version. Must be one of post, get,
188 soap (default) or solr. Version should be either 1.1, 1.2 or 2.0
189 for SRU. Other versions are allowed - for testing purposes (version
190 negotiation with SRU server). The version is currently not used for
191 Solr Web Services
192 list_all
194 This command displays status and values for many settings.
195 lslb n
197 Sets the limit for when no records should be returned together with
198 the search result. See the Z39.50 standard on set bounds[4] for
199 more details.
200 ssub n
202 Sets the limit for when all records should be returned with the
203 search result. See the Z39.50 standard on set bounds[4] for more
204 details.
205 mspn n
207 Sets the number of records that should be returned if the number of
208 records in the result set is between the values of lslb and ssub.
209 See the Z39.50 standard on set bounds[4] for more details.
210 status
212 Displays the values of lslb, ssub and mspn.
213 setname
215 Switches named result sets on and off. Default is on.
216 cancel
218 Sends a Trigger Resource Control Request to the target.
219 format oid
221 Sets the preferred transfer syntax for retrieved records.
222 yaz-client supports all the record syntaxes that currently are
223 registered. See Z39.50 Record Syntax Identifiers[5] for more
224 details. Commonly used records syntaxes include usmarc, sutrs and
225 xml.
226 elements e
228 Sets the element set name for the records. Many targets support
229 element sets B (for brief) and F (for full).
230 close
232 Sends a Z39.50 Close APDU and closes connection with the peer
233 querytype type
235 Sets the query type as used by command find. The following is
236 supported: prefix for Prefix Query Notation (Type-1 Query); ccl for
237 CCL search (Type-2 Query), cql for CQL (Type-104 search with CQL
238 OID), ccl2rpn for CCL to RPN conversion (Type-1 Query), cql2rpn for
239 CQL to RPN conversion (Type-1 Query).
240 attributeset set
242 Sets attribute set OID for prefix queries (RPN, Type-1).
243 refid id
245 Sets reference ID for Z39.50 Request(s).
246 itemorder type no
248 Sends an Item Order Request using the ILL External. type is either
249 1 or 2 which corresponds to ILL-Profile 1 and 2 respectively. The
250 no is the Result Set position of the record to be ordered.
251 update action recid doc
253 Sends Item Update Request. The action argument must be the action
254 type: one of insert, replace, delete and update. The second
255 argument, recid, is the record identifier (any string). Third
256 argument which is optional is the record document for the request.
257 If doc is preceded with "<", then the following characters are
258 treated as a filename with the records to be updated. Otherwise doc
259 is treated as a document itself. The doc may also be quoted in
260 double quotes. If doc is omitted, the last received record (as part
261 of present response or piggybacked search response) is used for the
262 update.
263 source filename
265 Executes list of commands from file filename, just like 'source' on
266 most UNIX shells. A single dot (.) can be used as an alternative.
267 ! args
269 Executes command args in subshell using the system call.
270 push_command command
272 The push_command takes another command as its argument. That
273 command is then added to the history information (so you can
274 retrieve it later). The command itself is not executed. This
275 command only works if you have GNU readline/history enabled.
276 set_apdufile filename
278 Sets that APDU should be logged to file filename. Another way to
279 achieve APDU log is by using command-line option -a.
280 set_auto_reconnect flag
282 Specifies whether YAZ client automatically reconnects if the target
283 closes connection (Z39.50 only).
284 flag must be either on or off.
286 set_auto_wait flag
288 Specifies whether YAZ client should wait for response protocol
289 packages after a request. By default YAZ client waits (on) for
290 response packages immediately after a command (find, show) has been
291 issued. If off is used, YAZ client does not attempt to receive
292 packages automatically. These will have to be manually received
293 when command wait_response is used.
294 flag must be either on or off.
296 set_marcdump filename
298 Specifies that all retrieved records should be appended to file
299 filename. This command does the thing as option -m.
300 schema schemaid
302 Specifies schema for retrieval. Schema may be specified as an OID
303 for Z39.50. For SRU, schema is a simple string URI.
304 charset negotiationcharset [displaycharset] [[marccharset]]
306 Specifies character set (encoding) for Z39.50 negotiation / SRU
307 encoding and/or character set for output (terminal).
308 negotiationcharset is the name of the character set to be
310 negotiated by the server. The special name - for negotiationcharset
311 specifies no character set to be negotiated.
312 If displaycharset is given, it specifies name of the character set
314 of the output (on the terminal on which YAZ client is running). To
315 disable conversion of characters to the output encoding, the
316 special name - (dash) can be used. If the special name auto is
317 given, YAZ client will convert strings to the encoding of the
318 terminal as returned by nl_langinfo call.
319 If marccharset is given, it specifies name of the character set of
321 retrieved MARC records from server. See also marccharset command.
322 Note
324 Since character set negotiation takes effect in the Z39.50
325 Initialize Request you should issue this command before command
326 open is used.
327 Note
329 MARC records are not covered by Z39.50 character set
330 negotiation, so that's why there is a separate character that
331 must be known in order to do meaningful conversion(s).
332 negcharset charset
334 Specifies character set for negotiation (Z39.50). The argument is
335 the same as second argument for command charset.
336 displaycharset charset
338 Specifies character set for output (display). The argument is the
339 same as second argument for command charset.
340 marccharset charset
342 Specifies character set for retrieved MARC records so that YAZ
343 client can display them in a character suitable for your display.
344 See charset command. If auto is given, YAZ will assume that
345 MARC21/USMARC is using MARC8/UTF8 and ISO-8859-1 for all other MARC
346 variants. The charset argument is the same as third argument for
347 command charset.
348 querycharset charset
350 Specifies character set for query terms for Z39.50 RPN queries and
351 Z39.50 Scan Requests (termListAndStartPoint). This is a pure
352 client-side conversion which converts from displayCharset to
353 queryCharset.
354 set_cclfile filename
356 Specifies that CCL fields should be read from file file filename.
357 This command does the thing as option -c.
358 set_cqlfile filename
360 Specifies that CQL fields should be read from file file filename.
361 This command does the thing as option -q.
362 register_oid name class OID
364 This command allows you to register your own object identifier - so
365 that instead of entering a long dot-notation you can use a short
366 name instead. The name is your name for the OID, class is the
367 class, and OID is the raw OID in dot notation. Class is one of:
368 appctx, absyn, attet, transyn, diagset, recsyn, resform, accform,
369 extserv, userinfo, elemspec, varset, schema, tagset, general. If
370 you're in doubt use the general class.
371 register_tab command string
373 This command registers a TAB completion string for the command
374 given.
375 sleep seconds
377 This command makes YAZ client sleep (be idle) for the number of
378 seconds given.
379 wait_response [ number]
381 This command makes YAZ client wait for a number of response
382 packages from target. If number is omitted, 1 is assumed.
383 This command is rarely used and is only useful if command
385 set_auto_wait is set to off.
386 xmles OID doc
388 Sends XML Extended Services request using the OID and doc given.
389 zversion ver
391 This command sets Z39.50 version for negotiation. Should be used
392 before open. By default 3 (version 3) is used.
393 options op1 op2..
395 This command sets Z39.50 options for negotiation. Should be used
396 before open.
397 The following options are supported: search, present, delSet,
399 resourceReport, triggerResourceCtrl, resourceCtrl, accessCtrl,
400 scan, sort, extendedServices, level_1Segmentation,
401 level_2Segmentation, concurrentOperations, namedResultSets,
402 encapsulation, resultCount, negotiationModel, duplicationDetection,
403 queryType104, pQESCorrection, stringSchema.
404
406 The simplest example of a Prefix Query would be something like
407 f knuth
409 or
412 f "donald knuth"
414 In those queries, no attributes were specified. This leaves it up to
417 the server what fields to search but most servers will search in all
418 fields. Some servers do not support this feature though, and require
419 that some attributes are defined. To add one attribute you could do:
420 f @attr 1=4 computer
422 where we search in the title field, since the use(1) is title(4). If we
425 want to search in the author field and in the title field, and in the
426 title field using right truncation it could look something like this:
427 f @and @attr 1=1003 knuth @attr 1=4 @attr 5=1 computer
429 Finally using a mix of Bib-1 and GILS attributes could look something
432 like this:
433 f @attrset Bib-1 @and @attr GILS 1=2008 Washington @attr 1=21 weather
435
439 yaz-<version>/client/client.c
440 $HOME/.yazclientrc
442 $HOME/.yazclient.history
444
446 yaz(7)bib1-attr(7)
447
449 1. Z39.50
450 http://www.loc.gov/z3950/agency/
451 2. SRU
453 http://www.loc.gov/standards/sru/
454 3. Solr
456 http://lucene.apache.org/solr/
457 4. Z39.50 standard on set bounds
459 http://www.loc.gov/z3950/agency/markup/04.html#3.2.2.1.6
460 5. Z39.50 Record Syntax Identifiers
462 http://www.loc.gov/z3950/agency/defns/oids.html#5
463YAZ 5.14.11 10/09/2015 YAZ-CLIENT(1)