Chapter 3. Building clients with ZOOM

Table of Contents
Connections
Search objects
Result sets
Records
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 futher, 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 website at zoom.z3950.org 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 many 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.

Connections

The Connection object is a session with a target.


   #include <yaz/zoom.h>
    
   Z3950_connection Z3950_connection_new (const char *host, int portnum);
    
   Z3950_connection Z3950_connection_create (Z3950_options options);

   void Z3950_connection_connect(Z3950_connection c, const char *host,
                                 int portnum);
   void Z3950_connection_destroy (Z3950_connection c);
   

Connection objects are created with either function Z3950_connection_new or Z3950_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 Z3950_connection_connect. If the portnumber, 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 Z3950_connection_destroy.


    const char *Z3950_connection_option (Z3950_connection c,
                                         const char *key,
                                         const char *val);
    const char *Z3950_connection_host (Z3950_connection c);
   

The Z3950_connection_option allows you to inspect or set an option given by key for the connection. If val is non-NULL that holds the new value for option. Otherwise, if val is NULL, the option is unchanged. The function returns the previous value of the option.

Table 3-1. ZOOM Connection Options

OptionDescriptionDefault
implementationNameName of Your client none
userAuthentication user name none
groupAuthentication group name none
passAuthentication password none
proxyProxy host none
asyncIf true (1) the connection operates in asynchronous operation which means that all calls are non-blocking except Z3950_event. 0
maximumRecordSize Maximum size of single record. 1 MB
preferredMessageSize Maximum size of multiple records. 1 MB

Function Z3950_connection_host returns the host for the connection as specified in a call to Z3950_connection_new or Z3950_connection_connect. This function returns NULL if host isn't set for the connection.


     int Z3950_connection_error (Z3950_connection c, const char **cp,
                                 const char **addinfo);
   

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