doc/zoom.xml

   1 <!-- $Id: zoom.xml,v 1.1 2001-10-23 21:00:19 adam Exp $ -->
   2  <chapter><title>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 apparanet
  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><title>Connections</title>
  41
  42    <para>The connection object Z3950_connection describes
  43    the connection between your client and a server.
  44    </para>
  45    <synopsis>
  46    #include &lt;yaz/zoom.h>
  47
  48    Z3950_connection Z3950_connection_new (const char *host, int portnum);
  49
  50    Z3950_connection Z3950_connection_create (Z3950_options options);
  51
  52    void Z3950_connection_connect(Z3950_connection c, const char *host,
  53                                  int portnum);
  54    void Z3950_connection_destroy (Z3950_connection c);
  55    </synopsis>
  56    <para>
  57     Connection objects are created with either function
  58     <function>Z3950_connection_new</function> or
  59     <function>Z3950_connection_create</function>.
  60     The former both creates and attempts to establishes a network
  61     connection with the target. The latter doesn't establishes
  62     a connection immediately, thus allowing you to set specify options
  63     before establishing network connection using function
  64     <function>Z3950_connection_connect</function>.
  65     If the portnumber, <literal>portnum</literal>, is zero, the
  66     <literal>host</literal> is consulted for a port specification.
  67     If no port is given, 210 is used. A colon denotes the beginning of
  68     a port number in the host string. If the host string includes a
  69     slash that specifies a database for the connection.
  70    </para>
  71    <para>
  72     Connection objects should be destroyed using function
  73     <function>Z3950_connection_destroy</function>.
  74    </para>
  75    <synopsis>
  76     const char *Z3950_connection_option (Z3950_connection c,
  77                                          const char *key,
  78                                          const char *val);
  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    <synopsis>
  91      const char *Z3950_connection_host (Z3950_connection c);
  92
  93    </synopsis>
  94    <para>
  95      Function <function>Z3950_connection_host</function> returns
  96      the host for the connection as specified in either a call to
  97      <function>Z3950_connection_new</function> or
  98      <function>Z3950_connection_connect</function>.
  99      This function returns <literal>NULL</literal> if host isn't
 100      set for the connection.
 101    </para>
 102    <synopsis>
 103      int Z3950_connection_error (Z3950_connection c, const char **cp,
 104                                  const char **addinfo);
 105    </synopsis>
 106    <para>
 107      Use <function>Z3950_connection_error</function> to check for
 108      errors for the last operation(s) performed. The function returns
 109      zero if no errors occurred; non-zero otherwise indicating the error.
 110      Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
 111      holds messages for the error and additional-info if passed as
 112      non-<literal>NULL</literal>.
 113    </para>
 114   </sect1>
 115   <sect1><title>Search objects</title>
 116    <para>
 117      Search objects defines how result sets are obtained. They
 118      act like queries.
 119    </para>
 120    <synopsis>
 121      Z3950_search Z3950_search_create(void);
 122
 123      void Z3950_search_destroy(Z3950_search s);
 124
 125      int Z3950_search_prefix(Z3950_search s, const char *str);
 126
 127      int Z3950_search_sortby(Z3950_search s, const char *criteria);
 128    </synopsis>
 129    <para>
 130      Create search objects using <function>Z3950_search_create</function>
 131      and destroy them by calling <function>Z3950_search_destroy</function>.
 132      RPN-queries can be specified in PQF notation by using the
 133      function <function>Z3950_search_prefix</function>. More
 134      query types will be added later, such as CCL to RPN-mapping, CCL
 135      query, etc.
 136      In addition to a search a sort critieria may be set. Function
 137      <function>Z3950_search_sortby</function> specifies a sort
 138      criteria using the same string notation for sort as offered by
 139      the YAZ client.
 140    </para>
 141   </sect1>
 142   <sect1><title>Result sets</title>
 143    <para>
 144      The result set describes a collection of records obtained from
 145      search.
 146    </para>
 147    <synopsis>
 148      Z3950_resultset Z3950_connection_search(Z3950_connection,
 149                                              Z3950_search q);
 150
 151      Z3950_resultset Z3950_connection_search_pqf(Z3950_connection c,
 152                                                  const char *q);
 153
 154      void Z3950_resultset_destroy(Z3950_resultset r);
 155    </synopsis>
 156    <para>
 157      Function <function>Z3950_connection_search</function> creates
 158      a result set given a connection - and search object.
 159      Destroy a result set by calling
 160      <function>Z3950_resultset_destroy</function>.
 161      Simple clients using YAZ' prefix query format may use
 162      function <function>Z3950_connection_search_pqf</function>
 163      instead.
 164    </para>
 165    <synopsis>
 166      const char *Z3950_resultset_option (Z3950_resultset r,
 167                                          const char *key,
 168                                          const char *val);
 169
 170      int Z3950_resultset_size (Z3950_resultset r);
 171
 172      void *Z3950_resultset_get (Z3950_resultset s, int pos,
 173                                 const char *type, int *len);
 174      void Z3950_resultset_records (Z3950_resultset r,
 175                                    Z3950_record *recs,
 176                                    size_t *cnt);
 177    </synopsis>
 178    <para>
 179      Description of result sets here.
 180    </para>
 181   </sect1>
 182   <sect1><title>Records</title>
 183    <para>
 184      A record object is a retrival record on the client side -
 185      created from result sets.
 186    </para>
 187    <synopsis>
 188      Z3950_record Z3950_resultset_record (Z3950_resultset s, int pos);
 189
 190      Z3950_record Z3950_resultset_record_immediate (Z3950_resultset s,
 191                                                     int pos);
 192
 193      void *Z3950_record_get (Z3950_record rec, const char *type,
 194                              int *len);
 195
 196      void Z3950_record_destroy (Z3950_record rec);
 197    </synopsis>
 198   </sect1>
 199   <sect1><title>Options</title>
 200    <para>
 201      Most objects in &zoom; allows you to specify options to change
 202      behaviour. From an implementation point of view a set of options
 203      is just like an associate array / hash array, etc.
 204    </para>
 205    <synopsis>
 206      Z3950_options Z3950_options_create (void);
 207
 208      Z3950_options Z3950_options_create_with_parent (Z3950_options parent);
 209
 210      void Z3950_options_destroy (Z3950_options opt);
 211    </synopsis>
 212    <synopsis>
 213      const char *Z3950_options_get (Z3950_options opt, const char *name);
 214
 215      void Z3950_options_set (Z3950_options opt, const char *name,
 216                              const char *v);
 217    </synopsis>
 218    <synopsis>
 219      typedef const char *(*Z3950_options_callback)
 220                                      (void *handle, const char *name);
 221
 222      Z3950_options_callback
 223              Z3950_options_set_callback (Z3950_options opt,
 224                                          Z3950_options_callback c,
 225                                          void *handle);
 226    </synopsis>
 227   </sect1>
 228   <sect1><title>Events</title>
 229    <para>
 230      If you're developing non-blocking applications you have to deal
 231      with events.
 232    </para>
 233    <synopsis>
 234      int Z3950_event (int no, Z3950_connection *cs);
 235    </synopsis>
 236   </sect1>
 237  </chapter>
 238
 239  <!-- Keep this comment at the end of the file
 240  Local variables:
 241  mode: sgml
 242  sgml-omittag:t
 243  sgml-shorttag:t
 244  sgml-minimize-attributes:nil
 245  sgml-always-quote-attributes:t
 246  sgml-indent-step:1
 247  sgml-indent-data:t
 248  sgml-parent-document: "yaz.xml"
 249  sgml-local-catalogs: "../../docbook/docbook.cat"
 250  sgml-namecase-general:t
 251  End:
 252  -->
 253