Chapter 3. ZOOM

Table of Contents

1. Connections
1.1. Z39.50 Protocol behavior
1.2. SRU/Solr Protocol behavior
2. Queries
3. Result sets
3.1. Z39.50 Result-set Sort
3.2. Z39.50 Protocol behavior
3.3. SRU Protocol behavior
4. Records
4.1. Z39.50 Protocol behavior
4.2. SRU/Solr Protocol behavior
5. ZOOM Facets
6. Scan
7. Extended Services
7.1. Item Order
7.2. Record Update
7.3. Database Create
7.4. Database Drop
7.5. Commit Operation
7.6. Protocol behavior
8. Options
9. Query conversions
10. Events

ZOOM is an acronym for 'Z39.50 Object-Orientation Model' and is an initiative started by Mike Taylor (Mike is from the UK, which explains the peculiar name of the model). The goal of ZOOM is to provide a common Z39.50 client API not bound to a particular programming language or toolkit.

From YAZ version 2.1.12, SRU is supported. You can make SRU ZOOM connections by specifying scheme http:// for the hostname for a connection. The dialect of SRU used is specified by the value of the connection's sru option, which may be SRU over HTTP GET (get), SRU over HTTP POST (post), (SRU over SOAP) (soap) or solr (Solr Web Service). Using the facility for embedding options in target strings, a connection can be forced to use SRU rather the SRW (the default) by prefixing the target string with sru=get,, like this: sru=get,

Solr protocol support was added to YAZ in version 4.1.0, as a dialect of a SRU protocol, since both are HTTP based protocols.

The lack of a simple Z39.50 client API for YAZ has become more and more apparent over time. So when the first ZOOM specification became available, an implementation for YAZ was quickly developed. For the first time, it is now as easy (or easier!) to develop clients as it is to develop servers with YAZ. This chapter describes the ZOOM C binding. Before going further, please reconsider whether C is the right programming language for the job. There are other language bindings available for YAZ, and still more are in active development. See the ZOOM web-site for more information.

In order to fully understand this chapter you should read and try the example programs zoomtst1.c, zoomtst2.c, .. in the zoom directory.

The C language misses features found in object oriented languages such as C++, Java, etc. For example, you'll have to manually, destroy all objects you create, even though you may think of them as temporary. Most objects have a _create - and a _destroy variant. All objects are in fact pointers to internal stuff, but you don't see that because of typedefs. All destroy methods should gracefully ignore a NULL pointer.

In each of the sections below you'll find a sub section called protocol behavior, that describes how the API maps to the Z39.50 protocol.

1. Connections

The Connection object is a session with a target.

    #include <yaz/zoom.h>

    ZOOM_connection ZOOM_connection_new(const char *host, int portnum);

    ZOOM_connection ZOOM_connection_create(ZOOM_options options);

    void ZOOM_connection_connect(ZOOM_connection c, const char *host,
                                 int portnum);
    void ZOOM_connection_destroy(ZOOM_connection c);

Connection objects are created with either function ZOOM_connection_new or ZOOM_connection_create. The former creates and automatically attempts to establish a network connection with the target. The latter doesn't establish a connection immediately, thus allowing you to specify options before establishing network connection using the function ZOOM_connection_connect. If the port number, portnum, is zero, the host is consulted for a port specification. If no port is given, 210 is used. A colon denotes the beginning of a port number in the host string. If the host string includes a slash, the following part specifies a database for the connection.

You can prefix the host with a scheme followed by colon. The default scheme is tcp (Z39.50 protocol). The scheme http selects SRU/SOAP over HTTP by default, but can be changed with option sru.

You can prefix the scheme-qualified host-string with one or more comma-separated key=value sequences, each of which represents an option to be set into the connection structure before the protocol-level connection is forged and the initialization handshake takes place. This facility can be used to provide authentication credentials, as in host-strings such as: user=admin,password=halfAm4n,tcp:localhost:8017/db

