File: zoom.records.html

package info (click to toggle)
yaz 3.0.34-2
  • links: PTS, VCS
  • area: main
  • in suites: lenny
  • size: 13,404 kB
  • ctags: 12,108
  • sloc: xml: 116,075; ansic: 52,205; sh: 9,746; tcl: 2,043; makefile: 1,141; yacc: 347
file content (139 lines) | stat: -rw-r--r-- 9,724 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
<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.73.2"><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>
    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>form</code></em>[; charset=<em class="replaceable"><code>from</code></em>[,<em class="replaceable"><code>to</code></em>]]
   </p><p>
    where <em class="replaceable"><code>form</code></em> specifies the format of the
    returned record, <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 charset is not given, then no character set conversion takes place.
    If <em class="replaceable"><code>to</code></em> is omitted UTF-8 is assumed.
   </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><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 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).
	GRS-1 and OPAC 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 for record is returned in XML.
       </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" lang="en"><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" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="zoom.sru.record.behavior"></a>4.2.�SRU Protocol behavior</h3></div></div></div><p>
     The ZOOM driver for SRU treats records returned by a SRU 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.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>