doc/zoom.xml

   1 <!-- $Id: zoom.xml,v 1.5 2001-10-26 20:13:44 adam 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    </para>
 190    <synopsis>
 191      Z3950_resultset Z3950_connection_search(Z3950_connection,
 192                                              Z3950_search q);
 193
 194      Z3950_resultset Z3950_connection_search_pqf(Z3950_connection c,
 195                                                  const char *q);
 196
 197      void Z3950_resultset_destroy(Z3950_resultset r);
 198    </synopsis>
 199    <para>
 200     Function <function>Z3950_connection_search</function> creates
 201      a result set given a connection - and search object.
 202     Destroy a result set by calling
 203     <function>Z3950_resultset_destroy</function>.
 204     Simple clients using PQF only may use function
 205     <function>Z3950_connection_search_pqf</function> instead.
 206    </para>
 207    <synopsis>
 208      const char *Z3950_resultset_option (Z3950_resultset r,
 209                                          const char *key,
 210                                          const char *val);
 211
 212      int Z3950_resultset_size (Z3950_resultset r);
 213
 214      void *Z3950_resultset_get (Z3950_resultset s, int pos,
 215                                 const char *type, int *len);
 216    </synopsis>
 217    <para>
 218     Function <function>Z3950_resultset_options</function> sets or
 219     modifies an option for a result set similar to
 220     <function>Z3950_connection_option</function>.
 221    </para>
 222    <para>
 223     The number of hits also called result-count is returned by
 224     function <function>Z3950_resultset_size</function>.
 225    </para>
 226    <para>
 227     Function <function>Z3950_resultset_get</function> is similar to
 228     <link linkend="zoom.record.get">
 229      <function>Z3950_record_get</function></link> but
 230     instead of operating on a record object, it operates on a record on
 231     a given offset within a result set.
 232    </para>
 233    <table frame="top"><title>ZOOM Result set Options</title>
 234     <tgroup cols="3">
 235      <colspec colwidth="4*" colname="name"></colspec>
 236      <colspec colwidth="7*" colname="description"></colspec>
 237      <colspec colwidth="2*" colname="default"></colspec>
 238      <thead>
 239       <row>
 240        <entry>Option</entry>
 241        <entry>Description</entry>
 242        <entry>Default</entry>
 243       </row>
 244      </thead>
 245      <tbody>
 246       <row><entry>
 247         piggyback</entry><entry>True (1) if piggyback should be
 248         used in searches; false (0) if not.
 249        </entry><entry>1</entry></row>
 250       <row><entry>
 251         start</entry><entry>Offset of first record we wish to
 252         retrieve from the target. Note first record has offset 0
 253         unlike the protocol specifications where first record has position
 254         1.
 255        </entry><entry>0</entry></row>
 256       <row><entry>
 257         count</entry><entry>Number of records to be retrieved.
 258        </entry><entry>0</entry></row>
 259       <row><entry>
 260         elementSetName</entry><entry>Element-Set name of records.
 261         Most targets should honor element set name <literal>B</literal>
 262         and <literal>F</literal> for brief and full respectively.
 263        </entry><entry>none</entry></row>
 264       <row><entry>
 265         preferredRecordSyntax</entry><entry>Preferred Syntax, such as
 266         <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
 267        </entry><entry>none</entry></row>
 268       <row><entry>
 269         databaseName</entry><entry>One or more database names
 270         separated by character plus (<literal>+</literal>).
 271        </entry><entry>Default</entry></row>
 272      </tbody>
 273     </tgroup>
 274    </table>
 275   </sect1>
 276   <sect1 id="zoom.records"><title>Records</title>
 277    <para>
 278     A record object is a retrival record on the client side -
 279     created from result sets.
 280    </para>
 281    <synopsis>
 282      void Z3950_resultset_records (Z3950_resultset r,
 283                                    Z3950_record *recs,
 284                                    size_t *cnt);
 285      Z3950_record Z3950_resultset_record (Z3950_resultset s, int pos);
 286
 287      void *Z3950_record_get (Z3950_record rec, const char *type,
 288                              int *len);
 289
 290      void Z3950_record_destroy (Z3950_record rec);
 291    </synopsis>
 292    <para>
 293     Records are created by functions
 294     <function>Z3950_resultset_records</function> or
 295     <function>Z3950_resultset_record</function>
 296     and destroyed by <function>Z3950_record_destroy</function>.
 297    </para>
 298    <para>
 299     A single record is created and returned by function
 300     <function>Z3950_resultset_record</function> that takes a
 301     position as argument. First record has position zero.
 302     If no record could be obtained <literal>NULL</literal> is returned.
 303    </para>
 304    <para>
 305     Function <function>Z3950_resultset_records</function> retrieves
 306     a number of records from a result set. Options <literal>start</literal>
 307     and <literal>count</literal> specifies the range of records to
 308     be returned. Upon completion <literal>recs[0], ..recs[*cnt]</literal>
 309     holds record objects for the records. These array of records
 310      <literal>recs</literal> should be allocate prior to calling
 311     <function>Z3950_resultset_records</function>. Note that for
 312     records that couldn't be retrieved from the target
 313     <literal>recs[ ..]</literal> is <literal>NULL</literal>.
 314    </para>
 315    <para id="zoom.record.get">
 316     In order to extract information about a single record,
 317     <function>Z3950_record_get</function> is provided. The
 318     function returns a pointer to certain record information. The
 319     nature (type) of the pointer depends on the <function>type</function>
 320     given. In addition for certain types, the length
 321     <literal>len</literal> passed will be set to the size in bytes of
 322     the returned information. The types <literal>database</literal>,
 323     <literal>syntax</literal> and <literal>render</literal> are
 324     supported. More will be added later.
 325    </para>
 326   </sect1>
 327   <sect1 id="zoom.options"><title>Options</title>
 328    <para>
 329     Most objects in &zoom; allow you to specify options to change
 330     default behaviour. From an implementation point of view a set of options
 331     is just like an associate array / hash array, etc.
 332    </para>
 333    <synopsis>
 334      Z3950_options Z3950_options_create (void);
 335
 336      Z3950_options Z3950_options_create_with_parent (Z3950_options parent);
 337
 338      void Z3950_options_destroy (Z3950_options opt);
 339    </synopsis>
 340    <synopsis>
 341      const char *Z3950_options_get (Z3950_options opt, const char *name);
 342
 343      void Z3950_options_set (Z3950_options opt, const char *name,
 344                              const char *v);
 345    </synopsis>
 346    <synopsis>
 347      typedef const char *(*Z3950_options_callback)
 348                                      (void *handle, const char *name);
 349
 350      Z3950_options_callback
 351              Z3950_options_set_callback (Z3950_options opt,
 352                                          Z3950_options_callback c,
 353                                          void *handle);
 354    </synopsis>
 355   </sect1>
 356   <sect1 id="zoom.events"><title>Events</title>
 357    <para>
 358     If you're developing non-blocking applications, you have to deal
 359     with events.
 360    </para>
 361    <synopsis>
 362     int Z3950_event (int no, Z3950_connection *cs);
 363    </synopsis>
 364    <para>
 365     The <function>Z3950_event</function> executes pending events for
 366     a number of connections. Supply the number of connections in
 367     <literal>no</literal> and an array of connections in
 368     <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
 369     A pending event could be a sending a search, receiving a response,
 370     etc.
 371     When an event has a occured for one of the connections, this function
 372     returns a positive integer <literal>n</literal> denoting that an event
 373     occurred for connection <literal>cs[n-1]</literal>.
 374     When no events are pending for the connections, a value of zero is
 375     returned.
 376     To make sure all outstanding requests are performed call this function
 377     repeatedly until zero is returned.
 378    </para>
 379   </sect1>
 380  </chapter>
 381
 382  <!-- Keep this comment at the end of the file
 383  Local variables:
 384  mode: sgml
 385  sgml-omittag:t
 386  sgml-shorttag:t
 387  sgml-minimize-attributes:nil
 388  sgml-always-quote-attributes:t
 389  sgml-indent-step:1
 390  sgml-indent-data:t
 391  sgml-parent-document: "yaz.xml"
 392  sgml-local-catalogs: nil
 393  sgml-namecase-general:t
 394  End:
 395  -->
 396