Chapter 3. ZOOM

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.

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.