X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fzoom.xml;h=63c1c1db44c9698bdf5d36b649db2112eef296dc;hp=6c887500e9990c24171f850142294d8d8a6361d7;hb=a0b43ae242eb940fb511c1d91742e61e442ca191;hpb=e7cef788e6e6ae270dc9a274b5da51e953ca5479
diff --git a/doc/zoom.xml b/doc/zoom.xml
index 6c88750..63c1c1d 100644
--- a/doc/zoom.xml
+++ b/doc/zoom.xml
@@ -45,8 +45,8 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
sru=get,http://sru.miketaylor.org.uk:80/sru.pl
- SOLR protocol support was added to YAZ in version 4.1.0,
- as a dialect of a SRU protocol, since both are HTTP based protocols.
+ SOLR 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
@@ -62,14 +62,14 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
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,
@@ -86,29 +86,29 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
protocol.
Connections
-
+
The 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_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.
+ 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
@@ -118,8 +118,8 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
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.
+ 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
@@ -154,7 +154,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
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.
+ 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
@@ -207,7 +207,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
of a client. Is used of ZOOM is used in a gateway of some sort.
none
- asyncIf true (1) the connection operates in
+ asyncIf true (1) the connection operates in
asynchronous operation which means that all calls are non-blocking
except
ZOOM_event.
@@ -296,9 +296,9 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
facets
A FacetList is comma-separated list of facet, which is defined
as AttributeList and a optional FacetTerm
- (a Term and a frequency). On request the terms is missing.
+ (a Term and a frequency). On request the terms is missing.
On response the the list contains the terms that the target
- could collect.
+ could collect.
none
apdulog
@@ -306,12 +306,30 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
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.
+
If either option lang or charset
- is set, then
+ is set, then
Character Set and Language Negotiation is in effect.
@@ -415,7 +433,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
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 specifies a
+ ZOOM_query_sortby specifies a
sort criteria using the same string notation for sort as offered by
the YAZ client.
@@ -466,7 +484,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
The number of hits also called result-count is returned by
function ZOOM_resultset_size.
-
ZOOM Result set Options
@@ -481,7 +499,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
- startOffset of first record to be
+ 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
@@ -491,7 +509,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
function ZOOM_resultset_records should be used.
0
- countNumber of records to be retrieved.
+ 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.
@@ -504,7 +522,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
option is also supported for the benefit of old applications.)
0
- elementSetNameElement-Set name of records.
+ elementSetNameElement-Set name of records.
Most targets should honor element set name B
and F for brief and full respectively.
none
@@ -539,14 +557,14 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
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
+ 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).
+ where no presents the item number (0=first, 1=second).
Read searchresult.size to determine the
number of items.
-
Search Info Report Options
@@ -659,13 +677,13 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
preferredRecordSyntax are ignored.
- Options start and count
+ Options start and count
are supported by SRU.
The remaining options
- piggyback,
- smallSetUpperBound,
- largeSetLowerBound,
- mediumSetPresentNumber,
+ piggyback,
+ smallSetUpperBound,
+ largeSetLowerBound,
+ mediumSetPresentNumber,
mediumSetElementSetName,
smallSetElementSetName are
unsupported.
@@ -682,7 +700,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
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
+ 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).
@@ -711,7 +729,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
void ZOOM_record_destroy(ZOOM_record rec);
- References to temporary records are returned by functions
+ References to temporary records are returned by functions
ZOOM_resultset_records or
ZOOM_resultset_record.
@@ -723,7 +741,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
A single record is returned by function
- ZOOM_resultset_record that takes a
+ ZOOM_resultset_record that takes a
position as argument. First record has position zero.
If no record could be obtained NULL is returned.
@@ -768,7 +786,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
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
@@ -782,13 +800,13 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
The format argument controls whether record data should be XML
pretty-printed (post process operation).
- It is enabled only if format value v is
+ 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 returned information.
The following are the supported values for form.
@@ -796,7 +814,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
databaseDatabase of record is returned
as a C null-terminated string. Return type
- const char *.
+ const char *.
syntax
@@ -804,13 +822,13 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
as a C null-terminated string containing the symbolic name of
the record syntax, e.g. Usmarc. Return type
is
- const char *.
+ const char *.
schemaThe schema of the record is returned
as a C null-terminated string. Return type is
- const char *.
+ const char *.
render
@@ -823,7 +841,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
rawThe record is returned in the internal
YAZ specific format. For GRS-1, Explain, and others, the
- raw data is returned as type
+ raw data is returned as type
Z_External * which is just the type for
the member retrievalRecord in
type NamePlusRecord.
@@ -837,9 +855,9 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
returned verbatim. MARC records are returned in
MARCXML
-
+
(converted from ISO2709 to MARCXML by YAZ).
- OPAC records are also converted to XML and the
+ 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
@@ -859,7 +877,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
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
@@ -871,7 +889,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
Most
MARC21
- records uses the
+ records uses the
MARC-8
character set encoding.
An application that wishes to display in Latin-1 would use
@@ -910,10 +928,10 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
Facets
- Facets operations is not part of the official ZOOM specification, but is an Index Data extension
- for YAZ-based Z39.50 targets or SOLR targets.
- In case the target can and is requested to return facets, using a result set the ZOOM client
- can request one or all facet fields. Using a facet field the client can request the term count and
+ Facets operations is not part of the official ZOOM specification, but is an Index Data extension
+ for YAZ-based Z39.50 targets or SOLR targets.
+ In case the target can and is requested to return facets, using a result set the ZOOM client
+ can request one or all facet fields. Using a facet field the client can request the term count and
then interate over the terms.
@@ -928,7 +946,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
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.
+ 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.
@@ -938,28 +956,28 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
A single Facet field is returned by function
- ZOOM_resultset_get_facet_field or ZOOM_resultset_get_facet_field_by_index that takes a
+ 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.
+ 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.
+ 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_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.
+ 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
@@ -1010,7 +1028,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
a scan set offset pos and returns a pointer
to a raw term or NULL if
non-present.
- If present, the occ and len
+ 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
@@ -1042,7 +1060,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
more generic alternative to ZOOM_connection_scan
which allows to use both CQL and PQF for Scan.
-
+
ZOOM Scan Set Options
@@ -1156,7 +1174,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
ZOOM_package_send sends
- the package the via connection specified in
+ the package the via connection specified in
ZOOM_connection_package.
The type specifies the actual extended service
package type to be sent.
@@ -1286,7 +1304,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
action
- The update action. One of
+ The update action. One of
specialUpdate,
recordInsert,
recordReplace,
@@ -1317,7 +1335,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
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
+ 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.
@@ -1356,9 +1374,9 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
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
+ 1.2.840.10003.9.5.1
+ (second version) and
+ 1.2.840.10003.9.5.1.1
(third and
newest version).
@@ -1367,7 +1385,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
-
+
Database Create
@@ -1375,7 +1393,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
For Database Create, type must be set to create in
ZOOM_package_send.
-
+
-
+
Commit Operation
For Commit, type must be set to commit in
@@ -1484,7 +1502,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
Events
- If you're developing non-blocking applications, you have to deal
+ If you're developing non-blocking applications, you have to deal
with events.
@@ -1574,7 +1592,7 @@ ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)