Changes

This [[Module Library|XQuery Module]] contains functions to access remote BaseX server instances from XQuery. With this module, you can on the one hand execute database commands and on evaluate XQuery expressions. Please note that the other hand client module should always be used to address independent BaseX server instances. You can create deadlocks if you evaluate queriesa query with a server instance, and if you are addressing the same server instance in your query. See the following example: <pre class="brush:xquery">(: Retrieve documents from database :)let $client-id := client:connect('localhost', 1984, 'admin', 'admin')let $docs := client:query($client-id, 'db:open("conflict")')(: Create database with same name :)return db:create('conflict', $docs, $docs ! db:path(.)) </pre> The read-only query cannot be processed, because the <code>conflict</code> database is currently write-locked by the results of which are returned as XDM sequencesmain query. See [[Transaction Management]] for more background information.

All functions and errors in this module are assigned to the {{Code|<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|http://basex.org/errors}} namespace, which is statically bound to the {{Code|bxerr}} prefix.

 {|width='100%'

| width='90120' | '''Signatures'''

|{{Error|BXCL0001connect|#Errors}} an error occurs while creating the session (possible reasons: server not available, access denied).<br/>

 {|width='100%'

| width='90120' | '''Signatures'''|{{Func|client:execute|$id as xs:anyURI, $command as xs:string|xs:string?}}

| This function executes a [[CommandCommands|command]] and returns a the result as string, if available. The parameter {{Code|$id}} contains the session id returned by [[Client Module#client:connect|client:connect]]. The {{Code|$command}} argument represents the database a single command string, which will be executed by the server.

|{{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.

{{Mark|Introduced with Version 7.4:}}{|width='100%'

| width='90120' | '''Signatures'''

| This function returns an information string, created by a previous the last call of [[#client:execute|client:execute]]. {{Code|$id}} specifies the session id.

 {|width='100%'

| width='90120' | '''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()*}}

|Evaluates a query and returns the result as sequence. The parameter {{Code|$id}} contains the session id returned by [[Client Module#client:connect|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, the values can be arbitrary items:* variables specified as QNames If a key is a QName, it will be directly interpreted adopted as variable name.* variables specified as xs:If a key is a string , it may be prefixed with a dollar sign. Namespace 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.

|{{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|function|#Errors}} function items (including maps and arrays) cannot be returned.

return client:query($c, "declare variable $n external; $n * 2", map{ 'n' := 123 })

 {|width='100%'

| width='90120' | '''Signatures'''

| 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.

|{{Error|BXCL0003error|#Errors}} an I/O error occurs while transferring data from or to the server.

! width="5%110"|Code! width="95%"|Description

|{{Code|BXCL0001command}}| An error occurred while executing a command.|-|{{Code|connect}}

|{{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}}

;Version 9.0 * Updated: error codes updated; errors now use the module namespace ;Version 8.0 * Updated: Bound values may now contain no or more than one item in [[#client:query|client:query]]. ;Version 7.45