XDBC driver for PHP
===================

In order to use the XDBC driver for PHP you need to include the "xdbc.php"
module:

  require_once 'xdbc.php';

Also, the "xdbc.php" module uses the "curl" library, so you need to have that
installed. I think the library is normally automatically installed on recent
versions of PHP for linux, but you may need to get it for a Windows
installation.

Once the environment is configured you can query the XDBC server by calling 
the method "xdbc_query" as follow:

  $ret = xdbc_query($host, $query [, $params, $userpass, $flags])

where:
  $host:     string - "<host>:<port>" (e.g. "localhost:8002")
  $query:    string - "<XQuery-request>"
  $params:   array  - query external parameters (see below)
  $userpass: string - "<user>:<password>" (e.g. "nobody:nobody")
  $flags:    int    - XDBC_XDBC_ARRAY|XDBC_XML|XDBC_HEADER
    XDBC_ARRAY  = the result is an array
    XDBC_XML    = the result is an XML document (as string)
    XDBC_HEADER = the first element is the HTTP header (for debug)
    XDBC_QUERY  = the first element is the original query (for debug)

By default $userpass is undefined and you'll access the XDBC server without
logging in (but most of the times you would want to login). Also, the default 
value for $flags is XDBC_ARRAY.

$params is a special array populated by calling xdbc_bind_param as follows:
  
  xdbc_bind_param(&$array, $lname, $style, $value [, $ns])
  
where:
  $array: array reference - array which will contain parameters 
          to be passed to xdbc_query
  $lname: string - local name of the parameter 
          (externally defined xquery variable)
  $stype: string - schema type of the parameter (e.g. "xs:string")
  $value: string - string representation of the parameter's value
  $ns:    string - parameter's namespace

example:
  $params = array();
  xdbc_bind_param(&$params, "param1", "xs:string", "value 1");
  xdbc_bind_param(&$params, "param2", "xs:integer", "2");
  $ret = xdbc_query($host, $query, $params, $userpass);
 
The result of an XQuery can normally be one single XML element (of course with
nested elements) or a list of nodes (XML elements, numbers, strings, etc.)

In order to support this the method "xdbc_query" can return two types of
results:

- an array of objects (equivalent to the list of nodes returned by XDBC
- an XML document (returned as a string)

You select the type of results by setting the flags parameter to XDBC_ARRAY 
or XDBC_XML.

If you select XDBC_ARRAY each element in the array will contain 3 fields:

- content-type
- x-type
- body

Content-type is the MIME type for the selected node (not needed most of the
times but XDBC returns it)

X-type is the type of node. Possible values are:

- integer : an integer number
- decimal : a decimal (floating point ?) number
- string : a string
- boolean : a boolean (true or false)
- node() : XML element
- binary() : binary data
- x-error : the XDBC driver returned an error or there was an error in the
  connection
- x-header : this is the type for the HTTP header (returned if you specify
  XDBC_HEADER)
- x-query : this is the type for the original query (returned if you specify
  XDBC_QUERY)

Body is the node value.

If you select XDBC_XML the output is a string containg a valid XML document.
The root element is always <results>. The nested elements (one for each node
returned by XDBC) are either the root element for nodes of type "node()" (see
before) or an <entry> element with 2 attributes (@type containing the node
type as specified before, and @content-type containing the MIME type for
the node as specified before). The content for the <entry> element is the node
value (same as the "body" field described before).

In case of an error you will get an entry of type "x-error" and the XML
representation of the error (either an <err:error> element returned by XDBC
or an <error> element caused by errors accessing the XDBC server.


EXAMPLES
========

There are two examples that you can look at:

- xqtor.php : a simple command line tool
- webxqtor.php : a simple "web" application

Both of them parse some input parameters, read the query and call
"xdbc_query".

Both of them display the output either as an XML string, or using "print_r"
to display the returned array.


xqtor.php
=========

This is a tool useful to run queries from the command line (or in a shell
scripts). It can be pretty handy if you don't have Java installed and need 
to quickly test some queries or populate your databases.

You can run xqtor.php as:

  php -q xqtor.php [options] [query]

or rename it "xqtor", make it executable (chmod +x) and run it as:

  xqtor [options] [query]

This script expects to find the file xdbc.php in its same folder (even if run
from a different folder). If you prefer to have a single copy of xdbc.php
installed in one of the configured PHP include directories edit this file
(xqtor.php), uncomment the first "require_once" and comment out the second.

For a list of option, you can use the option "--help".

Here is a brief description:

  --user=user:pass : login as user <user> with password <pass>
    default: nobody:nobody

  --host=host:port : access the XDBC server at host <host>, port <port>
    default: localhost:8002

  --query|--noquery : add the requested query to the result (or not)
    default : --noquery

  --header|--noheader : add the response HTTP header to the result (or not)
    default : --noheader

  --xml|--noxml : the result is an XML document (as string) or a PHP array
    default : --xml

  --file=file.xqy : the input query is read from file.xqy
  --stdin : the input query is read from standard input (for piped commands)
 
  If no --file or --stdin are specified the last parameter is expected to
  be the requested query (mind your quotes :)


webxqtor.php
============

This script, that you can install on your webserver, will display an 
input form if accessed without parameters, or will execute the query 
when you submit the form. 

Because the query is read from the textarea (and passed to the webserver 
on the query string it needs to be "decoded" (see call to urldecode). 
Also the browser (or the server ?) seems to escape quotes, so they need 
to be unescaped. 

For regular use the query will be embedded in the code, so no encoding/escaping 
is necessary.

This script expects the file 'xdbc.php' to be installed in one of the
configured PHP include directories (or in the current folder). In this case
I use a simple "require_once 'xdbc.php'" directive because the web server will
always set the current directory for the execution to the one where the script
resides.

This script lets you select the XDBC server and your authentication
information from the form. Of course in a real use you will need to code this
information in the script itself.