diff --git a/chapters.ent b/chapters.ent index 0290680222..0b80de7847 100644 --- a/chapters.ent +++ b/chapters.ent @@ -91,6 +91,7 @@ + diff --git a/functions/yaz.xml b/functions/yaz.xml new file mode 100644 index 0000000000..b87ae3e1c2 --- /dev/null +++ b/functions/yaz.xml @@ -0,0 +1,386 @@ + + Yaz + 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 + &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 modules and add + option --with-yaz. Your task is roughly the following: + + + gunzip -c yaz-1.6.tar.gz|tar xf - + gunzip -c php-4.0.X.tar.gz|tar xf - + cd yaz-1.6 + ./configure --prefix=/usr + make + make install + cd ../php-4.0.X + ./configure --with-yaz=/usr/bin + make + make install + + + + + 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. + + + <function>readline</function> + +$num_hosts = count($host); +if (empty($term) || count($host) == 0) +{ + echo '<form method="get"> + <input type="checkbox" + name="host[]" value="bagel.indexdata.dk/gils"> + GILS test + <input type="checkbox" + name="host[]" value="localhost:9999/Default"> + local test + <input type="checkbox" checked="1" + name="host[]" value="z3950.bell-labs.com/books"> + BELL Labs Library + <br> + RPN Query: + <input type="text" size="30" name="term"> + <input type="submit" name="action" value="Search"> + '; +} +else +{ + echo 'You searced for ' . htmlspecialchars($term) . '<br>'; + for ($i = 0; $i > $num_hosts; $i++) { + $id[] = yaz_connect($host[$i]); + yaz_syntax($id[$i],"sutrs"); + yaz_search($id[$i],"rpn",$term); + } + yaz_wait(); + for ($i = 0; $i < $num_hosts; $i++) + { + echo '<hr>' . $host[$i] . ":"; + $error = yaz_error($id[$i]); + if (!empty($error)) { + echo "Error: $error"; + } else { + $hits = yaz_hits($id[$i]); + echo "Result Count $hits"; + } + echo '<dl>'; + for ($p = 1; $p <= 10; $p++) + { + $rec = yaz_record($id[$i],$p,"string"); + if (empty($rec)) continue; + echo "<dt><b>$p</b></dt><dd>"; + echo ereg_replace("\n", "<br>\n",$rec); + echo "</dd>"; + } + echo '</dl>'; + } +} + + + + + + + yaz_addinfo + Returns additional error information. + + + Description + + + int yaz_addinfo + int id + + + + Returns additional error message for target (last request). An empty string + is returned if last operation was a success or if no additional information + was provided by the target. + + + + + + + yaz_close + Closes a YAZ connection. + + + Description + + + int yaz_close + int id + + + + Closes a connection to a target. The application can no longer refer to the + target with the given id. + + + + + + + yaz_connect + Returns a positive association ID on success; zero on failure. + + + Description + + + int yaz_connect + string zurl + + + + yaz_connect prepares for a connection to a Z39.50 + target. The zurl argument takes the form host[:port][/database]. If port is + omitted 210 is used. If database is omitted Default is used. This function + is non-blocking and doesn't attempt to establish a socket - it merely + prepares a connect to be performed later when yaz_wait + is called. + + + + + + + yaz_errno + Returns error number. + + + Description + + + int yaz_errno + int id + + + + Returns error for target (last request). A positive value is returned if + the target returned a diagnostic code; a value of zero is returned if no + errors occurred (success); negative value is returned for other errors + targets didn't indicate the error in question. + + + yaz_errno should be called after network activity for + each target - (after yaz_wait returns) to determine + the success or failure of the last operation (e.g. search). + + + + + + + yaz_error + Returns error description. + + + Description + + + int yaz_error + int id + + + + Returns error message for target (last request). An empty string is + returned if last operation was a success. + + + yaz_error returns a english message corresponding to + the last error number as returned by yaz_errno. + + + + + + + yaz_hits + Returns number of hits for last search. + + + Description + + + int yaz_hits + int id + + + + yaz_hits returns number of hits for last search. + + + + + + + yaz_range + Specifies the maximum number of records to retrieve. + + + Description + + + int yaz_range + int id + int start + int number + + + + This function is used in conjunction with yaz_search + to specify the maximum number of records to retrieve (number) and the first + record position (start). If this function is not invoked (only + yaz_search) start is set to 1 and number is set to 10. + + + Returns true on success; false on error. + + + + + + + yaz_record + Returns a record. + + + Description + + + int yaz_record + int id + int pos + string type + + + + Returns record at position or empty string if no record exists at given + position. + + + The yaz_record function inspects a record in the + current result set at the position specified. If no database record exists + at the given position an empty string is returned. The argument, type, + specifies the form of the returned record. If type is "string" the record + is returned in a string representation suitable for printing (for XML and + SUTRS). If type is "array" the record is returned as an array + representation (for structured records). + + + + + + + yaz_search + Prepares for a search. + + + Description + + + int yaz_search + int id + string type + string query + + + + 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. + + + + + + + yaz_syntax + Specifies the preferred record syntax for retrieval. + + + Description + + + int yaz_syntax + int id + string syntax + + + + This function is used in conjunction with yaz_search + to specify the preferred record syntax for retrieval. + + + + + + + yaz_wait + Executes queries. + + + Description + + + int yaz_wait + int id + string syntax + + + + This function carries out networked (blocked) activity for outstanding + requests which have been prepared by the functions + yaz_connect, yaz_search. + yaz_wait returns when all targets have either + completed all requests or otherwise completed (in case of errors). + + + + + +