dickmeiss Thu Jan 16 04:44:50 2003 EDT
Added files:
/phpdoc/en/reference/yaz/functions yaz-get-option.xml
yaz-schema.xml
yaz-set-option.xml
Modified files:
/phpdoc/en/reference/yaz configure.xml reference.xml
/phpdoc/en/reference/yaz/functions yaz-addinfo.xml yaz-ccl-conf.xml
yaz-ccl-parse.xml yaz-close.xml
yaz-connect.xml yaz-database.xml
yaz-element.xml yaz-errno.xml
yaz-error.xml yaz-itemorder.xml
yaz-present.xml yaz-range.xml
yaz-record.xml
yaz-scan-result.xml yaz-scan.xml
yaz-search.xml yaz-sort.xml
yaz-syntax.xml
Log:
Documentation of yaz_set_option, yaz_get_option and yaz_schema.
More examples for searching as well as CCL. Pointers to
More Z39.50 related links. Connection ID is resource - rather than
integer.
Index: phpdoc/en/reference/yaz/configure.xml
diff -u phpdoc/en/reference/yaz/configure.xml:1.2
phpdoc/en/reference/yaz/configure.xml:1.3
--- phpdoc/en/reference/yaz/configure.xml:1.2 Fri Jan 10 20:15:30 2003
+++ phpdoc/en/reference/yaz/configure.xml Thu Jan 16 04:44:49 2003
@@ -1,10 +1,10 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<section id="yaz.installation">
&reftitle.install;
<para>
- Compile YAZ (ANSI/NISO Z39.50) and install it. Build PHP with your favourite
- modules and add option
+ Compile YAZ (ANSI/NISO Z39.50 support) and install it.
+ Build PHP with your favourite modules and add option
<option role="configure">--with-yaz[=DIR]</option>.
Your task is roughly the following:
</para>
@@ -12,13 +12,13 @@
<informalexample>
<programlisting role="shell">
<![CDATA[
-gunzip -c yaz-1.6.tar.gz|tar xf -
-gunzip -c php-4.0.X.tar.gz|tar xf -
-cd yaz-1.6
+gunzip -c php-4.3.X.tar.gz|tar xf -
+gunzip -c yaz-1.9.Y.tar.gz|tar xf -
+cd yaz-1.9.Y
./configure --prefix=/usr
make
make install
-cd ../php-4.0.X
+cd ../php-4.3.X.
./configure --with-yaz=/usr/bin
make
make install
Index: phpdoc/en/reference/yaz/reference.xml
diff -u phpdoc/en/reference/yaz/reference.xml:1.5
phpdoc/en/reference/yaz/reference.xml:1.6
--- phpdoc/en/reference/yaz/reference.xml:1.5 Mon Dec 2 07:55:45 2002
+++ phpdoc/en/reference/yaz/reference.xml Thu Jan 16 04:44:49 2003
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.5 $ -->
+<!-- $Revision: 1.6 $ -->
<reference id="ref.yaz">
<title>YAZ functions</title>
<titleabbrev>YAZ</titleabbrev>
@@ -9,15 +9,16 @@
&reftitle.intro;
<para>
This extension offers a PHP interface to the
- <productname>YAZ</productname> toolkit that implements the Z39.50
- protocol for information retrieval. With this extension you can easily
- implement a Z39.50 origin (client) that searches or scans Z39.50
- targets (servers) in parallel.
+ <productname>YAZ</productname> toolkit that implements the
+ <ulink url="&url.yaz-loc;">Z39.50
+ Protocol for Information Retrieval</ulink>.
+ With this extension you can easily implement a Z39.50 origin (client)
+ that searches or scans Z39.50 targets (servers) in parallel.
</para>
<para>
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
+ similar to those offered by the various RDB 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.
@@ -48,8 +49,8 @@
&reftitle.examples;
<para>
PHP/YAZ keeps track of connections with targets
- (Z-Associations). A positive integer represents the ID of a
- particular association.
+ (Z-Associations). A resource represents a connection to a
+ target.
</para>
<para>
<example>
@@ -57,8 +58,8 @@
<simpara>
The script below demonstrates the parallel searching feature of
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.
+ (arguments are supplied) it searches the targets as given in array
+ <literal>host</literal>.
</simpara>
<programlisting role="php">
<![CDATA[
@@ -72,8 +73,8 @@
name="host[]" value="localhost:9999/Default">
local test
<input type="checkbox" checked="1"
- name="host[]" value="z3950.bell-labs.com/books">
- BELL Labs Library
+ name="host[]" value="z3950.loc.gov:7090/voyager">
+ Library of Congress
<br>
RPN Query:
<input type="text" size="30" name="term">
@@ -83,7 +84,7 @@
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_range($id[$i], 1, 10);
yaz_search($id[$i],"rpn",$term);
}
yaz_wait();
Index: phpdoc/en/reference/yaz/functions/yaz-addinfo.xml
diff -u phpdoc/en/reference/yaz/functions/yaz-addinfo.xml:1.2
phpdoc/en/reference/yaz/functions/yaz-addinfo.xml:1.3
--- phpdoc/en/reference/yaz/functions/yaz-addinfo.xml:1.2 Wed Apr 17 02:45:26
2002
+++ phpdoc/en/reference/yaz/functions/yaz-addinfo.xml Thu Jan 16 04:44:49 2003
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.1 -->
<refentry id="function.yaz-addinfo">
<refnamediv>
@@ -9,8 +9,8 @@
<refsect1>
<title>Description</title>
<methodsynopsis>
- <type>int</type><methodname>yaz_addinfo</methodname>
- <methodparam><type>int</type><parameter>id</parameter></methodparam>
+ <type>string</type><methodname>yaz_addinfo</methodname>
+ <methodparam><type>resource</type><parameter>id</parameter></methodparam>
</methodsynopsis>
<para>
Returns additional error message for target (last request). An
Index: phpdoc/en/reference/yaz/functions/yaz-ccl-conf.xml
diff -u phpdoc/en/reference/yaz/functions/yaz-ccl-conf.xml:1.2
phpdoc/en/reference/yaz/functions/yaz-ccl-conf.xml:1.3
--- phpdoc/en/reference/yaz/functions/yaz-ccl-conf.xml:1.2 Wed Apr 17 02:45:26
2002
+++ phpdoc/en/reference/yaz/functions/yaz-ccl-conf.xml Thu Jan 16 04:44:49 2003
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.8 -->
<refentry id="function.yaz-ccl-conf">
<refnamediv>
@@ -10,7 +10,7 @@
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>yaz_ccl_conf</methodname>
- <methodparam><type>int</type><parameter>id</parameter></methodparam>
+ <methodparam><type>resource</type><parameter>id</parameter></methodparam>
<methodparam><type>array</type><parameter>config</parameter></methodparam>
</methodsynopsis>
<para>
@@ -32,15 +32,15 @@
In the example below, the CCL parser is configured to support
three CCL fields: <literal>ti</literal>, <literal>au</literal> and
<literal>isbn</literal>. Each field is mapped to their BIB-1
- equivalent. It is assumed that variable <literal>$id</literal> is a
- target ID.
+ equivalent. It is assumed that variable <literal>$id</literal> is the
+ connection ID.
</simpara>
<programlisting>
<![CDATA[
- $field["ti"] = "1=4";
- $field["au"] = "1=1";
- $field["isbn"] = "1=7";
- yaz_ccl_conf($id,$field);
+$fields["ti"] = "1=4";
+$fields["au"] = "1=1";
+$fields["isbn"] = "1=7";
+yaz_ccl_conf($id,$fields);
]]>
</programlisting>
</example>
Index: phpdoc/en/reference/yaz/functions/yaz-ccl-parse.xml
diff -u phpdoc/en/reference/yaz/functions/yaz-ccl-parse.xml:1.2
phpdoc/en/reference/yaz/functions/yaz-ccl-parse.xml:1.3
--- phpdoc/en/reference/yaz/functions/yaz-ccl-parse.xml:1.2 Wed Apr 17 02:45:26
2002
+++ phpdoc/en/reference/yaz/functions/yaz-ccl-parse.xml Thu Jan 16 04:44:49 2003
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.1 -->
<refentry id="function.yaz-ccl-parse">
<refnamediv>
@@ -10,12 +10,12 @@
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>yaz_ccl_parse</methodname>
- <methodparam><type>int</type><parameter>id</parameter></methodparam>
+ <methodparam><type>resource</type><parameter>id</parameter></methodparam>
<methodparam><type>string</type><parameter>query</parameter></methodparam>
<methodparam><type>array &</type><parameter>result</parameter></methodparam>
</methodsynopsis>
<para>
- This function invokes the CCL parser. It converts a given
+ This function invokes a CCL parser. It converts a given
CCL FIND query to an RPN query which may be passed to the
<function>yaz_search</function> function to perform a search.
To define a set of valid CCL fields call
@@ -32,6 +32,23 @@
<literal>errorpos</literal>approximate position in query of failure
(integer is character position).
</para>
+ <example>
+ <title>CCL Parsing</title>
+ <para>We'll try to search using CCL. In the example below,
+ <literal>$ccl</literal> is a CCL query.
+ </para>
+ <programlisting>
+<![CDATA[
+yaz_ccl_conf($id,$fields); // see example for yaz_ccl_conf
+if (!yaz_ccl_parse($id, $ccl, &$cclresult) {
+ echo 'Error: ' . $cclresult["errorstring"];
+} else {
+ $rpn = $cclresult["rpn"];
+ yaz_search($id,"rpn",$rpn);
+}
+]]>
+ </programlisting>
+ </example>
</refsect1>
</refentry>
Index: phpdoc/en/reference/yaz/functions/yaz-close.xml
diff -u phpdoc/en/reference/yaz/functions/yaz-close.xml:1.2
phpdoc/en/reference/yaz/functions/yaz-close.xml:1.3
--- phpdoc/en/reference/yaz/functions/yaz-close.xml:1.2 Wed Apr 17 02:45:27 2002
+++ phpdoc/en/reference/yaz/functions/yaz-close.xml Thu Jan 16 04:44:49 2003
@@ -1,21 +1,21 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.1 -->
<refentry id="function.yaz-close">
<refnamediv>
<refname>yaz_close</refname>
- <refpurpose>Closes a YAZ connection</refpurpose>
+ <refpurpose>Close YAZ connection</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>yaz_close</methodname>
- <methodparam><type>int</type><parameter>id</parameter></methodparam>
+ <methodparam><type>resource</type><parameter>id</parameter></methodparam>
</methodsynopsis>
<para>
- Closes the Z-association given by <parameter>id</parameter>.
- The <parameter>id</parameter> is a target ID as returned by a
- previous <function>yaz_connect</function> command.
+ Closes connection given by <parameter>id</parameter>.
+ The <parameter>id</parameter> is a connection resource as returned
+ by a previous <function>yaz_connect</function> call.
</para>
</refsect1>
</refentry>
Index: phpdoc/en/reference/yaz/functions/yaz-connect.xml
diff -u phpdoc/en/reference/yaz/functions/yaz-connect.xml:1.2
phpdoc/en/reference/yaz/functions/yaz-connect.xml:1.3
--- phpdoc/en/reference/yaz/functions/yaz-connect.xml:1.2 Wed Apr 17 02:45:27
2002
+++ phpdoc/en/reference/yaz/functions/yaz-connect.xml Thu Jan 16 04:44:49 2003
@@ -1,31 +1,31 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.1 -->
<refentry id="function.yaz-connect">
<refnamediv>
<refname>yaz_connect</refname>
<refpurpose>
- Prepares for a connection and Z-association to a Z39.50 target.
+ Prepares for a connection to a Z39.50 target (server).
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
- <type>int</type><methodname>yaz_connect</methodname>
+ <type>resource</type><methodname>yaz_connect</methodname>
<methodparam><type>string</type><parameter>zurl</parameter></methodparam>
<methodparam
choice="opt"><type>mixed</type><parameter>options</parameter></methodparam>
</methodsynopsis>
<para>
- This function returns a positive ID on success; zero on
+ This function returns a connection resource on success; zero on
failure.
</para>
<para>
<function>yaz_connect</function> prepares for a connection to a
- Z39.50 target. The zurl argument takes the form
+ Z39.50 target. The <parameter>zurl</parameter> 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
+ database is omitted <literal>Default</literal> 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>
<para>
@@ -77,6 +77,12 @@
</varlistentry>
</variablelist>
</para>
+ <note>
+ <para>The use of a proxy often improves performance. A Z39.50 proxy
+ is part of the free <ulink url="&url.yaz-proxy;">YAZ++</ulink>
+ package.
+ </para>
+ </note>
</refsect1>
</refentry>
Index: phpdoc/en/reference/yaz/functions/yaz-database.xml
diff -u phpdoc/en/reference/yaz/functions/yaz-database.xml:1.2
phpdoc/en/reference/yaz/functions/yaz-database.xml:1.3
--- phpdoc/en/reference/yaz/functions/yaz-database.xml:1.2 Wed Apr 17 02:45:27
2002
+++ phpdoc/en/reference/yaz/functions/yaz-database.xml Thu Jan 16 04:44:49 2003
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.7 -->
<refentry id="function.yaz-database">
<refnamediv>
@@ -12,7 +12,7 @@
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>yaz_database</methodname>
- <methodparam><type>int</type><parameter>id</parameter></methodparam>
+ <methodparam><type>resource</type><parameter>id</parameter></methodparam>
<methodparam><type>string</type><parameter>databases</parameter></methodparam>
</methodsynopsis>
<para>
Index: phpdoc/en/reference/yaz/functions/yaz-element.xml
diff -u phpdoc/en/reference/yaz/functions/yaz-element.xml:1.2
phpdoc/en/reference/yaz/functions/yaz-element.xml:1.3
--- phpdoc/en/reference/yaz/functions/yaz-element.xml:1.2 Wed Apr 17 02:45:27
2002
+++ phpdoc/en/reference/yaz/functions/yaz-element.xml Thu Jan 16 04:44:49 2003
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.11 -->
<refentry id="function.yaz-element">
<refnamediv>
@@ -12,15 +12,16 @@
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>yaz_element</methodname>
- <methodparam><type>int</type><parameter>id</parameter></methodparam>
+ <methodparam><type>resource</type><parameter>id</parameter></methodparam>
<methodparam><type>string</type><parameter>elementset</parameter></methodparam>
</methodsynopsis>
<para>
- This function is used in conjunction with
- <function>yaz_search</function> and <function>yaz_present</function>
+ This function sets the element set name for retrieval.
+ Call this function before <function>yaz_search</function> or
+ <function>yaz_present</function>
to specify the element set name for records to be retrieved.
- Most servers support <literal>F</literal> (full) and
- <literal>B</literal> (brief).
+ Most servers support <literal>F</literal> (for full records) and
+ <literal>B</literal> (for brief records).
</para>
<para>
Returns &true; on success; &false; on error.
Index: phpdoc/en/reference/yaz/functions/yaz-errno.xml
diff -u phpdoc/en/reference/yaz/functions/yaz-errno.xml:1.2
phpdoc/en/reference/yaz/functions/yaz-errno.xml:1.3
--- phpdoc/en/reference/yaz/functions/yaz-errno.xml:1.2 Wed Apr 17 02:45:27 2002
+++ phpdoc/en/reference/yaz/functions/yaz-errno.xml Thu Jan 16 04:44:49 2003
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.1 -->
<refentry id="function.yaz-errno">
<refnamediv>
@@ -10,20 +10,20 @@
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>yaz_errno</methodname>
- <methodparam><type>int</type><parameter>id</parameter></methodparam>
+ <methodparam><type>resource</type><parameter>id</parameter></methodparam>
</methodsynopsis>
<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 (such as when the target
- closed connection, etc).
+ Returns error for target (last request). The error code is either
+ a Z39.50 diagnostic code (usually a Bib-1 diagnostic) or a
+ client side error code which is generated by PHP/YAZ itself, such
+ as "Connect failed", "Init Rejected", etc.
</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).
+ operation (e.g. search). To get a text description of the
+ error, call <function>yaz_error</function>.
</para>
</refsect1>
</refentry>
Index: phpdoc/en/reference/yaz/functions/yaz-error.xml
diff -u phpdoc/en/reference/yaz/functions/yaz-error.xml:1.2
phpdoc/en/reference/yaz/functions/yaz-error.xml:1.3
--- phpdoc/en/reference/yaz/functions/yaz-error.xml:1.2 Wed Apr 17 02:45:27 2002
+++ phpdoc/en/reference/yaz/functions/yaz-error.xml Thu Jan 16 04:44:49 2003
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.1 -->
<refentry id="function.yaz-error">
<refnamediv>
@@ -10,10 +10,10 @@
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>yaz_error</methodname>
- <methodparam><type>int</type><parameter>id</parameter></methodparam>
+ <methodparam><type>resource</type><parameter>id</parameter></methodparam>
</methodsynopsis>
<para>
- Returns error message for target (last request). An empty string
+ Returns error text message for target (last request). An empty string
is returned if last operation was a success.
</para>
<para>
Index: phpdoc/en/reference/yaz/functions/yaz-itemorder.xml
diff -u phpdoc/en/reference/yaz/functions/yaz-itemorder.xml:1.3
phpdoc/en/reference/yaz/functions/yaz-itemorder.xml:1.4
--- phpdoc/en/reference/yaz/functions/yaz-itemorder.xml:1.3 Sun Dec 1 21:21:13
2002
+++ phpdoc/en/reference/yaz/functions/yaz-itemorder.xml Thu Jan 16 04:44:49 2003
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.8 -->
<refentry id="function.yaz-itemorder">
<refnamediv>
@@ -12,6 +12,7 @@
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>yaz_itemorder</methodname>
+ <methodparam><type>resource</type><parameter>id</parameter></methodparam>
<methodparam><type>array</type><parameter>args</parameter></methodparam>
</methodsynopsis>
<para>
Index: phpdoc/en/reference/yaz/functions/yaz-present.xml
diff -u phpdoc/en/reference/yaz/functions/yaz-present.xml:1.2
phpdoc/en/reference/yaz/functions/yaz-present.xml:1.3
--- phpdoc/en/reference/yaz/functions/yaz-present.xml:1.2 Wed Apr 17 02:45:27
2002
+++ phpdoc/en/reference/yaz/functions/yaz-present.xml Thu Jan 16 04:44:49 2003
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.8 -->
<refentry id="function.yaz-present">
<refnamediv>
@@ -12,7 +12,7 @@
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>yaz_present</methodname>
- <void/>
+ <methodparam><type>resource</type><parameter>id</parameter></methodparam>
</methodsynopsis>
<para>
This function prepares for retrieval of records after
Index: phpdoc/en/reference/yaz/functions/yaz-range.xml
diff -u phpdoc/en/reference/yaz/functions/yaz-range.xml:1.2
phpdoc/en/reference/yaz/functions/yaz-range.xml:1.3
--- phpdoc/en/reference/yaz/functions/yaz-range.xml:1.2 Wed Apr 17 02:45:27 2002
+++ phpdoc/en/reference/yaz/functions/yaz-range.xml Thu Jan 16 04:44:49 2003
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.1 -->
<refentry id="function.yaz-range">
<refnamediv>
@@ -12,17 +12,18 @@
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>yaz_range</methodname>
- <methodparam><type>int</type><parameter>id</parameter></methodparam>
+ <methodparam><type>resource</type><parameter>id</parameter></methodparam>
<methodparam><type>int</type><parameter>start</parameter></methodparam>
<methodparam><type>int</type><parameter>number</parameter></methodparam>
</methodsynopsis>
<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.
+ This function should be called before either
+ <function>yaz_search</function> or <function>yaz_present</function>
+ to specify a range of records to be retrieved.
+ The <parameter>start</parameter> specifies position of first record
+ to be retrieved and <parameter>number</parameter> is the number
+ records. Records in a result set are numbered 1, 2, ... $hits where
+ $hits is the count returned by <function>yaz_hits</function>.
</para>
<para>
Returns &true; on success; &false; on error.
Index: phpdoc/en/reference/yaz/functions/yaz-record.xml
diff -u phpdoc/en/reference/yaz/functions/yaz-record.xml:1.2
phpdoc/en/reference/yaz/functions/yaz-record.xml:1.3
--- phpdoc/en/reference/yaz/functions/yaz-record.xml:1.2 Wed Apr 17 02:45:28
2002
+++ phpdoc/en/reference/yaz/functions/yaz-record.xml Thu Jan 16 04:44:49 2003
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.1 -->
<refentry id="function.yaz-record">
<refnamediv>
@@ -9,24 +9,35 @@
<refsect1>
<title>Description</title>
<methodsynopsis>
- <type>int</type><methodname>yaz_record</methodname>
- <methodparam><type>int</type><parameter>id</parameter></methodparam>
+ <type>string</type><methodname>yaz_record</methodname>
+ <methodparam><type>resource</type><parameter>id</parameter></methodparam>
<methodparam><type>int</type><parameter>pos</parameter></methodparam>
<methodparam><type>string</type><parameter>type</parameter></methodparam>
</methodsynopsis>
<para>
- Returns record at position or empty string if no record exists at
- given position.
+ Returns record at position <parameter>pos</parameter> 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).
+ returned. The <parameter>type</parameter> specifies the form of
+ the returned record.
+ </para>
+ <para>
+ If type is <literal>"string"</literal> the record is
+ returned in a string representation suitable for printing
+ (for XML and SUTRS).
+ If <parameter>type</parameter> is <literal>"array"</literal>
+ the record is returned as an array representation (for structured
+ records).
+ If <parameter>type</parameter> is <literal>"raw"</literal> the
+ record is returned in its original raw form.
+ </para>
+ <para>
+ Records in a result set are numbered 1, 2, ... $hits where
+ $hits is the count returned by <function>yaz_hits</function>.
</para>
</refsect1>
</refentry>
Index: phpdoc/en/reference/yaz/functions/yaz-scan-result.xml
diff -u phpdoc/en/reference/yaz/functions/yaz-scan-result.xml:1.2
phpdoc/en/reference/yaz/functions/yaz-scan-result.xml:1.3
--- phpdoc/en/reference/yaz/functions/yaz-scan-result.xml:1.2 Wed Apr 17 02:45:28
2002
+++ phpdoc/en/reference/yaz/functions/yaz-scan-result.xml Thu Jan 16 04:44:49
+2003
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.8 -->
<refentry id="function.yaz-scan-result">
<refnamediv>
@@ -10,12 +10,13 @@
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>yaz_scan_result</methodname>
- <methodparam><type>int</type><parameter>id</parameter></methodparam>
+ <methodparam><type>resource</type><parameter>id</parameter></methodparam>
<methodparam choice="opt"><type>array
&</type><parameter>result</parameter></methodparam>
</methodsynopsis>
<para>
- Given a target ID this function returns and array with terms as received
- from the target in the last Scan Response.
+ <function>yaz_scan_result</function> returns terms and associated
+ information as received from the target in the last performed
+ <function>yaz_scan</function>.
This function returns an array (0..n-1) where n is the number
of terms returned. Each value is a pair where first item is
term, second item is result-count.
Index: phpdoc/en/reference/yaz/functions/yaz-scan.xml
diff -u phpdoc/en/reference/yaz/functions/yaz-scan.xml:1.2
phpdoc/en/reference/yaz/functions/yaz-scan.xml:1.3
--- phpdoc/en/reference/yaz/functions/yaz-scan.xml:1.2 Wed Apr 17 02:45:28 2002
+++ phpdoc/en/reference/yaz/functions/yaz-scan.xml Thu Jan 16 04:44:49 2003
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.8 -->
<refentry id="function.yaz-scan">
<refnamediv>
@@ -10,14 +10,14 @@
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>yaz_scan</methodname>
- <methodparam><type>int</type><parameter>id</parameter></methodparam>
+ <methodparam><type>resource</type><parameter>id</parameter></methodparam>
<methodparam><type>string</type><parameter>type</parameter></methodparam>
<methodparam><type>string</type><parameter>startterm</parameter></methodparam>
<methodparam
choice="opt"><type>array</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
This function prepares for a Z39.50 Scan Request. Argument
- <parameter>id</parameter> specifies target ID. Starting term
+ <parameter>id</parameter> specifies connection. Starting term
point for the scan is given by <parameter>startterm</parameter>.
The form in which is the starting term is specified is given by
<parameter>type</parameter>. Currently type <literal>rpn</literal>
@@ -44,29 +44,28 @@
<title>PHP function that scans titles</title>
<programlisting>
<![CDATA[
- function scan_titles($id, $starterm) {
- yaz_scan($id,"rpn", "@attr 1=4 " . $starterm);
- yaz_wait();
- $errno = yaz_errno($id);
- if ($errno == 0) {
- $ar = yaz_scan_result($id,&$options);
- echo 'Scan ok; ';
- $ar = yaz_scan_result($id, &$options);
- while(list($key,$val)=each($options)) {
- echo "$key = $val ";
- }
- echo '<br><table><tr><td>';
- while(list($key,list($k, $term, $tcount))=each($ar)) {
- if (empty($k)) continue;
- echo "<tr><td>$term</td><td>";
- echo $tcount;
- echo "</td></tr>";
- }
- echo '</table>';
- } else {
- echo "Scan failed. Error: " . yaz_error($id) . "<br>";
- }
- }
+function scan_titles($id, $startterm) {
+ yaz_scan($id,"rpn", "@attr 1=4 " . $startterm);
+ yaz_wait();
+ $errno = yaz_errno($id);
+ if ($errno == 0) {
+ $ar = yaz_scan_result($id,&$options);
+ echo 'Scan ok; ';
+ while(list($key,$val)=each($options)) {
+ echo "$key = $val ";
+ }
+ echo '<br><table><tr><td>';
+ while(list($key,list($k, $term, $tcount))=each($ar)) {
+ if (empty($k)) continue;
+ echo "<tr><td>$term</td><td>";
+ echo $tcount;
+ echo "</td></tr>";
+ }
+ echo '</table>';
+ } else {
+ echo "Scan failed. Error: " . yaz_error($id) . "<br>";
+ }
+}
]]>
</programlisting>
</example>
Index: phpdoc/en/reference/yaz/functions/yaz-search.xml
diff -u phpdoc/en/reference/yaz/functions/yaz-search.xml:1.2
phpdoc/en/reference/yaz/functions/yaz-search.xml:1.3
--- phpdoc/en/reference/yaz/functions/yaz-search.xml:1.2 Wed Apr 17 02:45:28
2002
+++ phpdoc/en/reference/yaz/functions/yaz-search.xml Thu Jan 16 04:44:49 2003
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.1 -->
<refentry id="function.yaz-search">
<refnamediv>
@@ -10,15 +10,17 @@
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>yaz_search</methodname>
- <methodparam><type>int</type><parameter>id</parameter></methodparam>
+ <methodparam><type>resource</type><parameter>id</parameter></methodparam>
<methodparam><type>string</type><parameter>type</parameter></methodparam>
<methodparam><type>string</type><parameter>query</parameter></methodparam>
</methodsynopsis>
<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 specifies
- a Type-1 query (RPN). Like <function>yaz_connect</function> this
+ connection given by <parameter>id</parameter>.
+ The <parameter>type</parameter> represents the query type - only
+ <literal>"rpn"</literal> is supported now in which case the
+ third argument specifies a Type-1 query in prefix query notation.
+ 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>
@@ -37,71 +39,94 @@
<table>
<title>RPN Operators</title>
<tgroup cols="2">
+ <colspec colwidth="1*" colname="construct"/>
+ <colspec colwidth="2*" colname="description"/>
<thead>
<row>
- <entry>Syntax</entry>
+ <entry>Construct</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
- <row>
- <entry><literal>@and query1 query2</literal></entry>
- <entry>intersection of query1 and query2</entry>
- </row>
- <row>
- <entry><literal>@or query1 query2</literal></entry>
- <entry>union of query1 and query2</entry>
- </row>
- <row>
- <entry><literal>@not query1 query2</literal></entry>
- <entry>query1 and not query2</entry>
- </row>
- <row>
- <entry><literal>@set name</literal></entry>
- <entry>result set reference</entry>
- </row>
- <row>
- <entry><literal>@attrset set query</literal></entry>
- <entry>specifies attribute-set for query. This construction is only
- allowed once - in the beginning of the whole query</entry>
- </row>
- <row>
- <entry><literal>@attr set type=value query</literal></entry>
- <entry>applies attribute to query. The type and value are
+ <row>
+ <entry><literal>@and</literal> query1 query2</entry>
+ <entry>intersection of query1 and query2</entry>
+ </row>
+ <row>
+ <entry><literal>@or</literal> query1 query2</entry>
+ <entry>union of query1 and query2</entry>
+ </row>
+ <row>
+ <entry><literal>@not</literal> query1 query2</entry>
+ <entry>query1 and not query2</entry>
+ </row>
+ <row>
+ <entry><literal>@set</literal> name</entry>
+ <entry>result set reference</entry>
+ </row>
+ <row>
+ <entry><literal>@attrset</literal> set query</entry>
+ <entry>specifies attribute-set for query. This construction is only
+ allowed once - in the beginning of the whole query</entry>
+ </row>
+ <row>
+ <entry><literal>@attr</literal> [set] type=value query</entry>
+ <entry>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.</entry>
- </row>
+ </row>
</tbody>
</tgroup>
</table>
<example>
<title>Query Examples</title>
<para>
- Query
+ You can search for simple terms, like this
<screen>computer</screen>
- matches documents where "computer" occur. No attributes are specified.
+ which matches documents where "computer" occur.
+ No attributes are specified.
</para>
<para>
The Query
- <screen>"donald knuth"</screen>
- matches documents where "donald knuth" occur.
+ <screen>"knuth donald"</screen>
+ matches documents where "knuth donald" occur (provided that the
+ server supports phrase search).
+ </para>
+ <para>
+ This query applies two attributes for the same phrase.
+ <screen>@attr 1=1003 @attr 4=1 "knuth donald"</screen>
+ First attribute is type 1 (Bib-1 use), attribute value is 1003
+ (Author).
+ Second attribute has is type 4 (structure), value 1 (phrase),
+ so this should match documents where Donald Knuth is author.
</para>
<para>
- For the query
- <screen>@attr 1=4 art</screen>
- attribute type is 1 (Bib-1 use), attribute value is 4
- Title), so this should match documents where <literal>art</literal>
- occur in the title.
+ This query
+ <screen>@and @or a b @not @or c d e</screen>
+ would in infix notation look like
+ <literal>(a or b) and ((c or d) not e)</literal>.
</para>
<para>
- Another more complex one:
-<screen>@attrset gils @and @attr 1=4 art @attr 1=1003 "donald knuth"</screen>
+ Another, more complex, one:
+<screen>@attrset gils @and @attr 1=4 art @attr 1=2000 company</screen>
The query as a whole uses the GILS attributeset. The query matches
- documents where <literal>art</literal> occur in the title and in which
- <literal>donald knuth</literal> occur in the author.
+ documents where <literal>art</literal> occur in the title (GILS,BIB-1)
+ and in which <literal>company</literal> occur as Distributor (GILS).
</para>
</example>
+ <para>
+ You can find information about attributes at the
+ <ulink url="&url.yaz-loc-bib1;">Z39.50 Maintenance Agency</ulink>
+ site.
+ </para>
+ <note>
+ <para>
+ If you would like to use a more friendly notation,
+ use the CCL parser - functions <function>yaz_ccl_conf</function> and
+ <function>yaz_ccl_parse</function>.
+ </para>
+ </note>
</refsect1>
</refentry>
Index: phpdoc/en/reference/yaz/functions/yaz-sort.xml
diff -u phpdoc/en/reference/yaz/functions/yaz-sort.xml:1.2
phpdoc/en/reference/yaz/functions/yaz-sort.xml:1.3
--- phpdoc/en/reference/yaz/functions/yaz-sort.xml:1.2 Wed Apr 17 02:45:28 2002
+++ phpdoc/en/reference/yaz/functions/yaz-sort.xml Thu Jan 16 04:44:49 2003
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.1 -->
<refentry id="function.yaz-sort">
<refnamediv>
@@ -10,15 +10,16 @@
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>yaz_sort</methodname>
- <methodparam><type>int</type><parameter>id</parameter></methodparam>
+ <methodparam><type>resource</type><parameter>id</parameter></methodparam>
<methodparam><type>string</type><parameter>criteria</parameter></methodparam>
</methodsynopsis>
<para>
This function sets sorting criteria and enables Z39.50 Sort.
- Use this function together with <function>yaz_search</function>
- or <function>yaz_present</function>. Using this function alone
- doesn't have any effect. If used in conjunction with
- <function>yaz_search</function> a Z39.50 Sort will be sent after
+ Call this function <emphasis>before</emphasis>
+ <function>yaz_search</function>.
+ Using this function alone doesn't have any effect.
+ When in conjunction with <function>yaz_search</function>,
+ a Z39.50 Sort will be sent after
a search response has been received and before any records are
retrieved with Z39.50 Present. The <parameter>criteria</parameter>
takes the form
Index: phpdoc/en/reference/yaz/functions/yaz-syntax.xml
diff -u phpdoc/en/reference/yaz/functions/yaz-syntax.xml:1.2
phpdoc/en/reference/yaz/functions/yaz-syntax.xml:1.3
--- phpdoc/en/reference/yaz/functions/yaz-syntax.xml:1.2 Wed Apr 17 02:45:28
2002
+++ phpdoc/en/reference/yaz/functions/yaz-syntax.xml Thu Jan 16 04:44:49 2003
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.8 -->
<refentry id="function.yaz-syntax">
<refnamediv>
@@ -12,16 +12,15 @@
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>yaz_syntax</methodname>
- <methodparam><type>int</type><parameter>id</parameter></methodparam>
+ <methodparam><type>resource</type><parameter>id</parameter></methodparam>
<methodparam><type>string</type><parameter>syntax</parameter></methodparam>
</methodsynopsis>
<para>
- The syntax is specified as an OID (Object Identifier) in a
+ The syntax must be specified as an OID (Object Identifier) in a
raw dot-notation (like <literal>1.2.840.10003.5.10</literal>) or
as one of the known registered record syntaxes (sutrs, usmarc, grs1,
- xml, etc.). This function is used in conjunction with
- <function>yaz_search</function> and <function>yaz_present</function>
- to specify the preferred record syntax for retrieval.
+ xml, etc.). This function should be called before
+ <function>yaz_search</function> or <function>yaz_present</function>.
</para>
</refsect1>
</refentry>
Index: phpdoc/en/reference/yaz/functions/yaz-get-option.xml
+++ phpdoc/en/reference/yaz/functions/yaz-get-option.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.yaz-get-option">
<refnamediv>
<refname>yaz_get_option</refname>
<refpurpose>Returns value of option for connection</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>yaz_get_option</methodname>
<methodparam><type>resource</type><parameter>id</parameter></methodparam>
<methodparam><type>string</type><parameter>name</parameter></methodparam>
</methodsynopsis>
<para>
Returns value of option with the <parameter>name</parameter> specified.
If option is unset, an empty string is returned.
</para>
<para>
See description of <function>yaz_set_option</function> for
available options.
</para>
</refsect1>
</refentry>
<!-- 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
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
Index: phpdoc/en/reference/yaz/functions/yaz-schema.xml
+++ phpdoc/en/reference/yaz/functions/yaz-schema.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.yaz-schema">
<refnamediv>
<refname>yaz_schema</refname>
<refpurpose>
Specifies schema for retrieval.
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>yaz_schema</methodname>
<methodparam><type>resource</type><parameter>id</parameter></methodparam>
<methodparam><type>string</type><parameter>schema</parameter></methodparam>
</methodsynopsis>
<para>
The schema must be specified as an OID (Object Identifier) in a
raw dot-notation (like <literal>1.2.840.10003.13.4</literal>) or
as one of the known registered schemas:
<literal>GILS-schema</literal>, <literal>Holdings</literal>,
<literal>Zthes</literal>, ...
This function should be called before
<function>yaz_search</function> or <function>yaz_present</function>.
</para>
</refsect1>
</refentry>
<!-- 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
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
Index: phpdoc/en/reference/yaz/functions/yaz-set-option.xml
+++ phpdoc/en/reference/yaz/functions/yaz-set-option.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.yaz-set-option">
<refnamediv>
<refname>yaz_set_option</refname>
<refpurpose>Sets one or more options for connection</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>yaz_set_option</methodname>
<methodparam><type>resource</type><parameter>id</parameter></methodparam>
<methodparam><type>string</type><parameter>name</parameter></methodparam>
<methodparam><type>string</type><parameter>value</parameter></methodparam>
</methodsynopsis>
<para>
Sets option <parameter>name</parameter> to <parameter>value</parameter>.
</para>
<table>
<title>PYP/YAZ Connection Options</title>
<tgroup cols="2">
<colspec colwidth="2*" colname="name"/>
<colspec colwidth="5*" colname="description"/>
<thead>
<row>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>implementationName</entry>
<entry>implementation name of target</entry>
</row>
<row>
<entry>implementationVersion</entry>
<entry>implementation version of target</entry>
</row>
<row>
<entry>implementationId</entry>
<entry>implementation ID of target</entry>
</row>
<row>
<entry>schema</entry>
<entry>schema for retrieval. By default, no
schema is used. Setting this option is equivalent to
using function <function>yaz_schema</function></entry>
</row>
<row>
<entry>preferredRecordSyntax</entry>
<entry>record syntax for retrieval. By default, no
syntax is used. Setting this option is equivalent to
using function <function>yaz_syntax</function></entry>
</row>
<row>
<entry>start</entry>
<entry>offset for first record to be retrieved via
<function>yaz_search</function> or <function>yaz_present</function>.
Records are numbered from zero and upwards.
Setting this option in combination with option
<literal>count</literal> has the same effect as calling
<function>yaz_range</function> except that records are
numbered from 1 in <function>yaz_range</function>
</entry>
</row>
<row>
<entry>count</entry>
<entry>maximum number of records to be retrieved via
<function>yaz_search</function> or <function>yaz_present</function>.
</entry>
</row>
<row>
<entry>elementSetName</entry>
<entry>element-set-name for retrieval. Setting this option is
equivalent to calling <function>yaz_element</function>.
</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
</refentry>
<!-- 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
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
