OpenCReports uses an RLIB-compatible report description with extensions.
The report XML description, like all XML files start with declaring that it's an XML file and the optional declaration of the Document Type Definition that the XML file can be checked against. For an OpenCReports report description, the first two lines are:
<?xml version="1.0"?> <!DOCTYPE OpenCReport SYSTEM "opencreport.dtd">
The DTD file opencreport.dtd can be
found in the sources of OpenCReports
here.
After the XML header lines, a fully specified report description looks like this:
<OpenCReport>
<Datasources>
...
</Datasources>
<Queries>
...
</Queries>
<Part>
<pr>
<pd>
<Report>
...
</Report>
</pd>
</pr>
</Part>
</OpenCReport>or like this:
<OpenCReport>
<Datasources>
...
</Datasources>
<Queries>
...
</Queries>
<Report>
...
</Report>
</OpenCReport>
The XML sections Datasources and Queries are optional in the XML description. They can be substituted by program code using the datasource and query related calls in the Low level C API, similarly to RLIB.
For RLIB compatibility, a report description may start
with either <Part> or
<Report> as the toplevel node.
In this case, there's no other way to add datasources
and queries, but through program code, like the
Low level C API.
Since XML files are hierarchical with a single toplevel
node with child nodes, multiple
<Report> nodes in the same
report output were only possible in RLIB with using
<Part> as the toplevel node,
with all the nodes having to be spelled out between
<Part> and
<Report>. With
<OpenCReport> being the
toplevel node, multiple <Report>
child nodes can be used without the parent
<Part> node.
Most (if not all) XML attributes in the report description file are handled with the expression parser (see Expressions), with fallback to literal strings if the the location of expression wouldn't allow identifier references at that location.
For example, the datasource name may be declared using either of the three examples below:
<Datasource name="mysource" ... /> <Datasource name="'mysource'" ... /> <Datasource name=""mysource"" ... />
The first form is a regular XML string value.
Since expression parsing would find that
mysource is an identifier
which may be a query column name and this is not
a valid place for a query reference, the non-parsed
string value is used.
The second form is a single quoted OpenCReports
string constant. The value of the string constant
(i.e. mysource) is used.
The third form is a double quoted OpenCReports
string constant, but in XML the double quote
character must be substituted with
" because they are
reserved for quoting the attribute values.
The value of the string constant (i.e.
mysource) is used.
(This substitution is called "string escaping"
and various other formats besides XML require some
kind of substutition for reserved characters.)
To make the XML easier to read, the second form is recommended because it still allows embedding the single quote character inside a string (see Report XML description) in case e.g. a strong password contains this. For security-by-obscurity, the third form may be used because it is harder to read. For all special characters that should be escaped in XML, see Simplified XML Escaping.