Client Module

From BaseX Documentation
Jump to navigation Jump to search

This XQuery Module contains functions to access remote BaseX server instances from XQuery. With this module, you can both execute commands and perform queries, and the result sets are returned as valid sequences using the correct XDM data types. All functions use the client prefix, which is linked to the statically declared http://basex.org/modules/client namespace.

Functions

client:connect

Signatures client:connect($host as xs:string, $post 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 and creates a new client session. As a result, a session id is returned. The parameter $host is the name of the database server, $host specifies the database host, and $user and $password represent the login data.
Errors BXCL0001 is raised if a connection error occurs (e.g., if the addressed server is not available).

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 BXCL0002 is raised if the specified session id is unknown.
BXCL0003 is raised if an error occurs while executing the 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 queru string, which will be evaluated by the server.
Errors BXCL0002 is raised if the specified session id is unknown.
BXCL0003 is raised if an error occurs while evaluating the query.
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.
Errors FOSQ0001 is raised if an SQL exception occurs.

FOSQ0002 is raised if a wrong connection handle is passed.

Changelog

The module was introduced with Version 7.2.2.