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

## DESCRIPTION

`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` environment variable is used to determine the home directory. Normally, `$HOME` is only set on POSIX systems such as Linux, FreeBSD, Solaris.

## OPTIONS

-a `filename`

- If specified, logging of protocol packages will be appended to the 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 the 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.

## COMMANDS

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 command overrides the database given in `zurl`.

`show` [`start`[+`number` [+`resultset`]]]

- Fetches records by sending a Present Request from the start position given by `start` and a number of records given by `number`, from the result set `resultset`. If `start` is not given, then the client will fetch from the position of the last retrieved record plus 1. If `number` is not given, then one record will be fetched at a time. If `resultset` is not given, the most recently retrieved result set is used.

`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 the 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 the 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.

  Example using sort criterion with attributes use=local-number and structure=numeric and ascending flag: `1=12,4=109 <`

  Another example with "Title" sort field and descending flag: `Title >`

`sort+`

- Same as `sort` but stores the sorted result set in a new result set.

`authentication` [`auth1` [`auth2` [`auth3`]]]

- Configures authentication strings to be sent to server. Zero, 1, 2 or 3 arguments may follow the auth command.

  If no (0) arguments are given, no authentication string is sent.

  If one argument is given, the Z39.50 v2 OpenStyle authentication is used. A common convention for the `auth1` string is that the username and password is separated by a slash, e.g. `myusername/mysecret`.

  If two or more arguments is given Z39.50 v3 authentication is used, in which cased the first argument is used, second argument is group and third argument is password. If only two arguments are given the group is assumed to be empty.

  As for other commands in yaz-client, the arguments are separated by whitespace. A backslash character can be used to include a character verbatim. For example, `auth myuser a\ b` is a two argument auth command where user is `myuser` and password is `a b`.

  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.

`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 that 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.

`facets` `spec`

- Specifies requested facets to be used in search. The notation is specified in facets.

`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 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 quoted 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 reconnects if the 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 same 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 `marccharset` is given, it specifies name of the character set of retrieved MARC records from server. See also `marccharset` 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 same thing as option `-c`.

`set_cqlfile` `filename`

- Specifies that CQL fields should be read from file file `filename`. This command does the same 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 of: `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`.

## EXAMPLE

The simplest example of a Prefix Query would be something like

        f knuth

or

        f "donald knuth"

In those queries, no attributes were specified. This leaves it up to the server what fields to search but most servers will search in all fields. Some servers do 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

## FILES

`yaz-<version>/client/client.c`

`$HOME/.yazclientrc`

`$HOME/.yazclient.history`

## SEE ALSO

yaz

7

bib1-attr

7

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

## DESCRIPTION

`yaz-ztest` is a Z39.50/SRU test server that uses the YAZ generic front-end 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.

## OPTIONS

`-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 fork a process. Only available on UNIX systems that offer 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 before listening to 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 the 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.

## TESTING

`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, then 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 from a file (one record per file). The path for the filename is `F` `E``.``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 will 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`.

## GFS CONFIGURATION AND VIRTUAL HOSTS

The Virtual hosts mechanism allows a YAZ front-end server to support multiple back-ends. A back-end is selected on the basis of the TCP/IP binding (port+listening address) and/or the virtual host.

A back-end can be configured to execute in a particular working directory. Or the YAZ front-end may perform CQL to RPN conversion, thus allowing traditional Z39.50 back-ends to be offered as a SRW/SRU service. SRW/SRU Explain information for a particular back-end 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 allow the VHOST information to be set. For those, the selection of the back-end must rely on the TCP/IP information alone (port and address).

The YAZ front-end server uses XML to describe the back-end 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 specified, the YAZ frontend 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 cql.to.rpn. 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 ccl.qualifiers. 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 none is given, then if the client does not specify one, then 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 (/ excluded) 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/xsl` 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 seem redundant because host information, etc. is also stored elsewhere.

element `maximumrecordsize` (optional)

- Specifies maximum record size/message size, in bytes. This value also serves as the 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 to support conversions and specifications of record formats/types. See tools.retrieval 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 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"`.

## FILES

`yaz-<version>/ztest/yaz-ztest.c`

`yaz-<version>/include/yaz/backend.h`

## SEE ALSO

yaz

7

yaz-log

7

yaz-config

1 Commands

yaz-config

