Skip to content

Commit d08f5a3

Browse files
author
Adam Dickmeiss
committed
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. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@112077 c90b9560-bf6c-de11-be94-00142212c4b1
1 parent de8094c commit d08f5a3

23 files changed

+433
-174
lines changed

‎reference/yaz/configure.xml‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,24 @@
11
<?xml version="1.0" encoding="iso-8859-1"?>
2-
<!-- $Revision: 1.2 $ -->
2+
<!-- $Revision: 1.3 $ -->
33
<section id="yaz.installation">
44
&reftitle.install;
55
<para>
6-
Compile YAZ (ANSI/NISO Z39.50) and install it. Build PHP with your favourite
7-
modules and add option
6+
Compile YAZ (ANSI/NISO Z39.50 support) and install it.
7+
Build PHP with your favourite modules and add option
88
<option role="configure">--with-yaz[=DIR]</option>.
99
Your task is roughly the following:
1010
</para>
1111
<para>
1212
<informalexample>
1313
<programlisting role="shell">
1414
<![CDATA[
15-
gunzip -c yaz-1.6.tar.gz|tar xf -
16-
gunzip -c php-4.0.X.tar.gz|tar xf -
17-
cd yaz-1.6
15+
gunzip -c php-4.3.X.tar.gz|tar xf -
16+
gunzip -c yaz-1.9.Y.tar.gz|tar xf -
17+
cd yaz-1.9.Y
1818
./configure --prefix=/usr
1919
make
2020
make install
21-
cd ../php-4.0.X
21+
cd ../php-4.3.X.
2222
./configure --with-yaz=/usr/bin
2323
make
2424
make install

‎reference/yaz/functions/yaz-addinfo.xml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<?xml version="1.0" encoding="iso-8859-1"?>
2-
<!-- $Revision: 1.2 $ -->
2+
<!-- $Revision: 1.3 $ -->
33
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.1 -->
44
<refentry id="function.yaz-addinfo">
55
<refnamediv>
@@ -9,8 +9,8 @@
99
<refsect1>
1010
<title>Description</title>
1111
<methodsynopsis>
12-
<type>int</type><methodname>yaz_addinfo</methodname>
13-
<methodparam><type>int</type><parameter>id</parameter></methodparam>
12+
<type>string</type><methodname>yaz_addinfo</methodname>
13+
<methodparam><type>resource</type><parameter>id</parameter></methodparam>
1414
</methodsynopsis>
1515
<para>
1616
Returns additional error message for target (last request). An

‎reference/yaz/functions/yaz-ccl-conf.xml‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<?xml version="1.0" encoding="iso-8859-1"?>
2-
<!-- $Revision: 1.2 $ -->
2+
<!-- $Revision: 1.3 $ -->
33
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.8 -->
44
<refentry id="function.yaz-ccl-conf">
55
<refnamediv>
@@ -10,7 +10,7 @@
1010
<title>Description</title>
1111
<methodsynopsis>
1212
<type>int</type><methodname>yaz_ccl_conf</methodname>
13-
<methodparam><type>int</type><parameter>id</parameter></methodparam>
13+
<methodparam><type>resource</type><parameter>id</parameter></methodparam>
1414
<methodparam><type>array</type><parameter>config</parameter></methodparam>
1515
</methodsynopsis>
1616
<para>
@@ -32,15 +32,15 @@
3232
In the example below, the CCL parser is configured to support
3333
three CCL fields: <literal>ti</literal>, <literal>au</literal> and
3434
<literal>isbn</literal>. Each field is mapped to their BIB-1
35-
equivalent. It is assumed that variable <literal>$id</literal> is a
36-
target ID.
35+
equivalent. It is assumed that variable <literal>$id</literal> is the
36+
connection ID.
3737
</simpara>
3838
<programlisting>
3939
<![CDATA[
40-
$field["ti"] = "1=4";
41-
$field["au"] = "1=1";
42-
$field["isbn"] = "1=7";
43-
yaz_ccl_conf($id,$field);
40+
$fields["ti"] = "1=4";
41+
$fields["au"] = "1=1";
42+
$fields["isbn"] = "1=7";
43+
yaz_ccl_conf($id,$fields);
4444
]]>
4545
</programlisting>
4646
</example>

‎reference/yaz/functions/yaz-ccl-parse.xml‎

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<?xml version="1.0" encoding="iso-8859-1"?>
2-
<!-- $Revision: 1.2 $ -->
2+
<!-- $Revision: 1.3 $ -->
33
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.1 -->
44
<refentry id="function.yaz-ccl-parse">
55
<refnamediv>
@@ -10,12 +10,12 @@
1010
<title>Description</title>
1111
<methodsynopsis>
1212
<type>int</type><methodname>yaz_ccl_parse</methodname>
13-
<methodparam><type>int</type><parameter>id</parameter></methodparam>
13+
<methodparam><type>resource</type><parameter>id</parameter></methodparam>
1414
<methodparam><type>string</type><parameter>query</parameter></methodparam>
1515
<methodparam><type>array &amp;</type><parameter>result</parameter></methodparam>
1616
</methodsynopsis>
1717
<para>
18-
This function invokes the CCL parser. It converts a given
18+
This function invokes a CCL parser. It converts a given
1919
CCL FIND query to an RPN query which may be passed to the
2020
<function>yaz_search</function> function to perform a search.
2121
To define a set of valid CCL fields call
@@ -32,6 +32,23 @@
3232
<literal>errorpos</literal>approximate position in query of failure
3333
(integer is character position).
3434
</para>
35+
<example>
36+
<title>CCL Parsing</title>
37+
<para>We'll try to search using CCL. In the example below,
38+
<literal>$ccl</literal> is a CCL query.
39+
</para>
40+
<programlisting>
41+
<![CDATA[
42+
yaz_ccl_conf($id,$fields); // see example for yaz_ccl_conf
43+
if (!yaz_ccl_parse($id, $ccl, &$cclresult) {
44+
echo 'Error: ' . $cclresult["errorstring"];
45+
} else {
46+
$rpn = $cclresult["rpn"];
47+
yaz_search($id,"rpn",$rpn);
48+
}
49+
]]>
50+
</programlisting>
51+
</example>
3552
</refsect1>
3653
</refentry>
3754

‎reference/yaz/functions/yaz-close.xml‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,21 @@
11
<?xml version="1.0" encoding="iso-8859-1"?>
2-
<!-- $Revision: 1.2 $ -->
2+
<!-- $Revision: 1.3 $ -->
33
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.1 -->
44
<refentry id="function.yaz-close">
55
<refnamediv>
66
<refname>yaz_close</refname>
7-
<refpurpose>Closes a YAZ connection</refpurpose>
7+
<refpurpose>Close YAZ connection</refpurpose>
88
</refnamediv>
99
<refsect1>
1010
<title>Description</title>
1111
<methodsynopsis>
1212
<type>int</type><methodname>yaz_close</methodname>
13-
<methodparam><type>int</type><parameter>id</parameter></methodparam>
13+
<methodparam><type>resource</type><parameter>id</parameter></methodparam>
1414
</methodsynopsis>
1515
<para>
16-
Closes the Z-association given by <parameter>id</parameter>.
17-
The <parameter>id</parameter> is a target ID as returned by a
18-
previous <function>yaz_connect</function> command.
16+
Closes connection given by <parameter>id</parameter>.
17+
The <parameter>id</parameter> is a connection resource as returned
18+
by a previous <function>yaz_connect</function> call.
1919
</para>
2020
</refsect1>
2121
</refentry>

‎reference/yaz/functions/yaz-connect.xml‎

Lines changed: 14 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,31 @@
11
<?xml version="1.0" encoding="iso-8859-1"?>
2-
<!-- $Revision: 1.2 $ -->
2+
<!-- $Revision: 1.3 $ -->
33
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.1 -->
44
<refentry id="function.yaz-connect">
55
<refnamediv>
66
<refname>yaz_connect</refname>
77
<refpurpose>
8-
Prepares for a connection and Z-association to a Z39.50 target.
8+
Prepares for a connection to a Z39.50 target (server).
99
</refpurpose>
1010
</refnamediv>
1111
<refsect1>
1212
<title>Description</title>
1313
<methodsynopsis>
14-
<type>int</type><methodname>yaz_connect</methodname>
14+
<type>resource</type><methodname>yaz_connect</methodname>
1515
<methodparam><type>string</type><parameter>zurl</parameter></methodparam>
1616
<methodparam choice="opt"><type>mixed</type><parameter>options</parameter></methodparam>
1717
</methodsynopsis>
1818
<para>
19-
This function returns a positive ID on success; zero on
19+
This function returns a connection resource on success; zero on
2020
failure.
2121
</para>
2222
<para>
2323
<function>yaz_connect</function> prepares for a connection to a
24-
Z39.50 target. The zurl argument takes the form
24+
Z39.50 target. The <parameter>zurl</parameter> argument takes the form
2525
host[:port][/database]. If port is omitted 210 is used. If
26-
database is omitted Default is used. This function is
27-
non-blocking and doesn't attempt to establish a socket - it
28-
merely prepares a connect to be performed later when
26+
database is omitted <literal>Default</literal> is used.
27+
This function is non-blocking and doesn't attempt to establish
28+
a socket - it merely prepares a connect to be performed later when
2929
<function>yaz_wait</function> is called.
3030
</para>
3131
<para>
@@ -77,6 +77,12 @@ element set names. For those, piggyback should be disabled.
7777
</varlistentry>
7878
</variablelist>
7979
</para>
80+
<note>
81+
<para>The use of a proxy often improves performance. A Z39.50 proxy
82+
is part of the free <ulink url="&url.yaz-proxy;">YAZ++</ulink>
83+
package.
84+
</para>
85+
</note>
8086
</refsect1>
8187
</refentry>
8288

‎reference/yaz/functions/yaz-database.xml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<?xml version="1.0" encoding="iso-8859-1"?>
2-
<!-- $Revision: 1.2 $ -->
2+
<!-- $Revision: 1.3 $ -->
33
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.7 -->
44
<refentry id="function.yaz-database">
55
<refnamediv>
@@ -12,7 +12,7 @@
1212
<title>Description</title>
1313
<methodsynopsis>
1414
<type>int</type><methodname>yaz_database</methodname>
15-
<methodparam><type>int</type><parameter>id</parameter></methodparam>
15+
<methodparam><type>resource</type><parameter>id</parameter></methodparam>
1616
<methodparam><type>string</type><parameter>databases</parameter></methodparam>
1717
</methodsynopsis>
1818
<para>

‎reference/yaz/functions/yaz-element.xml‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<?xml version="1.0" encoding="iso-8859-1"?>
2-
<!-- $Revision: 1.2 $ -->
2+
<!-- $Revision: 1.3 $ -->
33
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.11 -->
44
<refentry id="function.yaz-element">
55
<refnamediv>
@@ -12,15 +12,16 @@
1212
<title>Description</title>
1313
<methodsynopsis>
1414
<type>int</type><methodname>yaz_element</methodname>
15-
<methodparam><type>int</type><parameter>id</parameter></methodparam>
15+
<methodparam><type>resource</type><parameter>id</parameter></methodparam>
1616
<methodparam><type>string</type><parameter>elementset</parameter></methodparam>
1717
</methodsynopsis>
1818
<para>
19-
This function is used in conjunction with
20-
<function>yaz_search</function> and <function>yaz_present</function>
19+
This function sets the element set name for retrieval.
20+
Call this function before <function>yaz_search</function> or
21+
<function>yaz_present</function>
2122
to specify the element set name for records to be retrieved.
22-
Most servers support <literal>F</literal> (full) and
23-
<literal>B</literal> (brief).
23+
Most servers support <literal>F</literal> (for full records) and
24+
<literal>B</literal> (for brief records).
2425
</para>
2526
<para>
2627
Returns &true; on success; &false; on error.

‎reference/yaz/functions/yaz-errno.xml‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<?xml version="1.0" encoding="iso-8859-1"?>
2-
<!-- $Revision: 1.2 $ -->
2+
<!-- $Revision: 1.3 $ -->
33
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.1 -->
44
<refentry id="function.yaz-errno">
55
<refnamediv>
@@ -10,20 +10,20 @@
1010
<title>Description</title>
1111
<methodsynopsis>
1212
<type>int</type><methodname>yaz_errno</methodname>
13-
<methodparam><type>int</type><parameter>id</parameter></methodparam>
13+
<methodparam><type>resource</type><parameter>id</parameter></methodparam>
1414
</methodsynopsis>
1515
<para>
16-
Returns error for target (last request). A positive value is
17-
returned if the target returned a diagnostic code; a value of
18-
zero is returned if no errors occurred (success); negative value
19-
is returned for other errors (such as when the target
20-
closed connection, etc).
16+
Returns error for target (last request). The error code is either
17+
a Z39.50 diagnostic code (usually a Bib-1 diagnostic) or a
18+
client side error code which is generated by PHP/YAZ itself, such
19+
as "Connect failed", "Init Rejected", etc.
2120
</para>
2221
<para>
2322
<function>yaz_errno</function> should be called after network
2423
activity for each target - (after <function>yaz_wait</function>
2524
returns) to determine the success or failure of the last
26-
operation (e.g. search).
25+
operation (e.g. search). To get a text description of the
26+
error, call <function>yaz_error</function>.
2727
</para>
2828
</refsect1>
2929
</refentry>

‎reference/yaz/functions/yaz-error.xml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<?xml version="1.0" encoding="iso-8859-1"?>
2-
<!-- $Revision: 1.2 $ -->
2+
<!-- $Revision: 1.3 $ -->
33
<!-- splitted from ./en/functions/yaz.xml, last change in rev 1.1 -->
44
<refentry id="function.yaz-error">
55
<refnamediv>
@@ -10,10 +10,10 @@
1010
<title>Description</title>
1111
<methodsynopsis>
1212
<type>string</type><methodname>yaz_error</methodname>
13-
<methodparam><type>int</type><parameter>id</parameter></methodparam>
13+
<methodparam><type>resource</type><parameter>id</parameter></methodparam>
1414
</methodsynopsis>
1515
<para>
16-
Returns error message for target (last request). An empty string
16+
Returns error text message for target (last request). An empty string
1717
is returned if last operation was a success.
1818
</para>
1919
<para>

0 commit comments

Comments
 (0)