cvs: 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-es-result.xml yaz-get-option.xml yaz-hits.xml yaz-itemorder.xml yaz-present.xml yaz-range.xml
yaz-record.xml yaz-scan-result.xml yaz-scan.xml yaz-schema.xml yaz-search.xml yaz-set-option.xml yaz-sort.xml yaz-syntax.xml yaz-wait.xml

From:	Mehdi Achour	Date:	Tue, 05 Apr 2005 16:18:00 +0000
Subject:	cvs: 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-es-result.xml yaz-get-option.xml yaz-hits.xml yaz-itemorder.xml yaz-present.xml yaz-range.xml yaz-record.xml yaz-scan-result.xml yaz-scan.xml yaz-schema.xml yaz-search.xml yaz-set-option.xml yaz-sort.xml yaz-syntax.xml yaz-wait.xml
Groups:	php.doc
Request:	Send a blank email to phpdoc+get-969367505@lists.php.net to get a copy of this message

didou Tue Apr 5 12:18:00 2005 EDT Modified files: /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-es-result.xml yaz-get-option.xml yaz-hits.xml yaz-itemorder.xml yaz-present.xml yaz-range.xml yaz-record.xml yaz-scan-result.xml yaz-scan.xml yaz-schema.xml yaz-search.xml yaz-set-option.xml yaz-sort.xml yaz-syntax.xml yaz-wait.xml Log: WS, preparing for new style