Connection objects should be destroyed using the function ZOOM_connection_destroy.

    void ZOOM_connection_option_set(ZOOM_connection c,
                                    const char *key, const char *val);

    void ZOOM_connection_option_setl(ZOOM_connection c,
                                     const char *key,
                                     const char *val, int len);

    const char *ZOOM_connection_option_get(ZOOM_connection c,
                                           const char *key);
    const char *ZOOM_connection_option_getl(ZOOM_connection c,
                                            const char *key,
                                            int *lenp);

The functions ZOOM_connection_option_set and ZOOM_connection_option_setl allows you to set an option given by key to the value value for the connection. For ZOOM_connection_option_set, the value is assumed to be a 0-terminated string. Function ZOOM_connection_option_setl specifies a value of a certain size (len).

Functions ZOOM_connection_option_get and ZOOM_connection_option_getl returns the value for an option given by key.

Table 3.1. ZOOM Connection Options

implementationNameName of your client none
userAuthentication user name none
groupAuthentication group name none
passwordAuthentication password. none
authenticationModeHow authentication is encoded. basic
hostTarget host. This setting is "read-only". It's automatically set internally when connecting to a target. none
proxyProxy host. If set, the logical host is encoded in the otherInfo area of the Z39.50 Init PDU with OID 1.2.840.10003.10.1000.81.1. none
clientIPClient IP. If set, is encoded in the otherInfo area of a Z39.50 PDU with OID 1.2.840.10003.10.1000.81.3. Holds the original IP addresses of a client. Is used if ZOOM is used in a gateway of some sort. none
timeoutIdle timeout which specifies how long ZOOM will wait for network I/O before giving up. Thus, the actual waiting time might be longer than this value if the target makes a chunked response and the time between each chunk arrive is less this value. For the connect+init, this is the time ZOOM will wait until receiving first byte from Init response. 30
asyncIf true (1) the connection operates in asynchronous operation which means that all calls are non-blocking except ZOOM_event. 0
maximumRecordSize Maximum size of single record. 1 MB
preferredMessageSize Maximum size of multiple records. 1 MB
lang Language for negotiation. none
charset Character set for negotiation. none
rpnCharset Client-side character conversion for RPN queries and scan terms. The input terms are converted from UTF-8 to the character set of rpnCharset. none (no conversion)
serverImplementationId Implementation ID of server. (The old targetImplementationId option is also supported for the benefit of old applications.) none
targetImplementationName Implementation Name of server. (The old targetImplementationName option is also supported for the benefit of old applications.) none
serverImplementationVersion Implementation Version of server. (The old targetImplementationVersion option is also supported for the benefit of old applications.) none
databaseNameOne or more database names separated by character plus (+), which is to be used by subsequent search requests on this Connection. Default
piggybackTrue (1) if piggyback should be used in searches; false (0) if not. 1
smallSetUpperBoundIf hits is less than or equal to this value, then target will return all records using small element set name 0
largeSetLowerBoundIf hits is greater than this value, the target will return no records. 1
mediumSetPresentNumberThis value represents the number of records to be returned as part of a search when hits is less than or equal to large set lower bound and if hits is greater than small set upper bound. 0
smallSetElementSetName The element set name to be used for small result sets. none
mediumSetElementSetName The element set name to be used for medium-sized result sets. none
init_opt_search, init_opt_present, init_opt_delSet, etc. After a successful Init, these options may be interrogated to discover whether the server claims to support the specified operations. none
sru SRU/Solr transport type. Must be either soap, get, post, or solr. soap if scheme is already http; ignored otherwise
sru_version SRU/SRW version. Should be 1.1, or 1.2. This is, prior to connect, the version to offer (highest version). And following connect (in fact first operation), holds the negotiated version with the server (same or lower version). 1.2
extraArgs Extra arguments for SRU/Solr URLs. The value must be URL encoded already.  
facets Requested or recommended facets may be given before a search is sent. The value of this setting is described in Section 8, “Facets” For inspection of the facets returned, refer to the functions described in Section 5, “ZOOM Facets”. none
apdulog If set to a true value such as "1", a log of low-level protocol packets is emitted on standard error stream. This can be very useful for debugging. 0
saveAPDU If set to a true value such as "1", a log of low-level protocol packets is saved. The log can be retrieved by reading option APDU. Setting saveAPDU always has the side effect of resetting the currently saved log. This setting is write-only. If read, NULL will be returned. It is only recognized in ZOOM_connection_option_set. 0
APDU Returns the log of protocol packets. Will be empty if logging is not enabled (see saveAPDU above). This setting is read-only. It is only recognized if used in call to ZOOM_connection_option_get or ZOOM_connection_option_getl.  
memcached If given and non-empty, libMemcached will be configured for the connection. This option is inspected by ZOOM when a connection is established. If the memcached option is given and YAZ is compiled without libMemcached support, an internal diagnostic (10018) will be thrown. libMemcached support is available for YAZ 5.0.13 or later. If this option is supplied for an earlier version of YAZ, it is ignored. The value of this option is a list options - each is of the form --name=value. Option --server=host[:port] specifies a memcached server. It may be repeated for multiple memcached servers. Option --expire=seconds sets expiry time in seconds for how long result sets are to be cached. none
redis If given and non-empty, a redis context will be created for the connection. This option is inspected by ZOOM when a connection is established. If the redis option is given and YAZ is compiled without redis support, an internal diagnostic (10018) will be thrown. redis support is available for YAZ 5.2.0 or later. If this option is supplied for an earlier version of YAZ, it is ignored. The value of this option is a set of options, similar to that of the memcached setting. At this stage only --server=host[:port] and --expire=seconds are supported. none

