Chapter 3. Building clients with ZOOM

Table of Contents
Connections
Queries
Result sets
Records
Scan
Options
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.

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

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.

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

    const char *ZOOM_connection_option_get (ZOOM_connection c,
                                            const char *key);

The ZOOM_connection_option_set allows you to set an option given by key to the value value for the connection. Function ZOOM_connection_option_get returns the value for an option given by key.

Table 3-1. ZOOM Connection Options

Option	Description	Default
implementationName	Name of Your client	none
user	Authentication user name	none
group	Authentication group name	none
pass	Authentication password	none
host	Target host. This setting is "read-only". It's automatically set internally when connecting to a target.	none
proxy	Proxy host	none
async	If 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

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

Use ZOOM_connection_error to check 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.

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 waits 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 PDU's 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).