X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fzoom.xml;h=8c9986987880cd9153ce1cc8e3999681c7f2f2cb;hp=5ca427241c7b049d9f92c7950f2d598b45b4b2f2;hb=d72929b7de6221054feb6a220dc72289b0f3e03d;hpb=4102d95bf434baaf92b1a8db63d1f7396c8e469f diff --git a/doc/zoom.xml b/doc/zoom.xml index 5ca4272..8c99869 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -17,8 +17,10 @@ ZOOM_options_setl(opt, name, value, len) ZOOM_options_get_bool(opt, name, defa) ZOOM_options_get_int(opt, name, defa) ZOOM_options_set_int(opt, name, value) +ZOOM_connection_scan1 (ZOOM_connection c, ZOOM_query startterm) +ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn) --> - + ZOOM &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is @@ -30,9 +32,17 @@ ZOOM_options_set_int(opt, name, value) - A recent addition to &yaz; is SRW support. You can now make - SRW ZOOM connections by specifying scheme http:// - for the hostname for a connection. + A recent addition to &yaz; is SRU support. You can now 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) or SRW (SRU over + SOAP) (soap). 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.pl @@ -47,7 +57,7 @@ ZOOM_options_set_int(opt, name, value) There are other language bindings available for &yaz;, and still more are in active development. See the - ZOOM web-site for + ZOOM web-site for more information. @@ -73,7 +83,7 @@ ZOOM_options_set_int(opt, name, value) protocol behavior, that describes how the API maps to the Z39.50 protocol. - Connections + Connections The Connection object is a session with a target. @@ -106,7 +116,18 @@ ZOOM_options_set_int(opt, name, value) You can prefix the host with a scheme followed by colon. The default scheme is tcp (Z39.50 protocol). - The scheme http selects SRW over HTTP. + The scheme http selects SRU over HTTP. + + + 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 @@ -141,7 +162,8 @@ ZOOM_options_set_int(opt, name, value) ZOOM_connection_option_getl returns the value for an option given by key. - ZOOM Connection Options +
+ ZOOM Connection Options @@ -239,13 +261,27 @@ ZOOM_options_set_int(opt, name, value) 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. + none + + 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
If either option lang or charset is set, then - + Character Set and Language Negotiation is in effect. @@ -265,7 +301,8 @@ ZOOM_options_set_int(opt, name, value) of ZOOM_connection_error that is capable of returning name of diagnostic set in dset. - Z39.50 Protocol behavior + + Z39.50 Protocol behavior The calls ZOOM_connection_new and ZOOM_connection_connect establishes a TCP/IP @@ -303,14 +340,15 @@ ZOOM_options_set_int(opt, name, value) API cannot tell the outcome (yet). - SRW Protocol behavior + + SRU Protocol behavior - The SRW protocol doesn't feature an Inititialize Request, so + The SRU protocol doesn't feature an Inititialize Request, so the connection phase merely establishes a TCP/IP connection with the SOAP service. Most of the ZOOM connection options do not - affect SRW and they are ignored. However, future versions + affect SRU and they are ignored. However, future versions of &yaz; might honor implementationName and put that as part of User-Agent header for HTTP requests. @@ -350,7 +388,7 @@ ZOOM_options_set_int(opt, name, value) sort criteria using the same string notation for sort as offered by the YAZ client. - Protocol behavior + Protocol behavior The query object is just an interface for the member Query in the SearchRequest. The sortby-function is an interface to the @@ -401,7 +439,8 @@ ZOOM_options_set_int(opt, name, value) The number of hits also called result-count is returned by function ZOOM_resultset_size. - ZOOM Result set Options +
ZOOM Result set Options @@ -447,6 +486,13 @@ ZOOM_options_set_int(opt, name, value) 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
@@ -465,7 +511,8 @@ ZOOM_options_set_int(opt, name, value) Read searchresult.size to determine the number of items. - Search Info Report options +
Search Info Report Options @@ -510,7 +557,7 @@ ZOOM_options_set_int(opt, name, value)
- + Z39.50 Protocol behavior The creation of a result set involves at least a SearchRequest @@ -562,23 +609,23 @@ ZOOM_options_set_int(opt, name, value) to specify one elementSetName option rather than three. - - SRW Protocol behavior + + SRU Protocol behavior Current version of &yaz; does not take advantage of a result set id - returned by the SRW server. Future versions might do, however. + 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 SRW SearchRetrieveRequest + present (retrieval) is transformed to a SRU SearchRetrieveRequest with same query but, possibly, different offsets. - Option schema specifies SRW schema + Option schema specifies SRU schema for retrieval. However, options elementSetName and preferredRecordSyntax are ignored. Options start and count - are supported by SRW. + are supported by SRU. The remaining options piggyback, smallSetUpperBound, @@ -589,18 +636,18 @@ ZOOM_options_set_int(opt, name, value) unsupported. - SRW supports CQL queries, not PQF. + SRU supports CQL queries, not PQF. If PQF is used, however, the PQF query is transferred anyway using non-standard element pQuery in - SRW SearchRetrieveRequest. + SRU SearchRetrieveRequest. - Unfortunately, SRW does not define a database setting. Hence, + Unfortunately, SRU 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; SRW server). + database (at least for the &yaz; SRU server). @@ -610,13 +657,16 @@ ZOOM_options_set_int(opt, name, value) 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); + 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); + 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); @@ -640,6 +690,12 @@ ZOOM_options_set_int(opt, name, value) 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 @@ -696,6 +752,12 @@ ZOOM_options_set_int(opt, name, value) 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 @@ -716,9 +778,9 @@ ZOOM_options_set_int(opt, name, value) xml The record is returned in XML if possible. - SRW/SRU and Z39.50 records with transfer syntax XML are + 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). @@ -736,20 +798,17 @@ ZOOM_options_set_int(opt, name, value) Most - - MARC21 - + MARC21 records uses the - - MARC-8 - + 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 + + Z39.50 Protocol behavior The functions ZOOM_resultset_record and ZOOM_resultset_records inspects the client-side @@ -768,9 +827,10 @@ ZOOM_options_set_int(opt, name, value) now. - SRW Protocol behavior + + SRU Protocol behavior - The ZOOM driver for SRW treats records returned by a SRW server + 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. @@ -785,14 +845,16 @@ ZOOM_options_set_int(opt, name, value) - The Scan interface is Z39.50 only. SRW version 1.0 does not - support this. + The Scan interface is supported for both Z39.50 and SRU. 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, @@ -848,8 +910,15 @@ ZOOM_options_set_int(opt, name, value) @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 Options +
+ ZOOM Scan Set Options @@ -877,12 +946,19 @@ ZOOM_options_set_int(opt, name, value) 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 + Extended Services ZOOM offers an interface to a subset of the Z39.50 extended services as well as a few privately defined ones: @@ -891,35 +967,35 @@ ZOOM_options_set_int(opt, name, value) Z39.50 Item Order (ILL). - See . + See . Record Update. This allows a client to insert, modify or delete records. - See . + See . Database Create. This a non-standard feature. Allows a client to create a database. - See . + See . Database Drop. This a non-standard feature. Allows a client to delete/drop a database. - See . + See . Commit operation. This a non-standard feature. Allows a client to commit operations. - See . + See . @@ -960,7 +1036,8 @@ ZOOM_options_set_int(opt, name, value) package type to be sent. - Extended Service Common Options +
+ Extended Service Common Options @@ -994,10 +1071,19 @@ ZOOM_options_set_int(opt, name, value) create + waitAction + + Wait action for package. Possible values: + wait, waitIfPossible, + dontWait or dontReturnPackage. + + waitIfPossible + + targetReference Target Reference. This is part of the response as returned - by the server. Read it after a succesful operation. + by the server. Read it after a successful operation. none @@ -1005,13 +1091,14 @@ ZOOM_options_set_int(opt, name, value)
- Item Order + Item Order For Item Order, type must be set to itemorder in ZOOM_package_send. - Item Order Options +
+ Item Order Options @@ -1050,13 +1137,14 @@ ZOOM_options_set_int(opt, name, value) - Record Update + Record Update For Record Update, type must be set to update in ZOOM_package_send. -
Record Update Options +
+ Record Update Options @@ -1079,7 +1167,7 @@ ZOOM_options_set_int(opt, name, value) recordDelete, elementUpdate. - specialUpdate + specialUpdate (recordInsert for updateVersion=1 which does not support specialUpdate) recordIdOpaque @@ -1108,19 +1196,49 @@ ZOOM_options_set_int(opt, name, value) Database from connection object Default + + correlationInfo.note + Correlation Info Note (string) + none + + + correlationInfo.id + Correlation Info ID (integer) + none + + + elementSetName + Element Set for Record + none + + + updateVersion + Record 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 + Database Create For Database Create, type must be set to create in ZOOM_package_send. - Database Create Options +
+ Database Create Options @@ -1143,13 +1261,14 @@ ZOOM_options_set_int(opt, name, value)
- Database Drop + Database Drop For Database Drop, type must be set to drop in ZOOM_package_send. - Database Create Options +
+ Database Drop Options @@ -1172,14 +1291,15 @@ ZOOM_options_set_int(opt, name, value)
- Commit Operation + Commit Operation For Commit, type must be set to commit in ZOOM_package_send. - Protocol behavior + + Protocol behavior All the extended services are Z39.50-only. @@ -1258,7 +1378,8 @@ ZOOM_options_set_int(opt, name, value) (integer) for the last event. - ZOOM Event IDs +
+ ZOOM Event IDs