YAZ User's Guide and Reference
Prev | Chapter 3. ZOOM | Next

# Records

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`.

`database`

  Database of record is returned as a C null-terminated string. Return type `const char *`.

`syntax`

  The 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 *`.

`render`

  The record is returned in a display friendly format. Upon completion buffer is returned (type `const char *`) and length is stored in `*len`.

`raw`

  The 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.

`xml`

  The record is returned in XML if possible. SRW/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`.

`opac`

  OPAC 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

## Z39.50 Protocol behavior

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.

## SRW Protocol behavior

The ZOOM driver for SRW treats records returned by a SRW server as if they where Z39.50 records with transfer syntax XML and no element set name or database name.

Prev | Home | Next
Result sets | Up | Scan