Changes

This [[Module Library|XQuery Module]] contains functions to access remote BaseX server instances from XQuery. With this module, you can both execute database commands and perform queriesevaluate XQuery expressions. Please note that the client module should always be used to address independent BaseX server instances. You can create deadlocks if you evaluate a query with a server instance, and if you are addressing the result sets are returned as valid sequences using same server instance in your query. See the correct XDM data typesfollowing example: <syntaxhighlight lang="xquery">(: Retrieve documents from database :)let $client-id := client:connect('localhost', 1984, 'admin', '...')let $docs := client:query($client-id, 'db:get("conflict")')(: Create database with same name :)return db:create('conflict', $docs, $docs ! db:path(. All functions use )) </syntaxhighlight> The read-only query cannot be processed, because the <code>clientconflict</code> prefix, which database is linked currently write-locked by the main query. See [[Transaction Management]] for more background information. =Conventions= All functions and errors in this module are assigned to the statically declared <code><nowiki>http://basex.org/modules/client</nowiki></code> namespace, which is statically bound to the {{Code|client}} prefix.<br/>

 {|width='100%'|-| valign='"top' "| width='90120' | '''Signatures'''|<code><b>{{Func|client:connect</b>(|$host as xs:string, $post port as xs:integer, $user username as xs:string, $password as xs:string) as |xs:anyURI</code>}}<br/ >|-| valign='"top' "| '''Summary'''|This function establishes a connection to a remote BaseX server and , creates a new client session. As a result, and returns a session id is returned. The parameter <code>{{Code|$host</code> }} is the name of the database server, <code>{{Code|$host</code> port}} specifies the database hostserver port, and <code>{{Code|$user</code> username}} and <code>{{Code|$password</code> }} represent the login data.|-| valign='"top' "| '''Errors'''|<b>BXCL0001</b> is raised if a connection {{Error|connect|#Errors}} an error occurs while creating the session (e.g., if the addressed possible reasons: server is not available, access denied).<br/>

 {|width='100%'|-| valign='"top' "| width='90120' | '''Signatures'''|<code><b>{{Func|client:execute</b>(|$id as xs:anyURI, $command as xs:string) as |xs:string</code>}}|-| valign='"top' "| '''Summary'''| This function executes a database [[Commands|command ]] and returns the result as a string. The parameter <code>{{Code|$id</code> }} contains the session id ID returned by [[Client Module#client:connect{{Function||client:connect()]]}}. The <code>{{Code|$command</code> }} argument represents the database a single command string, which will be executed by the server.|-| valign='"top' "| '''Errors'''|<b>BXCL0002<{{Error|error|#Errors}} an I/b> is raised if O error occurs while transferring data from or to the specified session id is unknownserver.<br/><b>BXCL0003</b> is raised if {{Error|command|#Errors}} an error occurs while executing the a command.|- valign="top"| '''Examples'''|The following query creates a new database {{Code|TEST}} on a remote BaseX server:<syntaxhighlight lang="xquery">client:connect('basex.server.org', 8080, 'admin', '...') ! client:execute(., 'create database TEST')<br/syntaxhighlight>|} ==client:info== {| width='100%'|- valign="top"| width='120' | '''Signatures'''|{{Func|client:info|$id as xs:anyURI|xs:string}}|- valign="top"| '''Summary'''| This function returns an information string, created by the last call of {{Function||client:execute}}. {{Code|$id}} specifies the session id.

 {|width='100%'|-| valign='"top' "| width='90120' | '''Signatures'''|<code><b>{{Func|client:query|$id as xs:anyURI, $query as xs:string|item()*}}<br/b>({{Func|client:query|$id as xs:anyURI, $query as xs:string, $bindings as map(*) as ?|item()*</code>}}|-| valign='"top' "| '''Summary'''| This function evaluates Evaluates a query and returns the result as sequence. The parameter <code>{{Code|$id</code> }} contains the session id returned by [[Client Module#client:connect{{Function||client:connect()]]}}, and <code>{{Code|$query</code> }} represents the queru query string, which will be evaluated by the server.<br />Variables and the context item can be declared via {{Code|$bindings}}. The specified keys must be QNames or strings:* If a key is a QName, it will be directly adopted as variable name.* If a key is a string, it may be prefixed with a dollar sign. A namespace can be specified using the [http://www.jclark.com/xml/xmlns.htm Clark Notation]. If the specified string is empty, the value will be bound to the context item.|-| valign='"top' "| '''Errors'''|{{Error|error|#Errors}} an I/O error occurs while transferring data from or to the server.<b>BXCL0002<br/b> is raised {{Error|query|#Errors}} an error occurs while evaluating a query, and if the specified session id is unknownoriginal error cannot be extracted from the returned error string.<br/>{{Error|function|#Errors}} function items (including maps and arrays) cannot be returned.|- valign="top"| '''Examples'''|The following query sends a query on a local server instance, binds the integer {{Code|123}} to the variable {{Code|$n}} and returns {{Code|246}}:<bsyntaxhighlight lang="xquery">BXCL0003let $c := client:connect('localhost', 1984, 'admin', '...')return client:query($c, "declare variable $n external; $n * 2", map { 'n': 123 })</bsyntaxhighlight> is raised if an error occurs while evaluating The following query performs a query on a first server, the results of which are passed on to a second server:<syntaxhighlight lang="xquery">let $c1 := client:connect('basex1.server.org', 8080, 'jack', 'C0S19tt2X')let $c2 := client:connect('basex2.server.org', 8080, 'john', '465wFHe26')for $it in client:query($c1, '1 to 10')return client:query.($c2, $it || '* 2')<br/syntaxhighlight>

 {|width='100%'|-| valign='"top' "| width='90120' | '''Signatures'''|<code><b>{{Func|client:close</b>(|$id as xs:anyURI) as |empty-sequence()</code>}}|-| valign='"top' "| '''Summary'''| This function closes a client session. <code>{{Code|$id}} specifies the session id.<br/code> specifies Opened connections will automatically be closed after the session idXQuery expression has been evaluated, but it is recommendable to explicitly close them with this function if you open many connections.|-| valign='"top' "| '''Errors'''|<b>[[XQuery Errors{{Error|error|#SQL Functions Errors|FOSQ0001]]<}} an I/b> is raised if an SQL exception O error occurswhile transferring data from or to the server.<br/ ><b>[[XQuery Errors#SQL Functions |} =Errors= {| class="wikitable" width="100%"! width="110"|Code|Description|- valign="top"|{{Code|command}}| An error occurred while executing a command.|- valign="top"|{{Code|connect}}| An error occurred while creating a new session (possible reasons: server not available, access denied).|- valign="top"|{{Code|error}}|FOSQ0002]]<An I/b> O error occurred while transferring data from or to the server.|- valign="top"|{{Code|function}}| Function items (including maps and arrays) cannot be returned.|- valign="top"|{{Code|id}}| The id with the specified session is unknown, or has already been closed.|- valign="top"|{{Code|query}}| An error occurred while evaluating a query. Will only be raised if a wrong connection handle is passedthe XQuery error cannot be extracted from the returned error string.<br/ >

The ;Version 9.0 * Updated: error codes updated; errors now use the module was introduced with namespace ;Version 78.20 * Updated: Bound values may now contain no or more than one item in {{Function||client:query}}.2 ;Version 7.5 * Added: {{Function||client:info}}