BZoom - a Bigloo binding for Zoom
---------------------------------
(C) 2003 Johannes Leveling
email: Johannes.Leveling@fernuni-hagen.de
---------------------------------
BZoom is a Bigloo binding to the high level ZOOM
(Z39.50 Object-Orientation Model) client API for the Z39.50 protocol.
It is implemented on top of the YAZ implementation
as a set of C and Scheme functions.
BZoom was developed and tested under Linux (2.4.18)
with Bigloo (version 2.5c) and YAZ (version 1.9.2).

Before trying to compile, make sure you have both Bigloo and 
YAZ installed. Several demos are included (adapted from the 
YAZ Z39.50 toolkit), which may expect an argument specifying 
an URL consisting of Z39.50 server name, port and database.
For example, the database of the Library of Congress is
represented by the URL:
z3950.loc.gov:7090/Voyager

See the section 'Links' at the end of this document for
links to further information on Z39.50, YAZ, Zoom and Bigloo.

-----------
Scheme API:
-----------
This description of the Scheme API is meant help identify
between the YAZ Zoom API and the Bigloo binding. Please refer
to the YAZ documentation for a more complete description. 

Constants such as ZOOM_ERROR_NONE, ZOOM_EVENT_CONNECT, ...
are defined via macros and are accessible from Bigloo.


ZOOM Connections:
-----------------
Name:
* (zoom:connection_new host port)
  Description: 
   create new ZOOM connection object and connect 
  Parameters:
   host: string
   port: integer
  Returns:
  -> conn: integer

Name:
* (zoom:connection_create options)
  Description: 
   create ZOOM connection object with options set
  Parameters:
   options: Zoom options
  Returns:
  -> conn: integer

Name:
* (zoom:connection_connect conn host port)
  Description: 
   try to connect
  Parameters:
   conn: Zoom connection
   host: string
   port: integer
  Returns:
  -> always 0

Name:
* (zoom:connection_destroy conn)
  Description: 
   destroy connection
  Parameters:
   conn: Zoom connection
  Returns:
  -> always 0 

Name:
* (zoom:connection_option_set conn key val)
  Description: 
   set option for a connection
  Parameters:
   conn: Zoom connection
   key: string
   val: string 
  Returns:
  -> always 0

Name:
* (zoom:connection_option_get conn key)
  Description: 
   get connection option
  Parameters:
   conn: Zoom connection
   key: string
  Returns:
  -> val: string

ZOOM Error handling:
--------------------
Name:
* (zoom:connection_error conn)
  Description: 
   get a list representing the error status for a connection
  Parameters:
   conn: Zoom connection
  Returns:
  -> (errcode errmsg addinfo): (int string string)

Name:
* (zoom:connection_errcode conn) 
  Description: 
   get error code
  Parameters:
   conn: Zoom connection
  Returns:
  -> errcode: integer

Name:
* (zoom:connection_errmsg conn)
  Description: 
   get error message
  Parameters:
   conn: Zoom connection
  Returns:
  -> errmsg: string

Name:
* (zoom:connection_addinfo conn)
  Description: 
   get additional error information
  Parameters:
   conn: Zoom connection
  Returns:
  -> addinfo: string

Name:
* (zoom:connection_last_event conn)
  Description: 
   get last event (probably one causing an error)
  Parameters:
   conn: Zoom connection
  Returns:
  -> event: integer 

ZOOM Queries:
-------------
Name:
* (zoom:query_create)
  Description: 
   create Zoom query object
  Returns:
  -> Zoom query: integer

Name:
* (zoom:query_destroy q)
  Description: 
   destroy Zoom query object
  Parameters:
   q: Zoom query
  Returns:
  -> always 0

Name:
* (zoom:query_prefix q s)
  Description: 
   parse and set query string for query
  Parameters:
   q: Zoom query 
   s: string
  Returns:
  -> parse result: integer

Name:
* (zoom:query_sortby q c)
  Description: 
   set sort criteria
  Parameters:
   q: Zoom query
   c: string
  Returns:
  -> result: integer

ZOOM Result sets:
-----------------
Name:
* (zoom:connection_search conn q)
  Description:
   create ZOOM result set object 
  Parameters:
   conn: Zoom connection
   q: Zoom query
  Returns:
  -> Zoom resultset: integer

Name:
* (zoom:connection_search_pqf conn s)
  Description: 
   returns ZOOM result set object
  Parameters:
   conn: Zoom connection
   s: string
  Returns:
  -> Zoom resultset: integer

Name:
* (zoom:resultset_destroy r)
  Description: 
   destroy ZOOM result set object
  Parameters:
   r: Zoom resultset
  Returns:
  -> always 0

Name:
* (zoom:resultset_option_get r key)
  Description: 
   get result set option
  Parameters:
   r: Zoom resultset
   key: string
  Returns:
  -> val: string

Name:
* (zoom:resultset_option_set r key val)
  Description: 
   set result set option
  Parameters:
   r: Zoom resultset
   key: string
   val: string
  Returns:
  -> always 0

Name:
* (zoom:resultset_size r)
  Description: 
   size of result set
  Parameters:
   r: Zoom resultset
  Returns:
  -> cardinality of r: integer
 
