<?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;
}