doc/zoom.xml

   1 <!-- $Id: zoom.xml,v 1.3 2001-10-24 20:12:36 adam Exp $ -->
   2  <chapter id="zoom"><title>Building clients with ZOOM</title>
   3
   4   <para>
   5    &zoom; is an acronym for Z39.50 Object Oriented Model and is
   6    an initiative started by Mike Taylor. The goal of &zoom; is to
   7    provide a common Z39.50 client API not bound to a particular
   8    programming language or toolkit.
   9   </para>
  10   <para>
  11    The lack of a simple Z39.50 client API for &yaz; was more apparent
  12    than ever. So, when the first ZOOM specification was available
  13    an implementation for &yaz; was developed. For the first time, it is
  14    now easier to develop clients than servers with &yaz;. This
  15    chapter describes the ZOOM C binding. Before going futher
  16    reconsider whether C is still the programming language of your
  17    choice. There are other language bindings available and others
  18    are in active development. See the ZOOM website at
  19    <ulink url="http://zoom.z3950.org/">zoom.z3950.org</ulink> for
  20    more information.
  21   </para>
  22
  23   <para>
  24    In order to fully understand this chapter you should read and
  25    try the example programs <literal>zoomtst1.c</literal>,
  26    <literal>zoomtst2.c</literal>, .. in the <literal>zoom</literal>
  27    directory.
  28   </para>
  29
  30   <para>
  31    The C language misses many features found in object oriented languages
  32    such as C++, Java, etc. For example, you'll have to, manually,
  33    destroy all objects you create, even though you may think of them as
  34    temporary. Most objects has a <literal>_create</literal> - and a
  35    <literal>_destroy</literal> variant.
  36    All objects are in fact pointers to internal stuff, but you don't see
  37    that because of typedefs. All destroy methods should gracefully ignore a
  38    <literal>NULL</literal> pointer.
  39   </para>
  40   <sect1 id="zoom.connections"><title>Connections</title>
  41
  42    <para>The Connection object is a session with a target.
  43    </para>
  44    <synopsis>
  45    #include &lt;yaz/zoom.h>
  46
  47    Z3950_connection Z3950_connection_new (const char *host, int portnum);
  48
  49    Z3950_connection Z3950_connection_create (Z3950_options options);
  50
  51    void Z3950_connection_connect(Z3950_connection c, const char *host,
  52                                  int portnum);
  53    void Z3950_connection_destroy (Z3950_connection c);
  54    </synopsis>
  55    <para>
  56     Connection objects are created with either function
  57     <function>Z3950_connection_new</function> or
  58     <function>Z3950_connection_create</function>.
  59     The former both creates and attempts to establishes a network
  60     connection with the target. The latter doesn't establishes
  61     a connection immediately, thus allowing you to set specify options
  62     before establishing network connection using function
  63     <function>Z3950_connection_connect</function>.
  64     If the portnumber, <literal>portnum</literal>, is zero, the
  65     <literal>host</literal> is consulted for a port specification.
  66     If no port is given, 210 is used. A colon denotes the beginning of
  67     a port number in the host string. If the host string includes a
  68     slash that specifies a database for the connection.
  69    </para>
  70    <para>
  71     Connection objects should be destroyed using function
  72     <function>Z3950_connection_destroy</function>.
  73    </para>
  74    <synopsis>
  75     const char *Z3950_connection_option (Z3950_connection c,
  76                                          const char *key,
  77                                          const char *val);
  78     const char *Z3950_connection_host (Z3950_connection c);
  79    </synopsis>
  80    <para>
  81     The <function>Z3950_connection_option</function> allows you to
  82     inspect or set an option given by <parameter>key</parameter>
  83     for the connection.
  84     If <parameter>val</parameter> is non-<literal>NULL</literal> that
  85     holds the new value for option.
  86     Otherwise, if <parameter>val</parameter> is <literal>NULL</literal>
  87     the option is unchanged.
  88     The function returns the previous value of the option.
  89    </para>
  90    <table frame="top"><title>ZOOM Connection Options</title>
  91     <tgroup cols="3">
  92      <colspec colwidth="4*" colname="name"></colspec>
  93      <colspec colwidth="7*" colname="description"></colspec>
  94      <colspec colwidth="3*" colname="default"></colspec>
  95     <thead>
  96      <row>
  97       <entry>Option</entry>
  98       <entry>Description</entry>
  99       <entry>Default</entry>
 100      </row>
 101     </thead>
 102     <tbody>
 103      <row><entry>
 104        implementationName</entry><entry>Name of Your client
 105       </entry><entry>none</entry></row>
 106      <row><entry>
 107        user</entry><entry>Authentication user name
 108       </entry><entry>none</entry></row>
 109      <row><entry>
 110        group</entry><entry>Authentication group name
 111       </entry><entry>none</entry></row>
 112      <row><entry>
 113        pass</entry><entry>Authentication password
 114       </entry><entry>none</entry></row>
 115      <row><entry>
 116        proxy</entry><entry>Proxy host
 117       </entry><entry>none</entry></row>
 118      <row><entry>
 119        async</entry><entry>If true (1) the connection operates in
 120        asynchronous operatio which means that all calls are non-blocking
 121        except <function>Z3950_event</function>.
 122       </entry><entry>0</entry></row>
 123      <row><entry>
 124        maximumRecordSize</entry><entry> Maximum size of single record.
 125       </entry><entry>1 MB</entry></row>
 126      <row><entry>
 127        preferredMessageSize</entry><entry> Maximum size of multiple records.
 128       </entry><entry>1 MB</entry></row>
 129     </tbody>
 130    </tgroup>
 131    </table>
 132    <para>
 133      Function <function>Z3950_connection_host</function> returns
 134      the host for the connection as specified in a call to
 135      <function>Z3950_connection_new</function> or
 136      <function>Z3950_connection_connect</function>.
 137      This function returns <literal>NULL</literal> if host isn't
 138      set for the connection.
 139    </para>
 140    <synopsis>
 141      int Z3950_connection_error (Z3950_connection c, const char **cp,
 142                                  const char **addinfo);
 143    </synopsis>
 144    <para>
 145      Use <function>Z3950_connection_error</function> to check for
 146      errors for the last operation(s) performed. The function returns
 147      zero if no errors occurred; non-zero otherwise indicating the error.
 148      Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
 149      holds messages for the error and additional-info if passed as
 150      non-<literal>NULL</literal>.
 151    </para>
 152   </sect1>
 153   <sect1 id="zoom.search"><title>Search objects</title>
 154    <para>
 155      Search objects defines how result sets are obtained. They
 156      act like queries.
 157    </para>
 158    <synopsis>
 159      Z3950_search Z3950_search_create(void);
 160
 161      void Z3950_search_destroy(Z3950_search s);
 162
 163      int Z3950_search_prefix(Z3950_search s, const char *str);
 164
 165      int Z3950_search_sortby(Z3950_search s, const char *criteria);
 166    </synopsis>
 167    <para>
 168      Create search objects using <function>Z3950_search_create</function>
 169      and destroy them by calling <function>Z3950_search_destroy</function>.
 170      RPN-queries can be specified in <link linkend="PQF">PQF</link>
 171      notation by using the
 172      function <function>Z3950_search_prefix</function>. More
 173      query types will be added later, such as
 174      <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
 175      etc. In addition to a search, a sort critieria may be set. Function
 176      <function>Z3950_search_sortby</function> specifies a
 177      sort criteria using the same string notation for sort as offered by
 178      the <link linkend="sortspec">YAZ client</link>.
 179    </para>
 180   </sect1>
 181   <sect1 id="zoom.resultsets"><title>Result sets</title>
 182    <para>
 183      The result set object is a container for records returned from
 184      a target.
 185      search.
 186    </para>
 187    <synopsis>
 188      Z3950_resultset Z3950_connection_search(Z3950_connection,
 189                                              Z3950_search q);
 190
 191      Z3950_resultset Z3950_connection_search_pqf(Z3950_connection c,
 192                                                  const char *q);
 193
 194      void Z3950_resultset_destroy(Z3950_resultset r);
 195    </synopsis>
 196    <para>
 197      Function <function>Z3950_connection_search</function> creates
 198      a result set given a connection - and search object.
 199      Destroy a result set by calling
 200      <function>Z3950_resultset_destroy</function>.
 201      Simple clients using PQF only may use function
 202      <function>Z3950_connection_search_pqf</function> instead.
 203    </para>
 204    <synopsis>
 205      const char *Z3950_resultset_option (Z3950_resultset r,
 206                                          const char *key,
 207                                          const char *val);
 208
 209      int Z3950_resultset_size (Z3950_resultset r);
 210
 211      void *Z3950_resultset_get (Z3950_resultset s, int pos,
 212                                 const char *type, int *len);
 213    </synopsis>
 214    <para>
 215      Function <function>X3950_resultset_options</function> sets or
 216      modifies an option for a result set similar to
 217     <function>Z3950_connection_option</function>.
 218    </para>
 219    <para>
 220      The number of hits also called result-count is returned by
 221      function <function>Z3950_resultset_size</function>.
 222    </para>
 223    <para>
 224      Function <function>Z3950_resultset_get</function> is similar to
 225      <link linkend="zoom.record.get">
 226      <function>Z3950_record_get</function></link> but
 227      instead of operating on a record object it operates on a record on
 228      a given offset within a result set.
 229    </para>
 230    <table frame="top"><title>ZOOM Result set Options</title>
 231     <tgroup cols="3">
 232      <colspec colwidth="4*" colname="name"></colspec>
 233      <colspec colwidth="7*" colname="description"></colspec>
 234      <colspec colwidth="2*" colname="default"></colspec>
 235     <thead>
 236      <row>
 237       <entry>Option</entry>
 238       <entry>Description</entry>
 239       <entry>Default</entry>
 240      </row>
 241     </thead>
 242     <tbody>
 243      <row><entry>
 244        piggyback</entry><entry>True (1) if piggyback should be
 245        used in searches; false (0) if not.
 246       </entry><entry>1</entry></row>
 247      <row><entry>
 248        start</entry><entry>Offset of first record we wish to
 249        retrieve from the target. Note first record has offset 0
 250       unlike the protocol specifications where first record has position
 251        1.
 252       </entry><entry>0</entry></row>
 253      <row><entry>
 254        count</entry><entry>Number of records to be retrieved.
 255       </entry><entry>0</entry></row>
 256      <row><entry>
 257        elementSetName</entry><entry>Element-Set name of records.
 258        Most targets should honor element set name <literal>B</literal>
 259        and <literal>F</literal> for brief and full respectively.
 260       </entry><entry>none</entry></row>
 261      <row><entry>
 262        preferredRecordSyntax</entry><entry>Preferred Syntax, such as
 263        <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
 264       </entry><entry>none</entry></row>
 265      <row><entry>
 266        databaseName</entry><entry>One or more database names
 267        separated by character plus (<literal>+</literal>).
 268       </entry><entry>Default</entry></row>
 269     </tbody>
 270    </tgroup>
 271    </table>
 272   </sect1>
 273   <sect1 id="zoom.records"><title>Records</title>
 274    <para>
 275      A record object is a retrival record on the client side -
 276      created from result sets.
 277    </para>
 278    <synopsis>
 279      void Z3950_resultset_records (Z3950_resultset r,
 280                                    Z3950_record *recs,
 281                                    size_t *cnt);
 282      Z3950_record Z3950_resultset_record (Z3950_resultset s, int pos);
 283
 284      void *Z3950_record_get (Z3950_record rec, const char *type,
 285                              int *len);
 286
 287      void Z3950_record_destroy (Z3950_record rec);
 288    </synopsis>
 289    <para>
 290      Records are created by functions
 291      <function>Z3950_resultset_records</function> or
 292      <function>Z3950_resultset_record</function>
 293      and destroyed by <function>Z3950_record_destroy</function>.
 294    </para>
 295    <para>
 296      A single record is created and returned by function
 297      <function>Z3950_resultset_record</function> that takes a
 298      position as argument. First record has position zero.
 299      If no record could be obtained <literal>NULL</literal> is returned.
 300    </para>
 301    <para>
 302      Function <function>Z39_resultset_records</function> retrieves
 303      a number of records from a result set. Options <literal>start</literal>
 304      and <literal>count</literal> specifies the range of records to
 305      be returned. Upon completion <literal>recs[0], ..recs[*cnt]</literal>
 306      holds record objects for the records. These array of records
 307      <literal>recs</literal> should be allocate prior to calling
 308      <function>Z3950_resultset_records</function>. Note that for
 309      records that couldn't be retrieved from the target
 310      <literal>recs[ ..]</literal> is <literal>NULL</literal>.
 311    </para>
 312    <para id="zoom.record.get">
 313      In order to extract information about a single record,
 314      <function>Z3950_record_get</function> is provided. The
 315      function returns a pointer to certain record information. The
 316      nature (type) of the pointer depends on the <function>type</function>
 317      given. In addition for certain types, the length
 318      <literal>len</literal> passed will be set to the size in bytes of
 319      the returned information. The types <literal>database</literal>,
 320      <literal>syntax</literal> and <literal>render</literal> are
 321      supported. More will be added later.
 322    </para>
 323   </sect1>
 324   <sect1 id="zoom.options"><title>Options</title>
 325    <para>
 326      Most objects in &zoom; allows you to specify options to change
 327      behaviour. From an implementation point of view a set of options
 328      is just like an associate array / hash array, etc.
 329    </para>
 330    <synopsis>
 331      Z3950_options Z3950_options_create (void);
 332
 333      Z3950_options Z3950_options_create_with_parent (Z3950_options parent);
 334
 335      void Z3950_options_destroy (Z3950_options opt);
 336    </synopsis>
 337    <synopsis>
 338      const char *Z3950_options_get (Z3950_options opt, const char *name);
 339
 340      void Z3950_options_set (Z3950_options opt, const char *name,
 341                              const char *v);
 342    </synopsis>
 343    <synopsis>
 344      typedef const char *(*Z3950_options_callback)
 345                                      (void *handle, const char *name);
 346
 347      Z3950_options_callback
 348              Z3950_options_set_callback (Z3950_options opt,
 349                                          Z3950_options_callback c,
 350                                          void *handle);
 351    </synopsis>
 352   </sect1>
 353   <sect1 id="zoom.events"><title>Events</title>
 354    <para>
 355      If you're developing non-blocking applications you have to deal
 356      with events.
 357    </para>
 358    <synopsis>
 359      int Z3950_event (int no, Z3950_connection *cs);
 360    </synopsis>
 361    <para>
 362      The <function>Z3950_event</function> executes pending events for
 363      a number of connections. Supply the number of connections in
 364      <literal>no</literal> and an array of connections in
 365      <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
 366      A pending event could be a sending a search, receiving a response,
 367      etc.
 368      When an event has a occured for one of the connections this function
 369      returns a positive integer <literal>n</literal> denoting that an event
 370      occurred for connection <literal>cs[n-1]</literal>.
 371      When no events are pending for the connections a value of zero is
 372      returned.
 373      To make sure all outstanding requests are performed call this function
 374      repeatedly until zero is returned.
 375    </para>
 376   </sect1>
 377  </chapter>
 378
 379  <!-- Keep this comment at the end of the file
 380  Local variables:
 381  mode: sgml
 382  sgml-omittag:t
 383  sgml-shorttag:t
 384  sgml-minimize-attributes:nil
 385  sgml-always-quote-attributes:t
 386  sgml-indent-step:1
 387  sgml-indent-data:t
 388  sgml-parent-document: "yaz.xml"
 389  sgml-local-catalogs: "../../docbook/docbook.cat"
 390  sgml-namecase-general:t
 391  End:
 392  -->
 393