Script to get information about YAZ.

       yaz-config
       --prefix[=DIR]
       --version
       --libs
       --lalibs
       --cflags
       --include
       --comp
       -V
       libraries

## DESCRIPTION

`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.

## OPTIONS

--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

- Returns YAZ SHA1 ID (from Git) and version.

## FILES

`/usr/bin/yaz-config`

`/usr/lib/libyaz*.a`

`/usr/include/yaz/*.h`

## SEE ALSO

yaz(7)

Section "How to make apps using YAZ on UNIX" in the YAZ manual.

yaz

7 Conventions and miscellaneous

yaz

Z39.50 toolkit.

## DESCRIPTION

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

Copyright © 1995-2026 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.

## SEE ALSO

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.

zoomsh

1 Commands

zoomsh

ZOOM shell

       zoomsh
       -a apdufile
       -e
       -v loglevel
       commands

## DESCRIPTION

`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.

## OPTIONS

-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`.

## EXAMPLES

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`

## COMMANDS

`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.

## SEE ALSO

yaz

7 ,

yaz-ztest

8 ,

Section "Building clients with ZOOM" in the YAZ manual.

ZOOM home page.

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

## DESCRIPTION

`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 DEFINITIONS 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.

## OPTIONS

`-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.

## DEFINITIONS FILE

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 consist 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 two 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.

## FILES

`/usr/share/yaz/z39.50/z.tcl`

`/usr/share/yaz/z39.50/*.asn`

## SEE ALSO

yaz

7

Section "The ODR Module" in the YAZ manual.

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
       -O offset
       -L limit
       -n
       -p
       -r
       -v
       -V
       file

## DESCRIPTION

`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 sub-field x. The output format may be changed with option `-o`,

`yaz-marcdump` can also be requested to perform character set conversion of each record.

## OPTIONS

-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 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 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 records 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`.

-O `offset`

- Integer offset for at what position records whould be written. 0=first record, 1=second, .. With -L option, this allows a specific range of records to be processed.

-L `limit`

- Integer limit for how many records should at most be written. With -O option, this allows a specific range of records to be processed.

-p

- Makes yaz-marcdump print record number and input file offset of each record read.

-n

- MARC output is omitted so that MARC input is only checked.

-r

- Writes to stderr a summary about number of records read by yaz-marcdump.

-v

- Writes more information about the parsing process. Useful if you have ill-formatted ISO2709 records as input.

-V

- Prints YAZ version.

## EXAMPLES

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

## FILES

``prefix`/bin/yaz-marcdump`

``prefix`/include/yaz/marcdisp.h`

## SEE ALSO

yaz

7

yaz-iconv

1

yaz-iconv

1 Commands

yaz-iconv

YAZ Character set conversion utility

       yaz-iconv
       -f from
       -t to
       -v
       file

## DESCRIPTION

`yaz-iconv` converts data in the character set specified by `from` to output in the character set as specified by `to`.

This `yaz-iconv` utility is similar to the `iconv` found on many POSIX systems (Glibc, Solaris, etc).

If no `file` is specified, `yaz-iconv` reads from standard input.

## OPTIONS

-f`from`]

- Specify the character set `from` of the input file. Should be used in conjunction with option `-t`.

-t`to`]

- Specify the character set `of` of the output. Should be used in conjunction with option `-f`.

-v

- Print more information about the conversion process.

## ENCODINGS

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 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 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.

## EXAMPLES

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

## FILES

``prefix`/bin/yaz-iconv`

``prefix`/include/yaz/yaz-iconv.h`

## SEE ALSO

yaz(7) iconv(1)

yaz-log

7 Conventions and miscellaneous

yaz-log

Log handling in all yaz-based programs

       yaz-XXXX
       -v loglevel,...
       -l logfile

## DESCRIPTION

All YAZ-based programs use a common log subsystem, and should support common command line options for controlling it. This man page documents those.

## OPTIONS

-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 '-'.

## LOG LEVELS TO CONTROL LOGGING

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.

## GENERAL LOG LEVELS IN YAZ ITSELF

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.

## LOG LEVELS FOR CLIENTS

`zoom` logs the calls to the zoom API, which may be useful in debugging client applications.

## LOG LEVELS FOR SERVERS

`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.

## LOGGING EXAMPLES

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

## LOG FILENAME EXAMPLES

A file with format my_YYYYMMDD.log (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, rotation will occur on midnight.

A weekly log could be specified as `-l my_%Y%U.log`.

## FILES

``prefix`/include/yaz/log.h` ``prefix`/src/log.c`

## SEE ALSO

yaz

7

yaz-ztest

8

yaz-client

1

strftime

3

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

## DESCRIPTION

`yaz-illclient` is a 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.

## OPTIONS

-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.

## EXAMPLES

None yet.

## FILES

None yet.

## SEE ALSO

yaz(7)

yaz-icu

1 Commands

yaz-icu

YAZ ICU utility

       yaz-icu
       -c config
       -p opt
       -s
       -x
       infile

## DESCRIPTION

`yaz-icu` is a 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 specifies 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`.

## OPTIONS

-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`, then available locales are printed. If `type` is `t`, then 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.

## ICU chain configuration

The ICU chain configuration specifies 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

- Lower case using ICU function u_strToLower.

u

- Upper case using ICU function u_strToUpper.

t

- To title using ICU 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.

## EXAMPLES

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>

## SEE ALSO

yaz

7

ICU Home

ICU Transforms

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

## DESCRIPTION

`yaz-url` is utility to get web content. It is very limited in functionality compared to programs such as curl, wget.

The options must precede the URL given on the command line, to take effect.

Fetched HTTP content is written to stdout, unless option -O is given.

## OPTIONS

-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 following 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 used in HTTP basic authentication in the following URL fetch. The user and password must be separated by a slash (thus 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.

## SEE ALSO

yaz

7

Bib-1 Attribute Set

7 Conventions and miscellaneous

bib1-attr

Bib-1 Attribute Set

## DESCRIPTION

This reference entry lists the Bib-1 attribute set types and values.

## TYPES

The Bib-1 attribute set defines six attribute types: Use (1), Relation (2), Position (3), Structure (4), Truncation (5) and Completeness (6).

## USE (1)

        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

## RELATION (2)

        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

## POSITION (3)

        1 First in field
        2 First in subfield
        3 Any position in field

## STRUCTURE (4)

        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

## TRUNCATION (5)

        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

The 105-106 truncation attributes below are only supported by Index Data's Zebra server.

        105 Process * ! regular: *=.*, !=. and right truncate
        106 Process * ! regular: *=.*, !=.

## COMPLETENESS (6)

        1 Incomplete subfield
        2 Complete subfield
        3 Complete field

## SORTING (7)

        1 ascending
        2 descending

Type 7 is an Index Data extension to RPN queries that allows embedding a sort critieria into a query.

## SEE ALSO

Bib-1 Attribute Set

Attribute Set Bib-1 Semantics.

yaz-json-parse

1 Commands

yaz-json-parse

YAZ JSON parser

       yaz-json-parse
       -p

## DESCRIPTION

`yaz-json-parse` is a 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 if parsing succeeds, and returns no output unless -p is given (see below).

## OPTIONS

-p

- Makes the JSON parser echo the JSON result string to standard output, if parsing from stdin was successful. If -p is given twice, then the output is a multi-line output with indentation (pretty print).

## SEE ALSO

yaz

7

yaz-record-iconv

1 Commands

yaz-record-conv

YAZ Record Conversion Utility

       yaz-record-conv

        -v loglevel

       config
       fname

## DESCRIPTION

`yaz-record-conv` is a program that exercises the record conversion sub system. Refer to record_conv.h header.

## OPTIONS

`-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`.

## EXAMPLES

The following backend configuration converts MARC records (ISO2709) to Dublin-Core XML.

        <backend name="F" syntax="usmarc">
          <marc inputcharset="marc-8" inputformat="marc" outputformat="marcxml"/>
          <xslt stylesheet="../etc/MARC21slim2DC.xsl"/>
        </backend>

We can convert one of the sample records from YAZ' test directory with:

    $ ../util/yaz-record-conv record-conv-conf.xml marc6.marc
    <?xml version="1.0"?>
    <dc:dc xmlns:dc="http://purl.org/dc/elements/1.1/">
      <dc:title>How to program a computer</dc:title>
      <dc:creator>
        Jack Collins
      </dc:creator>
      <dc:type>text</dc:type>
      <dc:publisher>Penguin</dc:publisher>
      <dc:language>eng</dc:language>
    </dc:dc>

## FILES

`record_conv.h`

## SEE ALSO

yaz(7)