4. Records
Prev | Chapter 3. ZOOM | Next

## 4. 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);

         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);

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.

Error information for a record can be checked with `ZOOM_record_error` which returns non-zero (error code) if record is in error, called Surrogate Diagnostics in Z39.50.

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

`schema`

  The schema of the record is returned as a C null-terminated string. 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. 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). 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 `const char *`) and length is stored in `*len`.

`opac`

  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.

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

### 4.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.

### 4.2. SRU Protocol behavior

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.

Prev | Up | Next
3. Result sets | Home | 5. Scan