From 6ba14eb5dc7229aa17977882024a475b6d258368 Mon Sep 17 00:00:00 2001 From: Adam Dickmeiss Date: Tue, 3 Sep 2002 09:50:34 +0000 Subject: [PATCH] Updated doc about PQF. Spell fixes. --- doc/odr.xml | 6 ++-- doc/tools.xml | 111 +++++++++++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 100 insertions(+), 17 deletions(-) diff --git a/doc/odr.xml b/doc/odr.xml index 9a8e406..820fa26 100644 --- a/doc/odr.xml +++ b/doc/odr.xml @@ -1,4 +1,4 @@ - + The ODR Module Introduction @@ -132,7 +132,7 @@ The memory subsystem of &odr; is fairly efficient at allocating and releasing little bits of memory. Rather than managing the individual, - small bits of space, the system maintains a freelist of larger chunks + small bits of space, the system maintains a free-list of larger chunks of memory, which are handed out in small bits. This scheme is generally known as a nibble memory system. It is very useful for maintaining short-lived constructions such @@ -679,7 +679,7 @@ int ODR_MASK_GET(Odr_bitmask *b, int bitno); - The functions are modelled after the manipulation functions that + The functions are modeled after the manipulation functions that accompany the fd_set type used by the select(2) call. ODR_MASK_ZERO should always be called first on a diff --git a/doc/tools.xml b/doc/tools.xml index 4d19542..36138fa 100644 --- a/doc/tools.xml +++ b/doc/tools.xml @@ -1,4 +1,4 @@ - + Supporting Tools @@ -32,19 +32,73 @@ in simple test applications and scripting environments (like Tcl). The demonstration client included with YAZ uses the PQF. + + + + The PQF have been adopted by other parties developing Z39.50 + software. It is often referred to as Prefix Query Notation + - PQN. + + - The PQF is defined by the pquery module in the YAZ library. The - pquery.h file provides the declaration of the - functions + The PQF is defined by the pquery module in the YAZ library. + There are two sets of function that have similar behavior. First + set operates on a PQF parser handle, second set doesn't. First set + set of functions are more flexible than the second set. Second set + is obsolete and is only provided to ensure backwards compatibility. - -Z_RPNQuery *p_query_rpn (ODR o, oid_proto proto, const char *qbuf); + + First set of functions all operate on a PQF parser handle: + + + #include <yaz/pquery.h> -Z_AttributesPlusTerm *p_query_scan (ODR o, oid_proto proto, - Odr_oid **attributeSetP, const char *qbuf); + YAZ_PQF_Parser yaz_pqf_create (void); -int p_query_attset (const char *arg); - + void yaz_pqf_destroy (YAZ_PQF_Parser p); + + Z_RPNQuery *yaz_pqf_parse (YAZ_PQF_Parser p, ODR o, const char *qbuf); + + Z_AttributesPlusTerm *yaz_pqf_scan (YAZ_PQF_Parser p, ODR o, + Odr_oid **attributeSetId, const char *qbuf); + + + int yaz_pqf_error (YAZ_PQF_Parser p, const char **msg, size_t *off); + + + A PQF parser is created and destructed by functions + yaz_pqf_create and + yaz_pqf_destroy respectively. + Function yaz_pqf_parse parses query given + by string qbuf. If parsing was successful, + a Z39.50 RPN Query is returned which is created using ODR stream + o. If parsing failed, a NULL pointer is + returned. + Function yaz_pqf_scan takes a scan query in + qbuf. If parsing was successful, the function + returns attributes plus term pointer and modifies + attributeSetId to hold attribute set for the + scan request - both allocated using ODR stream o. + If parsing failed, yaz_pqf_scan returns a NULL pointer. + Error information for bad queries can be obtained by a call to + yaz_pqf_error which returns an error code and + modifies *msg to point to an error description, + and modifies *off to the offset within last + query were parsing failed. + + + The second set of functions are declared as follows: + + + #include <yaz/pquery.h> + + Z_RPNQuery *p_query_rpn (ODR o, oid_proto proto, const char *qbuf); + + Z_AttributesPlusTerm *p_query_scan (ODR o, oid_proto proto, + Odr_oid **attributeSetP, const char *qbuf); + + int p_query_attset (const char *arg); + The function p_query_rpn() takes as arguments an &odr; stream (see section The ODR Module) @@ -57,10 +111,10 @@ int p_query_attset (const char *arg); If the parse went well, p_query_rpn() returns a pointer to a Z_RPNQuery structure which can be - placed directly into a Z_SearchRequest. + placed directly into a Z_SearchRequest. + If parsing failed, due to syntax error, a NULL pointer is returned. - The p_query_attset specifies which attribute set to use if the query doesn't specify one by the @attrset operator. @@ -77,7 +131,7 @@ int p_query_attset (const char *arg); top-set ::= [ '@attrset' string ] - query-struct ::= attr-spec | simple | complex + query-struct ::= attr-spec | simple | complex | '@term' term-type attr-spec ::= '@attr' [ string ] string query-struct @@ -89,7 +143,7 @@ int p_query_attset (const char *arg); result-set ::= '@set' string. - term ::= string + term ::= string. proximity ::= exclusion distance ordered relation which-code unit-code. @@ -104,6 +158,9 @@ int p_query_attset (const char *arg); which-code ::= 'known' | 'private' | integer. unit-code ::= integer. + + term-type ::= 'general' | 'numeric' | 'string' | 'oid' | + 'datetime' | 'null'. @@ -115,6 +172,26 @@ int p_query_attset (const char *arg); + The @attr operator is followed by an attribute specification + (attr-spec above). The specification consists + of optional an attribute set, an attribute type-value pair and + a sub query. The attribute type-value pair is packed in one string: + an attribute type, a dash, followed by an attribute value. + The type is always an integer but the value may be either an + integer or a string (if it doesn't start with a digit character). + + + + Z39.50 version 3 defines various encoding of terms. + Use the @term operator to indicate the encoding type: + general, numeric, + string (for InternationalString), .. + If no term type has been given, the general form + is used which is the only encoding allowed in both version 2 - and 3 + of the Z39.50 standard. + + + The following are all examples of valid queries in the PQF. @@ -129,6 +206,8 @@ int p_query_attset (const char *arg); @or @and bob dylan @set Result-1 + @attr 1=4 computer + @attr 4=1 @and @attr 1=1 "bob dylan" @attr 1=4 "slow train coming" @attr 4=1 @attr 1=4 "self portrait" @@ -136,6 +215,10 @@ int p_query_attset (const char *arg); @prox 0 3 1 2 k 2 dylan zimmerman @and @attr 2=4 @attr gils 1=2038 -114 @attr 2=2 @attr gils 1=2039 -109 + + @term string "a UTF-8 string, maybe?" + + @attr 1=/book/title computer -- 1.7.10.4