YAZ 5.8.1 Index Data yaz-client 1 Commands yaz-client Z39.50/SRU client for implementors yaz-client -a apdulog -b berdump -c cclfile -d dump -f cmdfile -k size -m marclog -p proxy-addr -q cqlfile -t dispcharset -u auth -v loglevel -V -x server-addr yaz-client is a Z39.50/SRU client (origin) with a simple command line interface that allows you to test behavior and performance of Z39.50 targets and SRU servers. From YAZ version 4.1.0 yaz-client may also operate as a Solr Web Service client. If the server-addr is specified, the client creates a connection to the Z39.50/SRU target at the address given. When yaz-client is started it tries to read commands from one of the following files: Command file if it is given by option -f. .yazclientrc in current working directory. .yazclientrc in the user's home directory. The value of the HOME is used to determine the home directory. Normally, HOME is only set on POSIX systems such as Linux, FreeBSD, Solaris. -a filename If specified, logging of protocol packages will be appended file given. If filename is specified as -, the output is written to stdout. -b filename If specified, YAZ will dump BER data in readable notation to the file specified. If filename is specified as - the output is written to stdout. -c filename If specified, CCL configuration will be read from the file given. -d dump If specified, YAZ will dump BER data for all PDUs sent and received to individual files, named dump.DDD.raw, where DDD is 001, 002, 003, .. -f cmdfile Reads commands from cmdfile. When this option is used, YAZ client does not read .yazclientrc from current directory or home directory. -k size Sets preferred messages and maximum record size for Initialize Request in kilobytes. Default value is 65536 (64 MB). -m filename If specified, retrieved records will be appended to the file given. -p proxy-addr If specified, the client will use the proxy at the address given. YAZ client will connect to a proxy on the address and port given. The actual target will be specified as part of the InitRequest to inform the proxy about actual target. -q filename If specified, CQL configuration will be read from the file given. -t displaycharset If displaycharset is given, it specifies name of the character set of the output (on the terminal on which YAZ client is running). -u auth If specified, the auth string will be used for authentication. -v level Sets the LOG level to level. Level is a sequence of tokens separated by comma. Each token is a integer or a named LOG item - one of fatal, debug, warn, log, malloc, all, none. -V Prints YAZ version. -x Makes the YAZ client print hex dumps of packages sent and received on standard output. The YAZ client accepts the following commands. open zurl Opens a connection to a server. The syntax for zurl is the same as described above for connecting from the command line. Syntax: [(tcp|ssl|unix|http)':']host [:port][/base] quit Quits YAZ client find query Sends a Search Request using the query given. By default the query is assumed to be PQF. See command querytype for more information. delete setname Deletes result set with name setname on the server. base base1 base2 ... Sets the name(s) of the database(s) to search. One or more databases may be specified separated by blanks. This commands overrides the database given in zurl. show [start[+number]] Fetches records by sending a Present Request from the start position given by start a number of records given by number. If start is not given, then the client will fetch from position of the last retrieved record plus 1. If number is not given, then one record will be fetched at a time. scan term Scans database index for a term. The syntax resembles the syntax for find. If you want to scan for the word water you could write scan water but if you want to scan only in, say the title field, you would write scan @attr 1=4 water setscan set term Scans database index for a term within a result set. This is similar to the scan command but has a result set as its first argument. scanpos pos Sets preferred position for scan. This value is used in next scan. By default position is 1. scansize size Sets number of entries to be returned by scan. Default number of entries is 20. scanstep step Set step-size for scan. This value is used in next scan sent to the target. By default step-size is 0. sort sortspecs Sorts a result set. The sort command takes a sequence of space-separated sort specifications, with each sort specification consisting of two space-separated words (so that the whole specification list is made up of an even number of words). The first word of each specification holds a field (sort criterion) and the second holds flags. If the sort criterion includes = it is assumed that the SortKey is of type sortAttributes using Bib-1: in this case the integer before = is the attribute type and the integer following = is the attribute value. If no = character is in the criterion, it is treated as a sortfield of type InternationalString. The flags word of each sort specification must consist of s for case sensitive or i for case insensitive, and < for ascending order or > for descending order. sort+ Same as sort but stores the sorted result set in a new result set. authentication openauth Sets up a authentication string if a server requires authentication (v2 OpenStyle). The authentication string is first sent to the server when the open command is issued and the Z39.50 Initialize Request is sent, so this command must be used before open in order to be effective. A common convention for the authopen string is that the username - and password is separated by a slash, e.g. myusername/mysecret. sru method version Selects Web Service method and version. Must be one of post, get, soap (default) or solr. Version should be either 1.1, 1.2 or 2.0 for SRU. Other versions are allowed - for testing purposes (version negotiation with SRU server). The version is currently not used for Solr Web Services list_all This command displays status and values for many settings. lslb n Sets the limit for when no records should be returned together with the search result. See the Z39.50 standard on set bounds for more details. ssub n Sets the limit for when all records should be returned with the search result. See the Z39.50 standard on set bounds for more details. mspn n Sets the number of records should be returned if the number of records in the result set is between the values of lslb and ssub. See the Z39.50 standard on set bounds for more details. status Displays the values of lslb, ssub and mspn. setname Switches named result sets on and off. Default is on. cancel Sends a Trigger Resource Control Request to the target. format oid Sets the preferred transfer syntax for retrieved records. yaz-client supports all the record syntaxes that currently are registered. See Z39.50 Record Syntax Identifiers for more details. Commonly used records syntaxes include usmarc, sutrs and xml. elements e Sets the element set name for the records. Many targets support element sets are B (for brief) and F (for full). close Sends a Z39.50 Close APDU and closes connection with the peer querytype type Sets the query type as used by command find. The following is supported: prefix for Prefix Query Notation (Type-1 Query); ccl for CCL search (Type-2 Query), cql for CQL (Type-104 search with CQL OID), ccl2rpn for CCL to RPN conversion (Type-1 Query). cql2rpn for CQL to RPN conversion (Type-1 Query). attributeset set Sets attribute set OID for prefix queries (RPN, Type-1). refid id Sets reference ID for Z39.50 Request(s). itemorder type no Sends an Item Order Request using the ILL External. type is either 1 or 2 which corresponds to ILL-Profile 1 and 2 respectively. The no is the Result Set position of the record to be ordered. update action recid doc Sends Item Update Request. The action argument must be the action type: one of insert, replace, delete and update. The second argument, recid, is the record identifier (any string). Third argument which is optional is the record document for the request. If doc is preceded with "<", then the following characters are treated as a filename with the records to be updated. Otherwise doc is treated as a document itself. The doc may also be quited in double quotes. If doc is omitted, the last received record (as part of present response or piggybacked search response) is used for the update. source filename Executes list of commands from file filename, just like source on most UNIX shells. A single dot (.) can be used as an alternative. ! args Executes command args in subshell using the system call. push_command command The push_command takes another command as its argument. That command is then added to the history information (so you can retrieve it later). The command itself is not executed. This command only works if you have GNU readline/history enabled. set_apdufile filename Sets that APDU should be logged to file filename. Another way to achieve APDU log is by using command-line option -a. set_auto_reconnect flag Specifies whether YAZ client automatically reconnect if target closes connection (Z39.50 only). flag must be either on or off. set_auto_wait flag Specifies whether YAZ client should wait for response protocol packages after a request. By default YAZ client waits (on) for response packages immediately after a command (find, show) has been issued. If off is used, YAZ client does not attempt to receive packages automatically. These will have to be manually received when command wait_response is used. flag must be either on or off. set_marcdump filename Specifies that all retrieved records should be appended to file filename. This command does the thing as option -m. schema schemaid Specifies schema for retrieval. Schema may be specified as an OID for Z39.50. For SRU, schema is a simple string URI. charset negotiationcharset [displaycharset] [[marccharset]] Specifies character set (encoding) for Z39.50 negotiation / SRU encoding and/or character set for output (terminal). negotiationcharset is the name of the character set to be negotiated by the server. The special name - for negotiationcharset specifies no character set to be negotiated. If displaycharset is given, it specifies name of the character set of the output (on the terminal on which YAZ client is running). To disable conversion of characters to the output encoding, the special name - (dash) can be used. If the special name auto is given, YAZ client will convert strings to the encoding of the terminal as returned by nl_langinfo call. If marcharset is given, it specifies name of the character set of retrieved MARC records from server. See also marcharset command. Since character set negotiation takes effect in the Z39.50 Initialize Request you should issue this command before command open is used. MARC records are not covered by Z39.50 character set negotiation, so that's why there is a separate character that must be known in order to do meaningful conversion(s). negcharset charset Specifies character set for negotiation (Z39.50). The argument is the same as second argument for command charset. displaycharset charset Specifies character set for output (display). The argument is the same as second argument for command charset. marccharset charset Specifies character set for retrieved MARC records so that YAZ client can display them in a character suitable for your display. See charset command. If auto is given, YAZ will assume that MARC21/USMARC is using MARC8/UTF8 and ISO-8859-1 for all other MARC variants. The charset argument is the same as third argument for command charset. querycharset charset Specifies character set for query terms for Z39.50 RPN queries and Z39.50 Scan Requests (termListAndStartPoint). This is a pure client-side conversion which converts from displayCharset to queryCharset. set_cclfile filename Specifies that CCL fields should be read from file file filename. This command does the thing as option -c. set_cqlfile filename Specifies that CQL fields should be read from file file filename. This command does the thing as option -q. register_oid name class OID This command allows you to register your own object identifier - so that instead of entering a long dot-notation you can use a short name instead. The name is your name for the OID, class is the class, and OID is the raw OID in dot notation. Class is one appctx, absyn, attet, transyn, diagset, recsyn, resform, accform, extserv, userinfo, elemspec, varset, schema, tagset, general. If you're in doubt use the general class. register_tab command string This command registers a TAB completion string for the command given. sleep seconds This command makes YAZ client sleep (be idle) for the number of seconds given. wait_response [ number] This command makes YAZ client wait for a number of response packages from target. If number is omitted, 1 is assumed. This command is rarely used and is only useful if command set_auto_wait is set to off. xmles OID doc Sends XML Extended Services request using the OID and doc given. zversion ver This command sets Z39.50 version for negotiation. Should be used before open. By default 3 (version 3) is used. options op1 op2.. This command sets Z39.50 options for negotiation. Should be used before open. The following options are supported: search, present, delSet, resourceReport, triggerResourceCtrl, resourceCtrl, accessCtrl, scan, sort, extendedServices, level_1Segmentation, level_2Segmentation, concurrentOperations, namedResultSets, encapsulation, resultCount, negotiationModel, duplicationDetection, queryType104, pQESCorrection, stringSchema. The simplest example of a Prefix Query would be something like f knuth or f "donald knuth" In those queries no attributes was specified. This leaves it up to the server what fields to search but most servers will search in all fields. Some servers does not support this feature though, and require that some attributes are defined. To add one attribute you could do: f @attr 1=4 computer where we search in the title field, since the use(1) is title(4). If we want to search in the author field and in the title field, and in the title field using right truncation it could look something like this: f @and @attr 1=1003 knuth @attr 1=4 @attr 5=1 computer Finally using a mix of Bib-1 and GILS attributes could look something like this: f @attrset Bib-1 @and @attr GILS 1=2008 Washington @attr 1=21 weather yaz-<version>/client/client.c $HOME/.yazclientrc $HOME/.yazclient.history yaz 7 bib1-attr 7 YAZ 5.8.1 Index Data yaz-ztest 8 System management commands yaz-ztest Z39.50/SRU Test Server application -install -installa -remove -a file -v level -l file -u uid -c config -f vconfig -C fname -t minutes -k kilobytes -K -d daemon -w dir -p pidfile -r kilobytes -ziDSTV1 listener-spec yaz-ztest is a Z39.50/SRU test server that uses the YAZ generic frontend server (GFS) API. The server acts as a real Z39.50/SRU server but does not use a database. It returns a random hit count and returns a subset of a few built-in records. The listener-spec consists of a transport mode followed by a colon, followed by a listener address. The transport mode is either tcp, unix, or ssl. For TCP and SSL, an address has the form: hostname | IP-number [ : portnumber ] For UNIX local socket the address is the filename of the local socket. -a file Specify a file for dumping PDUs (for diagnostic purposes). The special name - (dash) sends output to stderr. -S Don't fork or make threads on connection requests. This is good for debugging, but not recommended for real operation: Although the server is asynchronous and non-blocking, it can be nice to keep a software malfunction (okay then, a crash) from affecting all current users. -1 Like -S but after one session the server exits. This mode is for debugging only. -T Operate the server in threaded mode. The server creates a thread for each connection rather than a fork a process. Only available on UNIX systems that offers POSIX threads. -s Use the SR protocol (obsolete). -z Use the Z39.50 protocol (default). This option and -s complement each other. You can use both multiple times on the same command line, between listener-specifications (see below). This way, you can set up the server to listen for connections in both protocols concurrently, on different local ports. -l file The logfile. -c config A user option that serves as a specifier for some sort of configuration, usually a filename. The argument to this option is transferred to member configname of the statserv_options_block. -f vconfig This specifies an XML file that describes one or more YAZ frontend virtual servers. -C fname Sets SSL certificate file name for server (PEM). -v level The log level. Use a comma-separated list of members of the set {fatal,debug,warn,log,malloc,all,none}. -u uid Set user ID. Sets the real UID of the server process to that of the given user. It's useful if you aren't comfortable with having the server run as root, but you need to start it as such to bind a privileged port. -w dir The server changes to this directory during before listening on incoming connections. This option is useful when the server is operating from the inetd daemon (see -i). -p pidfile Specifies that the server should write its Process ID to file given by pidfile. A typical location would be /var/run/yaz-ztest.pid. -i Use this to make the the server run from the inetd server (UNIX only). -D Use this to make the server put itself in the background and run as a daemon. If neither -i nor -D is given, the server starts in the foreground. -install Use this to install the server as an NT service (Windows NT/2000/XP only). Control the server by going to the Services in the Control Panel. -installa Use this to install the server as an NT service and mark it as "auto-start. Control the server by going to the Services in the Control Panel. -remove Use this to remove the server from the NT services (Windows NT/2000/XP only). -t minutes Idle session timeout, in minutes. -k size Maximum record size/message size, in kilobytes. -K Forces no-keepalive for HTTP sessions. By default GFS will keep sessions alive for HTTP 1.1 sessions (as defined by the standard). Using this option will force GFS to close the connection for each operation. -r size Maximum size of log file before rotation occurs, in kilobytes. Default size is 1048576 k (=1 GB). -d daemon Set name of daemon to be used in hosts access file. See hosts_access 5 and tcpd 8 . -m time-format Sets the format of time-stamps in the log-file. Specify a string in the input format to strftime(). -V Display YAZ version and exit. yaz-ztest normally returns a random hit count between 0 and 24. However, if a query term includes leading digits, then the integer value of that term is used as hit count. This allows testers to return any number of hits. yaz-ztest includes 24 MARC records for testing. Hit counts exceeding 24 will make yaz-ztest return the same record batch over and over.. So record at position 1, 25, 49, etc .. are equivalent. For XML if no element set is given or element has value "marcxml", MARCXML is returned (each of the 24 dummy records converted from ISO2709 to XML). For element set OP, OPAC XML is returned. yaz-ztest may also return predefined XML records (for testing). This is enabled if YAZ_ZTEST_XML_FETCH environment variable is defined. A record is fetched form a file (one record per file). The path for the filename is FE.d.xml where F is the YAZ_ZTEST_XML_FETCH value (possibly empty), E is element-set, d is record position (starting from 1). The following databases are honored by yaz-ztest: Default, slow and db.* (all databases with prefix "db"). Any other database will make yaz-ztest return diagnostic 109: "Database unavailable". Options for search may be included in the form or URL get arguments included as part of the Z39.50 database name. The following database options are present: search-delay, present-delay, fetch-delay and seed. The former, delay type options, specify a fake delay (sleep) that yaz-ztest will perform when searching, presenting, fetching records respectively. The value of the delay may either be a fixed floating point value which specifies the delay in seconds. Alternatively the value may be given as two floating point numbers separated by colon, which wil make yaz-ztest perform a random sleep between the first and second number. The database parameter seed takes an integer as value. This will call srand with this integer to ensure that the random behavior can be re-played. Suppose we want searches to take between 0.1 and 0.5 seconds and a fetch to take 0.2 second. To access test database Default we'd use: Default?search-delay=0.1:0.5&fetch-delay=0.2. The Virtual hosts mechanism allows a YAZ frontend server to support multiple backends. A backend is selected on the basis of the TCP/IP binding (port+listening adddress) and/or the virtual host. A backend can be configured to execute in a particular working directory. Or the YAZ frontend may perform CQL to RPN conversion, thus allowing traditional Z39.50 backends to be offered as a SRW/SRU service. SRW/SRU Explain information for a particular backend may also be specified. For the HTTP protocol, the virtual host is specified in the Host header. For the Z39.50 protocol, the virtual host is specified as in the Initialize Request in the OtherInfo, OID 1.2.840.10003.10.1000.81.1. Not all Z39.50 clients allows the VHOST information to be set. For those the selection of the backend must rely on the TCP/IP information alone (port and address). The YAZ frontend server uses XML to describe the backend configurations. Command-line option -f specifies filename of the XML configuration. The configuration uses the root element yazgfs. This element includes a list of listen elements, followed by one or more server elements. The listen describes listener (transport end point), such as TCP/IP, Unix file socket or SSL server. Content for a listener: CDATA (required) The CDATA for the listen element holds the listener string, such as tcp:@:210, tcp:server1:2100, etc. attribute id (optional) identifier for this listener. This may be referred to from server sections. We expect more information to be added for the listen section in a future version, such as CERT file for SSL servers. The server describes a server and the parameters for this server type. Content for a server: attribute id (optional) Identifier for this server. Currently not used for anything, but it might be for logging purposes. attribute listenref (optional) Specifies one or more listeners for this server. Each server ID is separated by a comma. If this attribute is not given, the server is accessible from all listeners. In order for the server to be used for real, however, the virtual host must match if specified in the configuration. element config (optional) Specifies the server configuration. This is equivalent to the config specified using command line option -c. element directory (optional) Specifies a working directory for this backend server. If specifid, the YAZ fronend changes current working directory to this directory whenever a backend of this type is started (backend handler bend_start), stopped (backend handler hand_stop) and initialized (bend_init). element host (optional) Specifies the virtual host for this server. If this is specified a client must specify this host string in order to use this backend. element cql2rpn (optional) Specifies a filename that includes CQL to RPN conversion for this backend server. See If given, the backend server will only "see" a Type-1/RPN query. element ccl2rpn (optional) Specifies a filename that includes CCL to RPN conversion for this backend server. See If given, the backend server will only "see" a Type-1/RPN query. element stylesheet (optional) Specifies the stylesheet reference to be part of SRU HTTP responses when the client does not specify one. If neither this is given, nor the client specifies one, no stylesheet reference is part of the SRU HTTP response. element client_query_charset (optional) If specified, a conversion from the character set given to UTF-8 is performed by the generic frontend server. It is only executed for Z39.50 search requests (SRU/Solr are assumed to be UTF-8 encoded already). element docpath (optional) Specifies a path for local file access using HTTP. All URLs with a leading prefix (/ exluded) that matches the value of docpath are used for file access. For example, if the server is to offer access in directory xsl, the docpath would be xsl and all URLs of the form http://host/exl will result in a local file access. element explain (optional) Specifies SRW/SRU ZeeRex content for this server. Copied verbatim to the client. As things are now, some of the Explain content seeem redundant because host information, etc. is also stored elsewhere. element maximumrecordsize (optional) Specifies maximum record size/message size, in bytes. This value also servers as maximum size of incoming packages (for Record Updates etc). It's the same value as that given by the -k option. element retrievalinfo (optional) Enables the retrieval facility supporting conversions and specifications of record formats/types. See for more information. The XML below configures a server that accepts connections from two ports, TCP/IP port 9900 and a local UNIX file socket. We name the TCP/IP server public and the other server internal. <yazgfs> <listen id="public">tcp:@:9900</listen> <listen id="internal">unix:/var/tmp/socket</listen> <server id="server1"> <host>server1.mydomain</host> <directory>/var/www/s1</directory> <config>config.cfg</config> </server> <server id="server2" listenref="public,internal"> <host>server2.mydomain</host> <directory>/var/www/s2</directory> <config>config.cfg</config> <cql2rpn>../etc/pqf.properties</cql2rpn> <explain xmlns="http://explain.z3950.org/dtd/2.0/"> <serverInfo> <host>server2.mydomain</host> <port>9900</port> <database>a</database> </serverInfo> </explain> </server> <server id="server3" listenref="internal"> <directory>/var/www/s3</directory> <config>config.cfg</config> </server> </yazgfs> There are three configured backend servers. The first two servers, "server1" and "server2", can be reached by both listener addresses. "server1" is reached by all (two) since no listenref attribute is specified. "server2" is reached by the two listeners specified. In order to distinguish between the two, a virtual host has been specified for each of server in the host elements. For "server2" elements for CQL to RPN conversion is supported and explain information has been added (a short one here to keep the example small). The third server, "server3" can only be reached via listener "internal". yaz-<version>/ztest/yaz-ztest.c yaz-<version>/include/yaz/backend.h yaz 7 yaz-log 7 YAZ 5.8.1 Index Data yaz-config 1 Commands yaz-config Script to get information about YAZ. yaz-config --prefix[=DIR] --version --libs --lalibs --cflags --include --comp -V libraries yaz-config is a script that returns information that your own software should use to build software that uses YAZ. The following libraries are supported: threads Use the threaded version of YAZ. --prefix[=DIR] Returns prefix of YAZ or assume a different one if DIR is specified. --version Returns version of YAZ. --libs Library specification be used when using YAZ. --lalibs Return library specification. --cflags Return C Compiler flags. --include Return C compiler includes for YAZ header files (-Ipath). --comp Returns full path to YAZ' ASN.1 compiler: yaz-asncomp. -V veturns YAZ SHA1 ID (from Git) and version. /usr/bin/yaz-config /usr/lib/libyaz*.a /usr/include/yaz/*.h yaz(7) Section "How to make apps using YAZ on UNIX" in the YAZ manual. YAZ 5.8.1 Index Data yaz 7 Conventions and miscellaneous yaz Z39.50 toolkit. YAZ is a C/C++ programmer's toolkit supporting the development of Z39.50v3 clients and servers. The YAZ toolkit offers several different levels of access to the ISO23950/Z39.50, SRU Solr (client only) and ILL protocols. The level that you need to use depends on your requirements, and the role (server or client) that you want to implement. Copyright © 1995-2015 Index Data. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of Index Data nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. yaz-client 1 , yaz-ztest 8 , yaz-config 8 , zoomsh 1 bib1-attr 7 YAZ manual ( /usr/share/doc/yaz) YAZ home page. Z39.50 Maintenance Agency Page. YAZ 5.8.1 Index Data zoomsh 1 Commands zoomsh ZOOM shell zoomsh -a apdufile -e -v loglevel commands zoomsh is a ZOOM client with a simple command line interface. The client demonstrates the ZOOM API and is useful for testing targets. You may pass one or more commands to zoomsh. These commands are invoked first. -a apdufile Logs protocol packages into apdufile (APDU log). -e Makes zoomsh stop processing commands as soon as an error occur. The exit code of zoomsh is 1 if error occurs; 0 otherwise. -v loglevel Sets YAZ log level to loglevel. If you start the yaz-ztest in one console you can use the ZOOM shell as follows: $ zoomsh ZOOM>connect localhost:9999 ZOOM>search computer localhost:9999: 7 hits ZOOM>show 0 1 1 Default USmarc 001 11224466 003 DLC 005 00000000000000.0 008 910710c19910701nju 00010 eng 010 $a 11224466 040 $a DLC $c DLC 050 00 $a 123-xyz 100 10 $a Jack Collins 245 10 $a How to program a computer 260 1 $a Penguin 263 $a 8710 300 $a p. cm. ZOOM>quit You can also achieve the same result by passing the commands as arguments on a single command line: $ zoomsh "connect localhost:9999" "search computer" "show 0 1" quit connect zurl Connects to the target given by zurl. close [zurl] Closes connection to target given by zurl or all targets if zurl was omitted. show [start [count]] Displays count records starting at offset given by start. First records has offset 0 (unlike the Z39.50 protocol). quit Quits zoomsh. set name [value] Sets option name to value. get name Prints value of option name. help Prints list of available commands. yaz 7 , yaz-ztest 8 , Section "Building clients with ZOOM" in the YAZ manual. ZOOM home page. YAZ 5.8.1 Index Data yaz-asncomp 1 Commands yaz-asncomp YAZ ASN.1 compiler yaz-asncomp -v -c cfile -h hfile -p pfile -d config -I includeout -i includedir -m module filename yaz-asncomp is an ASN.1 compiler that reads an ASN.1 specification in filename and produces C/C++ definitions and BER encoders/decoders for it. The produced C/C++ code and header files uses the ODR module of YAZ which is a library that encodes/decodes/prints BER packages. yaz-asncomp allows you to specify name of resulting source via options. Alternatively, you can specify a DEFINISIONS file, which provides customized output to many output files - if the ASN.1 specification file consists of many modules. This utility is written in Tcl. Any version of Tcl should work. -v Makes the ASN.1 compiler print more verbose about the various stages of operations. -c cfile Specifies the name of the C/C++ file with encoders/decoders. -h hfile Specifies the name of header file with definitions. -p pfile Specifies the name of the a private header file with definitions. By default all definitions are put in header file (option -h). -d dfile Specifies the name of a definitions file. -I iout Specifies first part of directory in which header files are written. -i idir Specifies second part of directory in which header files are written. -m module Specifies that ASN.1 compiler should only process the module given. If this option is not specified, all modules in the ASN.1 file are processed. The definitions file is really a Tcl script but follows traditional rules for Shell like configuration files. That is # denotes the beginning of a comment. Definitions are line oriented. The definitions files usually consists of a series of variable assignments of the form: set name value Available variables are: default-prefix Sets prefix for names in the produced output. The value consists of three tokens: C function prefix, C typedef prefix and preprocessor prefix respectively. prefix(module) This value sets prefix values for module module. The value has same form as default-prefix. filename(module) Specifies filename for C/header file for module module. init(module,h) Code fragment to be put in first part of public header for module module. body(module,h) Code fragment to be put in last part of public header for module module (trailer). init(module,c) Code fragment to be put in first part of C based encoder/decoder for module module. body(module,c) Code fragment to be put in last part of C based encoder/decoder for module module (trailer). map(module,name) Maps ASN.1 type in module module of name to value. membermap(module,name,member) Maps member member in SEQUENCE/CHOICE of name in module module to value. The value consists of one or two tokens. First token is name of C preprocessor part. Second token is resulting C member name. If second token is omitted the value (one token) is both preprocessor part and C struct,union. unionmap(module,name,member) Maps member member in CHOICE of name in module module to value. Value consists of to or three tokens. The first token is name of the integer in the union that is used as selector for the union itself. The second token is name of the union. The third token overrides the name of the CHOICE member; if omitted the member name is used. /usr/share/yaz/z39.50/z.tcl /usr/share/yaz/z39.50/*.asn yaz 7 Section "The ODR Module" in the YAZ manual. YAZ 5.8.1 Index Data yaz-marcdump 1 Commands yaz-marcdump MARC record dump utility yaz-marcdump -i format -o format -f from -t to -l spec -c cfile -s prefix -C size -n -p -v -V file yaz-marcdump reads MARC records from one or more files. It parses each record and supports output in line-format, ISO2709, MARCXML, MARC-in-JSON, MarcXchange as well as Hex output. This utility parses records ISO2709(raw MARC), line format, MARC-in-JSON format as well as XML if that is structured as MARCXML/MarcXchange. MARC-in-JSON encoding/decoding is supported in YAZ 5.0.5 and later. As of YAZ 2.1.18, OAI-MARC is no longer supported. OAI-MARC is deprecated. Use MARCXML instead. By default, each record is written to standard output in a line format with newline for each field, $x for each subfield x. The output format may be changed with option -o, yaz-marcdump can also be requested to perform character set conversion of each record. -i format Specifies input format. Must be one of marcxml, marc (ISO2709), marcxchange (ISO25577), line (line mode MARC), turbomarc (Turbo MARC), or json (MARC-in-JSON). -o format Specifies output format. Must be one of marcxml, marc (ISO2709), marcxchange (ISO25577), line (line mode MARC), turbomarc (Turbo MARC), or json (MARC-in-JSON). -f from Specify the character set from of the input MARC record. Should be used in conjunction with option -t. Refer to the yaz-iconv man page for supported character sets. -t to Specify the character set of of the output. Should be used in conjunction with option -f. Refer to the yaz-iconv man page for supported character sets. -l leaderspec Specify a simple modification string for MARC leader. The leaderspec is a list of pos=value pairs, where pos is an integer offset (0 - 23) for leader. Value is either a quoted string or an integer (character value in decimal). Pairs are comma separated. For example, to set leader at offset 9 to a, use 9='a'. -s prefix Writes a chunk of records to a separate file with prefix given, i.e. splits a record batch into files with only at most "chunk" ISO2709 record per file. By default chunk is 1 (one record per file). See option -C. -C chunksize Specifies chunk size; to be used conjunction with option -s. -p Makes yaz-marcdump prints record number and input file offset of each record read. -n MARC output is omitted so that MARC input is only checkecd. -v Writes more information about the parsing process. Useful if you have ill-formatted ISO2709 records as input. -V Prints YAZ version. The following command converts MARC21/USMARC in MARC-8 encoding to MARC21/USMARC in UTF-8 encoding. Leader offset 9 is set to 'a'. Both input and output records are ISO2709 encoded. yaz-marcdump -f MARC-8 -t UTF-8 -o marc -l 9=97 marc21.raw >marc21.utf8.raw The same records may be converted to MARCXML instead in UTF-8: yaz-marcdump -f MARC-8 -t UTF-8 -o marcxml marc21.raw >marcxml.xml Turbo MARC is a compact XML notation with same semantics as MARCXML, but which allows for faster processing via XSLT. In order to generate Turbo MARC records encoded in UTF-8 from MARC21 (ISO), one could use: yaz-marcdump -f MARC8 -t UTF8 -o turbomarc -i marc marc21.raw >out.xml prefix/bin/yaz-marcdump prefix/include/yaz/marcdisp.h yaz 7 yaz-iconv 1 YAZ 5.8.1 Index Data yaz-iconv 1 Commands yaz-iconv YAZ Character set conversion utility yaz-iconv -f from -t to -v file yaz-iconv converts data in file in character set specified by from to output in character set as specified by to. This yaz-iconv utility similar to the iconv found on many POSIX systems (Glibc, Solaris, etc). If no file is specified, yaz-iconv reads from standard input. -ffrom] Specify the character set from of the input file. Should be used in conjunction with option -t. -tto] Specify the character set of of the output. Should be used in conjunction with option -f. -v Print more information about the conversion process. The yaz-iconv command and the API as defined in yaz/yaz-iconv.h is a wrapper for the library system call iconv. But YAZ' iconv utility also implements conversions on its own. The table below lists characters sets (or encodings). that are supported by YAZ. Each character set is marked with either encode or decode. If an encoding is encode-enabled YAZ may convert to to the designated encoding. If an encoding is decode-enabled, YAZ may convert from the designated encoding. marc8 (encode, decode) The MARC8 encoding as defined by the Library of Congress. Most MARC21/USMARC records use this encoding. marc8s (encode, decode) Like MARC8 but with conversion prefers non-combined characters in the Latin-1 plane over combined characters. marc8lossy (encode) Lossy encoding of MARC-8. marc8lossless (encode) Lossless encoding of MARC8. utf8 (encode, decode) The most commonly used UNICODE encoding on the Internet. iso8859-1 (encode, decode) ISO-8859-1, AKA Latin-1. iso5426 (decode) ISO 5426. Some MARC records (UNIMARC) use this encoding. iso5428:1984 (encode, decode) ISO 5428:1984. advancegreek (encode, decode) An encoding for Greek in use by some vendors (Advance). danmarc (decode) Danmarc (in danish) is an encoding based on UNICODE which is used for DanMARC2 records. The following command converts from ISO-8859-1 (Latin-1) to UTF-8. yaz-iconv -f ISO-8859-1 -t UTF-8 <input.lst >output.lst prefix/bin/yaz-iconv prefix/include/yaz/yaz-iconv.h yaz(7) iconv(1) YAZ 5.8.1 Index Data yaz-log 7 Conventions and miscellaneous yaz-log Log handling in all yaz-based programs yaz-XXXX -v loglevel,... -l logfile All YAZ-based programs use a common log subsystem, and should support common command line options for controlling it. This man page documents those. -l logfile Specify the file where the log is to be written. If none is specified, stderr is used. The log is appended to this file. If the file grows overly large, it is silently rotated: It is renamed to logfile.1, logfile.2, .., 9 (old such file is deleted), and a new file is opened. The limit defaults to 1GB, but can be set by the program. The rotating limit can be specified with option -r for the YAZ frontend server (yaz-ztest). Rotation can also be implicitly enabled by using a filename which gets changed for a given date, due to substitutions as given by the strftime(3) function. -v loglevel Specify the logging level. The argument is a set of log level names, separated by commas (no whitespace!), optionally preceded by a '-' to negate that level. Most programs have their own default, often containing fatal,warn,log, and some application-specific values. The default list can be cleared with the word none, or individual bits can be removed by prefixing them with a dash '-'. Some of the log levels control the way the log is written. flush causes the log to be flushed after every write. This can have serious implications to performance, and should not be used in production. On the other hand, when debugging a program crash, this can be extremely useful. The option debug implies flush as well. notime prevents the writing of time stamps. This is intended for automatic test scripts, which should produce predictable log files that are easy to compare. YAZ itself uses the following log levels: fatal for fatal errors, that prevent further execution of the program. warn for warnings about things that should be corrected. debug for debugging. This flag may be used temporarily when developing or debugging yaz, or a program that uses yaz. It is practically deprecated, you should be defining and using your own log levels (see below). all turns on almost all hard-coded log levels. loglevel logs information about the log levels used by the program. Every time the log level is changed, lists all bits that are on. Every time a module asks for its log bits, this is logged. This can be used for getting an idea of what log levels are available in any program that uses yaz-log. Start the program with -v none,loglevel, and do some common operations with it. Another way is to grep for yaz_log_module_level in the source code, as in find . -name '*.[ch]' -print | xargs grep yaz_log_module_level | grep '"' | cut -d'"' -f2 | sort -u eventl, malloc, nmem, odr are used internally for debugging yaz. zoom logs the calls to the zoom API, which may be useful in debugging client applications. server logs the server functions on a high level, starting up, listening on a port, etc. session logs individual sessions (connections). request logs a one-liner for each request (init, search, etc). requestdetail logs the details of every request, before it is passed to the back-end, and the results received from it. Each server program (zebra, etc) is supposed to define its own log levels in addition to these. As they depend on the server in question, they can not be described here. See above how to find out about them. See what log levels yaz-ztest is using: yaz-ztest -1 -v none,loglevel 14:43:29-23/11 [loglevel] Setting log level to 4096 = 0x00001000 14:43:29-23/11 [loglevel] Static log bit 00000001 'fatal' is off 14:43:29-23/11 [loglevel] Static log bit 00000002 'debug' is off 14:43:29-23/11 [loglevel] Static log bit 00000004 'warn' is off 14:43:29-23/11 [loglevel] Static log bit 00000008 'log' is off 14:43:29-23/11 [loglevel] Static log bit 00000080 'malloc' is off 14:43:29-23/11 [loglevel] Static log bit 00000800 'flush' is off 14:43:29-23/11 [loglevel] Static log bit 00001000 'loglevel' is ON 14:43:29-23/11 [loglevel] Static log bit 00002000 'server' is off 14:43:29-23/11 [loglevel] Dynamic log bit 00004000 'session' is off 14:43:29-23/11 [loglevel] Dynamic log bit 00008000 'request' is off 14:44:13-23/11 yaz-ztest [loglevel] returning log bit 0x4000 for 'session' 14:44:13-23/11 yaz-ztest [loglevel] returning log bit 0x2000 for 'server' 14:44:13-23/11 yaz-ztest [loglevel] returning NO log bit for 'eventl' 14:44:20-23/11 yaz-ztest [loglevel] returning log bit 0x4000 for 'session' 14:44:20-23/11 yaz-ztest [loglevel] returning log bit 0x8000 for 'request' 14:44:20-23/11 yaz-ztest [loglevel] returning NO log bit for 'requestdetail' 14:44:20-23/11 yaz-ztest [loglevel] returning NO log bit for 'odr' 14:44:20-23/11 yaz-ztest [loglevel] returning NO log bit for 'ztest' See the details of the requests for yaz-ztest ./yaz-ztest -1 -v requestdetail 14:45:35-23/11 yaz-ztest [server] Adding static Z3950 listener on tcp:@:9999 14:45:35-23/11 yaz-ztest [server] Starting server ./yaz-ztest pid=32200 14:45:38-23/11 yaz-ztest [session] Starting session from tcp:127.0.0.1 (pid=32200) 14:45:38-23/11 yaz-ztest [requestdetail] Got initRequest 14:45:38-23/11 yaz-ztest [requestdetail] Id: 81 14:45:38-23/11 yaz-ztest [requestdetail] Name: YAZ 14:45:38-23/11 yaz-ztest [requestdetail] Version: 2.0.28 14:45:38-23/11 yaz-ztest [requestdetail] Negotiated to v3: srch prst del extendedServices namedresults scan sort 14:45:38-23/11 yaz-ztest [request] Init from 'YAZ' (81) (ver 2.0.28) OK 14:45:39-23/11 yaz-ztest [requestdetail] Got SearchRequest. 14:45:39-23/11 yaz-ztest [requestdetail] ResultSet '1' 14:45:39-23/11 yaz-ztest [requestdetail] Database 'Default' 14:45:39-23/11 yaz-ztest [requestdetail] RPN query. Type: Bib-1 14:45:39-23/11 yaz-ztest [requestdetail] term 'foo' (general) 14:45:39-23/11 yaz-ztest [requestdetail] resultCount: 7 14:45:39-23/11 yaz-ztest [request] Search Z: @attrset Bib-1 foo OK:7 hits 14:45:41-23/11 yaz-ztest [requestdetail] Got PresentRequest. 14:45:41-23/11 yaz-ztest [requestdetail] Request to pack 1+1 1 14:45:41-23/11 yaz-ztest [requestdetail] pms=1048576, mrs=1048576 14:45:41-23/11 yaz-ztest [request] Present: [1] 1+1 OK 1 records returned A file with format my_YYYYMMDD.log is where Y, M, D is year, month, and day digits is given as follows -l my_%Y%m%d.log . And since the filename is depending on day, rotaion will occur on midnight. A weekly log could be specified as -l my_%Y%U.log. prefix/include/yaz/log.h prefix/src/log.c yaz 7 yaz-ztest 8 yaz-client 1 strftime 3 YAZ 5.8.1 Index Data yaz-illclient 1 Commands yaz-illclient ILL client yaz-illclient -f filename -v loglevel -D name=value -o -u user -p password -V server-addr yaz-illclient is an client which sends an ISO ILL request to a remote server and decodes the response from it. Exactly one server address ( server-addr ) must be specified. -f filename] Specify filename. -v loglevel] Specify the log level -D name=value] Defines name & value pair. -o Enable OCLC authentication. -u user] Specify user. -p password] Specify password. -V Show yaz-illclient version. None yet. None yet. yaz(7) YAZ 5.8.1 Index Data yaz-icu 1 Commands yaz-icu YAZ ICU utility yaz-icu -c config -p opt -s -x infile yaz-icu is utility which demonstrates the ICU chain module of yaz. (yaz/icu.h). The utility can be used in two ways. It may read some text using an XML configuration for configuring ICU and show text analysis. This mode is triggered by option -c which specififies the configuration to be used. The input file is read from standard input or from a file if infile is specified. The utility may also show ICU information. This is triggered by option -p. -c config Specifies the file containing ICU chain configuration which is XML based. -p type Specifies extra information to be printed about the ICU system. If type is c then ICU converters are printed. If type is l available locales are printed. If type is t available transliterators are printed. -s Specifies that output should include sort key as well. Note that sort key differs between ICU versions. -x Specifies that output should be XML based rather than "text" based. The ICU chain configuration speicifies one or more rules to convert text data into tokens. The configuration format is XML based. The toplevel element must be named icu_chain. The icu_chain element has one required attribute locale which specifies the ICU locale to be used in the conversion steps. The icu_chain element must include elements where each element specifies a conversion step. The conversion is performed in the order in which the conversion steps are specified. Each conversion element takes one attribute: rule which serves as argument to the conversion step. The following conversion elements are available: casemap Converts case and rule specifies how: l Lowercase using ICU function u_strToLower. u Upper case using ICU function u_strToUpper. t To title using UCU function u_strToTitle. f Fold case using ICU function u_strFoldCase. display This is a meta step which specifies that a term/token is to be displayed. This term is retrieved in an application using function icu_chain_token_display (yaz/icu.h). transform Specifies an ICU transform rule using a transliterator Identifier. The rule attribute is the transliterator Identifier. See ICU Transforms for more information. transliterate Specifies a rule-based transliterator. The rule attribute is the custom transformation rule to be used. See ICU Transforms for more information. tokenize Breaks / tokenizes a string into components using ICU functions ubrk_open, ubrk_setText, .. . The rule is one of: l Line. ICU: UBRK_LINE. s Sentence. ICU: UBRK_SENTENCE. w Word. ICU: UBRK_WORD. c Character. ICU: UBRK_CHARACTER. t Title. ICU: UBRK_TITLE. join Joins tokens into one string. The rule attribute is the joining string, which may be empty. The join conversion element was added in YAZ 4.2.49. The following command analyzes text in file text using ICU chain configuration chain.xml: cat text | yaz-icu -c chain.xml The chain.xml might look as follows: <icu_chain locale="en"> <transform rule="[:Control:] Any-Remove"/> <tokenize rule="w"/> <transform rule="[[:WhiteSpace:][:Punctuation:]] Remove"/> <transliterate rule="xy > z;"/> <display/> <casemap rule="l"/> </icu_chain> yaz 7 ICU Home ICU Transforms YAZ 5.8.1 Index Data yaz-url 1 Commands yaz-url YAZ URL fetch utility yaz-url -H name:value -m method -O fname -p fname -R num -u user/password -v -x proxy url yaz-url is utility to get web content. It is very limited in functionality compared to programs such as curl, wget. The options must be precede the URL given on the command line to take effect. Fetched HTTP content is written to stdout, unless option -O is given. -H name:value Specifies HTTP header content with name and value. This option can be given multiple times (for different names, of course). -m method Specifies the HTTP method to be used for the next URL. Default is method "GET". However, option -p sets it to "POST". -O fname Sets output filename for HTTP content. -p fname Sets a file to be POSTed in the folloing URL. -R num Sets maximum number of HTTP redirects to be followed. A value of zero disables follow of HTTP redirects. -u user/password Specifies a user and a password to be uesd in HTTP basic authentication in the following URL fetch. The user and password must be separated by a slash (this it is not possible to specify a user with a slash in it). -v Makes yaz-url dump each HTTP request/response to stdout. -x proxy Specifies a proxy to be used for URL fetch. yaz 7 YAZ 5.8.1 Index Data Bib-1 Attribute Set 7 Conventions and miscellaneous bib1-attr Bib-1 Attribute Set This reference entry lists the Bib-1 attribute set types and values. The Bib-1 attribute defines six attribute types: Use (1), Relation (2), Position (3), Structure (4), Truncation (5) and completeness (6). 1 Personal-name 2 Corporate-name 3 Conference-name 4 Title 5 Title-series 6 Title-uniform 7 ISBN 8 ISSN 9 LC-card-number 10 BNB-card-number 11 BGF-number 12 Local-number 13 Dewey-classification 14 UDC-classification 15 Bliss-classification 16 LC-call-number 17 NLM-call-number 18 NAL-call-number 19 MOS-call-number 20 Local-classification 21 Subject-heading 22 Subject-Rameau 23 BDI-index-subject 24 INSPEC-subject 25 MESH-subject 26 PA-subject 27 LC-subject-heading 28 RVM-subject-heading 29 Local-subject-index 30 Date 31 Date-of-publication 32 Date-of-acquisition 33 Title-key 34 Title-collective 35 Title-parallel 36 Title-cover 37 Title-added-title-page 38 Title-caption 39 Title-running 40 Title-spine 41 Title-other-variant 42 Title-former 43 Title-abbreviated 44 Title-expanded 45 Subject-precis 46 Subject-rswk 47 Subject-subdivision 48 Number-natl-biblio 49 Number-legal-deposit 50 Number-govt-pub 51 Number-music-publisher 52 Number-db 53 Number-local-call 54 Code-language 55 Code-geographic 56 Code-institution 57 Name-and-title 58 Name-geographic 59 Place-publication 60 CODEN 61 Microform-generation 62 Abstract 63 Note 1000 Author-title 1001 Record-type 1002 Name 1003 Author 1004 Author-name-personal 1005 Author-name-corporate 1006 Author-name-conference 1007 Identifier-standard 1008 Subject-LC-childrens 1009 Subject-name-personal 1010 Body-of-text 1011 Date/time-added-to-db 1012 Date/time-last-modified 1013 Authority/format-id 1014 Concept-text 1015 Concept-reference 1016 Any 1017 Server-choice 1018 Publisher 1019 Record-source 1020 Editor 1021 Bib-level 1022 Geographic-class 1023 Indexed-by 1024 Map-scale 1025 Music-key 1026 Related-periodical 1027 Report-number 1028 Stock-number 1030 Thematic-number 1031 Material-type 1032 Doc-id 1033 Host-item 1034 Content-type 1035 Anywhere 1036 Author-Title-Subject 1 Less than 2 Less than or equal 3 Equal 4 Greater or equal 5 Greater than 6 Not equal 100 Phonetic 101 Stem 102 Relevance 103 AlwaysMatches 1 First in field 2 First in subfield 3 Any position in field 1 Phrase 2 Word 3 Key 4 Year 5 Date (normalized) 6 Word list 100 Date (un-normalized) 101 Name (normalized) 102 Name (un-normalized) 103 Structure 104 Urx 105 Free-form-text 106 Document-text 107 Local-number 108 String 109 Numeric-string 1 Right truncation 2 Left truncation 3 Left and right truncation 100 Do not truncate 101 Process # in search term . regular #=.* 102 RegExpr-1 103 RegExpr-2 104 Process # ?n . regular: #=., ?n=.{0,n} or ?=.* Z39.58 Thw 105-106 truncation attributes below are only supported by Index Data's Zebra server. 105 Process * ! regular: *=.*, !=. and right truncate 106 Process * ! regular: *=.*, !=. 1 Incomplete subfield 2 Complete subfield 3 Complete field 1 ascending 2 descending Type 7 is an Index Data extension to RPN queries that allows embedding a sort critieria into a query. Bib-1 Attribute Set Attibute Set Bib-1 Semantics. YAZ 5.8.1 Index Data yaz-json-parse 1 Commands yaz-json-parse YAZ JSON parser yaz-json-parse -p yaz-json-parse is utility which demonstrates the JSON API of YAZ. (yaz/json.h). The program attempts to parse a JSON from standard input (stdin). It will return exit code 1 if parsing fails and the parsing error message will be printed to standard error (stderr). The program returns exit code 0 parsing succeeds and return no output, unless -p is given (see below). -p Makes the JSON parser echo the JSON result string to standard output - if parsing from stdin was successful. If -p is given twice the output is a multi line output with indentation (pretty print). yaz 7