# class ZOOM::Connection

The Connection object is a session with a target.

### Public Class Methods

new(options=nil) click to toggle source

options: options for the connection, as a Hash object.

Creates a new connection object, but does not establish a network connection immediately, allowing you to specify options before (if given). You can thus establish the connection using #connect.

Returns: a newly created ZOOM::Connection object.

    static VALUE
    rbz_connection_new (int argc, VALUE *argv, VALUE self)
    {
        ZOOM_options options;
        ZOOM_connection connection;
        VALUE rb_options;

        rb_scan_args (argc, argv, "01", &rb_options);

        if (NIL_P (rb_options))
            options = ZOOM_options_create ();
        else
            options = ruby_hash_to_zoom_options (rb_options);

        connection = ZOOM_connection_create (options);
        ZOOM_options_destroy (options);
        RAISE_IF_FAILED (connection);

        return rbz_connection_make (connection);
    }

open(host, port=nil) { |conn| ... } click to toggle source

host: hostname of the target to connect to.

port: network port of the target to connect to.

A convenience method that creates a new connection and attempts to establish a network connection to the given target, basically calling ::new and #connect.

If a block is given, then it will be called once the connection is established, passing a reference to the connection object as a parameter, and destroying the connection automatically at the end of the block. With no block, this method just returns the connection object.

Returns: a newly created ZOOM::Connection object.

    static VALUE
    rbz_connection_open (int argc, VALUE *argv, VALUE self)
    {
        VALUE host;
        VALUE port;
        ZOOM_connection connection;
        VALUE rb_connection;

        rb_scan_args (argc, argv, "11", &host, &port);

        connection = ZOOM_connection_new (RVAL2CSTR (host),
                                          NIL_P (port) ? 0 : FIX2INT (port));
        RAISE_IF_FAILED (connection);

        rb_connection = rbz_connection_make (connection);
        if (rb_block_given_p ()) {
            rb_yield(rb_connection);
            return Qnil;
        }
        return rb_connection;
    }

### Public Instance Methods

connect(host, port=nil) click to toggle source

host: hostname of the target to connect to.

port: network port of the target to connect to.

Establishes a network connection to the target specified by the given arguments. If no port is given, 210 will be used. A colon in the host string denotes the beginning of a port number. If the host string includes a slash, the following part specifies a database for the connection.

You can also prefix the host string with a scheme followed by a colon. The default scheme is tcp (Z39.50 protocol). The scheme http selects SRW over HTTP.

This method raises an exception on error.

Returns: self.

    static VALUE
    rbz_connection_connect (int argc, VALUE *argv, VALUE self)
    {
        ZOOM_connection connection;
        VALUE host;
        VALUE port;

        rb_scan_args (argc, argv, "11", &host, &port);

        connection = rbz_connection_get (self);
        ZOOM_connection_connect (connection,
                                 RVAL2CSTR (host),
                                 NIL_P (port) ? 0 : FIX2INT (port));
        RAISE_IF_FAILED (connection);

        return self;
    }

get_option(key) click to toggle source

key: the name of the option, as a string.

Gets the value of a connection's option.

Returns: the value of the given option, as a string, integer or boolean.

    static VALUE
    rbz_connection_get_option (VALUE self, VALUE key)
    {
        ZOOM_connection connection;
        const char *value;

        connection = rbz_connection_get (self);
        value = ZOOM_connection_option_get (connection,
                                            RVAL2CSTR (key));

        return zoom_option_value_to_ruby_value (value);
    }

package() click to toggle source

Constructs a new extended services ZOOM::Package using this connections host information.

Note: The Perl script passes this connections options if already set, otherwise constructs a new ZOOM::Option object. Currently this method always constructs a new ZOOM::Option object for each package.

Returns: a new ZOOM::Package object.

    static VALUE
    rbz_connection_package(VALUE self)
    {
      ZOOM_connection connection;
      ZOOM_options options;
      ZOOM_package package;

      connection = rbz_connection_get (self);
      options = ZOOM_options_create ();
      package = rbz_package_make(connection, options);
      return package;
    }

search(criterion) click to toggle source

criterion: the search criterion, either as a ZOOM::Query object or as a string, representing a PQF query.

Searches the connection from the given criterion. You can either create and pass a reference to a ZOOM::Query object, or you can simply pass a string that represents a PQF query.

This method raises an exception on error.

Returns: a result set from the search, as a ZOOM::ResultSet object, empty if no results were found.

    static VALUE
    rbz_connection_search (VALUE self, VALUE criterion)
    {
        ZOOM_connection connection;
        ZOOM_resultset resultset;

        connection = rbz_connection_get (self);
        if (TYPE (criterion) == T_STRING)
            resultset = ZOOM_connection_search_pqf (connection,
                                                    RVAL2CSTR (criterion));
        else
            resultset = ZOOM_connection_search (connection,
                                                rbz_query_get (criterion));
        RAISE_IF_FAILED (connection);
        assert (resultset != NULL);

        return rbz_resultset_make (resultset);
    }

set_option(key, value) click to toggle source

key: the name of the option, as a string.

value: the value of this option (as a string, integer or boolean).

Sets an option on the connection.

Returns: self.

    static VALUE
    rbz_connection_set_option (VALUE self, VALUE key, VALUE val)
    {
        ZOOM_connection connection;

        connection = rbz_connection_get (self);
        ZOOM_connection_option_set (connection,
                                    RVAL2CSTR (key),
                                    RVAL2CSTR (val));
        RAISE_IF_FAILED (connection);

        return self;
    }