mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-19 10:28:54 +00:00
510ef4e605
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@43452 c90b9560-bf6c-de11-be94-00142212c4b1
917 lines
31 KiB
XML
917 lines
31 KiB
XML
<reference id="ref.yaz">
|
|
<title>YAZ functions</title>
|
|
<titleabbrev>YAZ</titleabbrev>
|
|
<partintro>
|
|
<sect1 id="yaz.intro">
|
|
<title>Introduction</title>
|
|
<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.
|
|
</para>
|
|
<para>
|
|
<productname>YAZ</productname> is available at <ulink
|
|
url="&url.yaz;">&url.yaz;</ulink>. You can find news information,
|
|
example scripts, etc. for this extension at <ulink
|
|
url="&url.yaz-phpyaz;">&url.yaz-phpyaz;</ulink>.
|
|
</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
|
|
for PHP. This means that sessions are stateless but shared amongst
|
|
users, thus saving the connect and initialize phase steps in most
|
|
cases.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="yaz.install">
|
|
<title>Installation</title>
|
|
<para>
|
|
Compile YAZ and install it. Build PHP with your favourite
|
|
modules and add option --with-yaz. Your task is roughly the
|
|
following:
|
|
</para>
|
|
<para>
|
|
<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>
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="yaz.example">
|
|
<title>Example</title>
|
|
<para>
|
|
PHP/YAZ keeps track of connections with targets
|
|
(Z-Associations). A positive integer represents the ID of a
|
|
particular association.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>Parallel searching using YAZ</function></title>
|
|
<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.
|
|
</simpara>
|
|
<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>
|
|
</para>
|
|
</sect1>
|
|
</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 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.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.yaz-connect">
|
|
<refnamediv>
|
|
<refname>yaz_connect</refname>
|
|
<refpurpose>
|
|
Prepares for a connection and Z-association to a Z39.50 target.
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>yaz_connect</function></funcdef>
|
|
<paramdef>string
|
|
<parameter>zurl</parameter>
|
|
</paramdef>
|
|
<paramdef>string
|
|
<parameter><optional>authentication</optional></parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function returns a positive ID 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
|
|
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 (such as when the target
|
|
closed connection, 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).
|
|
</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>string <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 an english text 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-element">
|
|
<refnamediv>
|
|
<refname>yaz_element</refname>
|
|
<refpurpose>
|
|
Specifies Element-Set Name for retrieval
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>yaz_element</function></funcdef>
|
|
<paramdef>int <parameter>id</parameter></paramdef>
|
|
<paramdef>string <parameter>elementset</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function is used in conjunction with
|
|
<function>yaz_search</function> and <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).
|
|
</para>
|
|
<para>
|
|
Returns true on success; false on error.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.yaz-database">
|
|
<refnamediv>
|
|
<refname>yaz_database</refname>
|
|
<refpurpose>
|
|
Specifies the databases within a session
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>yaz_database</function></funcdef>
|
|
<paramdef>int <parameter>id</parameter></paramdef>
|
|
<paramdef>string <parameter>databases</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function specifies one or more databases to be used in search,
|
|
retrieval, etc. - overriding databases specified in call to
|
|
<function>yaz_connect</function>. Multiple databases are
|
|
separated by a plus sign <literal>+</literal>.
|
|
</para>
|
|
<para>
|
|
This function allows you to use different sets of databases within
|
|
a session.
|
|
</para>
|
|
<para>
|
|
Returns true on success; false on error.
|
|
</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 specifies
|
|
a Type-1 query (RPN). 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>
|
|
<refsect1>
|
|
<title>The RPN query</title>
|
|
<para>
|
|
The RPN query is a textual represenation of the Type-1 query as
|
|
defined by the Z39.50 standard. However, in the text representation
|
|
as used by YAZ a prefix notation is used, that is the operater
|
|
precedes the operands. The query string is a sequence of tokens where
|
|
white space is ignored is ignored unless surrounded by double
|
|
quotes. Tokens beginning with an at-character (<literal>@</literal>)
|
|
are considered operators, otherwise they are treated as search terms.
|
|
</para>
|
|
<table>
|
|
<title>RPN Operators</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Syntax</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
|
|
integers specifying the attribute-type and attribute-value
|
|
respectively. The set, if given, specifies the
|
|
attribute-set.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<para>
|
|
The following illustrates valid query constructions:
|
|
<informalexample>
|
|
<screen>computer</screen>
|
|
</informalexample>
|
|
Matches documents where "computer" occur. No attributes are specified.
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>"donald knuth"</screen>
|
|
</informalexample>
|
|
Matches documents where "donald knuth" occur.
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>@attr 1=4 art</screen>
|
|
</informalexample>
|
|
Attribute type is 1 (Bib-1 use), attribute value is 4
|
|
Title), so this should match documents where "art" occur
|
|
in the title.
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>@attrset gils @and @attr 1=4 art @attr 1=1003 "donald knuth"</screen>
|
|
</informalexample>
|
|
The query as a whole uses the GILS attributeset. The query matches
|
|
documents where "art" occur in the title and in which "donald knuth"
|
|
occur in the author.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.yaz-present">
|
|
<refnamediv>
|
|
<refname>yaz_present</refname>
|
|
<refpurpose>
|
|
Prepares for retrieval (Z39.50 present).
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>yaz_present</function></funcdef>
|
|
<void></void>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function prepares for retrieval of records after
|
|
a successful search. The <function>yaz_range</function> should
|
|
be called prior to this function to specify the range of
|
|
records to be retrieved.
|
|
</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>
|
|
The syntax is 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.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.yaz-scan">
|
|
<refnamediv>
|
|
<refname>yaz_scan</refname>
|
|
<refpurpose>Prepares for a scan</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>yaz_scan</function></funcdef>
|
|
<paramdef>int <parameter>id</parameter></paramdef>
|
|
<paramdef>string <parameter>type</parameter></paramdef>
|
|
<paramdef>string <parameter>startterm</parameter></paramdef>
|
|
<paramdef>array
|
|
<parameter><optional>flags</optional></parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function prepares for a Z39.50 Scan Request. Argument
|
|
<parameter>id</parameter> specifies target ID. 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>
|
|
is supported. The optional <parameter>flags</parameter>
|
|
specifies additional information to control the behaviour of the
|
|
scan request. Three indexes are currently read from the flags:
|
|
<literal>number</literal> (number of terms requested),
|
|
<literal>position</literal> (preferred position of term) and
|
|
<literal>stepSize</literal> (preferred step size).
|
|
To actually tranfer the Scan Request to the target and receive the
|
|
Scan Response, <function>yaz_wait</function> must be called. Upon
|
|
completion of <function>yaz_wait</function> call
|
|
<function>yaz_error</function> and
|
|
<function>yaz_scan_result</function> to handle the response.
|
|
</para>
|
|
<para>
|
|
The syntax of <parameter>startterm</parameter> is similar to the
|
|
RPN query as described in <function>yaz_search</function>. The
|
|
startterm consists of zero or more <literal>@attr</literal>-operator
|
|
specifications, then followed by exactly one token.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>PHP function that scans titles</title>
|
|
<programlisting>
|
|
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>";
|
|
}
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.yaz-scan-result">
|
|
<refnamediv>
|
|
<refname>yaz_scan_result</refname>
|
|
<refpurpose>Returns Scan Response result</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>array <function>yaz_scan_result</function></funcdef>
|
|
<paramdef>int <parameter>id</parameter></paramdef>
|
|
<paramdef>array &
|
|
<parameter><optional>result</optional></parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Given a target ID this function returns and array with terms as received
|
|
from the target in the last Scan Response.
|
|
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.
|
|
If the <parameter>result</parameter> is given it will be modified to hold
|
|
additional information taken from the Scan Response:
|
|
<literal>number</literal> (number of entries returned),
|
|
<literal>stepsize</literal> (Step-size),
|
|
<literal>position</literal> (position of term),
|
|
<literal>status</literal> (Scan Status).
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.yaz-ccl-conf">
|
|
<refnamediv>
|
|
<refname>yaz_ccl_conf</refname>
|
|
<refpurpose>Configure CCL parser</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>yaz_ccl_conf</function></funcdef>
|
|
<paramdef>int <parameter>id</parameter></paramdef>
|
|
<paramdef>array <parameter>config</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function configures the CCL query parser for a target
|
|
with definitions of access points (CCL qualifiers) and their
|
|
mapping to RPN. To map a specific CCL query to RPN afterwards
|
|
call the <function>yaz_ccl_parse</function> function.
|
|
Each index of the array <parameter>config</parameter> is the
|
|
name of a CCL field and the corresponding value holds a string
|
|
that specifies a mapping to RPN.
|
|
The mapping is a sequence of attribute-type, attribute-value
|
|
pairs. Attribute-type and attribute-value is separated by an equal
|
|
sign (<literal>=</literal>). Each pair is separated by white space.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>CCL configuration</title>
|
|
<simpara>
|
|
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.
|
|
</simpara>
|
|
<programlisting>
|
|
$field["ti"] = "1=4";
|
|
$field["au"] = "1=1";
|
|
$field["isbn"] = "1=7";
|
|
yaz_ccl_conf($id,$field);
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.yaz-ccl-parse">
|
|
<refnamediv>
|
|
<refname>yaz_ccl_parse</refname>
|
|
<refpurpose>Invoke CCL Parser</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>yaz_ccl_parse</function></funcdef>
|
|
<paramdef>int <parameter>id</parameter></paramdef>
|
|
<paramdef>string <parameter>query</parameter></paramdef>
|
|
<paramdef>array &<parameter>result</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function invokes the 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
|
|
<function>yaz_ccl_conf</function> prior to this function.
|
|
If the supplied <parameter>query</parameter> was successfully
|
|
converted to RPN, this function returns true, and the index
|
|
<literal>rpn</literal> of the supplied array
|
|
<parameter>result</parameter> holds a valid RPN query.
|
|
If the query could not be converted (because of invalid syntax,
|
|
unknown field, etc.) this function returns false and three
|
|
indexes are set in the resulting array to indicate the cause
|
|
of failure: <literal>errorcode</literal>CCL error code (integer),
|
|
<literal>errorstring</literal>CCL error string, and
|
|
<literal>errorpos</literal>approximate position in query of failure
|
|
(integer is character position).
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.yaz-itemorder">
|
|
<refnamediv>
|
|
<refname>yaz_itemorder</refname>
|
|
<refpurpose>
|
|
Prepares for Z39.50 Item Order with an ILL-Request package
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>yaz_itemorder</function></funcdef>
|
|
<paramdef>array <parameter>args</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function prepares for an Extended Services request using the
|
|
Profile for the Use of Z39.50 Item Order Extended Service to
|
|
Transport ILL (Profile/1). See
|
|
<ulink url="http://www.nlc-bnc.ca/iso/ill/stanprf.htm">this</ulink>
|
|
and the
|
|
<ulink url="http://www.nlc-bnc.ca/iso/ill/document/standard/z-ill-1a.pdf">
|
|
specification</ulink>.
|
|
The args parameter must be a hash array with information about the
|
|
Item Order request to be sent. The key of the hash is the name
|
|
of the corresponding ASN.1 tag path. For example, the ISBN below
|
|
the Item-ID has the key item-id,ISBN.
|
|
</para>
|
|
<para>
|
|
The ILL-Request parameters are:
|
|
</para>
|
|
<literallayout>
|
|
protocol-version-num
|
|
transaction-id,initial-requester-id,person-or-institution-symbol,person
|
|
transaction-id,initial-requester-id,person-or-institution-symbol,institution
|
|
transaction-id,initial-requester-id,name-of-person-or-institution,name-of-person
|
|
transaction-id,initial-requester-id,name-of-person-or-institution,name-of-institution
|
|
transaction-id,transaction-group-qualifier
|
|
transaction-id,transaction-qualifier
|
|
transaction-id,sub-transaction-qualifier
|
|
service-date-time,this,date
|
|
service-date-time,this,time
|
|
service-date-time,original,date
|
|
service-date-time,original,time
|
|
requester-id,person-or-institution-symbol,person
|
|
requester-id,person-or-institution-symbol,institution
|
|
requester-id,name-of-person-or-institution,name-of-person
|
|
requester-id,name-of-person-or-institution,name-of-institution
|
|
responder-id,person-or-institution-symbol,person
|
|
responder-id,person-or-institution-symbol,institution
|
|
responder-id,name-of-person-or-institution,name-of-person
|
|
responder-id,name-of-person-or-institution,name-of-institution
|
|
transaction-type
|
|
delivery-address,postal-address,name-of-person-or-institution,name-of-person
|
|
delivery-address,postal-address,name-of-person-or-institution,name-of-institution
|
|
delivery-address,postal-address,extended-postal-delivery-address
|
|
delivery-address,postal-address,street-and-number
|
|
delivery-address,postal-address,post-office-box
|
|
delivery-address,postal-address,city
|
|
delivery-address,postal-address,region
|
|
delivery-address,postal-address,country
|
|
delivery-address,postal-address,postal-code
|
|
delivery-address,electronic-address,telecom-service-identifier
|
|
delivery-address,electronic-address,telecom-service-addreess
|
|
billing-address,postal-address,name-of-person-or-institution,name-of-person
|
|
billing-address,postal-address,name-of-person-or-institution,name-of-institution
|
|
billing-address,postal-address,extended-postal-delivery-address
|
|
billing-address,postal-address,street-and-number
|
|
billing-address,postal-address,post-office-box
|
|
billing-address,postal-address,city
|
|
billing-address,postal-address,region
|
|
billing-address,postal-address,country
|
|
billing-address,postal-address,postal-code
|
|
billing-address,electronic-address,telecom-service-identifier
|
|
billing-address,electronic-address,telecom-service-addreess
|
|
ill-service-type
|
|
requester-optional-messages,can-send-RECEIVED
|
|
requester-optional-messages,can-send-RETURNED
|
|
requester-optional-messages,requester-SHIPPED
|
|
requester-optional-messages,requester-CHECKED-IN
|
|
search-type,level-of-service
|
|
search-type,need-before-date
|
|
search-type,expiry-date
|
|
search-type,expiry-flag
|
|
place-on-hold
|
|
client-id,client-name
|
|
client-id,client-status
|
|
client-id,client-identifier
|
|
item-id,item-type
|
|
item-id,call-number
|
|
item-id,author
|
|
item-id,title
|
|
item-id,sub-title
|
|
item-id,sponsoring-body
|
|
item-id,place-of-publication
|
|
item-id,publisher
|
|
item-id,series-title-number
|
|
item-id,volume-issue
|
|
item-id,edition
|
|
item-id,publication-date
|
|
item-id,publication-date-of-component
|
|
item-id,author-of-article
|
|
item-id,title-of-article
|
|
item-id,pagination
|
|
item-id,ISBN
|
|
item-id,ISSN
|
|
item-id,additional-no-letters
|
|
item-id,verification-reference-source
|
|
copyright-complicance
|
|
retry-flag
|
|
forward-flag
|
|
requester-note
|
|
forward-note
|
|
</literallayout>
|
|
<para>
|
|
There are also a few parameters that are part of the Extended
|
|
Services Request package and the ItemOrder package:
|
|
</para>
|
|
<literallayout>
|
|
package-name
|
|
user-id
|
|
contact-name
|
|
contact-phone
|
|
contact-email
|
|
itemorder-item
|
|
</literallayout>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.yaz-wait">
|
|
<refnamediv>
|
|
<refname>yaz_wait</refname>
|
|
<refpurpose>Wait for Z39.50 requests to complete</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>yaz_wait</function></funcdef>
|
|
<void></void>
|
|
</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_present</function>,
|
|
<function>yaz_scan</function> and <function>yaz_itemorder</function>.
|
|
<function>yaz_wait</function> returns when all targets have either
|
|
completed all requests or aborted (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:
|
|
-->
|