ZOOM
&zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
an initiative started by Mike Taylor (Mike is from the UK, which
explains the peculiar name of the model). The goal of &zoom; is to
provide a common Z39.50 client API not bound to a particular
programming language or toolkit.
From YAZ version 2.1.12, SRU is supported.
You can make SRU ZOOM connections by specifying scheme
http:// for the hostname for a connection.
The dialect of SRU used is specified by the value of the
connection's sru option, which may be SRU over
HTTP GET (get),
SRU over HTTP POST (post), (SRU over
SOAP) (soap) or solr
(Solr Web Service).
Using the facility for embedding options in target strings, a
connection can be forced to use SRU rather the SRW (the default) by
prefixing the target string with sru=get,, like this:
sru=get,http://sru.miketaylor.org.uk:80/sru.plSolr protocol support was added to
YAZ in version 4.1.0, as a dialect of a SRU protocol, since both are
HTTP based protocols.
The lack of a simple Z39.50 client API for &yaz; has become more
and more apparent over time. So when the first &zoom; specification
became available,
an implementation for &yaz; was quickly developed. For the first time, it is
now as easy (or easier!) to develop clients than servers with &yaz;. This
chapter describes the &zoom; C binding. Before going further, please
reconsider whether C is the right programming language for the job.
There are other language bindings available for &yaz;, and still
more
are in active development. See the
ZOOM web-site for
more information.
In order to fully understand this chapter you should read and
try the example programs zoomtst1.c,
zoomtst2.c, .. in the zoom
directory.
The C language misses features found in object oriented languages
such as C++, Java, etc. For example, you'll have to manually,
destroy all objects you create, even though you may think of them as
temporary. Most objects has a _create - and a
_destroy variant.
All objects are in fact pointers to internal stuff, but you don't see
that because of typedefs. All destroy methods should gracefully ignore a
NULL pointer.
In each of the sections below you'll find a sub section called
protocol behavior, that describes how the API maps to the Z39.50
protocol.
ConnectionsThe Connection object is a session with a target.
#include <yaz/zoom.h>
ZOOM_connection ZOOM_connection_new(const char *host, int portnum);
ZOOM_connection ZOOM_connection_create(ZOOM_options options);
void ZOOM_connection_connect(ZOOM_connection c, const char *host,
int portnum);
void ZOOM_connection_destroy(ZOOM_connection c);
Connection objects are created with either function
ZOOM_connection_new or
ZOOM_connection_create.
The former creates and automatically attempts to establish a network
connection with the target. The latter doesn't establish
a connection immediately, thus allowing you to specify options
before establishing network connection using the function
ZOOM_connection_connect.
If the port number, portnum, is zero, the
host is consulted for a port specification.
If no port is given, 210 is used. A colon denotes the beginning of
a port number in the host string. If the host string includes a
slash, the following part specifies a database for the connection.
You can prefix the host with a scheme followed by colon. The
default scheme is tcp (Z39.50 protocol).
The scheme http selects SRU/get over HTTP by default,
but can overridded to use SRU/post, SRW and the Solr protocol.
You can prefix the scheme-qualified host-string with one or more
comma-separated
key=value
sequences, each of which represents an option to be set into the
connection structure before the
protocol-level connection is forged and the initialization
handshake takes place. This facility can be used to provide
authentication credentials, as in host-strings such as:
user=admin,password=halfAm4n,tcp:localhost:8017/db
Connection objects should be destroyed using the function
ZOOM_connection_destroy.
void ZOOM_connection_option_set(ZOOM_connection c,
const char *key, const char *val);
void ZOOM_connection_option_setl(ZOOM_connection c,
const char *key,
const char *val, int len);
const char *ZOOM_connection_option_get(ZOOM_connection c,
const char *key);
const char *ZOOM_connection_option_getl(ZOOM_connection c,
const char *key,
int *lenp);
The functions ZOOM_connection_option_set and
ZOOM_connection_option_setl allows you to
set an option given by key to the value
value for the connection.
For ZOOM_connection_option_set, the
value is assumed to be a 0-terminated string. Function
ZOOM_connection_option_setl specifies a
value of a certain size (len).
Functions ZOOM_connection_option_get and
ZOOM_connection_option_getl returns
the value for an option given by key.
ZOOM Connection OptionsOptionDescriptionDefault
implementationNameName of Your client
none
userAuthentication user name
none
groupAuthentication group name
none
passwordAuthentication password.
none
authenticationModeHow authentication is encoded.
basic
hostTarget host. This setting is "read-only".
It's automatically set internally when connecting to a target.
none
proxyProxy host. If set, the logical host
is encoded in the otherInfo area of the Z39.50 Init PDU
with OID 1.2.840.10003.10.1000.81.1.
none
clientIPClient IP. If set, is
encoded in the otherInfo area of a Z39.50 PDU with OID
1.2.840.10003.10.1000.81.3. Holds the original IP addreses
of a client. Is used of ZOOM is used in a gateway of some sort.
none
asyncIf true (1) the connection operates in
asynchronous operation which means that all calls are non-blocking
except
ZOOM_event.
0
maximumRecordSize Maximum size of single record.
1 MB
preferredMessageSize Maximum size of multiple records.
1 MB
lang Language for negotiation.
none
charset Character set for negotiation.
none
serverImplementationId
Implementation ID of server. (The old targetImplementationId
option is also supported for the benefit of old applications.)
none
targetImplementationName
Implementation Name of server. (The old
targetImplementationName option is also supported for the
benefit of old applications.)
none
serverImplementationVersion
Implementation Version of server. (the old
targetImplementationVersion option is also supported for the
benefit of old applications.)
none
databaseNameOne or more database names
separated by character plus (+), which to
be used by subsequent search requests on this Connection.
Default
piggybackTrue (1) if piggyback should be
used in searches; false (0) if not.
1
smallSetUpperBoundIf hits is less than or equal to this
value, then target will return all records using small element set name
0
largeSetLowerBoundIf hits is greater than this
value, the target will return no records.
1
mediumSetPresentNumberThis 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
init_opt_search, init_opt_present, init_opt_delSet, etc.
After a successful Init, these options may be interrogated to
discover whether the server claims to support the specified
operations.
nonesru
SRU/Solr transport type. Must be either soap,
get, post, or
solr.
soap
sru_version
SRU/SRW version. Should be 1.1, or
1.2. This is , prior to connect, the version
to offer (highest version). And following connect (in fact
first operation), holds the negotiated version with the server
(same or lower version).
1.2
facets
Requested or recommend facets may be given before a search is sent.
The value of this setting is described in
For inspection of the facets returned, refer to the functions
described in .
none
apdulog
If set to a true value such as "1", a log of low-level
protocol packets is emitted on standard error stream. This
can be very useful for debugging.
0
saveAPDU
If set to a true value such as "1", a log of low-level
protocol packets is saved. The log can be retrieved by reading
option APDU. Setting saveAPDU always has the side effect of
resetting the currently saved log. This setting is
write-only. If read, NULL will be returned.
It is only recognized in
ZOOM_connection_option_set.
0
APDU
Returns the log of protocol packets. Will be empty if logging
is not enabled (see saveAPDU above). This setting is
read-only. It is only recognized if used
in call to ZOOM_connection_option_get or
ZOOM_connection_option_getl.
memcached
If given and non-empty,
libMemcached
will be configured for the connection.
This option is inspected by ZOOM when a connection is established.
If the memcached option is given
and YAZ is compiled without libMemcached support, an internal
diagnostic (10018) will be thrown.
libMemcached support is available for YAZ 5.0.13 or later. If this
option is supplied for an earlier version of YAZ, it is
ignored.
The value of this option is a string passed verbatim to
the memcached function part of libMemcached.
Refer to man page
memcached(3).
Earlier versions of libMemcached
do not offer this function. In this case only the option
--server=host may
be given (YAZ emulates that part of libMemcached).
none
If either option lang or charset
is set, then
Character Set and Language Negotiation is in effect.
int ZOOM_connection_error(ZOOM_connection c, const char **cp,
const char **addinfo);
int ZOOM_connection_error_x(ZOOM_connection c, const char **cp,
const char **addinfo, const char **dset);
Function ZOOM_connection_error checks for
errors for the last operation(s) performed. The function returns
zero if no errors occurred; non-zero otherwise indicating the error.
Pointers cp and addinfo
holds messages for the error and additional-info if passed as
non-NULL. Function
ZOOM_connection_error_x is an extended version
of ZOOM_connection_error that is capable of
returning name of diagnostic set in dset.
Z39.50 Protocol behavior
The calls ZOOM_connection_new and
ZOOM_connection_connect establishes a TCP/IP
connection and sends an Initialize Request to the target if
possible. In addition, the calls waits for an Initialize Response
from the target and the result is inspected (OK or rejected).
If proxy is set then the client will establish
a TCP/IP connection with the peer as specified by the
proxy host and the hostname as part of the
connect calls will be set as part of the Initialize Request.
The proxy server will then "forward" the PDU's transparently
to the target behind the proxy.
For the authentication parameters, if option user
is set and both options group and
pass are unset, then Open style
authentication is used (Version 2/3) in which case the username
is usually followed by a slash, then by a password.
If either group
or pass is set then idPass authentication
(Version 3 only) is used. If none of the options are set, no
authentication parameters are set as part of the Initialize Request
(obviously).
When option async is 1, it really means that
all network operations are postponed (and queued) until the
function ZOOM_event is invoked. When doing so
it doesn't make sense to check for errors after
ZOOM_connection_new is called since that
operation "connecting - and init" is still incomplete and the
API cannot tell the outcome (yet).
SRU/Solr Protocol behavior
The HTTP based protocols (SRU, SRW, Solr) doesn't feature an
Inititialize Request, so the connection phase merely establishes a
TCP/IP connection with the HTTP server.
Most of the ZOOM connection options do not
affect SRU/Solr and they are ignored. However, future versions
of &yaz; might honor implementationName and
put that as part of User-Agent header for HTTP requests.
The charset is used in the Content-Type header
of HTTP requests.
Setting authentcationMode specifies how
authentication parameters are encoded for HTTP. The default is
"basic" where user and
password are encoded by using HTTP basic
authentication.
If authentcationMode is "url", then
user and password are encoded in the URL by parameters
x-username and x-password as
given by the SRU standard.
Queries
Query objects represents queries.
ZOOM_query ZOOM_query_create(void);
void ZOOM_query_destroy(ZOOM_query q);
int ZOOM_query_prefix(ZOOM_query q, const char *str);
int ZOOM_query_cql(ZOOM_query s, const char *str);
int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
int ZOOM_query_sortby2(ZOOM_query q, const char *strategy,
const char *criteria);
Create query objects using ZOOM_query_create
and destroy them by calling ZOOM_query_destroy.
RPN-queries can be specified in PQF
notation by using the
function ZOOM_query_prefix.
The ZOOM_query_cql specifies a CQL
query to be sent to the server/target.
More query types will be added in future versions of &yaz;, such as
CCL to RPN-mapping, native CCL query,
etc. In addition to a search, a sort criteria may be set. Function
ZOOM_query_sortby enables Z39.50 sorting and
it takes sort criteria using the same string notation as
yaz-client's sort command.
ZOOM_query_sortby2 is similar to
ZOOM_query_sortby but allows a strategy for
sorting. The reason for the strategy parameter is that some
protocols offers multiple ways of performing sorting.
For example, Z39.50 has the standard sort, which is performed after
search on an existing result set.
It's also possible to use CQL in Z39.50 as the query type and use
CQL's SORTBY keyword. Finally, Index Data's
Zebra server also allows sorting to be specified as part of RPN (Type 7).
ZOOM sort strategyNameDescriptionz39.50Z39.50 resultset sorttype7Sorting embedded in RPN(Type-7)cqlCQL SORTBYsru11SRU sortKeys parametersolrSolr sortembedtype7 for Z39.50, cql for SRU,
solr for Solr protocol
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.
ZOOM Result set OptionsOptionDescriptionDefault
startOffset of first record to be
retrieved from target. First record has offset 0 unlike the
protocol specifications where first record has position 1.
This option affects ZOOM_resultset_search and
ZOOM_resultset_search_pqf and must be set before any of
these functions are invoked. If a range of
records must be fetched manually after search,
function ZOOM_resultset_records should be used.
0
countNumber of records to be retrieved.
This option affects ZOOM_resultset_search and
ZOOM_resultset_search_pqf and must be set before any of
these functions are invoked.
0
presentChunkThe number of records to be
requested from the server in each chunk (present request). The
value 0 means to request all the records in a single chunk.
(The old step
option is also supported for the benefit of old applications.)
0
elementSetNameElement-Set name of records.
Most targets should honor element set name B
and F for brief and full respectively.
none
preferredRecordSyntaxPreferred Syntax, such as
USMARC, SUTRS, etc.
none
schemaSchema for retrieval, such as
Gils-schema, Geo-schema, etc.
none
setnameName of Result Set (Result Set ID).
If this option isn't set, the ZOOM module will automatically
allocate a result set name.
default
rpnCharsetCharacter set for RPN terms.
If this is set, ZOOM C will assume that the ZOOM application is
running UTF-8. Terms in RPN queries are then converted to the
rpnCharset. If this is unset, ZOOM C will not assume any encoding
of RPN terms and no conversion is performed.
none
For servers that support Search Info report, the following
options may be read using ZOOM_resultset_get.
This detailed information is read after a successful search has
completed.
This information is a list of of items, where each item is
information about a term or subquery. All items in the list
are prefixed by
SearchResult.no
where no presents the item number (0=first, 1=second).
Read searchresult.size to determine the
number of items.
Search Info Report OptionsOptionDescriptionsearchresult.size
number of search result entries. This option is-nonexistant
if no entries are returned by the server.
searchresult.no.idsub query IDsearchresult.no.countresult count for item (number of hits)searchresult.no.subquery.termsubquery term
searchresult.no.interpretation.term
interpretation term
searchresult.no.recommendation.term
recommendation term
Z39.50 Result-set Sort
void ZOOM_resultset_sort(ZOOM_resultset r,
const char *sort_type, const char *sort_spec);
int ZOOM_resultset_sort1(ZOOM_resultset r,
const char *sort_type, const char *sort_spec);
ZOOM_resultset_sort and
ZOOM_resultset_sort1 both sort an existing
result-set. The sort_type parameter is not use. Set it to "yaz".
The sort_spec is same notation as ZOOM_query_sortby and identical
to that offered by yaz-client's
sort command.
These functions only work for Z39.50. Use the more generic utility
ZOOM_query_sortby2
for other protocols (and even Z39.50).
Z39.50 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
are set. Following Search - and a possible sort - Retrieval takes
place - as one or more Present Requests/Response pairs 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 searching on a Connection object
for which 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.
SRU Protocol behavior
Current version of &yaz; does not take advantage of a result set id
returned by the SRU server. Future versions might do, however.
Since, the ZOOM driver does not save result set IDs any
present (retrieval) is transformed to a SRU SearchRetrieveRequest
with same query but, possibly, different offsets.
Option schema specifies SRU schema
for retrieval. However, options elementSetName and
preferredRecordSyntax are ignored.
Options start and count
are supported by SRU.
The remaining options
piggyback,
smallSetUpperBound,
largeSetLowerBound,
mediumSetPresentNumber,
mediumSetElementSetName,
smallSetElementSetName are
unsupported.
SRU supports CQL queries, not PQF.
If PQF is used, however, the PQF query is transferred anyway
using non-standard element pQuery in
SRU SearchRetrieveRequest.
Solr queries has to be done in Solr query format.
Unfortunately, SRU or Solr does not define a database setting. Hence,
databaseName is unsupported and ignored.
However, the path part in host parameter for functions
ZOOM_connecton_new and
ZOOM_connection_connect acts as a
database (at least for the &yaz; SRU server).
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:
format[;charset=from[/opacfrom][,to]][;format=v]
where format 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 to is omitted UTF-8 is assumed.
If charset is not given, then no character set conversion takes place.
OPAC records may be returned in a different
set from the bibliographic MARC record. If this is this the case,
opacfrom should be set to the character set
of the OPAC record part.
Specifying the OPAC record character set requires YAZ 4.1.5 or later.
The format argument controls whether record data should be XML
pretty-printed (post process operation).
It is enabled only if format value v is
1 and the record content is XML well-formed.
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 *.
schemaThe schema of the record is returned
as a C null-terminated string. 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, Solr 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.
opacOPAC 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.
txmlThe record is returned in TurboMARC if possible.
SRU and Z39.50 records with transfer syntax XML are
returned verbatim. MARC records are returned in
TurboMARC
(converted from ISO2709 to TurboMARC by YAZ).
Upon completion, the XML buffer is returned
(type const char *) and length is stored in
*len.
jsonLike xml, but MARC records are converted to
MARC-in-JSON.
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.
SRU/Solr Protocol behavior
The ZOOM driver for SRU/Solr treats records returned by a SRU/Solr server
as if they where Z39.50 records with transfer syntax XML and
no element set name or database name.
Facets
Facet operations is not part of the official ZOOM specification, but
is an Index Data extension for YAZ-based Z39.50 targets,
Solr and SRU 2.0 targets.
Facets may be requestd by the
facets option before a
search is sent.
For inspection of the returned facets, the following functions are
available:
ZOOM_facet_field *ZOOM_resultset_facets(ZOOM_resultset r);
ZOOM_facet_field ZOOM_resultset_get_facet_field(ZOOM_resultset r,
const char *facet_name);
ZOOM_facet_field ZOOM_resultset_get_facet_field_by_index(ZOOM_resultset r,
int pos);
size_t ZOOM_resultset_facets_size(ZOOM_resultset r);
const char *ZOOM_facet_field_name(ZOOM_facet_field facet_field);
size_t ZOOM_facet_field_term_count(ZOOM_facet_field facet_field);
const char *ZOOM_facet_field_get_term(ZOOM_facet_field facet_field,
size_t idx, int *freq);
References to temporary structures are returned by all functions.
They are only valid as long the Result set is valid.
ZOOM_resultset_get_facet_field or
ZOOM_resultset_get_facet_field_by_index.
ZOOM_resultset_facets.
ZOOM_facet_field_name.
ZOOM_facet_field_get_term.
A single Facet field is returned by function
ZOOM_resultset_get_facet_field or
ZOOM_resultset_get_facet_field_by_index that takes
a result set and facet name or positive index respectively. First
facet has position zero. If no facet could be obtained (invalid name
or index out of bounds) NULL is returned.
An array of facets field can be returned by
ZOOM_resultset_facets. The length of the array is
given by ZOOM_resultset_facets_size. The array is
zero-based and last entry will be at
ZOOM_resultset_facets_size(result_set)-1.
It is possible to interate over facets by name, by calling
ZOOM_resultset_facets_names.
This will return an const array of char * where each string can be used
as parameter for ZOOM_resultset_get_facet_field.
Function ZOOM_facet_field_name gets the request
facet name from a returned facet field.
Function ZOOM_facet_field_get_term returns the
idx'th term and term count for a facet field.
Idx must between 0 and
ZOOM_facet_field_term_count-1, otherwise the
returned reference will be NULL. On a valid idx, the
value of the freq reference will be the term count.
The freq parameter must be valid pointer to integer.
Scan
This section describes an interface for Scan. Scan is not an
official part of the ZOOM model yet. The result of a scan operation
is the ZOOM_scanset which is a set of terms
returned by a target.
The Scan interface is supported for both Z39.50, SRU and Solr.
ZOOM_scanset ZOOM_connection_scan(ZOOM_connection c,
const char *startpqf);
ZOOM_scanset ZOOM_connection_scan1(ZOOM_connection c,
ZOOM_query q);
size_t ZOOM_scanset_size(ZOOM_scanset scan);
const char *ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
size_t *occ, size_t *len);
const char *ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos,
size_t *occ, size_t *len);
void ZOOM_scanset_destroy(ZOOM_scanset scan);
const char *ZOOM_scanset_option_get(ZOOM_scanset scan,
const char *key);
void ZOOM_scanset_option_set(ZOOM_scanset scan, const char *key,
const char *val);
The scan set is created by function
ZOOM_connection_scan which performs a scan
operation on the connection using the specified
startpqf.
If the operation was successful, the size of the scan set can be
retrieved by a call to ZOOM_scanset_size.
Like result sets, the items are numbered 0,..size-1.
To obtain information about a particular scan term, call function
ZOOM_scanset_term. This function takes
a scan set offset pos and returns a pointer
to a raw term or NULL if
non-present.
If present, the occ and len
are set to the number of occurrences and the length
of the actual term respectively.
ZOOM_scanset_display_term is similar to
ZOOM_scanset_term except that it returns
the display term rather than the raw term.
In a few cases, the term is different from display term. Always
use the display term for display and the raw term for subsequent
scan operations (to get more terms, next scan result, etc).
A scan set may be freed by a call to function
ZOOM_scanset_destroy.
Functions ZOOM_scanset_option_get and
ZOOM_scanset_option_set retrieves and sets
an option respectively.
The startpqf is a subset of PQF, namely
the Attributes+Term part. Multiple @attr can
be used. For example to scan in title (complete) phrases:
@attr 1=4 @attr 6=2 "science o"
The ZOOM_connecton_scan1 is a newer and
more generic alternative to ZOOM_connection_scan
which allows to use both CQL and PQF for Scan.
ZOOM Scan Set OptionsOptionDescriptionDefault
numberNumber of Scan Terms requested in next scan.
After scan it holds the actual number of terms returned.
20
positionPreferred Position of term in response
in next scan; actual position after completion of scan.
1
stepSizeStep Size
0
scanStatusAn integer indicating the Scan Status
of last scan.
0
rpnCharsetCharacter set for RPN terms.
If this is set, ZOOM C will assume that the ZOOM application is
running UTF-8. Terms in RPN queries are then converted to the
rpnCharset. If this is unset, ZOOM C will not assume any encoding
of RPN terms and no conversion is performed.
none
Extended Services
ZOOM offers an interface to a subset of the Z39.50 extended services
as well as a few privately defined ones:
Z39.50 Item Order (ILL).
See .
Record Update. This allows a client to insert, modify or delete
records.
See .
Database Create. This a non-standard feature. Allows a client
to create a database.
See .
Database Drop. This a non-standard feature. Allows a client
to delete/drop a database.
See .
Commit operation. This a non-standard feature. Allows a client
to commit operations.
See .
To create an extended service operation a ZOOM_package
must be created. The operation is a five step operation. The
package is created, package is configured by means of options,
the package is send, result is inspected (by means of options),
the package is destroyed.
ZOOM_package ZOOM_connection_package(ZOOM_connection c,
ZOOM_options options);
const char *ZOOM_package_option_get(ZOOM_package p,
const char *key);
void ZOOM_package_option_set(ZOOM_package p, const char *key,
const char *val);
void ZOOM_package_send(ZOOM_package p, const char *type);
void ZOOM_package_destroy(ZOOM_package p);
The ZOOM_connection_package creates a
package for the connection given using the options specified.
Functions ZOOM_package_option_get and
ZOOM_package_option_set gets and sets
options.
ZOOM_package_send sends
the package the via connection specified in
ZOOM_connection_package.
The type specifies the actual extended service
package type to be sent.
Extended Service Common OptionsOptionDescriptionDefaultpackage-nameExtended Service Request package name. Must be specified
as part of a requestnoneuser-idUser ID of Extended Service Package. Is a request optionnonefunction
Function of package - one of create,
delete, modify. Is
a request option.
createwaitAction
Wait action for package. Possible values:
wait, waitIfPossible,
dontWait or dontReturnPackage.
waitIfPossibletargetReference
Target Reference. This is part of the response as returned
by the server. Read it after a successful operation.
none
Item Order
For Item Order, type must be set to itemorder in
ZOOM_package_send.
Item Order OptionsOptionDescriptionDefaultcontact-nameILL contact namenonecontact-phoneILL contact phonenonecontact-emailILL contact emailnoneitemorder-itemPosition for item (record) requested. An integer1
Record Update
For Record Update, type must be set to update in
ZOOM_package_send.
Record Update OptionsOptionDescriptionDefaultaction
The update action. One of
specialUpdate,
recordInsert,
recordReplace,
recordDelete,
elementUpdate.
specialUpdate (recordInsert for updateVersion=1 which does not support specialUpdate)recordIdOpaqueOpaque Record IDnonerecordIdNumberRecord ID numbernonerecordThe record itselfnonerecordOpaqueSpecifies an opaque record which is
encoded as an ASN.1 ANY type with the OID as tiven by option
syntax (see below).
Option recordOpaque is an alternative
to record - and record option (above) is
ignored if recordOpaque is set. This option is only available in
YAZ 3.0.35 and later and is meant to facilitate Updates with
servers from OCLC.
nonesyntaxThe record syntax (transfer syntax). Is a string that
is a known record syntax.
no syntaxdatabaseNameDatabase from connection objectDefaultcorrelationInfo.noteCorrelation Info Note (string)nonecorrelationInfo.idCorrelation Info ID (integer)noneelementSetNameElement Set for RecordnoneupdateVersionRecord Update version which holds one of the values
1, 2 or 3. Each version has a distinct OID:
1.2.840.10003.9.5
(first version) ,
1.2.840.10003.9.5.1
(second version) and
1.2.840.10003.9.5.1.1
(third and
newest version).
3
Database Create
For Database Create, type must be set to create in
ZOOM_package_send.
Database Create OptionsOptionDescriptionDefaultdatabaseNameDatabase from connection objectDefault
Database Drop
For Database Drop, type must be set to drop in
ZOOM_package_send.
Database Drop OptionsOptionDescriptionDefaultdatabaseNameDatabase from connection objectDefault
Commit Operation
For Commit, type must be set to commit in
ZOOM_package_send.
Protocol behavior
All the extended services are Z39.50-only.
The database create, drop and commit services are privately defined
operations.
Refer to esadmin.asn in YAZ for the ASN.1
definitions.
Options
Most &zoom; objects provide a way to specify options to change behavior.
From an implementation point of view a set of options is just like
an associative array / hash.
ZOOM_options ZOOM_options_create(void);
ZOOM_options ZOOM_options_create_with_parent(ZOOM_options parent);
void ZOOM_options_destroy(ZOOM_options opt);
const char *ZOOM_options_get(ZOOM_options opt, const char *name);
void ZOOM_options_set(ZOOM_options opt, const char *name,
const char *v);
typedef const char *(*ZOOM_options_callback)
(void *handle, const char *name);
ZOOM_options_callback
ZOOM_options_set_callback(ZOOM_options opt,
ZOOM_options_callback c,
void *handle);
Query conversions
int ZOOM_query_cql2rpn(ZOOM_query s, const char *cql_str,
ZOOM_connection conn);
int ZOOM_query_ccl2rpn(ZOOM_query s, const char *ccl_str,
const char *config,
int *ccl_error, const char **error_string,
int *error_pos);
ZOOM_query_cql2rpn translates the CQL string,
client-side, into RPN which may be passed to the server.
This is useful for server's that don't themselves
support CQL, for which ZOOM_query_cql is useless.
`conn' is used only as a place to stash diagnostics if compilation
fails; if this information is not needed, a null pointer may be used.
The CQL conversion is driven by option cqlfile from
connection conn. This specifies a conversion file (eg pqf.properties)
which must be present.
ZOOM_query_ccl2rpn translates the CCL string,
client-side, into RPN which may be passed to the server.
The conversion is driven by the specification given by
config. Upon completion 0 is returned on success; -1
is returned on on failure. Om failure error_string and
error_pos holds error message and position of
first error in original CCL string.
Events
If you're developing non-blocking applications, you have to deal
with events.
int ZOOM_event(int no, ZOOM_connection *cs);
The ZOOM_event executes pending events for
a number of connections. Supply the number of connections in
no and an array of connections in
cs (cs[0] ... cs[no-1]).
A pending event could be a sending a search, receiving a response,
etc.
When an event has occurred for one of the connections, this function
returns a positive integer n denoting that an event
occurred for connection cs[n-1].
When no events are pending for the connections, a value of zero is
returned.
To ensure that all outstanding requests are performed call this function
repeatedly until zero is returned.
If ZOOM_event returns and returns non-zero, the
last event that occurred can be expected.
int ZOOM_connection_last_event(ZOOM_connection cs);
ZOOM_connection_last_event returns an event type
(integer) for the last event.
ZOOM Event IDsEventDescriptionZOOM_EVENT_NONENo event has occurredZOOM_EVENT_CONNECTTCP/IP connect has initiatedZOOM_EVENT_SEND_DATAData has been transmitted (sending)ZOOM_EVENT_RECV_DATAData has been received)ZOOM_EVENT_TIMEOUTTimeoutZOOM_EVENT_UNKNOWNUnknown eventZOOM_EVENT_SEND_APDUAn APDU has been transmitted (sending)ZOOM_EVENT_RECV_APDUAn APDU has been receivedZOOM_EVENT_RECV_RECORDA result-set record has been receivedZOOM_EVENT_RECV_SEARCHA search result been received