ZOOM Records:
-------------
Name:
* (z:resultset_records r start count)
  Description: 
   get records from result set
  Parameters:
   r: Zoom resultset
   start: integer
   count: integer
  Returns:
  -> (rec1 rec2 ... recn): (Zoom record  Zoom record ... Zoom record)

Name:
* (zoom:resultset_record r pos) "Zresultset_record")
  Description: 
   get record from result set
  Parameters:
   r: Zoom resultset
   pos: integer
  Returns:
  -> rec: Zoom record

Name:
* (z:record_get rec type)
  Description: 
   get string representation of record and length   
  Parameters:
   rec: Zoom record
   type: integer
  Returns:
  -> (val len): (string integer)

Name:
* (zoom:record_destroy rec)
  Description:
   destroy Zoom record object 
  Parameters:
   rec: Zoom record
  Returns:
  -> always 0

Name:
* (zoom:record_clone rec)
  Description: 
   copy Zoom record
  Parameters:
   rec: Zoom record
  Returns:
  -> rec

ZOOM Scan sets:
---------------
Name:
* (zoom:connection_scan conn startterm)
  Description: 
   perform scan and create scanset object
  Parameters:
   conn: Zoom connection
   startterm: string
  Returns:
  -> Zoom scanset

Name:
* (zoom:scanset_term st pos)
  Description: 
   scanset term, number of occurences and length
  Parameters:
   st: Zoom scanset
   pos: integer
  Returns:
  -> (term occ len): (string int int)

Name:
* (zoom:scanset_size st)
  Description: 
   size of scanset
  Parameters:
   st: Zoom scanset
  Returns:
  -> cardinality of st: integer

Name:
* (zoom:scanset_destroy st)
  Description: 
   destroy Zoom scanset object
  Parameters:
   st: Zoom scanset
  Returns:
  -> always 0

Name:
* (zoom:scanset_option_get st key)
  Description: 
   get scanset option
  Parameters:
   st: Zoom scanset
   key: string
  Returns:
  -> val: string

Name:
* (zoom:scanset_option_set key val)
  Description: 
   set scanset option
  Parameters:
   st: Zoom scanset
   key: string
   val: string
  Returns:
  -> always 0

ZOOM Options:
-------------
Name:
* (zoom:options_create)
  Description: 
   create Zoom option object
  Returns:
  -> Zoom options: integer

Name:
* (zoom:options_create_with_parent o)
  Description: 
   create new and inherit parent option
  Parameters:
   o: Zoom options
  Returns:
  -> Zoom options: integer

Name:
* (zoom:options_get o key)
  Description: 
   get option
  Parameters:
   o: Zoom options
   key: string
  Returns:
  -> val: string

Name:
* (zoom:options_set o key val)
  Description: 
   set option
  Parameters:
   o: Zoom options
   key: string
   val: string
  Returns:
  -> always 0

Name:
* (zoom:options_get_int o key def)
  Description: 
   get integer option
  Parameters:
   o: Zoom options
   key: string
   def: integer
  Returns:
  -> val: integer 

Name:
* (zoom:options_set_int o key val)
  Description: 
   set integer option
  Parameters:
   o: Zoom options
   key: string
   val: integer
  Returns:
  -> val: integer

Name:
* (zoom:options_destroy o)
  Description: 
   destroy ZOOM options object
  Parameters:
   o: Zoom options  
  Returns:
  -> always 0

Name:
* (Zoptions_set_callback o proc handle)
  Description: 
   install a callback to process options
  Parameters:
   o: Zoom options  
   proc: callback/Scheme procedure
   handle: Scheme object
  Returns:
  -> string

ZOOM Events:
Name:
* (zoom:event no cs)
  Description: 
   execute events for a number of connections
  Parameters:
   no: integer
   cs: vector/list
  Returns:
  -> event: integer


------------
BZOOM Demos:
------------
* canonical (hello world): 
- connects to LoC and retrievs a document about dinosaurs
./canonical

* bclient (interactive command-line client):
./bclient

* zoomtst1 (sync single-target search):
./zoomtst1 ki212.fernuni-hagen.de:2100/girt computer

* zoomtst2 (async single-target search): 
./zoomtst2 ki212.fernuni-hagen.de:2100/girt computer

* zoomtst3 (async multi-target search, piggyback retrieve): 
./zoomtst3 5 ki212.fernuni-hagen.de:2100/girt schule

* zoomtst4
./zoomtst4 localhost ki212.fernuni-hagen.de:2100/girt test

* zoomtst5 (async multi-target search, sort and present)
./zoomtst5 ki212.fernuni-hagen.de:2100/girt test '4 <'

* zoomtst6 (async multi-target, two searches): 
comment: like in YAZ, records are not displayed
./zoomtst6 ki212.fernuni-hagen.de:2100/girt gewalt schule

* zoomtst7 (API test, expects database at localhost:9999):
./zoomtst7

* zoomtst8 (scan test):
./zoomtst8 ki212.fernuni-hagen.de:2100/girt testament


------
Links:
------
* Bigloo:
http://www-sop.inria.fr/mimosa/fp/Bigloo
(download at: ftp://ftp-sop.inria.fr/mimosa/fp/Bigloo)

* Indexdata / YAZ:
http://www.indexdata.dk/yaz

* Z39.50 / Library of Congress
http://www.loc.goc/z3950/agency/

* Zoom:
http://zoom.z3950.org
http://www.indexdata.dk/yaz/doc/zoom.php