Difference between revisions of "Client Module"

From BaseX Documentation
Jump to navigation Jump to search
Line 3: Line 3:
 
=Conventions=
 
=Conventions=
  
All functions in this module are assigned to the <code>http://basex.org/modules/client</code> namespace, which is statically bound to the <code>client</code> prefix.<br/>
+
All functions in this module are assigned to the {{Code|http://basex.org/modules/client}} namespace, which is statically bound to the {{Code|client}} prefix.<br/>
All errors are assigned to the <code>http://basex.org/errors</code> namespace, which is statically bound to the <code>bxerr</code> prefix.
+
All errors are assigned to the {{Code|http://basex.org/errors}} namespace, which is statically bound to the {{Code|bxerr}} prefix.
  
 
=Functions=
 
=Functions=
Line 12: Line 12:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
|<code><b>client:connect</b>($host as xs:string, $port as xs:integer, $user as xs:string, $password as xs:string) as xs:anyURI</code><br/ >
+
|{{Func|client:connect|$host as xs:string, $port as xs:integer, $user as xs:string, $password as xs:string|xs:anyURI}}<br/ >
 
|-
 
|-
 
|'''Summary'''
 
|'''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</code> is the name of the database server, <code>$port</code> specifies the server port, and <code>$user</code> and <code>$password</code> represent the login data.
+
|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|$user}} and {{Code|$password}} represent the login data.
 
|-
 
|-
 
|'''Errors'''
 
|'''Errors'''
Line 25: Line 25:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
|<code><b>client:execute</b>($id as xs:anyURI, $command as xs:string) as xs:string</code>
+
|{{Func|client:execute|$id as xs:anyURI, $command as xs:string|xs:string}}
 
|-
 
|-
 
| '''Summary'''
 
| '''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}} contains the session id returned by [[Client Module#client:connect|client:connect()]]. The {{Code|$command}} represents the database command string, which will be executed by the server.
 
|-
 
|-
 
|'''Errors'''
 
|'''Errors'''
Line 34: Line 34:
 
|-
 
|-
 
| '''Examples'''
 
| '''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}} on a remote BaseX server:
 
<pre class="brush:xquery">
 
<pre class="brush:xquery">
 
let $c := client:connect('basex.server.org', 8080, 'admin', 'admin')
 
let $c := client:connect('basex.server.org', 8080, 'admin', 'admin')
Line 45: Line 45:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
|<code><b>client:query</b>($id as xs:anyURI, $query as xs:string) as item()*</code>
+
|{{Func|client:query|$id as xs:anyURI, $query as xs:string|item()*}}
 
|-
 
|-
 
| '''Summary'''
 
| '''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}} 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.
 
|-
 
|-
 
|'''Errors'''
 
|'''Errors'''
Line 68: Line 68:
 
|-
 
|-
 
| width='90' | '''Signatures'''
 
| width='90' | '''Signatures'''
|<code><b>client:close</b>($id as xs:anyURI) as empty-sequence()</code>
+
|{{Func|client:close|$id as xs:anyURI|empty-sequence()}}
 
|-
 
|-
 
| '''Summary'''
 
| '''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}} specifies the session id.<br/>At the end of query execution, open sessions will be automatically closed.
 
|-
 
|-
 
|'''Errors'''
 
|'''Errors'''
Line 83: Line 83:
 
! width="95%"|Description
 
! width="95%"|Description
 
|-
 
|-
|<code>BXCL0001</code>
+
|{{Code|BXCL0001}}
 
| An error occurred while creating a new session (possible reasons: server not available, access denied).
 
| An error occurred while creating a new session (possible reasons: server not available, access denied).
 
|-
 
|-
|<code>BXCL0002</code>
+
|{{Code|BXCL0002}}
 
| The specified session is unknown, or has already been closed.
 
| The specified session is unknown, or has already been closed.
 
|-
 
|-
|<code>BXCL0003</code>
+
|{{Code|BXCL0003}}
 
| An I/O error occurred while transferring data from or to the server.
 
| An I/O error occurred while transferring data from or to the server.
 
|-
 
|-
|<code>BXCL0004</code>
+
|{{Code|BXCL0004}}
 
| An error occurred while executing a command.
 
| An error occurred while executing a command.
 
|-
 
|-
|<code>BXCL0005</code>
+
|{{Code|BXCL0005}}
 
| An error occurred while evaluating a query. Will only be raised if the XQuery error cannot be extracted from the returned error string.
 
| An error occurred while evaluating a query. Will only be raised if the XQuery error cannot be extracted from the returned error string.
 
|}
 
|}

Revision as of 14:28, 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.

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: 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: an I/O error occurs while transferring data from or to the server.
BXCL0004: 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: an I/O error occurs while transferring data from or to the server.
BXCL0005: 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: 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.