+ <para>
+ The simplest thing to do with a retrieved record is simply to
+ <literal>render()</literal> it. This returns a human-readable, but
+ not necessarily very pretty, representation of the contents of the
+ record. This is useful primarily for testing and debugging, since
+ the application has no control over how the record appears.
+ (The application must <emphasis>not</emphasis>
+ <literal>delete</literal> the returned string - it is ``owned'' by
+ the record object.)
+ </para>
+ <para>
+ More sophisticated applications will want to deal with the raw data
+ themselves: the <literal>rawdata()</literal> method returns it.
+ Its format will vary depending on the record syntax: SUTRS, MARC
+ and XML records are returned ``as is'', and GRS-1 records as a
+ pointer to their top-level node, which is a
+ <literal>Z_GenericRecord</literal> structure as defined in the
+ <literal><yaz/z-grs.h></literal> header file.
+ (The application must <emphasis>not</emphasis>
+ <literal>delete</literal> the returned data - it is ``owned'' by
+ the record object.)
+ </para>
+ <para>
+ Perceptive readers will notice that there are no methods for access
+ to individual fields within a record. That's because the different
+ record syntaxes are so different that there is no even a uniform
+ notion of what a field is across them all, let alone a sensible way
+ to implement such a function. Fetch the raw data instead, and pick
+ it apart ``by hand''.
+ </para>
+
+ <sect2>
+ <title>Memory Management</title>
+ <para>
+ The <literal>record</literal> obejcts returned from
+ <literal>resultSet::getRecord()</literal> are ``owned'' by the
+ result set object: that means that the application is not
+ responsible for <literal>delete</literal>ing them - each
+ <literal>record</literal> is automatically deallocated when the
+ <literal>resultSet</literal> that owns it is
+ <literal>delete</literal>d.
+ </para>
+ <para>
+ Usually that's what you want: it means that you can easily fetch a
+ record, use it and forget all about it, like this:
+ </para>
+ <programlisting>
+ resultSet rs(conn, query);
+ cout << rs.getRecord(0)->render();
+ </programlisting>
+ <para>
+ But sometimes you want a <literal>record</literal> to live on past
+ the lifetime of the <literal>resultSet</literal> from which it was
+ fetched. In this case, the <literal>clone(f)</literal> method can
+ be used to make an autonomous copy. The application must
+ <literal>delete</literal> it when it doesn't need it any longer:
+ </para>
+ <programlisting>
+ record *rec;
+ {
+ resultSet rs(conn, query);
+ rec = rs.getRecord(0)->clone();
+ // `rs' goes out of scope here, and is deleted
+ }
+ cout << rec->render();
+ delete rec;
+ </programlisting>
+ </sect2>
+
+ <sect2>
+ <title>References</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="http://zoom.z3950.org/api/zoom-1.3.html#3.5"
+ >Section 3.5 (Record) of the ZOOM Abstract API</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://www.indexdata.dk/yaz/doc/zoom.records.php"
+ >The Records section of the ZOOM-C documentation</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect2>