doc/zoom.xml

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