Difference between revisions of "Client Module"
Jump to navigation
Jump to search
m (Text replace - "| valign='top' | " to "| ") |
|||
Line 27: | Line 27: | ||
|<code><b>client:execute</b>($id as xs:anyURI, $command as xs:string) as xs:string</code> | |<code><b>client:execute</b>($id as xs:anyURI, $command as xs:string) as xs:string</code> | ||
|- | |- | ||
− | + | | '''Summary''' | |
| This function executes a database command and returns the result as string. The parameter <code>$id</code> contains the session id returned by [[Client Module#client:connect|client:connect()]]. The <code>$command</code> represents the database command string, which will be executed by the server. | | This function executes a database command and returns the result as string. The parameter <code>$id</code> contains the session id returned by [[Client Module#client:connect|client:connect()]]. The <code>$command</code> represents the database command string, which will be executed by the server. | ||
|- | |- | ||
Line 33: | Line 33: | ||
|'''[[#Errors|BXCL0003]]''' is raised if an I/O error occurs while transferring data from or to the server.<br/>'''[[#Errors|BXCL0004]]''' is raised if an error occurs while executing a command. | |'''[[#Errors|BXCL0003]]''' is raised if an I/O error occurs while transferring data from or to the server.<br/>'''[[#Errors|BXCL0004]]''' is raised if an error occurs while executing a command. | ||
|- | |- | ||
− | + | | '''Examples''' | |
|The following query creates a new database <code>TEST</code> on a remote BaseX server: | |The following query creates a new database <code>TEST</code> on a remote BaseX server: | ||
<pre class="brush:xquery"> | <pre class="brush:xquery"> | ||
Line 47: | Line 47: | ||
|<code><b>client:query</b>($id as xs:anyURI, $query as xs:string) as item()*</code> | |<code><b>client:query</b>($id as xs:anyURI, $query as xs:string) as item()*</code> | ||
|- | |- | ||
− | + | | '''Summary''' | |
| This function evaluates a query and returns the result as sequence. The parameter <code>$id</code> contains the session id returned by [[Client Module#client:connect|client:connect()]], and <code>$query</code> represents the query string, which will be evaluated by the server. | | This function evaluates a query and returns the result as sequence. The parameter <code>$id</code> contains the session id returned by [[Client Module#client:connect|client:connect()]], and <code>$query</code> represents the query string, which will be evaluated by the server. | ||
|- | |- | ||
Line 53: | Line 53: | ||
|'''[[#Errors|BXCL0003]]''' is raised if an I/O error occurs while transferring data from or to the server.<br/>'''[[#Errors|BXCL0005]]''' is raised if an error occurs while evaluating a query, and if the original error cannot be extracted from the returned error string. | |'''[[#Errors|BXCL0003]]''' is raised if an I/O error occurs while transferring data from or to the server.<br/>'''[[#Errors|BXCL0005]]''' is raised if an error occurs while evaluating a query, and if the original error cannot be extracted from the returned error string. | ||
|- | |- | ||
− | + | | '''Examples''' | |
|The following query performs a query on a first server, the results of which are passed on to a second server: | |The following query performs a query on a first server, the results of which are passed on to a second server: | ||
<pre class="brush:xquery"> | <pre class="brush:xquery"> | ||
Line 70: | Line 70: | ||
|<code><b>client:close</b>($id as xs:anyURI) as empty-sequence()</code> | |<code><b>client:close</b>($id as xs:anyURI) as empty-sequence()</code> | ||
|- | |- | ||
− | + | | '''Summary''' | |
| This function closes a client session. <code>$id</code> specifies the session id.<br/>At the end of query execution, open sessions will be automatically closed. | | This function closes a client session. <code>$id</code> specifies the session id.<br/>At the end of query execution, open sessions will be automatically closed. | ||
|- | |- |
Revision as of 00:42, 26 May 2012
This 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 the other hand evaluate queries, the results of which are returned as XDM sequences.
Contents
Conventions
All functions in this module are assigned to the http://basex.org/modules/client
namespace, which is statically bound to the client
prefix.
All errors are assigned to the http://basex.org/errors
namespace, which is statically bound to the bxerr
prefix.
Functions
client:connect
Signatures | client:connect($host as xs:string, $port as xs:integer, $user as xs:string, $password as xs:string) as xs:anyURI |
Summary | This function establishes a connection to a remote BaseX server, creates a new client session, and returns a session id. The parameter $host is the name of the database server, $port specifies the server port, and $user and $password represent the login data.
|
Errors | BXCL0001 is raised if an error occurs while creating the session (possible reasons: server not available, access denied). |
client:execute
Signatures | client:execute($id as xs:anyURI, $command as xs:string) as xs:string
|
Summary | This function executes a database command and returns the result as string. The parameter $id contains the session id returned by client:connect(). The $command represents the database command string, which will be executed by the server.
|
Errors | BXCL0003 is raised if an I/O error occurs while transferring data from or to the server. BXCL0004 is raised if an error occurs while executing a command. |
Examples | The following query creates a new database TEST on a remote BaseX server:
let $c := client:connect('basex.server.org', 8080, 'admin', 'admin') return client:execute($c, 'create database TEST') |
client:query
Signatures | client:query($id as xs:anyURI, $query as xs:string) as item()*
|
Summary | This function evaluates a query and returns the result as sequence. The parameter $id contains the session id returned by client:connect(), and $query represents the query string, which will be evaluated by the server.
|
Errors | BXCL0003 is raised if an I/O error occurs while transferring data from or to the server. BXCL0005 is raised if an error occurs while evaluating a query, and if the original error cannot be extracted from the returned error string. |
Examples | The following query performs a query on a first server, the results of which are passed on to a second server:
let $c1 := client:connect('server1.basex.org', 8080, 'jack', 'C0S19tt2X') let $c2 := client:connect('server2.basex.org', 8080, 'john', '465wFHe26') return for $c in client:query($c1, '1 to 10') return client:query($c1, $c || '* 2') |
client:close
Signatures | client:close($id as xs:anyURI) as empty-sequence()
|
Summary | This function closes a client session. $id specifies the session id.At the end of query execution, open sessions will be automatically closed. |
Errors | BXCL0003 is raised if an I/O error occurs while transferring data from or to the server. |
Errors
Code | Description |
---|---|
BXCL0001
|
An error occurred while creating a new session (possible reasons: server not available, access denied). |
BXCL0002
|
The specified session is unknown, or has already been closed. |
BXCL0003
|
An I/O error occurred while transferring data from or to the server. |
BXCL0004
|
An error occurred while executing a command. |
BXCL0005
|
An error occurred while evaluating a query. Will only be raised if the XQuery error cannot be extracted from the returned error string. |
Changelog
The module was introduced with Version 7.2.2.