Result sets
The result set object is a container for records returned from a target.
ZOOM_resultset ZOOM_connection_search(ZOOM_connection,
ZOOM_query q);
ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
const char *q);
void ZOOM_resultset_destroy(ZOOM_resultset r);
|
Function ZOOM_connection_search creates a result set given a connection and query. Destroy a result set by calling ZOOM_resultset_destroy. Simple clients may using PQF only may use function ZOOM_connection_search_pqf in which case creating query objects is not necessary.
void ZOOM_resultset_option_set (ZOOM_resultset r,
const char *key,
const char *val);
const char *ZOOM_resultset_option_get (ZOOM_resultset r,
const char *key);
size_t ZOOM_resultset_size (ZOOM_resultset r);
|
Functions ZOOM_resultset_options_set and ZOOM_resultset_get sets and gets an option for a result set similar to ZOOM_connection_option_get and ZOOM_connection_option_set.
The number of hits also called result-count is returned by function ZOOM_resultset_size.
Table 3-2. ZOOM Result set Options
| Option | Description | Default |
|---|---|---|
| piggyback | True (1) if piggyback should be used in searches; false (0) if not. | 1 |
| start | Offset of first record to be retrieved from target. First record has offset 0 unlike the protocol specifications where first record has position 1. | 0 |
| count | Number of records to be retrieved. | 0 |
| elementSetName | Element-Set name of records. Most targets should honor element set name B and F for brief and full respectively. | none |
| preferredRecordSyntax | Preferred Syntax, such as USMARC, SUTRS, etc. | none |
| schema | Schema for retrieval, such as Gils-schema, Geo-schema, etc. | none |
| smallSetUpperBound | If hits is less than or equal to this value, then target will return all records using small element set name | 0 |
| largeSetLowerBound | If hits is greater than this value, the target will return no records. | 1 |
| mediumSetPresentNumber | This value represents the number of records to be returned as part of a search when when hits is less than or equal to large set lower bound and if hits is greater than small set upper bound. | 0 |
| smallSetElementSetName | The element set name to be used for small result sets. | none |
| mediumSetElementSetName | The element set name to be for medium-sized result sets. | none |
| databaseName | One or more database names separated by character plus (+). | Default |
| setname | Name of Result Set (Result Set ID). If this option isn't set, the ZOOM module will automatically allocate a result set name. | default |
Protocol behavior
The creation of a result set involves at least a SearchRequest - SearchResponse protocol handshake. Following that, if a sort criteria was specified as part of the query, a SortRequest - SortResponse handshake takes place. Note that it is necessary to perform sorting before any retrieval takes place, so no records will be returned from the target as part of the SearchResponse because these would be unsorted. Hence, piggyback is disabled when sort criteria is set. Following Search - and a Possible sort, Retrieval takes place - as one or more Present Requests - Present Response being transferred.
The API allows for two different modes for retrieval. A high level mode which is somewhat more powerful and a low level one. The low level is "enabled" when the settings smallSetUpperBound, mediumSetPresentNumber and largeSetLowerBound are set. The low level mode thus allows you to precisely set how records are returned as part of a search response as offered by the Z39.50 protocol. Since the client may be retrieving records as part of the search response, this mode doesn't work well if sorting is used.
The high-level mode allows you to fetch a range of records from the result set with a given start offset. When you use this mode the client will automatically use piggyback if that is possible with the target and perform one or more present requests as needed. Even if the target returns fewer records as part of a present response because of a record size limit, etc. the client will repeat sending present requests. As an example, if option start is 0 (default) and count is 4, and piggyback is 1 (default) and no sorting criteria is specified, then the client will attempt to retrieve the 4 records as part the search response (using piggyback). On the other hand, if either start is positive or if a sorting criteria is set, or if piggyback is 0, then the client will not perform piggyback but send Present Requests instead.
If either of the options mediumSetElementSetName and smallSetElementSetName are unset, the value of option elementSetName is used for piggyback searches. This means that for the high-level mode you only have to specify one elementSetName option rather than three.