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,
7 size_t start, size_t count);
8 ZOOM_record ZOOM_resultset_record (ZOOM_resultset s, size_t pos);
10 const char *ZOOM_record_get (ZOOM_record rec, const char *type,
13 ZOOM_record ZOOM_record_clone (ZOOM_record rec);
15 void ZOOM_record_destroy (ZOOM_record rec);
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>.
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>.
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.
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>.
48 The <em class="parameter"><code>type</code></em> is a string of the format:
50 <em class="replaceable"><code>form</code></em>[; charset=<em class="replaceable"><code>from</code></em>[,<em class="replaceable"><code>to</code></em>]]
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
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.
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.
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
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">
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>
101 <a href="http://www.loc.gov/marc/" target="_top">MARC21</a>
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
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
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!).
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>