439 lines
10 KiB
PHP
439 lines
10 KiB
PHP
<?php
|
|
|
|
namespace Safe;
|
|
|
|
use Safe\Exceptions\YazException;
|
|
|
|
/**
|
|
* This function invokes a CCL parser. It converts a given CCL FIND query to
|
|
* an RPN query which may be passed to the yaz_search
|
|
* function to perform a search.
|
|
*
|
|
* To define a set of valid CCL fields call yaz_ccl_conf
|
|
* prior to this function.
|
|
*
|
|
* @param resource $id The connection resource returned by yaz_connect.
|
|
* @param string $query The CCL FIND query.
|
|
* @param array|null $result If the function was executed successfully, this will be an array
|
|
* containing the valid RPN query under the key rpn.
|
|
*
|
|
* Upon failure, three indexes are set in this array to indicate the cause
|
|
* of failure:
|
|
*
|
|
*
|
|
*
|
|
* errorcode - the CCL error code (integer)
|
|
*
|
|
*
|
|
*
|
|
*
|
|
* errorstring - the CCL error string
|
|
*
|
|
*
|
|
*
|
|
*
|
|
* errorpos - approximate position in query of failure
|
|
* (integer is character position)
|
|
*
|
|
*
|
|
*
|
|
*
|
|
* errorcode - the CCL error code (integer)
|
|
*
|
|
* errorstring - the CCL error string
|
|
*
|
|
* errorpos - approximate position in query of failure
|
|
* (integer is character position)
|
|
* @throws YazException
|
|
*
|
|
*/
|
|
function yaz_ccl_parse($id, string $query, ?array &$result): void
|
|
{
|
|
error_clear_last();
|
|
$result = \yaz_ccl_parse($id, $query, $result);
|
|
if ($result === false) {
|
|
throw YazException::createFromPhpError();
|
|
}
|
|
}
|
|
|
|
|
|
/**
|
|
* Closes the connection given by parameter id.
|
|
*
|
|
* @param resource $id The connection resource returned by yaz_connect.
|
|
* @throws YazException
|
|
*
|
|
*/
|
|
function yaz_close($id): void
|
|
{
|
|
error_clear_last();
|
|
$result = \yaz_close($id);
|
|
if ($result === false) {
|
|
throw YazException::createFromPhpError();
|
|
}
|
|
}
|
|
|
|
|
|
/**
|
|
* This function returns a connection resource on success, zero on
|
|
* failure.
|
|
*
|
|
* yaz_connect prepares for a connection to a
|
|
* Z39.50 server.
|
|
* This function is non-blocking and does not attempt to establish
|
|
* a connection - it merely prepares a connect to be performed later when
|
|
* yaz_wait is called.
|
|
*
|
|
* @param string $zurl A string that takes the form host[:port][/database].
|
|
* If port is omitted, port 210 is used. If database is omitted
|
|
* Default is used.
|
|
* @param mixed $options If given as a string, it is treated as the Z39.50 V2 authentication
|
|
* string (OpenAuth).
|
|
*
|
|
* If given as an array, the contents of the array serves as options.
|
|
*
|
|
*
|
|
* user
|
|
*
|
|
*
|
|
* Username for authentication.
|
|
*
|
|
*
|
|
*
|
|
*
|
|
* group
|
|
*
|
|
*
|
|
* Group for authentication.
|
|
*
|
|
*
|
|
*
|
|
*
|
|
* password
|
|
*
|
|
*
|
|
* Password for authentication.
|
|
*
|
|
*
|
|
*
|
|
*
|
|
* cookie
|
|
*
|
|
*
|
|
* Cookie for session (YAZ proxy).
|
|
*
|
|
*
|
|
*
|
|
*
|
|
* proxy
|
|
*
|
|
*
|
|
* Proxy for connection (YAZ proxy).
|
|
*
|
|
*
|
|
*
|
|
*
|
|
* persistent
|
|
*
|
|
*
|
|
* A boolean. If TRUE the connection is persistent; If FALSE the
|
|
* connection is not persistent. By default connections are persistent.
|
|
*
|
|
*
|
|
*
|
|
* If you open a persistent connection, you won't be able to close
|
|
* it later with yaz_close.
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
* piggyback
|
|
*
|
|
*
|
|
* A boolean. If TRUE piggyback is enabled for searches; If FALSE
|
|
* piggyback is disabled. By default piggyback is enabled.
|
|
*
|
|
*
|
|
* Enabling piggyback is more efficient and usually saves a
|
|
* network-round-trip for first time fetches of records. However, a
|
|
* few Z39.50 servers do not support piggyback or they ignore element
|
|
* set names. For those, piggyback should be disabled.
|
|
*
|
|
*
|
|
*
|
|
*
|
|
* charset
|
|
*
|
|
*
|
|
* A string that specifies character set to be used in Z39.50
|
|
* language and character set negotiation. Use strings such as:
|
|
* ISO-8859-1, UTF-8,
|
|
* UTF-16.
|
|
*
|
|
*
|
|
* Most Z39.50 servers do not support this feature (and thus, this is
|
|
* ignored). Many servers use the ISO-8859-1 encoding for queries and
|
|
* messages. MARC21/USMARC records are not affected by this setting.
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
* preferredMessageSize
|
|
*
|
|
*
|
|
* An integer that specifies the maximum byte size of all records
|
|
* to be returned by a target during retrieval. See the
|
|
* Z39.50 standard for more
|
|
* information.
|
|
*
|
|
*
|
|
*
|
|
* This option is supported in PECL YAZ 1.0.5 or later.
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
* maximumRecordSize
|
|
*
|
|
*
|
|
* An integer that specifies the maximum byte size of a single record
|
|
* to be returned by a target during retrieval. This
|
|
* entity is referred to as Exceptional-record-size in the
|
|
* Z39.50 standard.
|
|
*
|
|
*
|
|
*
|
|
* This option is supported in PECL YAZ 1.0.5 or later.
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
* Username for authentication.
|
|
*
|
|
* Group for authentication.
|
|
*
|
|
* Password for authentication.
|
|
*
|
|
* Cookie for session (YAZ proxy).
|
|
*
|
|
* Proxy for connection (YAZ proxy).
|
|
*
|
|
* A boolean. If TRUE the connection is persistent; If FALSE the
|
|
* connection is not persistent. By default connections are persistent.
|
|
*
|
|
* If you open a persistent connection, you won't be able to close
|
|
* it later with yaz_close.
|
|
*
|
|
* A boolean. If TRUE piggyback is enabled for searches; If FALSE
|
|
* piggyback is disabled. By default piggyback is enabled.
|
|
*
|
|
* Enabling piggyback is more efficient and usually saves a
|
|
* network-round-trip for first time fetches of records. However, a
|
|
* few Z39.50 servers do not support piggyback or they ignore element
|
|
* set names. For those, piggyback should be disabled.
|
|
*
|
|
* A string that specifies character set to be used in Z39.50
|
|
* language and character set negotiation. Use strings such as:
|
|
* ISO-8859-1, UTF-8,
|
|
* UTF-16.
|
|
*
|
|
* Most Z39.50 servers do not support this feature (and thus, this is
|
|
* ignored). Many servers use the ISO-8859-1 encoding for queries and
|
|
* messages. MARC21/USMARC records are not affected by this setting.
|
|
*
|
|
* An integer that specifies the maximum byte size of all records
|
|
* to be returned by a target during retrieval. See the
|
|
* Z39.50 standard for more
|
|
* information.
|
|
*
|
|
* This option is supported in PECL YAZ 1.0.5 or later.
|
|
*
|
|
* An integer that specifies the maximum byte size of a single record
|
|
* to be returned by a target during retrieval. This
|
|
* entity is referred to as Exceptional-record-size in the
|
|
* Z39.50 standard.
|
|
*
|
|
* This option is supported in PECL YAZ 1.0.5 or later.
|
|
* @return mixed A connection resource on success, FALSE on error.
|
|
* @throws YazException
|
|
*
|
|
*/
|
|
function yaz_connect(string $zurl, $options = null)
|
|
{
|
|
error_clear_last();
|
|
if ($options !== null) {
|
|
$result = \yaz_connect($zurl, $options);
|
|
} else {
|
|
$result = \yaz_connect($zurl);
|
|
}
|
|
if ($result === false) {
|
|
throw YazException::createFromPhpError();
|
|
}
|
|
return $result;
|
|
}
|
|
|
|
|
|
/**
|
|
* This function allows you to change databases within a session by
|
|
* specifying one or more databases to be used in search, retrieval, etc.
|
|
* - overriding databases specified in call to
|
|
* yaz_connect.
|
|
*
|
|
* @param resource $id The connection resource returned by yaz_connect.
|
|
* @param string $databases A string containing one or more databases. Multiple databases are
|
|
* separated by a plus sign +.
|
|
* @throws YazException
|
|
*
|
|
*/
|
|
function yaz_database($id, string $databases): void
|
|
{
|
|
error_clear_last();
|
|
$result = \yaz_database($id, $databases);
|
|
if ($result === false) {
|
|
throw YazException::createFromPhpError();
|
|
}
|
|
}
|
|
|
|
|
|
/**
|
|
* This function sets the element set name for retrieval.
|
|
*
|
|
* Call this function before yaz_search or
|
|
* yaz_present to specify the element set name for
|
|
* records to be retrieved.
|
|
*
|
|
* @param resource $id The connection resource returned by yaz_connect.
|
|
* @param string $elementset Most servers support F (for full records) and
|
|
* B (for brief records).
|
|
* @throws YazException
|
|
*
|
|
*/
|
|
function yaz_element($id, string $elementset): void
|
|
{
|
|
error_clear_last();
|
|
$result = \yaz_element($id, $elementset);
|
|
if ($result === false) {
|
|
throw YazException::createFromPhpError();
|
|
}
|
|
}
|
|
|
|
|
|
/**
|
|
* This function prepares for retrieval of records after a successful search.
|
|
*
|
|
* The yaz_range function should be called prior to this
|
|
* function to specify the range of records to be retrieved.
|
|
*
|
|
* @param resource $id The connection resource returned by yaz_connect.
|
|
* @throws YazException
|
|
*
|
|
*/
|
|
function yaz_present($id): void
|
|
{
|
|
error_clear_last();
|
|
$result = \yaz_present($id);
|
|
if ($result === false) {
|
|
throw YazException::createFromPhpError();
|
|
}
|
|
}
|
|
|
|
|
|
/**
|
|
* yaz_search prepares for a search on the given
|
|
* connection.
|
|
*
|
|
* Like yaz_connect this function is non-blocking and
|
|
* only prepares for a search to be executed later when
|
|
* yaz_wait is called.
|
|
*
|
|
* @param resource $id The connection resource returned by yaz_connect.
|
|
* @param string $type This parameter represents the query type - only "rpn"
|
|
* is supported now in which case the third argument specifies a Type-1
|
|
* query in prefix query notation.
|
|
* @param string $query The RPN query is a textual representation 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 operator
|
|
* precedes the operands. The query string is a sequence of tokens where
|
|
* white space is ignored unless surrounded by double quotes. Tokens beginning
|
|
* with an at-character (@) are considered operators,
|
|
* otherwise they are treated as search terms.
|
|
*
|
|
* You can find information about attributes at the
|
|
* Z39.50 Maintenance Agency
|
|
* site.
|
|
*
|
|
* If you would like to use a more friendly notation,
|
|
* use the CCL parser - functions yaz_ccl_conf and
|
|
* yaz_ccl_parse.
|
|
* @throws YazException
|
|
*
|
|
*/
|
|
function yaz_search($id, string $type, string $query): void
|
|
{
|
|
error_clear_last();
|
|
$result = \yaz_search($id, $type, $query);
|
|
if ($result === false) {
|
|
throw YazException::createFromPhpError();
|
|
}
|
|
}
|
|
|
|
|
|
/**
|
|
* This function carries out networked (blocked) activity for outstanding
|
|
* requests which have been prepared by the functions
|
|
* yaz_connect, yaz_search,
|
|
* yaz_present, yaz_scan and
|
|
* yaz_itemorder.
|
|
*
|
|
* yaz_wait returns when all servers have either
|
|
* completed all requests or aborted (in case of errors).
|
|
*
|
|
* @param array $options An associative array of options:
|
|
*
|
|
*
|
|
* timeout
|
|
*
|
|
*
|
|
* Sets timeout in seconds. If a server has not responded within the
|
|
* timeout it is considered dead and yaz_wait
|
|
* returns. The default value for timeout is 15 seconds.
|
|
*
|
|
*
|
|
*
|
|
*
|
|
* event
|
|
*
|
|
*
|
|
* A boolean.
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
* Sets timeout in seconds. If a server has not responded within the
|
|
* timeout it is considered dead and yaz_wait
|
|
* returns. The default value for timeout is 15 seconds.
|
|
*
|
|
* A boolean.
|
|
* @return mixed Returns TRUE on success.
|
|
* In event mode, returns resource.
|
|
* @throws YazException
|
|
*
|
|
*/
|
|
function yaz_wait(array &$options = null)
|
|
{
|
|
error_clear_last();
|
|
$result = \yaz_wait($options);
|
|
if ($result === false) {
|
|
throw YazException::createFromPhpError();
|
|
}
|
|
return $result;
|
|
}
|