mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-28 14:58:55 +00:00
a84ff9e819
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@29859 c90b9560-bf6c-de11-be94-00142212c4b1
402 lines
13 KiB
XML
402 lines
13 KiB
XML
<reference id="ref.yaz">
|
|
<title>YAZ</title>
|
|
<titleabbrev>YAZ</titleabbrev>
|
|
|
|
<partintro>
|
|
<simpara>
|
|
The <function>yaz</function> functions wrap the YAZ API. The home
|
|
page of the project is <ulink url="&url.yaz;">&url.yaz;</ulink>.
|
|
Information about the phpyaz module can be found at <ulink
|
|
url="&url.yaz-phpyaz;">&url.yaz-phpyaz;</ulink>.
|
|
</simpara>
|
|
<simpara>
|
|
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.
|
|
</simpara>
|
|
<simpara>
|
|
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:
|
|
</simpara>
|
|
<informalexample>
|
|
<programlisting>
|
|
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
|
|
</programlisting>
|
|
</informalexample>
|
|
<simpara>
|
|
PHP/YAZ keeps track of connections with targets
|
|
(Z-Associations). A positive integer represents the ID of a
|
|
particular association.
|
|
</simpara>
|
|
<simpara>
|
|
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.
|
|
</simpara>
|
|
<example>
|
|
<title><function>YAZ</function></title>
|
|
<programlisting role="php">
|
|
$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>';
|
|
}
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</partintro>
|
|
|
|
<refentry id="function.yaz-addinfo">
|
|
<refnamediv>
|
|
<refname>yaz_addinfo</refname>
|
|
<refpurpose>Returns additional error information</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>yaz_addinfo</function></funcdef>
|
|
<paramdef>int <parameter>id</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.yaz-close">
|
|
<refnamediv>
|
|
<refname>yaz_close</refname>
|
|
<refpurpose>Closes a YAZ connection</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>yaz_close</function></funcdef>
|
|
<paramdef>int <parameter>id</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Closes a connection to a target. The application can no longer
|
|
refer to the target with the given id.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.yaz-connect">
|
|
<refnamediv>
|
|
<refname>yaz_connect</refname>
|
|
<refpurpose>
|
|
Returns a positive association ID on success; zero on failure
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>yaz_connect</function></funcdef>
|
|
<paramdef>string <parameter>zurl</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>Yaz_connect</function> 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
|
|
<function>yaz_wait</function> is called.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.yaz-errno">
|
|
<refnamediv>
|
|
<refname>yaz_errno</refname>
|
|
<refpurpose>Returns error number</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>yaz_errno</function></funcdef>
|
|
<paramdef>int <parameter>id</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
<function>Yaz_errno</function> should be called after network
|
|
activity for each target - (after <function>yaz_wait</function>
|
|
returns) to determine the success or failure of the last
|
|
operation (e.g. search).
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.yaz-error">
|
|
<refnamediv>
|
|
<refname>yaz_error</refname>
|
|
<refpurpose>Returns error description</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>yaz_error</function></funcdef>
|
|
<paramdef>int <parameter>id</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns error message for target (last request). An empty string
|
|
is returned if last operation was a success.
|
|
</para>
|
|
<para>
|
|
<function>Yaz_error</function> returns a english message
|
|
corresponding to the last error number as returned by
|
|
<function>yaz_errno</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.yaz-hits">
|
|
<refnamediv>
|
|
<refname>yaz_hits</refname>
|
|
<refpurpose>Returns number of hits for last search</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>yaz_hits</function></funcdef>
|
|
<paramdef>int <parameter>id</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>Yaz_hits</function> returns number of hits for last
|
|
search.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.yaz-range">
|
|
<refnamediv>
|
|
<refname>yaz_range</refname>
|
|
<refpurpose>
|
|
Specifies the maximum number of records to retrieve
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>yaz_range</function></funcdef>
|
|
<paramdef>int <parameter>id</parameter></paramdef>
|
|
<paramdef>int <parameter>start</parameter></paramdef>
|
|
<paramdef>int <parameter>number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function is used in conjunction with
|
|
<function>yaz_search</function> to specify the maximum number of
|
|
records to retrieve (number) and the first record position
|
|
(start). If this function is not invoked (only
|
|
<function>yaz_search</function>) start is set to 1 and number is
|
|
set to 10.
|
|
</para>
|
|
<para>
|
|
Returns true on success; false on error.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.yaz-record">
|
|
<refnamediv>
|
|
<refname>yaz_record</refname>
|
|
<refpurpose>Returns a record</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>yaz_record</function></funcdef>
|
|
<paramdef>int <parameter>id</parameter></paramdef>
|
|
<paramdef>int <parameter>pos</parameter></paramdef>
|
|
<paramdef>string <parameter>type</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns record at position or empty string if no record exists at
|
|
given position.
|
|
</para>
|
|
<para>
|
|
The <function>yaz_record</function> 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).
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.yaz-search">
|
|
<refnamediv>
|
|
<refname>yaz_search</refname>
|
|
<refpurpose>Prepares for a search</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>yaz_search</function></funcdef>
|
|
<paramdef>int <parameter>id</parameter></paramdef>
|
|
<paramdef>string <parameter>type</parameter></paramdef>
|
|
<paramdef>string <parameter>query</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>Yaz_search</function> 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
|
|
<function>yaz_connect</function> this function is non-blocking
|
|
and only prepares for a search to be executed later when
|
|
<function>yaz_wait</function> is called.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.yaz-syntax">
|
|
<refnamediv>
|
|
<refname>yaz_syntax</refname>
|
|
<refpurpose>
|
|
Specifies the preferred record syntax for retrieval
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>yaz_syntax</function></funcdef>
|
|
<paramdef>int <parameter>id</parameter></paramdef>
|
|
<paramdef>string <parameter>syntax</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function is used in conjunction with
|
|
<function>yaz_search</function> to specify the preferred record
|
|
syntax for retrieval.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.yaz-wait">
|
|
<refnamediv>
|
|
<refname>yaz_wait</refname>
|
|
<refpurpose>Executes queries</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>yaz_wait</function></funcdef>
|
|
<paramdef>int <parameter>id</parameter></paramdef>
|
|
<paramdef>string <parameter>syntax</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function carries out networked (blocked) activity for
|
|
outstanding requests which have been prepared by the functions
|
|
<function>yaz_connect</function>,
|
|
<function>yaz_search</function>. <function>yaz_wait</function>
|
|
returns when all targets have either completed all requests or
|
|
otherwise completed (in case of errors).
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
</reference>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"../../manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
-->
|