YAZ User's Guide and Reference
Prev | Chapter 3. Building clients with 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`. In addition, for certain types, the length `len` passed will be set to the size in bytes of the returned information.

`database`

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

`syntax`

  The transfer syntax (OID) 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.

## 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 passing a null pointer for `recs` you're indicating you're not interested in getting records objects now.

Prev | Home | Next
Result sets | Up | Scan