-<!-- $Id: tools.xml,v 1.11 2002-05-30 20:57:31 adam Exp $ -->
+<!-- $Id: tools.xml,v 1.12 2002-09-03 09:50:34 adam Exp $ -->
<chapter id="tools"><title>Supporting Tools</title>
<para>
in simple test applications and scripting environments (like Tcl). The
demonstration client included with YAZ uses the PQF.
</para>
+
+ <note>
+ <para>
+ The PQF have been adopted by other parties developing Z39.50
+ software. It is often referred to as Prefix Query Notation
+ - PQN.
+ </para>
+ </note>
<para>
- The PQF is defined by the pquery module in the YAZ library. The
- <filename>pquery.h</filename> 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.
</para>
- <screen>
-Z_RPNQuery *p_query_rpn (ODR o, oid_proto proto, const char *qbuf);
+ <para>
+ First set of functions all operate on a PQF parser handle:
+ </para>
+ <synopsis>
+ #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);
- </screen>
+ 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);
+ </synopsis>
+ <para>
+ A PQF parser is created and destructed by functions
+ <function>yaz_pqf_create</function> and
+ <function>yaz_pqf_destroy</function> respectively.
+ Function <function>yaz_pqf_parse</function> parses query given
+ by string <literal>qbuf</literal>. If parsing was successful,
+ a Z39.50 RPN Query is returned which is created using ODR stream
+ <literal>o</literal>. If parsing failed, a NULL pointer is
+ returned.
+ Function <function>yaz_pqf_scan</function> takes a scan query in
+ <literal>qbuf</literal>. If parsing was successful, the function
+ returns attributes plus term pointer and modifies
+ <literal>attributeSetId</literal> to hold attribute set for the
+ scan request - both allocated using ODR stream <literal>o</literal>.
+ If parsing failed, yaz_pqf_scan returns a NULL pointer.
+ Error information for bad queries can be obtained by a call to
+ <function>yaz_pqf_error</function> which returns an error code and
+ modifies <literal>*msg</literal> to point to an error description,
+ and modifies <literal>*off</literal> to the offset within last
+ query were parsing failed.
+ </para>
+ <para>
+ The second set of functions are declared as follows:
+ </para>
+ <synopsis>
+ #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);
+ </synopsis>
<para>
The function <function>p_query_rpn()</function> takes as arguments an
&odr; stream (see section <link linkend="odr">The ODR Module</link>)
<para>
If the parse went well, <function>p_query_rpn()</function> returns a
pointer to a <literal>Z_RPNQuery</literal> structure which can be
- placed directly into a <literal>Z_SearchRequest</literal>.
+ placed directly into a <literal>Z_SearchRequest</literal>.
+ If parsing failed, due to syntax error, a NULL pointer is returned.
</para>
<para>
-
The <literal>p_query_attset</literal> specifies which attribute set
to use if the query doesn't specify one by the
<literal>@attrset</literal> operator.
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
result-set ::= '@set' string.
- term ::= string
+ term ::= string.
proximity ::= exclusion distance ordered relation which-code unit-code.
which-code ::= 'known' | 'private' | integer.
unit-code ::= integer.
+
+ term-type ::= 'general' | 'numeric' | 'string' | 'oid' |
+ 'datetime' | 'null'.
</literallayout>
<para>
</para>
<para>
+ The @attr operator is followed by an attribute specification
+ (<literal>attr-spec</literal> 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).
+ </para>
+
+ <para>
+ Z39.50 version 3 defines various encoding of terms.
+ Use the @term operator to indicate the encoding type:
+ <literal>general</literal>, <literal>numeric</literal>,
+ <literal>string</literal> (for InternationalString), ..
+ If no term type has been given, the <literal>general</literal> form
+ is used which is the only encoding allowed in both version 2 - and 3
+ of the Z39.50 standard.
+ </para>
+
+ <para>
The following are all examples of valid queries in the PQF.
</para>
@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"
@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
</screen>
</sect2>
projects / yaz-moved-to-github.git / blobdiff