X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Ftools.xml;h=7f12685f89f37aed6643c5dd71c89f1ce2a811ab;hb=1dd26aed79c4c32a7a8b263651ddcd0ab88dbaf5;hp=d47683fc1d4dbb6bbe05dee6975880f0cb359a1e;hpb=21f7c16c6b1b694405dbc1760d3d6cb3caac38f6;p=yaz-moved-to-github.git diff --git a/doc/tools.xml b/doc/tools.xml index d47683f..7f12685 100644 --- a/doc/tools.xml +++ b/doc/tools.xml @@ -1,4 +1,4 @@ - + Supporting Tools @@ -129,11 +129,11 @@ query ::= top-set query-struct. - top-set ::= [ '@attrset' string ] + top-set ::= [ '@attrset' string ] query-struct ::= attr-spec | simple | complex | '@term' term-type query - attr-spec ::= '@attr' [ string ] string query-struct + attr-spec ::= '@attr' [ string ] string query-struct complex ::= operator query-struct query-struct. @@ -301,7 +301,8 @@ PQF queries - PQF queries using simple terms + + PQF queries using simple terms dylan @@ -310,7 +311,8 @@ - PQF boolean operators + + PQF boolean operators @or "dylan" "zimmerman" @@ -321,7 +323,8 @@ - PQF references to result sets + + PQF references to result sets @set Result-1 @@ -330,7 +333,8 @@ - Attributes for terms + + Attributes for terms @attr 1=4 computer @@ -345,7 +349,8 @@ - PQF Proximity queries + + PQF Proximity queries @prox 0 3 1 2 k 2 dylan zimmerman @@ -384,14 +389,16 @@ - PQF specification of search term + + PQF specification of search term type @term string "a UTF-8 string, maybe?" - PQF mixed queries + + PQF mixed queries @or @and bob dylan @set Result-1 @@ -439,12 +446,13 @@ license, it is included as a supplement to &yaz;. - CCL Syntax + + CCL Syntax The CCL parser obeys the following grammar for the FIND argument. The syntax is annotated by in the lines prefixed by - ‐‐. + --. @@ -488,7 +496,8 @@ - CCL queries + + CCL queries The following queries are all valid: @@ -522,7 +531,8 @@ - CCL Qualifiers + + CCL Qualifiers Qualifiers are used to direct the search to a particular searchable @@ -544,7 +554,8 @@ lines in a CCL profile: qualifier specification, qualifier alias, comments and directives. - Qualifier specification + + Qualifier specification A qualifier specification is of the form: @@ -569,7 +580,8 @@ or c for completeness. The attributes for the special qualifier name term are used when no CCL qualifier is given in a query. - Common Bib-1 attributes +
+ Common Bib-1 attributes @@ -648,7 +660,8 @@ which are used in combination with certain types. The special combinations are: -
Special attribute combos +
+ Special attribute combos @@ -734,7 +747,7 @@
- CCL profile + CCL profile Consider the following definition: @@ -779,7 +792,8 @@ - Qualifier alias + + Qualifier alias A qualifier alias is of the form: @@ -796,20 +810,23 @@ - Comments + + Comments Lines with white space or lines that begin with character # are treated as comments. - Directives + + Directives Directive specifications takes the form @directive value - CCL directives +
+ CCL directives @@ -873,7 +890,8 @@
- CCL API + + CCL API All public definitions can be found in the header file ccl.h. A profile identifier is of type @@ -936,7 +954,7 @@ struct ccl_rpn_node *ccl_find_str (CCL_bibset bibset, const char *str, - CQL + CQL CQL - Common Query Language - was defined for the @@ -986,7 +1004,7 @@ struct ccl_rpn_node *ccl_find_str (CCL_bibset bibset, const char *str, - CQL parsing + CQL parsing A CQL parser is represented by the CQL_parser handle. Its contents should be considered &yaz; internal (private). @@ -1032,7 +1050,7 @@ int cql_parser_stdio(CQL_parser cp, FILE *f); - CQL tree + CQL tree The the query string is valid, the CQL parser generates a tree representing the structure of the @@ -1136,7 +1154,7 @@ struct cql_node { - CQL to PQF conversion + CQL to PQF conversion Conversion to PQF (and Z39.50 RPN) is tricky by the fact that the resulting RPN depends on the Z39.50 target @@ -1218,7 +1236,7 @@ int cql_transform_FILE(cql_transform_t ct, open FILE. - + Specification of CQL to RPN mappings The file supplied to functions @@ -1245,6 +1263,13 @@ int cql_transform_FILE(cql_transform_t ct, value the attribute value. + The character * (asterisk) has special meaning + when used in the RPN pattern. + Each occurrence of * is substituted with the + CQL matching name (index, relation, qualifier etc). + This facility can be used to copy a CQL name verbatim to the RPN result. + + The following CQL patterns are recognized: @@ -1265,6 +1290,11 @@ int cql_transform_FILE(cql_transform_t ct, http://www.loc.gov/zing/cql/cql-indexes/v1.0/. If this pattern is not defined, the mapping will fail. + + The pattern, + index.set.* + is used when no other index pattern is matched. + @@ -1367,28 +1397,41 @@ int cql_transform_FILE(cql_transform_t ct, + + + set + + + + This specification defines a default CQL context set for index names. + The value on the right hand side is the URI for the set. + + + + - CQL to RPN mapping file + + CQL to RPN mapping file This simple file defines two context sets, three indexes and three relations, a position pattern and a default structure. @@ -1423,8 +1466,51 @@ int cql_transform_FILE(cql_transform_t ct, + + CQL to RPN string attributes + + In this example we allow any index to be passed to RPN as + a use attribute. + + + + + The http://bogus/rpn context set is also the default + so we can make queries such as + + title = a + + which is converted to + + @attr 2=3 @attr 4=1 @attr 3=3 @attr 1=title "a" + + + + + CQL to RPN using Bath Profile + + The file etc/pqf.properties has mappings from + the Bath Profile and Dublin Core to RPN. + If YAZ is installed as a package it's usually located + in /usr/share/yaz/etc and part of the + development package, such as libyaz-dev. + + - CQL to XCQL conversion + CQL to XCQL conversion Conversion from CQL to XCQL is trivial and does not require a mapping to be defined. @@ -1950,7 +2036,7 @@ typedef struct oident - MARC + MARC YAZ provides a fast utility that decodes MARC records and @@ -2012,7 +2098,7 @@ typedef struct oident - YAZ_MARC_MARXML + YAZ_MARC_MARCXML The resulting record is converted to MARCXML. @@ -2038,7 +2124,7 @@ typedef struct oident stores the resulting record in a WRBUF handle (WRBUF is a simple string type). - + Display of MARC record The followint program snippet illustrates how the MARC API may @@ -2061,6 +2147,267 @@ typedef struct oident + + Retrieval Facility + + YAZ version 2.1.20 or later includes a Retrieval facility tool + which allows a SRU/Z39.50 to describe itself and perform record + conversions. The idea is the following: + + + + + An SRU/Z39.50 client sends a retrieval request which includes + a combination of the following parameters: syntax (format), + schema (or element set name). + + + + + + The retrieval facility is invoked with parameters in a + server/proxy. The retrieval facility matches the parameters a set of + "supported" retrieval types. + If there is no match, the retrieval signals an error + (syntax and / or schema not supported). + + + + + + For a successful match, the backend is invoked with the same + or altered retrieval parameters (syntax, schema). If + a record is received from the backend, it is converted to the + frontend name / syntax. + + + + + + The resulting record is sent back the client and tagged with + the frontend syntax / schema. + + + + + + + The Retrieval facility is driven by an XML configuration. The + configuration is neither Z39.50 ZeeRex or SRU ZeeRex. But it + should be easy to generate both of them from the XML configuration. + (unfortunately the two versions + of ZeeRex differ substantially in this regard). + + + Retrieval XML format + + All elements should be covered by namespace + http://indexdata.com/yaz . + The root element node must be retrievalinfo. + + + The retrievalinfo must include one or + more retrieval elements. Each + retrieval defines specific combination of + syntax, name and identifier supported by this retrieval service. + + + The retrieval element may include any of the + following attributes: + + syntax (REQUIRED) + + + Defines the record syntax. Possible values is any + of the names defined in YAZ' OID database or a raw + OID in (n.n ... n). + + + + name (OPTIONAL) + + + Defines the name of the retrieval format. This can be + any string. For SRU, the value, is equivalent to schema (short-hand); + for Z39.50 it's equivalent to simple element set name. + + + + identifier (OPTIONAL) + + + Defines the URI schema name of the retrieval format. This can be + any string. For SRU, the value, is equivalent to URI schema. + For Z39.50, there is no equivalent. + + + + + + + The retrieval may include one + backend element. If a backend + element is given, it specifies how the records are retrieved by + some backend and how the records are converted from the backend to + the "frontend". + + + The attributes, name and syntax + may be specified for the backend element. These + semantics of these attributes is equivalent to those for the + retrieval. However, these values are passed to + the "backend". + + + The backend element may includes one or more + conversion instructions (as children elements). The supported + conversions are: + + marc + + + The marc element specifies a conversion + to - and from ISO2709 encoded MARC and + &marcxml;/MarcXchange. + The following attributes may be specified: + + + inputformat (REQUIRED) + + + Format of input. Supported values are + marc (for ISO2709); and xml + for MARCXML/MarcXchange. + + + + + outputformat (REQUIRED) + + + Format of output. Supported values are + line (MARC line format); + marcxml (for MARCXML), + marc (ISO2709), + marcxhcange (for MarcXchange). + + + + + inputcharset (OPTIONAL) + + + Encoding of input. For XML input formats, this need not + be given, but for ISO2709 based inputformats, this should + be set to the encoding used. For MARC21 records, a common + inputcharset value would be marc-8. + + + + + outputcharset (OPTIONAL) + + + Encoding of output. If outputformat is XML based, it is + strongly recommened to use utf-8. + + + + + + + + + xslt + + + The xslt element specifies a conversion + via &xslt;. The following attributes may be specified: + + + stylesheet (REQUIRED) + + + Stylesheet file. + + + + + + + + + + + + + Retrieval Facility Examples + + MARC21 backend + + A typical way to use the retrieval facility is to enable XML + for servers that only supports ISO2709 encoded MARC21 records. + + + + + + + + + + + + + + + + +]]> + + + This means that our frontend supports: + + + + MARC21 F(ull) records. + + + + + MARC21 B(rief) records. + + + + + + MARCXML records. + + + + + + Dublin core records. + + + + + + + + API + + It should be easy to use the retrieval systems from applications. Refer + to the headers + yaz/retrieval.h and + yaz/record_conv.h. + + +