node-zoom
Version:
174 lines (169 loc) • 12.1 kB
HTML
<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.78.1"><link rel="home" 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.facets.html" title="5.�Facets"></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.facets.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="zoom.records"></a>4.�Records</h2></div></div></div><p>
A record object is a retrieval record on the client side -
created from result sets.
</p><pre class="synopsis">
void ZOOM_resultset_records(ZOOM_resultset r,
ZOOM_record *recs,
size_t start, size_t count);
ZOOM_record ZOOM_resultset_record(ZOOM_resultset s, size_t pos);
const char *ZOOM_record_get(ZOOM_record rec, const char *type,
size_t *len);
int ZOOM_record_error(ZOOM_record rec, const char **msg,
const char **addinfo, const char **diagset);
ZOOM_record ZOOM_record_clone(ZOOM_record rec);
void ZOOM_record_destroy(ZOOM_record rec);
</pre><p>
References to temporary records are returned by functions
<code class="function">ZOOM_resultset_records</code> or
<code class="function">ZOOM_resultset_record</code>.
</p><p>
If a persistent reference to a record is desired
<code class="function">ZOOM_record_clone</code> should be used.
It returns a record reference that should be destroyed
by a call to <code class="function">ZOOM_record_destroy</code>.
</p><p>
A single record is returned by function
<code class="function">ZOOM_resultset_record</code> that takes a
position as argument. First record has position zero.
If no record could be obtained <code class="literal">NULL</code> is returned.
</p><p>
Error information for a record can be checked with
<code class="function">ZOOM_record_error</code> which returns non-zero
(error code) if record is in error, called <span class="emphasis"><em>Surrogate
Diagnostics</em></span> in Z39.50.
</p><p>
Function <code class="function">ZOOM_resultset_records</code> retrieves
a number of records from a result set. Parameter <code class="literal">start</code>
and <code class="literal">count</code> specifies the range of records to
be returned. Upon completion array
<code class="literal">recs[0], ..recs[count-1]</code>
holds record objects for the records. The array of records
<code class="literal">recs</code> should be allocated prior the call
<code class="function">ZOOM_resultset_records</code>. Note that for those
records that couldn't be retrieved from the target
<code class="literal">recs[ ..]</code> is set to <code class="literal">NULL</code>.
</p><p><a name="zoom.record.get"></a>
In order to extract information about a single record,
<code class="function">ZOOM_record_get</code> is provided. The
function returns a pointer to certain record information. The
nature (type) of the pointer depends on the parameter,
<em class="parameter"><code>type</code></em>.
</p><p>
The <em class="parameter"><code>type</code></em> is a string of the format:
</p><p>
<em class="replaceable"><code>format</code></em>[;charset=<em class="replaceable"><code>from</code></em>[/<em class="replaceable"><code>opacfrom</code></em>][,<em class="replaceable"><code>to</code></em>]][;format=<em class="replaceable"><code>v</code></em>][;base64=<em class="replaceable"><code>xpath</code></em>]
</p><p>
If <code class="literal">charset</code> is given, then <em class="replaceable"><code>from</code></em>
specifies the character set of the record in its original form
(as returned by the server), <em class="replaceable"><code>to</code></em> specifies
the output (returned) character set encoding.
If <em class="replaceable"><code>to</code></em> is omitted, then UTF-8 is assumed.
If charset is not given, then no character set conversion takes place.
OPAC records may be returned in a different
set from the bibliographic MARC record. If this is this the case,
<em class="replaceable"><code>opacfrom</code></em> should be set to the character set
of the OPAC record part.
</p><p>
The <code class="literal">format</code> is generic but can only be used to
specify XML indentation when the value <em class="replaceable"><code>v</code></em>
is 1 (<code class="literal">format=1</code>).
</p><p>
The <code class="literal">base64</code> allows a full record to be extracted
from base64-encoded string in an XML document.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Specifying the OPAC record character set requires YAZ 4.1.5 or later.
</p><p>
Specifying the base64 parameter requires YAZ 4.2.35 or later.
</p></div><p>
The format argument controls whether record data should be XML
pretty-printed (post process operation).
It is enabled only if format value <em class="replaceable"><code>v</code></em> is
<code class="literal">1</code> and the record content is XML well-formed.
</p><p>
In addition, for certain types, the length
<code class="literal">len</code> passed will be set to the size in bytes of
the returned information.
</p><p>
The following are the supported values for <em class="replaceable"><code>form</code></em>.
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">database</code></span></dt><dd><p>Database of record is returned
as a C null-terminated string. Return type
<code class="literal">const char *</code>.
</p></dd><dt><span class="term"><code class="literal">syntax</code></span></dt><dd><p>The transfer syntax of the record is returned
as a C null-terminated string containing the symbolic name of
the record syntax, e.g. <code class="literal">Usmarc</code>. Return type
is
<code class="literal">const char *</code>.
</p></dd><dt><span class="term"><code class="literal">schema</code></span></dt><dd><p>The schema of the record is returned
as a C null-terminated string. Return type is
<code class="literal">const char *</code>.
</p></dd><dt><span class="term"><code class="literal">render</code></span></dt><dd><p>The record is returned in a display friendly
format. Upon completion buffer is returned
(type <code class="literal">const char *</code>) and length is stored in
<code class="literal">*len</code>.
</p></dd><dt><span class="term"><code class="literal">raw</code></span></dt><dd><p>The record is returned in the internal
YAZ specific format. For GRS-1, Explain, and others, the
raw data is returned as type
<code class="literal">Z_External *</code> which is just the type for
the member <code class="literal">retrievalRecord</code> in
type <code class="literal">NamePlusRecord</code>.
For SUTRS and octet aligned record (including all MARCs) the
octet buffer is returned and the length of the buffer.
</p></dd><dt><span class="term"><code class="literal">xml</code></span></dt><dd><p>The record is returned in XML if possible.
SRU, Solr and Z39.50 records with transfer syntax XML are
returned verbatim. MARC records are returned in
<a class="ulink" href="http://www.loc.gov/standards/marcxml/" target="_top">
MARCXML
</a>
(converted from ISO2709 to MARCXML by YAZ).
OPAC records are also converted to XML and the
bibliographic record is converted to MARCXML (when possible).
GRS-1 records are not supported for this form.
Upon completion, the XML buffer is returned
(type <code class="literal">const char *</code>) and length is stored in
<code class="literal">*len</code>.
</p></dd><dt><span class="term"><code class="literal">opac</code></span></dt><dd><p>OPAC information for record is returned in XML
if an OPAC record is present at the position given. If no
OPAC record is present, a NULL pointer is returned.
</p></dd><dt><span class="term"><code class="literal">txml</code></span></dt><dd><p>The record is returned in TurboMARC if possible.
SRU and Z39.50 records with transfer syntax XML are
returned verbatim. MARC records are returned in
<a class="link" href="marc.html#tools.turbomarc" title="5.1.�TurboMARC">
TurboMARC
</a>
(converted from ISO2709 to TurboMARC by YAZ).
Upon completion, the XML buffer is returned
(type <code class="literal">const char *</code>) and length is stored in
<code class="literal">*len</code>.
</p></dd><dt><span class="term"><code class="literal">json</code></span></dt><dd><p>Like xml, but MARC records are converted to
<a class="ulink" href="http://dilettantes.code4lib.org/blog/2010/09/a-proposal-to-serialize-marc-in-json/" target="_top">MARC-in-JSON</a>.
</p></dd></dl></div><p>
</p><p>
Most
<a class="ulink" href="http://www.loc.gov/marc/" target="_top">MARC21</a>
records uses the
<a class="ulink" href="http://www.loc.gov/marc/specifications/speccharmarc8.html" target="_top">MARC-8</a>
character set encoding.
An application that wishes to display in Latin-1 would use
</p><pre class="screen">
render; charset=marc8,iso-8859-1
</pre><p>
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="zoom.z3950.record.behavior"></a>4.1.�Z39.50 Protocol behavior</h3></div></div></div><p>
The functions <code class="function">ZOOM_resultset_record</code> and
<code class="function">ZOOM_resultset_records</code> inspects the client-side
record cache. Records not found in cache are fetched using
Present.
The functions may block (and perform network I/O) - even though option
<code class="literal">async</code> is 1, because they return records objects.
(and there's no way to return records objects without retrieving them!).
</p><p>
There is a trick, however, in the usage of function
<code class="function">ZOOM_resultset_records</code> that allows for
delayed retrieval (and makes it non-blocking). By using
a null pointer for <em class="parameter"><code>recs</code></em> you're indicating
you're not interested in getting records objects
<span class="emphasis"><em>now</em></span>.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="zoom.sru.record.behavior"></a>4.2.�SRU/Solr Protocol behavior</h3></div></div></div><p>
The ZOOM driver for SRU/Solr treats records returned by a SRU/Solr server
as if they where Z39.50 records with transfer syntax XML and
no element set name or database name.
</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.facets.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.�Facets</td></tr></table></div></body></html>