A record object is a retrieval record on the client side - created from result sets.
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);
ZOOM_record ZOOM_record_clone (ZOOM_record rec);
void ZOOM_record_destroy (ZOOM_record rec);
References to temporary records are returned by functions
ZOOM_resultset_records or
ZOOM_resultset_record.
If a persistent reference to a record is desired
ZOOM_record_clone should be used.
It returns a record reference that should be destroyed
by a call to ZOOM_record_destroy.
A single record is returned by function
ZOOM_resultset_record that takes a
position as argument. First record has position zero.
If no record could be obtained NULL is returned.
Function ZOOM_resultset_records retrieves
a number of records from a result set. Parameter start
and count specifies the range of records to
be returned. Upon completion array
recs[0], ..recs[count-1]
holds record objects for the records. The array of records
recs should be allocated prior the call
ZOOM_resultset_records. Note that for those
records that couldn't be retrieved from the target
recs[ ..] is set to NULL.
In order to extract information about a single record,
ZOOM_record_get is provided. The
function returns a pointer to certain record information. The
nature (type) of the pointer depends on the parameter,
type.
The type is a string of the format:
form[; charset=from[,to]]
where form specifies the format of the
returned record, from
specifies the character set of the record in its original form
(as returned by the server), to specifies
the output (returned)
character set encoding.
If charset is not given, then no character set conversion takes place.
If to is omitted UTF-8 is assumed.
In addition, for certain types, the length
len passed will be set to the size in bytes of
the returned information.
The following are the supported values for form.
databaseDatabase of record is returned
as a C null-terminated string. Return type
const char *.
syntaxThe transfer syntax of the record is returned
as a C null-terminated string containing the symbolic name of
the record syntax, e.g. Usmarc. Return type
is
const char *.
renderThe record is returned in a display friendly
format. Upon completion buffer is returned
(type const char *) and length is stored in
*len.
rawThe record is returned in the internal
YAZ specific format. For GRS-1, Explain, and others, the
raw data is returned as type
Z_External * which is just the type for
the member retrievalRecord in
type NamePlusRecord.
For SUTRS and octet aligned record (including all MARCs) the
octet buffer is returned and the length of the buffer.
xmlThe record is returned in XML if possible.
SRU and Z39.50 records with transfer syntax XML are
returned verbatim. MARC records are returned in
MARCXML
(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 const char *) and length is stored in
*len.
opacOPAC for record is returned in XML.
Most MARC21 records uses the MARC-8 character set encoding. An application that wishes to display in Latin-1 would use
render; charset=marc8,iso-8859-1
The functions ZOOM_resultset_record and
ZOOM_resultset_records 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
async is 1, because they return records objects.
(and there's no way to return records objects without retrieving them!).
There is a trick, however, in the usage of function
ZOOM_resultset_records that allows for
delayed retrieval (and makes it non-blocking). By using
a null pointer for recs you're indicating
you're not interested in getting records objects
now.