Changes

Jump to navigation Jump to search
234 bytes added ,  15:45, 10 August 2022
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 same server instance in your query. See the following example:
<pre classsyntaxhighlight lang="brush:xquery">
(: Retrieve documents from database :)
let $client-id := client:connect('localhost', 1984, 'admin', 'admin...')let $docs := client:query($client-id, 'db:openget("conflict")')
(: Create database with same name :)
return db:create('conflict', $docs, $docs ! db:path(.))
</presyntaxhighlight>
The read-only query cannot be processed, because the <code>conflict</code> database is currently write-locked by the main query. See [[Transaction Management]] for more background information.
=Conventions=
 
{{Mark|Updated with Version 9.0:}}
All functions and errors in this module are assigned to the <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='120' | '''Signatures'''
|{{Func|client:connect|$host as xs:string, $port as xs:integer, $user username as xs:string, $password as xs:string|xs:anyURI}}<br/ >|-valign="top"
|'''Summary'''
|This function establishes a connection to a remote BaseX server, creates a new client session, and returns a session id. The parameter {{Code|$host}} is the name of the database server, {{Code|$port}} specifies the server port, and {{Code|$userusername}} and {{Code|$password}} represent the login data.|-valign="top"
|'''Errors'''
|{{Error|connect|#Errors}} an error occurs while creating the session (possible reasons: server not available, access denied).<br/>
{| width='100%'
|-valign="top"
| width='120' | '''Signatures'''
|{{Func|client:execute|$id as xs:anyURI, $command as xs:string|xs:string}}
|-valign="top"
| '''Summary'''
| This function executes a [[Commands|command]] and returns the result as a string. The parameter {{Code|$id}} contains the session id ID returned by [[Client Module#client:connect{{Function||client:connect]]}}. The {{Code|$command}} argument represents a single command, which will be executed by the server.|-valign="top"
|'''Errors'''
|{{Error|error|#Errors}} an I/O error occurs while transferring data from or to the server.<br/>{{Error|command|#Errors}} an error occurs while executing a command.
|-valign="top"
| '''Examples'''
|The following query creates a new database {{Code|TEST}} on a remote BaseX server:
<pre classsyntaxhighlight lang="brush:xquery">client:connect('basex.server.org', 8080, 'admin', 'admin...') !
client:execute(., 'create database TEST')
</presyntaxhighlight>
|}
{| 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 [[#client:execute{{Function||client:execute]]}}. {{Code|$id}} specifies the session id.
|}
{| width='100%'
|-valign="top"
| width='120' | '''Signatures'''
|{{Func|client:query|$id as xs:anyURI, $query as xs:string|item()*}}<br/>{{Func|client:query|$id as xs:anyURI, $query as xs:string, $bindings as map(*)?|item()*}}
|-valign="top"
| '''Summary'''
|Evaluates a query and returns the result as sequence. The parameter {{Code|$id}} contains the session id returned by [[Client Module#client:connect{{Function||client:connect]]}}, and {{Code|$query}} represents the 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.<br/>{{Error|query|#Errors}} an error occurs while evaluating a query, and if the original 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}}:
<pre classsyntaxhighlight lang="brush:xquery">let $c := client:connect('localhost', 1984, 'admin', 'admin...')
return client:query($c, "declare variable $n external; $n * 2", map { 'n': 123 })
</presyntaxhighlight>
The following query performs a query on a first server, the results of which are passed on to a second server:
<pre classsyntaxhighlight lang="brush: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')
</presyntaxhighlight>
|}
{| width='100%'
|-valign="top"
| width='120' | '''Signatures'''
|{{Func|client:close|$id as xs:anyURI|empty-sequence()}}
|-valign="top"
| '''Summary'''
| This function closes a client session. {{Code|$id}} specifies the session id.<br/>Opened connections will automatically be closed after the XQuery expression has been evaluated, but it is recommendable to explicitly close them with this function if you open many connections.
|-valign="top"
|'''Errors'''
|{{Error|error|#Errors}} an I/O error occurs while transferring data from or to the server.
=Errors=
 
{{Mark|Updated with Version 9.0:}}
{| 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}}
| An I/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 the XQuery error cannot be extracted from the returned error string.
;Version 8.0
* Updated: Bound values may now contain no or more than one item in [[#client:query{{Function||client:query]]}}.
;Version 7.5
* Added: [[#client:info{{Function||client:info]]}}
The module was introduced with Version 7.3.
Bureaucrats, editor, reviewer, Administrators
13,550

edits

Navigation menu