X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fzoom.xml;h=0ca1c8cc2e209db82781a00c07041199eb5e1ca2;hb=cf273cb8a7f73124935713928cd5df5b537f8b9c;hp=caa3ebacf1cfea39ff0d3270815dc5fd8fe1db8e;hpb=886a6a270e909137e3127ac4ce37c152a6e81c70;p=yaz-moved-to-github.git diff --git a/doc/zoom.xml b/doc/zoom.xml index caa3eba..0ca1c8c 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -1,6 +1,5 @@ - - Building clients with ZOOM - + + 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 @@ -8,6 +7,15 @@ provide a common Z39.50 client API not bound to a particular programming language or toolkit. + + + + 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. + + + 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 @@ -22,14 +30,14 @@ 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, @@ -50,15 +58,15 @@ The Connection object is a session with a target. - #include <yaz/zoom.h> + #include <yaz/zoom.h> - ZOOM_connection ZOOM_connection_new (const char *host, int portnum); + 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, + 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); + void ZOOM_connection_destroy (ZOOM_connection c); Connection objects are created with either function @@ -76,6 +84,11 @@ 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 SRW over HTTP. + + Connection objects should be destroyed using the function ZOOM_connection_destroy. @@ -91,7 +104,7 @@ The ZOOM_connection_option_set allows you to set an option given by key to the value value for the connection. - Function ZOOM_connection_option_get returns + Function ZOOM_connection_option_get returns the value for an option given by key. ZOOM Connection Options @@ -118,7 +131,7 @@ none passAuthentication password - none + none hostTarget host. This setting is "read-only". It's automatically set internally when connecting to a target. @@ -144,28 +157,48 @@ charset Character set for negotiation. none + + targetImplementationId Implementation ID of target. + none + + targetImplementationName Implementation Name of target. + none + + targetImplementationVersion Implementation Version + of target. + none + + databaseNameOne or more database names + separated by character plus (+), which to + be used by subsequent search requests on this Connection. + Default
If either option lang or charset - are defined, then + is set, then - Character Set and Language Negotiation is in effect. + Character Set and Language Negotiation is in effect. int ZOOM_connection_error (ZOOM_connection c, const char **cp, - const char **addinfo); + const char **addinfo); + int ZOOM_connection_error_x (ZOOM_connection c, const char **cp, + const char **addinfo, const char **dset); - Use ZOOM_connection_error to check for + 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. + 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. - Protocol behavior + Z39.50 Protocol behavior The calls ZOOM_connection_new and ZOOM_connection_connect establishes a TCP/IP @@ -203,6 +236,22 @@ API cannot tell the outcome (yet). + SRW Protocol behavior + + The SRW 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 + 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. + + Queries @@ -215,6 +264,8 @@ 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); @@ -222,8 +273,10 @@ and destroy them by calling ZOOM_query_destroy. RPN-queries can be specified in PQF notation by using the - function ZOOM_query_prefix. More - query types will be added later, such as + 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 specifies a @@ -307,6 +360,10 @@ countNumber of records to be retrieved. 0 + stepNumber of records to be retrieved in + one chunk. The value, 0 means unchunked. + 0 + elementSetNameElement-Set name of records. Most targets should honor element set name B and F for brief and full respectively. @@ -342,10 +399,6 @@ The element set name to be for medium-sized result sets. none - databaseNameOne or more database names - separated by character plus (+). - Default - setnameName of Result Set (Result Set ID). If this option isn't set, the ZOOM module will automatically allocate a result set name. @@ -354,7 +407,7 @@ - Protocol behavior + Z39.50 Protocol behavior The creation of a result set involves at least a SearchRequest - SearchResponse protocol handshake. Following that, if a sort @@ -404,6 +457,47 @@ to specify one elementSetName option rather than three. + + SRW 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. + Since, the ZOOM driver does not save result set IDs any + present (retrieval) is transformed to a SRW SearchRetrieveRequest + with same query but, possibly, different offsets. + + + Option schema specifies SRW schema + for retrieval. However, options elementSetName and + preferredRecordSyntax are ignored. + + + Options start and count + are supported by SRW. + The remaining options + piggyback, + smallSetUpperBound, + largeSetLowerBound, + mediumSetPresentNumber, + mediumSetElementSetName, + smallSetElementSetName are + unsupported. + + + SRW supports CQL queries, not PQF. + If PQF is used, however, the PQF query is transferred anyway + using non-standard element pQuery in + SRW SearchRetrieveRequest. + + + Unfortunately, SRW 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). + + Records @@ -457,30 +551,53 @@ 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. + type. + + + The type is a string of the format: + + + form[; charset=from[,to]] + + + where form 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 charset is not given, then no character set conversion takes place. + If to is omitted UTF-8 is assumed. + + 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. 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 + The 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 *. - + 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 @@ -491,10 +608,39 @@ For SUTRS and octet aligned record (including all MARCs) the octet buffer is returned and the length of the buffer. - + + xml + The record is returned in XML if possible. + SRW/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). + GRS-1 and OPAC records are not supported for this form. + Upon completion, the XML buffer is returned + (type const char *) and length is stored in + *len. + + - Protocol behavior + + 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 @@ -507,12 +653,19 @@ 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 + 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. + SRW Protocol behavior + + The ZOOM driver for SRW treats records returned by a SRW server + as if they where Z39.50 records with transfer syntax XML and + no element set name or database name. + + Scan @@ -521,6 +674,12 @@ is the ZOOM_scanset which is a set of terms returned by a target. + + + The Scan interface is Z39.50 only. SRW version 1.0 does not + support this. + + ZOOM_scanset ZOOM_connection_scan (ZOOM_connection c, const char *startterm);