dependencies/yaz-2.1.28/doc/zoom.records.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>4. Records</title><meta name="generator" content="DocBook XSL Stylesheets V1.70.1"><link rel="start" href="index.html" title="YAZ User's Guide and Reference"><link rel="up" href="zoom.html" title="Chapter 3. ZOOM"><link rel="prev" href="zoom.resultsets.html" title="3. Result sets"><link rel="next" href="zoom.scan.html" title="5. Scan"></head><body><link rel="stylesheet" type="text/css" href="common/style1.css"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4. Records</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="zoom.resultsets.html">Prev</a> </td><th width="60%" align="center">Chapter 3. ZOOM</th><td width="20%" align="right"> <a accesskey="n" href="zoom.scan.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="zoom.records"></a>4. Records</h2></div></div></div><p>
   2     A record object is a retrieval record on the client side -
   3     created from result sets.
   4    </p><pre class="synopsis">
   5      void ZOOM_resultset_records (ZOOM_resultset r,
   6                                   ZOOM_record *recs,
   7                                   size_t start, size_t count);
   8      ZOOM_record ZOOM_resultset_record (ZOOM_resultset s, size_t pos);
   9
  10      const char *ZOOM_record_get (ZOOM_record rec, const char *type,
  11                                   size_t *len);
  12
  13      ZOOM_record ZOOM_record_clone (ZOOM_record rec);
  14
  15      void ZOOM_record_destroy (ZOOM_record rec);
  16    </pre><p>
  17     References to temporary records are returned by functions
  18     <code class="function">ZOOM_resultset_records</code> or
  19     <code class="function">ZOOM_resultset_record</code>.
  20     </p><p>
  21     If a persistent reference to a record is desired
  22     <code class="function">ZOOM_record_clone</code> should be used.
  23     It returns a record reference that should be destroyed
  24     by a call to <code class="function">ZOOM_record_destroy</code>.
  25    </p><p>
  26     A single record is returned by function
  27     <code class="function">ZOOM_resultset_record</code> that takes a
  28     position as argument. First record has position zero.
  29     If no record could be obtained <code class="literal">NULL</code> is returned.
  30    </p><p>
  31     Function <code class="function">ZOOM_resultset_records</code> retrieves
  32     a number of records from a result set. Parameter <code class="literal">start</code>
  33     and <code class="literal">count</code> specifies the range of records to
  34     be returned. Upon completion array
  35     <code class="literal">recs[0], ..recs[count-1]</code>
  36     holds record objects for the records. The array of records
  37      <code class="literal">recs</code> should be allocated prior the call
  38     <code class="function">ZOOM_resultset_records</code>. Note that for those
  39     records that couldn't be retrieved from the target
  40     <code class="literal">recs[ ..]</code> is set to <code class="literal">NULL</code>.
  41    </p><p><a name="zoom.record.get"></a>
  42     In order to extract information about a single record,
  43     <code class="function">ZOOM_record_get</code> is provided. The
  44     function returns a pointer to certain record information. The
  45     nature (type) of the pointer depends on the parameter,
  46     <em class="parameter"><code>type</code></em>.
  47    </p><p>
  48     The <em class="parameter"><code>type</code></em> is a string of the format:
  49    </p><p>
  50     <em class="replaceable"><code>form</code></em>[; charset=<em class="replaceable"><code>from</code></em>[,<em class="replaceable"><code>to</code></em>]]
  51    </p><p>
  52     where <em class="replaceable"><code>form</code></em> specifies the format of the
  53     returned record, <em class="replaceable"><code>from</code></em>
  54     specifies the character set of the record in its original form
  55     (as returned by the server), <em class="replaceable"><code>to</code></em> specifies
  56     the output (returned)
  57     character set encoding.
  58     If charset is not given, then no character set conversion takes place.
  59     If <em class="replaceable"><code>to</code></em> is omitted UTF-8 is assumed.
  60    </p><p>
  61     In addition, for certain types, the length
  62     <code class="literal">len</code> passed will be set to the size in bytes of
  63     the returned information.
  64     </p><p>
  65     The following are the supported values for <em class="replaceable"><code>form</code></em>.
  66     </p><div class="variablelist"><dl><dt><span class="term"><code class="literal">database</code></span></dt><dd><p>Database of record is returned
  67         as a C null-terminated string. Return type
  68         <code class="literal">const char *</code>.
  69        </p></dd><dt><span class="term"><code class="literal">syntax</code></span></dt><dd><p>The transfer syntax of the record is returned
  70         as a C null-terminated string containing the symbolic name of
  71         the record syntax, e.g. <code class="literal">Usmarc</code>. Return type
  72         is
  73         <code class="literal">const char *</code>.
  74        </p></dd><dt><span class="term"><code class="literal">render</code></span></dt><dd><p>The record is returned in a display friendly
  75         format. Upon completion buffer is returned
  76         (type <code class="literal">const char *</code>) and length is stored in
  77         <code class="literal">*len</code>.
  78        </p></dd><dt><span class="term"><code class="literal">raw</code></span></dt><dd><p>The record is returned in the internal
  79         YAZ specific format. For GRS-1, Explain, and others, the
  80         raw data is returned as type
  81         <code class="literal">Z_External *</code> which is just the type for
  82         the member <code class="literal">retrievalRecord</code> in
  83         type <code class="literal">NamePlusRecord</code>.
  84         For SUTRS and octet aligned record (including all MARCs) the
  85         octet buffer is returned and the length of the buffer.
  86        </p></dd><dt><span class="term"><code class="literal">xml</code></span></dt><dd><p>The record is returned in XML if possible.
  87         SRU and Z39.50 records with transfer syntax XML are
  88         returned verbatim. MARC records are returned in
  89         <a href="http://www.loc.gov/standards/marcxml/" target="_top">
  90          MARCXML
  91          </a>
  92         (converted from ISO2709 to MARCXML by YAZ).
  93         GRS-1 and OPAC records are not supported for this form.
  94         Upon completion, the XML buffer is returned
  95         (type <code class="literal">const char *</code>) and length is stored in
  96         <code class="literal">*len</code>.
  97        </p></dd><dt><span class="term"><code class="literal">opac</code></span></dt><dd><p>OPAC for record is returned in XML.
  98        </p></dd></dl></div><p>
  99    </p><p>
 100     Most
 101     <a href="http://www.loc.gov/marc/" target="_top">MARC21</a>
 102     records uses the
 103     <a href="http://www.loc.gov/marc/specifications/speccharmarc8.html" target="_top">MARC-8</a>
 104     character set encoding.
 105     An application that wishes to display in Latin-1 would use
 106     </p><pre class="screen">
 107      render; charset=marc8,iso-8859-1
 108     </pre><p>
 109    </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2564926"></a>4.1. Z39.50 Protocol behavior</h3></div></div></div><p>
 110      The functions <code class="function">ZOOM_resultset_record</code> and
 111      <code class="function">ZOOM_resultset_records</code> inspects the client-side
 112      record cache. Records not found in cache are fetched using
 113      Present.
 114      The functions may block (and perform network I/O)  - even though option
 115      <code class="literal">async</code> is 1, because they return records objects.
 116      (and there's no way to return records objects without retrieving them!).
 117      </p><p>
 118      There is a trick, however, in the usage of function
 119      <code class="function">ZOOM_resultset_records</code> that allows for
 120      delayed retrieval (and makes it non-blocking). By using
 121      a null pointer for <em class="parameter"><code>recs</code></em> you're indicating
 122      you're not interested in getting records objects
 123      <span class="emphasis"><em>now</em></span>.
 124     </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2564982"></a>4.2. SRU Protocol behavior</h3></div></div></div><p>
 125      The ZOOM driver for SRU treats records returned by a SRU server
 126      as if they where Z39.50 records with transfer syntax XML and
 127      no element set name or database name.
 128     </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="zoom.resultsets.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="zoom.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="zoom.scan.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3. Result sets </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 5. Scan</td></tr></table></div></body></html>