http://cvs.php.net/diff.php/phpdoc/en/reference/yaz/functions/yaz-addinfo.xml?r1=1.6&r2=1.7&ty=u Index: phpdoc/en/reference/yaz/functions/yaz-addinfo.xml diff -u phpdoc/en/reference/yaz/functions/yaz-addinfo.xml:1.6 phpdoc/en/reference/yaz/functions/yaz-addinfo.xml:1.7 --- phpdoc/en/reference/yaz/functions/yaz-addinfo.xml:1.6 Mon Jan 26 08:42:22 2004 +++ phpdoc/en/reference/yaz/functions/yaz-addinfo.xml Tue Apr 5 12:17:59 2005 @@ -1,28 +1,27 @@ <?xml version="1.0" encoding="iso-8859-1"?> - - - <refentry id="function.yaz-addinfo"> - <refnamediv> - <refname>yaz_addinfo</refname> - <refpurpose>Returns additional error information</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <methodsynopsis> - <type>string</type><methodname>yaz_addinfo</methodname> - <methodparam><type>resource</type><parameter>id</parameter></methodparam> - </methodsynopsis> - <para> - Returns additional error message for server (last request), identified by - parameter <parameter>id</parameter>. An empty string is returned if the - last operation was successful or if no additional information was provided - by the server. - </para> - <para> - See also <function>yaz_error</function>. - </para> - </refsect1> - </refentry> + +<refentry id="function.yaz-addinfo"> + <refnamediv> + <refname>yaz_addinfo</refname> + <refpurpose>Returns additional error information</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>string</type><methodname>yaz_addinfo</methodname> + <methodparam><type>resource</type><parameter>id</parameter></methodparam> + </methodsynopsis> + <para> + Returns additional error message for server (last request), identified by + parameter <parameter>id</parameter>. An empty string is returned if the + last operation was successful or if no additional information was provided + by the server. + </para> + <para> + See also <function>yaz_error</function>. + </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> - <methodsynopsis> - <type>int</type><methodname>yaz_ccl_conf</methodname> - <methodparam><type>resource</type><parameter>id</parameter></methodparam> - <methodparam><type>array</type><parameter>config</parameter></methodparam> - </methodsynopsis> - <para> - This function configures the CCL query parser for a server - 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 the - connection ID. - </simpara> - <programlisting role="php"> + +<refentry id="function.yaz-ccl-conf"> + <refnamediv> + <refname>yaz_ccl_conf</refname> + <refpurpose>Configure CCL parser</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>int</type><methodname>yaz_ccl_conf</methodname> + <methodparam><type>resource</type><parameter>id</parameter></methodparam> + <methodparam><type>array</type><parameter>config</parameter></methodparam> + </methodsynopsis> + <para> + This function configures the CCL query parser for a server + 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 the + connection ID. + </simpara> + <programlisting role="php"> <![CDATA[ <?php $fields["ti"] = "1=4"; @@ -44,11 +43,11 @@ yaz_ccl_conf($id, $fields); ?> ]]> - </programlisting> - </example> - </para> - </refsect1> - </refentry> + </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> - <methodsynopsis> - <type>bool</type><methodname>yaz_ccl_parse</methodname> - <methodparam><type>resource</type><parameter>id</parameter></methodparam> - <methodparam><type>string</type><parameter>query</parameter></methodparam> - <methodparam><type>array</type><parameter role="reference">result</parameter></methodparam> - </methodsynopsis> - <para> - 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 - <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> - <example> - <title>CCL Parsing</title> - <para>We will try to search using CCL. In the example below, - <literal>$ccl</literal> is a CCL query. - </para> - <programlisting role="php"> + +<refentry id="function.yaz-ccl-parse"> + <refnamediv> + <refname>yaz_ccl_parse</refname> + <refpurpose>Invoke CCL Parser</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>bool</type><methodname>yaz_ccl_parse</methodname> + <methodparam><type>resource</type><parameter>id</parameter></methodparam> + <methodparam><type>string</type><parameter>query</parameter></methodparam> + <methodparam><type>array</type><parameter role="reference">result</parameter></methodparam> + </methodsynopsis> + <para> + 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 + <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> + <example> + <title>CCL Parsing</title> + <para>We will try to search using CCL. In the example below, + <literal>$ccl</literal> is a CCL query. + </para> + <programlisting role="php"> <![CDATA[ <?php yaz_ccl_conf($id, $fields); // see example for yaz_ccl_conf @@ -49,10 +48,10 @@ } ?> ]]> - </programlisting> - </example> - </refsect1> - </refentry> + </programlisting> + </example> + </refsect1> +</refentry>  - - <refentry id="function.yaz-close"> - <refnamediv> - <refname>yaz_close</refname> - <refpurpose>Close YAZ connection</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <methodsynopsis> - <type>bool</type><methodname>yaz_close</methodname> - <methodparam><type>resource</type><parameter>id</parameter></methodparam> - </methodsynopsis> - <para> - Closes the connection given by parameter <parameter>id</parameter>. - The <parameter>id</parameter> is a connection resource as returned - by a previous call to <function>yaz_connect</function>. - </para> - <para> - &return.success; - </para> - </refsect1> - </refentry> + +<refentry id="function.yaz-close"> + <refnamediv> + <refname>yaz_close</refname> + <refpurpose>Close YAZ connection</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>bool</type><methodname>yaz_close</methodname> + <methodparam><type>resource</type><parameter>id</parameter></methodparam> + </methodsynopsis> + <para> + Closes the connection given by parameter <parameter>id</parameter>. + The <parameter>id</parameter> is a connection resource as returned + by a previous call to <function>yaz_connect</function>. + </para> + <para> + &return.success; + </para> + </refsect1> +</refentry>  - - <refentry id="function.yaz-connect"> - <refnamediv> - <refname>yaz_connect</refname> - <refpurpose> - Prepares for a connection to a Z39.50 server - </refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <methodsynopsis> - <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 connection resource on success, zero on - failure. - </para> - <para> - <function>yaz_connect</function> prepares for a connection to a - Z39.50 server. The <parameter>zurl</parameter> argument takes the form - host[:port][/database]. If port is omitted, port 210 is used. If - database is omitted <literal>Default</literal> is used. - This function is non-blocking and does not attempt to establish - a connection - it merely prepares a connect to be performed later when - <function>yaz_wait</function> is called. - </para> - <para> - If the second argument, <parameter>options</parameter>, is given as - a string it is treated as the Z39.50 V2 authentication string - (OpenAuth). - </para> - <para> - If <parameter>options</parameter> is given as an array the contents - of the array serves as options. Note that array options are only - supported for PHP 4.1.0 and later. + +<refentry id="function.yaz-connect"> + <refnamediv> + <refname>yaz_connect</refname> + <refpurpose> + Prepares for a connection to a Z39.50 server + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <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 connection resource on success, zero on + failure. + </para> + <para> + <function>yaz_connect</function> prepares for a connection to a + Z39.50 server. The <parameter>zurl</parameter> argument takes the form + host[:port][/database]. If port is omitted, port 210 is used. If + database is omitted <literal>Default</literal> is used. + This function is non-blocking and does not attempt to establish + a connection - it merely prepares a connect to be performed later when + <function>yaz_wait</function> is called. + </para> + <para> + If the second argument, <parameter>options</parameter>, is given as + a string it is treated as the Z39.50 V2 authentication string + (OpenAuth). + </para> + <para> + If <parameter>options</parameter> is given as an array the contents + of the array serves as options. Note that array options are only + supported for PHP 4.1.0 and later. - <variablelist> - <title><function>yaz_connect</function> options</title> - <varlistentry> - <term>user</term> - <listitem> - <simpara>Username for authentication.</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term>group</term> - <listitem> - <simpara>Group for authentication.</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term>password</term> - <listitem> - <simpara>Password for authentication.</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term>cookie</term> - <listitem> - <simpara>Cookie for session (YAZ proxy).</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term>proxy</term> - <listitem> - <simpara>Proxy for connection (YAZ proxy).</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term>persistent</term> - <listitem> - <simpara>A boolean. If &true; the connection is persistent; If &false; - the connection is not persistent. By default connections are persistent. - </simpara> - </listitem> - </varlistentry> - <varlistentry> - <term>piggyback</term> - <listitem> - <simpara>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. - </simpara> - </listitem> - </varlistentry> + <variablelist> + <title><function>yaz_connect</function> options</title> + <varlistentry> + <term>user</term> + <listitem> + <simpara>Username for authentication.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>group</term> + <listitem> + <simpara>Group for authentication.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>password</term> + <listitem> + <simpara>Password for authentication.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>cookie</term> + <listitem> + <simpara>Cookie for session (YAZ proxy).</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>proxy</term> + <listitem> + <simpara>Proxy for connection (YAZ proxy).</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>persistent</term> + <listitem> + <simpara>A boolean. If &true; the connection is persistent; If &false; + the connection is not persistent. By default connections are persistent. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>piggyback</term> + <listitem> + <simpara>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. + </simpara> + </listitem> + </varlistentry> - <varlistentry> - <term>charset</term> - <listitem> - <simpara>A string that specifies character set to be used - in Z39.50 language and character set negotiation. - Use strings such as: - <literal>ISO-8859-1</literal>, <literal>UTF-8</literal>, - <literal>UTF-16</literal>. - </simpara> - <simpara> - 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. - </simpara> - </listitem> - </varlistentry> + <varlistentry> + <term>charset</term> + <listitem> + <simpara>A string that specifies character set to be used + in Z39.50 language and character set negotiation. + Use strings such as: + <literal>ISO-8859-1</literal>, <literal>UTF-8</literal>, + <literal>UTF-16</literal>. + </simpara> + <simpara> + 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. + </simpara> + </listitem> + </varlistentry> - </variablelist> - </para> + </variablelist> + </para> + <para> + <note> <para> - <note> - <para> - The <ulink url="&url.yaz-proxy;">YAZ proxy</ulink> is a - freely available Z39.50 proxy. - </para> - </note> + The <ulink url="&url.yaz-proxy;">YAZ proxy</ulink> is a + freely available Z39.50 proxy. </para> - </refsect1> - </refentry> + </note> + </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> - <methodsynopsis> - <type>bool</type><methodname>yaz_database</methodname> - <methodparam><type>resource</type><parameter>id</parameter></methodparam> - <methodparam><type>string</type><parameter>databases</parameter></methodparam> - </methodsynopsis> - <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 change databases within a session. - </para> - <para> - &return.success; - </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> + <methodsynopsis> + <type>bool</type><methodname>yaz_database</methodname> + <methodparam><type>resource</type><parameter>id</parameter></methodparam> + <methodparam><type>string</type><parameter>databases</parameter></methodparam> + </methodsynopsis> + <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 change databases within a session. + </para> + <para> + &return.success; + </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> - <methodsynopsis> - <type>bool</type><methodname>yaz_element</methodname> - <methodparam><type>resource</type><parameter>id</parameter></methodparam> - <methodparam><type>string</type><parameter>elementset</parameter></methodparam> - </methodsynopsis> - <para> - 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> (for full records) and - <literal>B</literal> (for brief records). - </para> - <para> - &return.success; - </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> + <methodsynopsis> + <type>bool</type><methodname>yaz_element</methodname> + <methodparam><type>resource</type><parameter>id</parameter></methodparam> + <methodparam><type>string</type><parameter>elementset</parameter></methodparam> + </methodsynopsis> + <para> + 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> (for full records) and + <literal>B</literal> (for brief records). + </para> + <para> + &return.success; + </para> + </refsect1> +</refentry>  - - <refentry id="function.yaz-errno"> - <refnamediv> - <refname>yaz_errno</refname> - <refpurpose>Returns error number</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <methodsynopsis> - <type>int</type><methodname>yaz_errno</methodname> - <methodparam><type>resource</type><parameter>id</parameter></methodparam> - </methodsynopsis> - <para> - Returns an errornumber for the server (last request) identified by - <parameter>id</parameter>. 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 server - (after <function>yaz_wait</function> - returns) to determine the success or failure of the last - operation (e.g. search). To get a text description of the - error, call <function>yaz_error</function>. - </para> - </refsect1> - </refentry> + +<refentry id="function.yaz-errno"> + <refnamediv> + <refname>yaz_errno</refname> + <refpurpose>Returns error number</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>int</type><methodname>yaz_errno</methodname> + <methodparam><type>resource</type><parameter>id</parameter></methodparam> + </methodsynopsis> + <para> + Returns an errornumber for the server (last request) identified by + <parameter>id</parameter>. 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 server - (after <function>yaz_wait</function> + returns) to determine the success or failure of the last + operation (e.g. search). To get a text description of the + error, call <function>yaz_error</function>. + </para> + </refsect1> +</refentry>  - - <refentry id="function.yaz-error"> - <refnamediv> - <refname>yaz_error</refname> - <refpurpose>Returns error description</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <methodsynopsis> - <type>string</type><methodname>yaz_error</methodname> - <methodparam><type>resource</type><parameter>id</parameter></methodparam> - </methodsynopsis> - <para> - Returns an error text message for server (last request), identified by - parameter <parameter>id</parameter>. An empty string is returned if the - last operation was successful. - </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-error"> + <refnamediv> + <refname>yaz_error</refname> + <refpurpose>Returns error description</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>string</type><methodname>yaz_error</methodname> + <methodparam><type>resource</type><parameter>id</parameter></methodparam> + </methodsynopsis> + <para> + Returns an error text message for server (last request), identified by + parameter <parameter>id</parameter>. An empty string is returned if the + last operation was successful. + </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-es-result"> - <refnamediv> - <refname>yaz_es_result</refname> - <refpurpose> - Inspects Extended Services Result - </refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <methodsynopsis> - <type>array</type><methodname>yaz_es_result</methodname> - <methodparam><type>resource</type><parameter>id</parameter></methodparam> - </methodsynopsis> + +<refentry id="function.yaz-es-result"> + <refnamediv> + <refname>yaz_es_result</refname> + <refpurpose> + Inspects Extended Services Result + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>array</type><methodname>yaz_es_result</methodname> + <methodparam><type>resource</type><parameter>id</parameter></methodparam> + </methodsynopsis> - &warn.undocumented.func; + &warn.undocumented.func; - </refsect1> - </refentry> + </refsect1> +</refentry>  - <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 the value of the option specified with <parameter>name</parameter>. - If an option is not set, an empty string is returned. - </para> - <para> - See the description of <function>yaz_set_option</function> for - available options. - </para> - </refsect1> - </refentry> + +<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 the value of the option specified with <parameter>name</parameter>. + If an option is not set, an empty string is returned. + </para> + <para> + See the description of <function>yaz_set_option</function> for + available options. + </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> - <methodsynopsis> - <type>int</type><methodname>yaz_hits</methodname> - <methodparam><type>resource</type><parameter>id</parameter></methodparam> - </methodsynopsis> - <para> - <function>yaz_hits</function> returns the number of hits for the last - search. - </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> + <methodsynopsis> + <type>int</type><methodname>yaz_hits</methodname> + <methodparam><type>resource</type><parameter>id</parameter></methodparam> + </methodsynopsis> + <para> + <function>yaz_hits</function> returns the number of hits for the last + search. + </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> - <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> - 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="&url.yaz.ill;">this</ulink> - and the - <ulink url="&url.yaz.specs;"> - specification</ulink>. - The <parameter>args</parameter> 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> + +<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> + <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> + 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="&url.yaz.ill;">this</ulink> + and the + <ulink url="&url.yaz.specs;"> + specification</ulink>. + The <parameter>args</parameter> 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 @@ -113,21 +112,21 @@ 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> + </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> + </literallayout> + </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> - <methodsynopsis> - <type>bool</type><methodname>yaz_present</methodname> - <methodparam><type>resource</type><parameter>id</parameter></methodparam> - </methodsynopsis> - <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> - <para> - &return.success; - </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> + <methodsynopsis> + <type>bool</type><methodname>yaz_present</methodname> + <methodparam><type>resource</type><parameter>id</parameter></methodparam> + </methodsynopsis> + <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> + <para> + &return.success; + </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> - <methodsynopsis> - <type>bool</type><methodname>yaz_range</methodname> - <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 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 <parameter>start</parameter> specifies the position of the - first record to be retrieved and parameter <parameter>number</parameter> is - the number of records. Records in a result set are numbered 1, 2, ... $hits - where $hits is the count returned by <function>yaz_hits</function>. - </para> - <para> - &return.success; - </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> + <methodsynopsis> + <type>bool</type><methodname>yaz_range</methodname> + <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 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 <parameter>start</parameter> specifies the position of the + first record to be retrieved and parameter <parameter>number</parameter> is + the number of records. Records in a result set are numbered 1, 2, ... $hits + where $hits is the count returned by <function>yaz_hits</function>. + </para> + <para> + &return.success; + </para> + </refsect1> +</refentry>  - - <refentry id="function.yaz-record"> + +<refentry id="function.yaz-record"> <refnamediv> <refname>yaz_record</refname> <refpurpose>Returns a record</refpurpose> @@ -247,7 +246,7 @@ </para> </example> </refsect1> - </refentry> +</refentry>  - - <refentry id="function.yaz-scan-result"> - <refnamediv> - <refname>yaz_scan_result</refname> - <refpurpose>Returns Scan Response result</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <methodsynopsis> - <type>array</type><methodname>yaz_scan_result</methodname> - <methodparam><type>resource</type><parameter>id</parameter></methodparam> - <methodparam choice="opt"><type>array</type><parameter role="reference">result</parameter></methodparam> - </methodsynopsis> - <para> - <function>yaz_scan_result</function> returns terms and associated - information as received from the server 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 the first item is the - term, and the second item is the result-count. - If the optional parameter <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-scan-result"> + <refnamediv> + <refname>yaz_scan_result</refname> + <refpurpose>Returns Scan Response result</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>array</type><methodname>yaz_scan_result</methodname> + <methodparam><type>resource</type><parameter>id</parameter></methodparam> + <methodparam choice="opt"><type>array</type><parameter role="reference">result</parameter></methodparam> + </methodsynopsis> + <para> + <function>yaz_scan_result</function> returns terms and associated + information as received from the server 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 the first item is the + term, and the second item is the result-count. + If the optional parameter <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-scan"> - <refnamediv> - <refname>yaz_scan</refname> - <refpurpose>Prepares for a scan</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <methodsynopsis> - <type>int</type><methodname>yaz_scan</methodname> - <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, where parameter - <parameter>id</parameter> specifies connection. Starting term - point for the scan is given by <parameter>startterm</parameter>. - The form in which the starting term is specified is given by parameter - <parameter>type</parameter>. Currently only type <literal>rpn</literal> - is supported. The optional parameter <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 transfer the Scan Request to the server 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> + +<refentry id="function.yaz-scan"> + <refnamediv> + <refname>yaz_scan</refname> + <refpurpose>Prepares for a scan</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>int</type><methodname>yaz_scan</methodname> + <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, where parameter + <parameter>id</parameter> specifies connection. Starting term + point for the scan is given by <parameter>startterm</parameter>. + The form in which the starting term is specified is given by parameter + <parameter>type</parameter>. Currently only type <literal>rpn</literal> + is supported. The optional parameter <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 transfer the Scan Request to the server 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 role="php"> <![CDATA[ @@ -69,10 +68,10 @@ ?> ]]> </programlisting> - </example> - </para> - </refsect1> - </refentry> + </example> + </para> + </refsect1> +</refentry>  - <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> + +<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>  - - <refentry id="function.yaz-search"> - <refnamediv> - <refname>yaz_search</refname> - <refpurpose>Prepares for a search</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <methodsynopsis> - <type>int</type><methodname>yaz_search</methodname> - <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 - connection given by parameter <parameter>id</parameter>. - The parameter <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> - </refsect1> - <refsect1> - <title>The RPN query</title> - <para> - 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 (<literal>@</literal>) are considered operators, - otherwise they are treated as search terms. - </para> - <table> - <title>RPN Operators</title> - <tgroup cols="2"> - <colspec colwidth="1*" colname="construct"/> - <colspec colwidth="2*" colname="description"/> - <thead> - <row> - <entry>Construct</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <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> - </tbody> - </tgroup> - </table> - <example> - <title>Query Examples</title> - <para> - You can search for simple terms, like this - <screen>computer</screen> - which matches documents where "computer" occur. - No attributes are specified. - </para> - <para> - The Query - <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> - 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: + +<refentry id="function.yaz-search"> + <refnamediv> + <refname>yaz_search</refname> + <refpurpose>Prepares for a search</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>int</type><methodname>yaz_search</methodname> + <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 + connection given by parameter <parameter>id</parameter>. + The parameter <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> + </refsect1> + <refsect1> + <title>The RPN query</title> + <para> + 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 (<literal>@</literal>) are considered operators, + otherwise they are treated as search terms. + </para> + <table> + <title>RPN Operators</title> + <tgroup cols="2"> + <colspec colwidth="1*" colname="construct"/> + <colspec colwidth="2*" colname="description"/> + <thead> + <row> + <entry>Construct</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <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> + </tbody> + </tgroup> + </table> + <example> + <title>Query Examples</title> + <para> + You can search for simple terms, like this + <screen>computer</screen> + which matches documents where "computer" occur. + No attributes are specified. + </para> + <para> + The Query + <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> + 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=2000 company</screen> - The query as a whole uses the GILS attributeset. The query matches - 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> + The query as a whole uses the GILS attributeset. The query matches + 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>  - <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> - <methodsynopsis> - <type>string</type><methodname>yaz_set_option</methodname> - <methodparam><type>resource</type><parameter>id</parameter></methodparam> - <methodparam><type>array</type><parameter>options</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 server</entry> - </row> - <row> - <entry>implementationVersion</entry> - <entry>implementation version of server</entry> - </row> - <row> - <entry>implementationId</entry> - <entry>implementation ID of server</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>. - First record is numbered has a start value of 0. Second record has - start value 1. - 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> + +<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> + <methodsynopsis> + <type>string</type><methodname>yaz_set_option</methodname> + <methodparam><type>resource</type><parameter>id</parameter></methodparam> + <methodparam><type>array</type><parameter>options</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 server</entry> + </row> + <row> + <entry>implementationVersion</entry> + <entry>implementation version of server</entry> + </row> + <row> + <entry>implementationId</entry> + <entry>implementation ID of server</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>. + First record is numbered has a start value of 0. Second record has + start value 1. + 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>  - - <refentry id="function.yaz-sort"> - <refnamediv> - <refname>yaz_sort</refname> - <refpurpose>Sets sorting criteria</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <methodsynopsis> - <type>int</type><methodname>yaz_sort</methodname> - <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. - Call this function <emphasis>before</emphasis> - <function>yaz_search</function>. - Using this function alone does not have any effect. When used 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 (<function>yaz_present</function>. The parameter - <parameter>criteria</parameter> takes the form - </para> - <para> - <replaceable>field1 flags1 field2 flags2</replaceable> ... - </para> - <para> - where field1 specifies the primary attributes for sort, field2 seconds, - etc.. The field specifies either a numerical attribute combinations consisting - of type=value pairs separated by comma (e.g. <literal>1=4,2=1</literal>) - ; or the field may specify a plain string criteria - (e.g. <literal>title</literal>. The flags is a sequence of the following - characters which may not be separated by any white space. - </para> - <variablelist> - <title>Sort Flags</title> - <varlistentry><term><literal>a</literal></term><listitem> - <simpara>Sort ascending</simpara></listitem> - </varlistentry> - <varlistentry><term><literal>d</literal></term><listitem> - <simpara>Sort descending</simpara></listitem> - </varlistentry> - <varlistentry><term><literal>i</literal></term><listitem> - <simpara>Case insensitive sorting</simpara></listitem> - </varlistentry> - <varlistentry><term><literal>s</literal></term><listitem> - <simpara>Case sensitive sorting</simpara></listitem> - </varlistentry> - </variablelist> - <example> - <title>Sort Criterias</title> - <para> - To sort on Bib1 attribute title, case insensitive, - and ascending you would use the following sort criteria: - <screen> - 1=4 ia - </screen> - </para> - <para> - If the secondary sorting criteria should be author, case sensitive - and ascending you would use: - <screen> - 1=4 ia 1=1003 sa - </screen> - </para> - </example> - </refsect1> - </refentry> + +<refentry id="function.yaz-sort"> + <refnamediv> + <refname>yaz_sort</refname> + <refpurpose>Sets sorting criteria</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <methodsynopsis> + <type>int</type><methodname>yaz_sort</methodname> + <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. + Call this function <emphasis>before</emphasis> + <function>yaz_search</function>. + Using this function alone does not have any effect. When used 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 (<function>yaz_present</function>. The parameter + <parameter>criteria</parameter> takes the form + </para> + <para> + <replaceable>field1 flags1 field2 flags2</replaceable> ... + </para> + <para> + where field1 specifies the primary attributes for sort, field2 seconds, + etc.. The field specifies either a numerical attribute combinations consisting + of type=value pairs separated by comma (e.g. <literal>1=4,2=1</literal>) + ; or the field may specify a plain string criteria + (e.g. <literal>title</literal>. The flags is a sequence of the following + characters which may not be separated by any white space. + </para> + <variablelist> + <title>Sort Flags</title> + <varlistentry><term><literal>a</literal></term><listitem> + <simpara>Sort ascending</simpara></listitem> + </varlistentry> + <varlistentry><term><literal>d</literal></term><listitem> + <simpara>Sort descending</simpara></listitem> + </varlistentry> + <varlistentry><term><literal>i</literal></term><listitem> + <simpara>Case insensitive sorting</simpara></listitem> + </varlistentry> + <varlistentry><term><literal>s</literal></term><listitem> + <simpara>Case sensitive sorting</simpara></listitem> + </varlistentry> + </variablelist> + <example> + <title>Sort Criterias</title> + <para> + To sort on Bib1 attribute title, case insensitive, + and ascending you would use the following sort criteria: + <screen> + 1=4 ia + </screen> + </para> + <para> + If the secondary sorting criteria should be author, case sensitive + and ascending you would use: + <screen> + 1=4 ia 1=1003 sa + </screen> + </para> + </example> + </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> - <methodsynopsis> - <type>int</type><methodname>yaz_syntax</methodname> - <methodparam><type>resource</type><parameter>id</parameter></methodparam> - <methodparam><type>string</type><parameter>syntax</parameter></methodparam> - </methodsynopsis> - <para> - 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 should be called before - <function>yaz_search</function> or <function>yaz_present</function>. - </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> + <methodsynopsis> + <type>int</type><methodname>yaz_syntax</methodname> + <methodparam><type>resource</type><parameter>id</parameter></methodparam> + <methodparam><type>string</type><parameter>syntax</parameter></methodparam> + </methodsynopsis> + <para> + 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 should be called before + <function>yaz_search</function> or <function>yaz_present</function>. + </para> + </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> - <methodsynopsis> - <type>int</type><methodname>yaz_wait</methodname> - <methodparam choice="opt"><type>array</type><parameter role="reference">options</parameter></methodparam> - </methodsynopsis> - <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 servers have either - completed all requests or aborted (in case of errors). - </para> - <para> - If the <parameter>options</parameter> array is given that holds - options that change the behaviour of <function>yaz_wait</function>. - </para> - <variablelist> - <varlistentry> - <term><literal>timeout</literal></term> - <listitem> - <para> - Sets timeout in seconds. If a server has not responded within - the timeout it is considered dead and <function>yaz_wait</function> - returns. The default value for timeout is 15 seconds. - </para> - </listitem> - </varlistentry> - </variablelist> - </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> + <methodsynopsis> + <type>int</type><methodname>yaz_wait</methodname> + <methodparam choice="opt"><type>array</type><parameter role="reference">options</parameter></methodparam> + </methodsynopsis> + <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 servers have either + completed all requests or aborted (in case of errors). + </para> + <para> + If the <parameter>options</parameter> array is given that holds + options that change the behaviour of <function>yaz_wait</function>. + </para> + <variablelist> + <varlistentry> + <term><literal>timeout</literal></term> + <listitem> + <para> + Sets timeout in seconds. If a server has not responded within + the timeout it is considered dead and <function>yaz_wait</function> + returns. The default value for timeout is 15 seconds. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> <!-- Keep this comment at the end of the file Local variables: