 |
 |
 |
 |
|
|
Date: 08/07/00
- Next message: Egon Schmid: "[PHP-DOC] cvs: phpdoc /en/functions yaz.xml"
- Previous message: Rasmus Lerdorf: "[PHP-DOC] cvs: phpdoc / manual.xml.in"
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
leon Mon Aug 7 13:15:13 2000 EDT
Added files:
/phpdoc/en/functions yaz.xml
Modified files:
/phpdoc global.ent manual.xml.in
/phpdoc/en chapters.ent
Log:
YAZ documentation.
Index: phpdoc/global.ent
diff -u phpdoc/global.ent:1.41 phpdoc/global.ent:1.42
--- phpdoc/global.ent:1.41 Sun Aug 6 13:29:23 2000
+++ phpdoc/global.ent Mon Aug 7 13:15:12 2000
@@ -1,6 +1,6 @@
<!-- -*- SGML -*-
- $Id: global.ent,v 1.41 2000/08/06 20:29:23 sniper Exp $
+ $Id: global.ent,v 1.42 2000/08/07 20:15:12 leon Exp $
Contains global "macros" for all the SGML documents.
@@ -99,6 +99,8 @@
<!ENTITY url.wddx "http://www.wddx.org/">
<!ENTITY url.xemacs "http://www.xemacs.org/">
<!ENTITY url.xml "http://www.w3.org/XML/">
+<!ENTITY url.yaz "http://www.indexdata.dk/yaz/">
+<!ENTITY url.yaz-phpyaz "http://www.indexdata.dk/phpyaz/">
<!ENTITY url.zend "http://www.zend.com/">
<!ENTITY url.zlib "http://www.cdrom.com/pub/infozip/zlib/">
Index: phpdoc/manual.xml.in
diff -u phpdoc/manual.xml.in:1.20 phpdoc/manual.xml.in:1.21
--- phpdoc/manual.xml.in:1.20 Mon Aug 7 12:19:39 2000
+++ phpdoc/manual.xml.in Mon Aug 7 13:15:12 2000
@@ -161,6 +161,7 @@
&reference.vmailmgr;
&reference.wddx;
&reference.xml;
+ &reference.yaz;
&reference.nis;
&reference.zlib;
</part>
Index: phpdoc/en/chapters.ent
diff -u phpdoc/en/chapters.ent:1.13 phpdoc/en/chapters.ent:1.14
--- phpdoc/en/chapters.ent:1.13 Mon Aug 7 12:02:59 2000
+++ phpdoc/en/chapters.ent Mon Aug 7 13:15:13 2000
@@ -91,6 +91,7 @@
<!ENTITY reference.var SYSTEM "functions/var.xml">
<!ENTITY reference.vmailmgr SYSTEM "functions/vmailmgr.xml">
<!ENTITY reference.wddx SYSTEM "functions/wddx.xml">
+<!ENTITY reference.yaz SYSTEM "functions/yaz.xml">
<!ENTITY reference.zlib SYSTEM "functions/zlib.xml">
<!ENTITY reference.xml SYSTEM "functions/xml.xml">
Index: phpdoc/en/functions/yaz.xml
+++ phpdoc/en/functions/yaz.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:
<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>
<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>readline</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:
-->
- Next message: Egon Schmid: "[PHP-DOC] cvs: phpdoc /en/functions yaz.xml"
- Previous message: Rasmus Lerdorf: "[PHP-DOC] cvs: phpdoc / manual.xml.in"
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]