From 3c6f9a47c9c804a184b4ea0d4f0d74b25a792e56 Mon Sep 17 00:00:00 2001 From: Adam Dickmeiss Date: Mon, 18 Sep 2000 17:32:37 +0000 Subject: [PATCH] Improved introduction of YAZ extension. Added more information about Z39.50 Type-1 queries. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@32787 c90b9560-bf6c-de11-be94-00142212c4b1 --- functions/yaz.xml | 173 ++++++++++++++++++++++++++++++++++++---------- 1 file changed, 137 insertions(+), 36 deletions(-) diff --git a/functions/yaz.xml b/functions/yaz.xml index b7b6abd071..1a397a8274 100644 --- a/functions/yaz.xml +++ b/functions/yaz.xml @@ -1,29 +1,38 @@ - YAZ + YAZ functions YAZ - - - The yaz functions wrap the YAZ API. The home - page of the project is &url.yaz;. - Information about the phpyaz module can be found at + Introduction + + This extension offers a PHP interface to the + YAZ toolkit that implements the Z39.50 + protocol for information retrieval. With this extension you can easily + implement a Z39.50 origin (client) that searches Z39.50 targets + (servers) in parallel. + + + YAZ is available at &url.yaz;. You can find news information, + example scripts, etc. for this extension at &url.yaz-phpyaz;. - - - PHP/YAZ is much simpler to use than the C API for YAZ but less - flexible. The intent is to make it easy to build basic client - functions. It supports persistent stateless connections very - similar to those offered by the various SQL APIs that are - available for PHP. This means that sessions are stateless but - shared amongst users, thus saving the connect and INIT steps in - many cases. - - - Before compiling PHP with the PHP/YAZ module you'll need the YAZ - toolkit. Build YAZ and install it. Build PHP with your favourite + + + The module hides most of the complexity of Z39.50 so it should be + fairly easy to use. It supports persistent stateless connections very + similar to those offered by the various SQL APIs that are available + for PHP. This means that sessions are stateless but shared amongst + users, thus saving the connect and initialize phase steps in most cases. + + + + Installation + + Compile YAZ and install it. Build PHP with your favourite modules and add option --with-yaz. Your task is roughly the following: - + + gunzip -c yaz-1.6.tar.gz|tar xf - @@ -38,17 +47,22 @@ make make install - + + + + Example + PHP/YAZ keeps track of connections with targets (Z-Associations). A positive integer represents the ID of a particular association. - - + + The script below demonstrates the parallel searching feature of - the API. When invoked it either prints a query form (if no - arguments are supplied) or if there are arguments (term and one or - more hosts) it searches the targets in array host. - + the API. When invoked with no arguments it prints a query form; else + (arguments are supplied) it searches the targets as given in in array + host. + + <function>YAZ</function> @@ -71,7 +85,7 @@ if (empty($term) || count($host) == 0) { '; } else { echo 'You searced for ' . htmlspecialchars($term) . '<br>'; - for ($i = 0; $i > $num_hosts; $i++) { + for ($i = 0; $i < $num_hosts; $i++) { $id[] = yaz_connect($host[$i]); yaz_syntax($id[$i],"sutrs"); yaz_search($id[$i],"rpn",$term); @@ -99,6 +113,8 @@ if (empty($term) || count($host) == 0) { } + + @@ -137,7 +153,7 @@ if (empty($term) || count($host) == 0) { Closes a connection to a target. The application can no longer - refer to the target with the given id. + refer to the target with the given ID. @@ -322,13 +338,94 @@ if (empty($term) || count($host) == 0) { - Yaz_search prepares for a search on the + yaz_search prepares for a search on the target with given id. The type represents the query type - only - "rpn" is supported now in which case the third argument is a - prefix notation query as used by YAZ. Like - yaz_connect this function is non-blocking - and only prepares for a search to be executed later when - yaz_wait is called. + "rpn" is supported now in which case the third argument specifies + a Type-1 query (RPN). Like yaz_connect this + function is non-blocking and only prepares for a search to be + executed later when yaz_wait is called. + + + + The RPN query + + The RPN query is a textual represenation of the Type-1 query as + defined by the Z39.50 standard. However, in the text representation + as used by YAZ a prefix notation is used, that is the operater + precedes the operands. The query string is a sequence of tokens where + white space is ignored is ignored unless surrounded by double + quotes. Tokens beginning with an at-character (@) + are considered operators, otherwise they are treated as search terms. + + + RPN Operators + + + + Syntax + Description + + + + + @and query1 query2 + intersection of query1 and query2 + + + @or query1 query2 + union of query1 and query2 + + + @not query1 query2 + query1 and not query2 + + + @set name + result set reference + + + @attrset set query + specifies attribute-set for query. This construction is only + allowed once - in the beginning of the whole query + + + @attr set type=value query + applies attribute to query. The type and value are + integers specifying the attribute-type and attribute-value + respectively. The set, if given, specifies the + attribute-set. + + + +
+ + The following illustrates valid query constructions: + + computer + + Matches documents where "computer" occur. No attributes are specified. + + + + "donald knuth" + + Matches documents where "donald knuth" occur. + + + + @attr 1=4 art + + Attribute type is 1 (Bib-1 use), attribute value is 4 + Title), so this should match documents where "art" occur + in the title. + + + +@attrset gils @and @attr 1=4 art @attr 1=1003 "donald knuth" + + The query as a whole uses the GILS attributeset. The query matches + documents where "art" occur in the title and in which "donald knuth" + occur in the author. @@ -337,7 +434,8 @@ if (empty($term) || count($host) == 0) { yaz_syntax - Specifies the preferred record syntax for retrieval + Specifies the object identifier (OID) for the preferred record syntax + for retrieval. @@ -350,6 +448,9 @@ if (empty($term) || count($host) == 0) { + The syntax may be specified in a raw dot-notation (like + 1.2.840.10003.5.10) or as one of the known + record syntaxes (sutrs, usmarc, grs1, xml, etc.). This function is used in conjunction with yaz_search to specify the preferred record syntax for retrieval.