Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
|-
|{{Code|BXCL0006}}
| Function items (including maps and arrays) cannot be returned.
no edit summary
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')
(: 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=
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/>All errors are assigned to the <code><nowiki>http://basex.org/errors</nowiki></code> namespace, which is statically bound to the {{Code|bxerr}} prefix.
=Functions=
==client:connect==
{| width='100%'
|-
|-
|'''Errors'''
|{{Error|BXCL0001connect|#Errors}} an error occurs while creating the session (possible reasons: server not available, access denied).<br/>
|}
==client:execute==
{| width='100%'
|-
|-
|'''Errors'''
|{{Error|BXCL0003error|#Errors}} an I/O error occurs while transferring data from or to the server.<br/>{{Error|BXCL0004command|#Errors}} an error occurs while executing a command.
|-
| '''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>
|}
|-
|'''Errors'''
|{{Error|BXCL0003error|#Errors}} an I/O error occurs while transferring data from or to the server.<br/>{{Error|BXCL0005query|#Errors}} an error occurs while evaluating a query, and if the original error cannot be extracted from the returned error string.<br/>{{Error|BXCL0006function|#Errors}} function items (including maps and arrays) cannot be returned.
|-
| '''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>
|}
==client:close==
{| width='100%'
|-
|-
| '''Summary'''
| This function closes a client session. {{Code|$id}} specifies the session id.<br/>At Opened connections will automatically be closed after the end of query executionXQuery expression has been evaluated, but it is recommendable to explicitly close them with this function if you open sessions will be automatically closedmany connections.
|-
|'''Errors'''
|{{Error|BXCL0003error|#Errors}} an I/O error occurs while transferring data from or to the server.
|}
|Description
|-
|{{Code|BXCL0001command}}| An error occurred while executing a command.|-|{{Code|connect}}
| An error occurred while creating a new session (possible reasons: server not available, access denied).
|-
|{{Code|BXCL0002error}}| The specified session is unknown, An I/O error occurred while transferring data from or has already been closedto the server.
|-
|{{Code|BXCL0003function}}| An I/O error occurred while transferring data from or to the serverFunction items (including maps and arrays) cannot be returned.
|-
|{{Code|BXCL0004id}}| An error occurred while executing a commandThe id with the specified session is unknown, or has already been closed.
|-
|{{Code|BXCL0005query}}
| An error occurred while evaluating a query. Will only be raised if the XQuery error cannot be extracted from the returned error string.
|}
=Changelog=
;Version 9.0
* Updated: error codes updated; errors now use the module namespace
;Version 8.0
