17.16. XSQL
XSQL is an XML-based format for describing simple stored procedures that
can parse XML data, query or update database tables and compose XML output.
Both input and output XMLs of such procedures are usually standard three-level
documents: a top-level ROWSET
element contains
some number of ROW
elements and every
ROW
contains one element per database field.
XSQL lets the application developer avoid writing routine code for parsing
and composing such documents:
the server translates a short and self-evident XSQL description into a relatively long Virtuoso/PL procedure.
XSQL pages are usually executed from XSLT stylesheets by calling
processXSQL()
XPATH function.
When the page is executed, it can access an XML entity that is context entity of the
processXSQL()
call. This entity is used inside the page as an
implicit parameter called "context XML".
An XSQL document that describes one procedure is called "XSQL page". A page consists of small directives. Every directive is written as a single XML element from namespace "urn:oracle-xsql" (the typical namespace prefix is "xsql"). Every directive describes one standard operation. The resulting Virtuoso/PL procedure will execute all directives in turn. Directives are of four sorts:
| Parameter assignments create and initialize local variables ("page parameters") that can be used in the rest of page. |
| Data modification requests can insert, delete or update data in database tables. |
| XML generators can query database or page parameters and produce XML fragments. These fragments form the resulting XML that is returned by the procedure. |
| DML directives let the author to put arbitrary Virtuoso/PL code in the procedure. |
All directives are children of one op-level element called 'xsql:page'. This element can have any number of attributes but no one attribute is used by Virtuoso. These attributes may be used by specialized XSQL editors and standalone XSQL processors that should establish a database connection to read and write data so store connection details as attributes of 'xsql:page'.
The XSQL development cycle consists of editing '.xsql' resources in the file system or Virtuoso DAV. The editing can take place using a regular text editor or a supporting XML editor or some specialized third-party XSQL tool.
17.16.1. XSQL Syntax
Properties of each XSQL directives are specified by XML attributes. These attributes are of different types, mostly SQL expressions, calculateable strings, SQL names and lists of names (e.g., name of a database table or a list of columns of a table).
In some cases, SQL expressions are long and it is not convenient to place them into attribute values. Such expressions are written as text content of the XSQL directive element.
SQL expressions.
XSQL allows slightly extended syntax of SQL expressions. If X is a name of page parameter made by xsql:set-page-param then
special notation "{@X}" stands for the reference to the parameter value.
This notation can be used in any place where a variable name is acceptable.
In addition, this notation can be used inside string literals, such a literal is translated into
a string concatenation expression; e.g., 'text-head{@X}text-middle{@Y}text-tail'
is converted into
concat ('text-head', cast ({@X} as varchar), 'text-middle', cast ({@Y} as varchar), 'text-tail')
.
Calculateable strings . Some attribute values are strings like resource URIs or XML names to be used in the output generated by a page. They are usually written 'as is' but they can use "{@X}" notation to insert the value of page parameter into the resulting string. The actual value of a calculateable string is compiled only once even if it appears many times in the XML output of the page.
Names of SQL columns . Some attributes are not arbitrary SQL expressions but only SQL column names. These names are written 'as is'. Only unqualified names are allowed, not in form 'table.column'. No "{@X}" is allowed for obvious reasons. If SQL name is case-sensitive or contains nonalphabetical characters then the name should be enclosed in double quotes. For readability, use single quotes to surround attribute value to not mix them with possible double quotes used in SQL name. Whitespace characters are not allowed in these names because these will not make proper names of XML elements.
Names of SQL tables . SQL table names are also written 'as is', with the same rules for double quotes around case-sensitive parts of the name. Both qualified and unqualified names are allowed.
Lists of names of SQL columns . When the value of attribute lists one or more column names, white space characters or commas delimit column names. The list should be space-delimited like 'COL1 COL2 COL3' or comma-delimited like 'COL1, COL2, COL3' but not a mix of them like 'COL1, COL2 COL3'.