If either option lang or charset is set, then Character Set and Language Negotiation is in effect.

     int ZOOM_connection_error(ZOOM_connection c, const char **cp,
                               const char **addinfo);
     int ZOOM_connection_error_x(ZOOM_connection c, const char **cp,
                                 const char **addinfo, const char **dset);

Function ZOOM_connection_error checks for errors for the last operation(s) performed. The function returns zero if no errors occurred; non-zero otherwise indicating the error. Pointers cp and addinfo holds messages for the error and additional-info if passed as non-NULL. Function ZOOM_connection_error_x is an extended version of ZOOM_connection_error that is capable of returning name of diagnostic set in dset.

1.1. Z39.50 Protocol behavior

The calls ZOOM_connection_new and ZOOM_connection_connect establishes a TCP/IP connection and sends an Initialize Request to the target if possible. In addition, the calls wait for an Initialize Response from the target and the result is inspected (OK or rejected).

If proxy is set then the client will establish a TCP/IP connection with the peer as specified by the proxy host and the hostname as part of the connect calls will be set as part of the Initialize Request. The proxy server will then "forward" the PDUs transparently to the target behind the proxy.

For the authentication parameters, if option user is set and both options group and pass are unset, then Open style authentication is used (Version 2/3) in which case the username is usually followed by a slash, then by a password. If either group or pass is set then idPass authentication (Version 3 only) is used. If none of the options are set, no authentication parameters are set as part of the Initialize Request (obviously).

When option async is 1, it really means that all network operations are postponed (and queued) until the function ZOOM_event is invoked. When doing so it doesn't make sense to check for errors after ZOOM_connection_new is called since that operation "connecting - and init" is still incomplete and the API cannot tell the outcome (yet).

1.2. SRU/Solr Protocol behavior

The HTTP based protocols (SRU, SRW, Solr) do not feature an Inititialize Request, so the connection phase merely establishes a TCP/IP connection with the HTTP server.

Most of the ZOOM connection options do not affect SRU/Solr and they are ignored. However, future versions of YAZ might honor implementationName and put that as part of User-Agent header for HTTP requests.

The charset is used in the Content-Type header of HTTP requests.

Setting authentcationMode specifies how authentication parameters are encoded for HTTP. The default is "basic" where user and password are encoded by using HTTP basic authentication.

If authentcationMode is "url", then user and password are encoded in the URL by parameters x-username and x-password as given by the SRU standard.