PERL XSQL DOCUMENTATION
-----------------------
This document describe the XML syntaxe used by the perl module XSQL::XSQL
to extract SQL queries from the XML file. You can also include Perl code
that will be executed during parsing.
Here is an example :
SELECT * FROM ARTICLE;
my ($self, $cgi) = @_;
my $name = uc($cgi->param('name'));
my $givenname = ucfirst(lc($cgi->param('givenname')));
return ($name, $givenname);
SELECT * FROM ARTICLE WHERE name='?' AND givenname='?' AND age=CGI::age
Each XSL template calling one or more SQL queries must have a file containing
the XML definition of the SQL queries. This file must be named and linked as
to an alias in the template alias configuration file.
This XML file can be replaced by a perl function, see Extended XSQL.
Element:
--------------
The XML element is the root element of the XML document, it also allow the
definition of the databade connection. Attributs supported by this element are:
- datasource : DBI DSN used to connect to the database.
- user : User allowed to connect to the database.
- password : Password of this user.
- error : Boolean (0 ou 1) used to raise error on demand. Defaut: 0
This attributes are optionals if the connection is the same as the default connection
set in the CGI frontend script. This default connection must always been set.
Element:
--------------------
The XML element is used to separate all different SQL queries to execute.
Attributs supported by this element are:
- name : name of the XML element used to replace the element into
the XML output.
You can set as many as element that you have SQL queries to executed to
match your needs. Of course attribut 'name' can not have the same value for all these
resultset.
Element:
--------------
The XML element is used to mark each tuple returned by a SQL query.
Attributs supported by this element are:
- name : name of the XML element used to replace the element in
the XML output for each tuple returned.
There can be as many element as there is SQL queries defined. The 'name' attribute
can have the same value if it is set in a different .
Element:
----------------
The XML element contain the SQL query to execute. It has no attribute.
Statics SQL queries doesn't create any problem. SQL queries with dynamics parameters, where
for example the conditional part need to use a current CGI parameter value need special
syntaxe into the SQL query. This can be done by two way:
- The simple one is to place a special call into the SQL query as follow:
CGI::param_name
For example if you want to set a conditional value that will be provide by
a CGI parameter nemed 'age', you can introduce CGI::name into the query and
it will be replaced directly into the query before SQL execution:
SELECT * FROM customer WHERE age>=CGI::age
- The advanced way is to use the '?' character instead of a value into the SQL query.
These characters will be replaced by the values returned by the perl code include
into the element (see bellow). This allow you to process some perl code
before substitution.
These methods can be used together.
Element:
---------------
The XML element allow the inclusion of any perl code that will be executed
before the SQL queries. It has no attributes.
Each value returned will be passed as argument in the given order to the prepared
statement of the SQL query in replacement of the '?' characters.
Writting perl code:
-------------------
The perl code include into the element is view as a standard perl method.
These methods receives two arguments:
- the current perl module instance.
- the current CGI instance.
To use these arguments simply set the following line at the begining of your perl code:
my ($self, $cgi) = @_;
You can then uses these variables like in any perl script.
For example if you have a SQL query you can write things like that:
SELECT * FROM article WHERE name='?' AND givenname='?' AND age=?;
then the Perl code must return parameters as follow:
return ($name, $cgi->param('givenname'), $age);
SQL queries that may be construct dynamically are not supported yet.
XSQL DTD
---------
Document Type Definition used by the XSQL XML code:
]>