A report generator uses a tabular data source, which contains rows and columns of data. The columns have labels or names. (An SQL database query is such a tabular data source.) It also uses some kind of description that specifies how to display the data. The input data is transformed into various output formats, some for human viewing, some for further machine processing. Such output formats may be PDF, HTML, XML, plain text or CSV.

The XML file format is widely used. It can describe structured data in a hierarchy with names for its sections or "nodes".

OpenCReports uses an RLIB-compatible report description with extensions. See Report XML description and the RLIB documentation

The Low level C API allows creating a report purely via program code. The High level C API allows loading an XML report description that contains all details about the report, including database access. Mixing the high and low level APIs allows a balance anywhere between the two extremes. For example, load the report description, which contains the complete layout, and pass database access details via program code. As a comparison, RLIB's API and report description allowed neither extremes: it relied on the report description to provide the layout, with data access and other supplementary details controlled from programming code.

OpenCReports uses a Flex/Bison based expression parser. The expression grammar doesn't allow incorrect expressions. See the Expressions chapter.

OpenCReports does some expression optimization to reduce runtime cost of computing expression values. For example, in a*2/3 the part 2/3 is two constants in a division. This is precomputed into a single constant as an optimization. Naturally, only mathematically valid optimizations are performed.

OpenCReports supports standard report variables for calculating sums, minimum, maximum and average values or custom defined ones. See Report variables

Report variables can also be used as manual expression optimization. A common subexpression can be moved to a report variable from multiple expressions, which in turn is computed once, and its result is used in the expressions referencing it.

A report break is a form of data grouping based on value changes. A break (break boundary) occurs when the value of a watched expression changes from one data row to the next. OpenCReports supports report breaks defined on arbitrary expressions. Report variables can reset their value on break boundaries. See Report breaks and Breaks.

OpenCReports has many operators and functions to be used in expressions. See Operators and functions in the Expressions chapter.

Custom functions can also be added to a report by programming code. Custom functions may override stock functions.

OpenCReports exclusively uses UTF-8 for strings. Input data must be in UTF-8 and output formats also use UTF-8. This allows text from different languages appear in the same report, provided that an applicable font is available.

OpenCReports uses a high precision numeric data type. This allows scientific computation or monetary calculations even with late stage hyperinflation prices. See Numeric constants in the Expressions chapter and the Numeric behavior related functions part in the Low level C API chapter.

OpenCReports handles both timestamp and time interval data types. The latter allows adding or subtracting a custom time period to and from timestamp data. See Datetime constants in the Expressions chapter.

For maximum portability, databases provide their data in strings. They also indicate the column type. OpenCReports detects the columns' data type and applies the conversion automatically.

In the report output, fields may have a fixed width in which they are displayed. Some field values are longer than the field width. When displaying them in a single row, fields may be left-, right- or center-aligned to show the interesting part of the value or for visual reasons.

Fields longer than the designated width may be wrapped either at word or character boundaries. This way, they become multi-row fields. Multi-row fields are also called "memo" fields. Such fields may wrap lines at word boundaries or break words at some character. Multi-row fields have configurable line number limits. Memo fields can break over to the next column or to the next page. Hyphenation is done automatically when using character wrapping. Memo fields may also use justified alignment.

OpenCReports supports both single- and multi-column layout in its PDF output format. Other output formats may only use single-column layout.

OpenCReports implements an RLIB compatibility mode for sizing report layout details, which uses a mix of units, mostly based on character widths (making it dependent on the font size used) mixed with points (1/72th inch) for some report elements.

OpenCReports also has a new, consistent size calculation method where everything is measured in points (1/72th inch).

OpenCReports supports both fixed and proportional fonts even with using the RLIB compatible size settings.

OpenCReports supports several output formats: PDF, HTML, CSV, TXT, XML and JSON.

The unit tests ensure that OpenCReports' features keep working when adding new features or fixes. Units tests exercise many aspects of the high and low level API, report description handling, runtime behavior and output generation.

OpenCReports uses LibXML2, utf8proc, MPFR, libpaper, libcsv, yajl, Cairo, Pango, librsvg2, gdk-pixbuf2, PostgreSQL, MariaDB and unixODBC.

For running the unit tests, Ghostscript and compare from Imagemagick are also needed.

xmllint, xsltproc and fop are used to generate the documentation.

Currently Gantt chart and various graph types (like barchart, pie chart and their various subtypes) are not supported.

There are other report generators on the market with nice GUIs to create the report visually.

SQL is the acronym for Standard Query Language. Many database software comply with the standard to a certain extent. The standard is occasionally revised, and a certain database software version complies to a specific version of the standard to a certain extent.

In general, database software are designed to store massive amounts of data and retrieve it as fast as possible. Database software and its data can be accessed through a network connection (even if it's installed in the same machine) or a faster local connection if both the database server and client are installed on the same computer.

The SQL based data sources OpenCReports natively supports are:

The file based data sources OpenCReports supports are:

The XML and JSON file types expect the data presented in a certain structure syntax. The semantics is application defined. The expected format for these file types are described below.

{
	"columns": ["colname1", ... ],
	"coltypes": ["type", ... ],
	"rows": [
		{ "colname1": value1, ...  },
		...
	]
}

<?xml version="1.0"?>
<data>
	<rows>
		<row>
			<col>value</col>
			...
		</row>
		...
	</rows>
	<fields>
		<field>column1</field>
		...
	</fields>
	<coltypes>
		<col>type1</col>
		...
	</coltypes>
</data>

Applications may also have internal data that can be used as input for OpenCReports.

OpenCReports supports using two-dimensional C arrays as directly accessible application data. Such arrays must be declared as

char *array[ROWS][COLUMNS]

or converted to it if using OpenCReports from a different language. Each element is a pointer to a zero-terminated C string. The first row contains the names of columns.

Optionally, a set of type indicators may be supplied, similarly to the File based data sources.

OpenCReports allows application defined datasource drivers that may even override built-in datasource drivers.

An application defined data source may be any of the previously listed types: SQL, file or data based.

An SQL query uses an SQL data source. An SQL query provides tabular data in rows and columns. The columns have names. One row of data is made up from individual values in columns.

Examples:

SELECT * FROM table1;

SELECT column1, column2 FROM table1;

For more information, read the specific database server documentation you intend to use.

File queries specify the file name and path on the computer. OpenCReports then loads the file into memory and processes it to present data on the report.

Data queries pass the internal data. OpenCReports processes it to present data on the report.

Reports may use one or more queries. If a report uses more queries, one of them must be the report's primary query.

Supplementary queries are either followers of the primary query, or independent queries

String literals in OpenCReports can be either single or double quoted. Some examples:

"apple"
’apple’
"I’ve eaten an apple"
’This an "apple".’

The values of these strings are:

apple
apple
I’ve eaten an apple
This an "apple".

We can see how the other quoting character can be used as part of the string value.

String literals can also use BASIC language style double quoting to embed a single quoting character used for quoting the string itself:

’apple’’’
’apple’’pear’
’apple’’’’pear’
"apple"""
"apple""pear"
"apple""""pear"

The values of these strings are:

apple’
apple’pear
apple’’pear
apple"
apple"pear
apple""pear

String literals can also use C language string continuation if there's at least one whitespace character (space, TAB or new line) between doubled quoting characters. String continuation can also switch quoting characters without whitespace between quoting.

"apple" "pear"
"apple" ’pear’
"apple"’pear’

The value of all these strings is:

applepear

Numeric constants can be integer or fractional numbers with or without the so called e-notation or scientific notation. Some examples:

1
1.234
1e4
1e-4
1.234e-5

E-notation means that that number preceding the letter "e" or "E" is multiplied by ten to the power of the number after the letter "e" or "E", the latter being an integer value. The values of the above examples are:

1
1.234
10000
0.0001
0.00001234

Numbers greater than 0 and less than 1 can be written with or without the leading zero.

0.123
.123

Technically, there are no negative numeric constants. Instead, the number and the unary minus operator (see Unary operators) are initially handled separately. Then the expression optimizer merges them, creating the negative numeric constant.

Boolean constants evalutate to numeric constans 1 and 0. The boolean constants are:

yes
no
true
false

There are no datetime constants per se, although expressions like stodt('1980-06-30 16:00:00') or interval('2 months') (i.e. function calls with constant arguments that result in a datetime value) are implicitly turned into constants by the expression optimizer.

Constant expressions are ones that only contain constant values (of any type) and operators or functions.

Identifiers are in the format domain.identifier where the domain name or the dot are optional.

OpenCReports uses UTF-8 encoding even in identifier names. National or accented characters are accepted in identifiers.

Valid names for domain and identifier may start with an underscore or UTF-8 letters and may contain underscore, UTF-8 letters and numbers in subsequent characters.

Any valid identifier is by default a query column reference, with or without the domain name. Examples:

field_name
field_name5
myquery1.field_name
oszlop_név
lekérdezés.oszlop_név

In the above example, oszlop_név means field_name, and lekérdezés.oszlop_név means query.field_name in Hungarian. The accented characters are a courtesy of UTF-8.

Query field identifiers in expressions are resolved by matching them against query names (used as the domain) and their field names.

If the domain name is specified, a query matching the domain name name must be declared for the report, either as the primary query, a follower query, or an independent query. That query must have a column name that matches the identifier name.

If the domain name is not specified, the field name references are matched against all the queries of the report in the order of their declaration. The first query with a matching column name will be used for that reference.

For exceptions (and exceptions from under the exceptions!), see below.

Domain v signifies user defined report variables, which can be used to shortcut expressions. Example:

v.my_variable

For details, see Report variables and Variable node.

Some domain names carry special meaning for the report.

m.current_date

r.pageno

r.totpages

printf("Page: %d / %d", r.pageno, r.totpages)

Page: 3 / 5

r.lineno

r.detailcnt

r.value

r.format

r.self

r.baseexpr
r.ignoreexpr
r.intermedexpr
r.intermed2expr

query.field_name1
query."field_name2"
query."field with space in the name"
"query2".field_name3
"query2"."and"

.field_name
."field_name"

.yes
.no
.true
.false
yes.no

."yes"
."no"
."true"
."false"
"yes"."no"

."and"
."or"
"and"."or"

"m".current_date
"r".totpages
"v".my_variable

The ternary operator works as in the C, PHP and other languages:

expression1 ? expression2 : expression3

It's evaluated as follows: if the value of numeric expression1 is true (i.e. non-zero), then the result is the expression2, otherwise it's expression3. Type of expression2 and expression3 may differ, i.e. the result type will be the type of the underlying expression but it can result in runtime errors.

Internally, it's implemented using the iif() function.

Logic OR can be written as || or or. Example: a || b

Logic AND can be written as && or and. Logic AND has precedence over OR. Example: a && b

Internally, they are implemented using the Boolean AND and Boolean OR functions.

The bitwise operators in this precedence class and in their increasing order of precedence are: bitwise OR (|) and bitwise AND (&).

The equality comparison operator can be written as = or ==.

The inequality comparison operator can be written as <> or !=.

[ expa1, expa2, ... ] op [ expb1, expb2, ... ]

(expa1 op expb1) and (expa2 op expb2) and ...

not ([ expa1, expa2, ... ] = [ expb1, expb2, ... ])
[ expa1, expa2, ... ] != [ expb1, expb2, ... ]

Less-than (<), less-or-equal (<=), greater-than (>) and greater-or-equal (>=).

Bitwise shift left (a >> b) and bitwise shift right (a << b).

a + b and a - b.

a * b, a / b and a % b.

a ^ b works as a-to-the-power-of-b.

a!, the '!' sign used as postfix operator.

Unary plus (+a), unary minus (-a), logical NOT (!a, '!' used as prefix operator), bitwise NOT (~a), prefix increment (++a) and prefix decrement (--a).

Postfix increment (a++) and decrement (a--).

Function calls execute a function on operands: function(operand[, ...]). A function name is a single word known by OpenCReports at the time of parsing, either as a built-in function, or a user-supplied one. The function name cannot have a leading dot or be a domain-qualified identifier.

Implicit multiplication is when two distinct operands are in juxtaposition, in other words they are written side by side without any whitespace. In this case, there is an implied multiplication between them that acts with higher precedence than regular multiplication or division. Implicit multiplication is applicable in these situations:

Implicit multiplication is NOT applicable in these situations, besides the exceptions already explained above:

Parenthesized expressions are always computed first.

Expression parsing works on two levels: token matching and applying grammar. Token matching breaks up the expression string into tokens in a greedy way: without whitepace delimiters, the longest possible token is chosen.

This may lead to slight confusion when coupled with implicit multiplication. For example, the expression 2e-1e is broken up into two tokens: 2e-1 juxtaposed with e. The first token is interpreted as a numeric constant using e-notation (so that it will mean 2 * 10^(-1)) and the second is the identifier e, leading to the meaning 0.2 * e. This is unambiguous for the computer, but can be somewhat confusing to the the user reading or writing expressions. To avoid any confusion, don't use implicit multiplication and use whitespace and parentheses gratituously.

Expression parsing handles precedence and whitespaces. For example, these below do not mean exactly the same:

a++ + ++b
a+++++b

The former is obvious, but the latter may be a little surprising: (a++)++ + b. This is how the lexer or token matching works, i.e. it matches the longest applicable token first.

If a and b are numbers, then the result of both expressions is a + b + 2, but the way it's arrived at is different.

However, the ++ (increment) and -- (decrement) operators may be interpreted differently for other types. For example, if both a and b are of the datetime type, then the result also depends on whether one of them is an interval datetime, and the other (regular) datetime value has valid time or not. To make the expression unambiguous, whitespace and/or parenthesis should be used.

Another ambiguous example:

a++b

The above may be interpreted as a + +b but since no whitespace is used, the tokenizer is free to interpret it as a++ b, because ++ is longer than +, so the former is matched first as an operator token. This is a syntax error and expression parsing throws an error for it.

Absolute value. It takes one numeric operand. Operator |...| is a shortcut for this function.

Division. It takes two or more numeric operands. The way it works is: take the first operand and divide it by the second and subsequent operands in sequence. Operator / is a shortcut for this function.

Factorial function. It takes one numeric operand. The postfix operator ! is the alias for this function.

The result to the value of x - ny (x and y being its two numeric operands), rounded according to the report's rounding mode, where n is the integer quotient of x divided by y, n is rounded toward zero. It takes two numeric operands.

An alias of remainder(). It takes two numeric operands. Operator % is a shortcut for this function.

Multiplication. It takes two or more numeric operands. Operator * is a shortcut for this function.

The result to the value of x - ny (x and y being its two numeric operands), rounded according to the report's rounding mode, where n is the integer quotient of x divided by y, n is rounded toward to the nearest integer. It takes two numeric operands.

Unary minus. Changes the sign of its numeric operand from positive to negative, or vice versa. It takes one numeric operand. Operator unary - is a shortcut of this function.

Unary plus. Leaves the sign of its numeric operand as is. It takes one numeric operand. Operator unary + is a shortcut of this function.

Bitwise AND. It takes two or more numeric operands. Operator & is a shortcut for this function.

Bitwise NOT. It takes one numeric operand. It returns the bit-by-bit negated value of its operand. Prefix operator ~ is a shortcut for this function.

Bitwise OR. It takes two or more numeric operands. Operator | is a shortcut for this function.

Bitwise shift left. It takes two numeric operands. Shifts the first operand left with the number of bits specified by the second operand. The operand << is a shortcut for this function.

Bitwise shift right. It takes two numeric operands. Shifts the first operand right with the number of bits specified by the second operand. The operand >> is a shortcut for this function.

Bitwise exclusive OR. It takes two or more numeric operands.

Boolean logic AND. It takes two or more numeric operands that are treated as boolean logic values. The function is executed until the result is fully determined, i.e. it stops at the first false value. Operator && is a shortcut for this function.

Boolean logic NOT. It takes one numeric operand. It returns the negated boolean value of its operand. Prefix operator ! is a shortcut for this function.

Boolean logic OR. It takes two or more numeric operands that are treated as boolean logic values. The function is executed until the result is fully determined, i.e. it stops at the first true value. Operator || is a shortcut for this function.

Equal. It takes two operands of the same type: numeric, string or datetime. The result is numeric value 1 or 0, if the two operands are equal or non-equal, respectively. The operators = and == are shortcuts for this function.

Greater-or-equal. It takes two operands of the same type, which can be either numeric, string or datetime. The operator >= is a shortcut for this function.

Greater-than. It takes two operands of the same type, which can be either numeric, string or datetime. The operator > is a shortcut for this function.

Less-or-equal. It takes two operands of the same type, which can be either numeric, string or datetime. The operator <= is a shortcut for this function.

Less-than. It takes two operands of the same type, which can be either numeric, string or datetime. The operator < is a shortcut for this function.

Not equal. It takes two operands of the same type, which can be either numeric, string or datetime. The operator != and <> are shortcuts for this function.

Rounds its operand to the next higher or equal integer. It takes one numeric operand.

Rounds its operand to the next lower or equal integer. It takes one numeric operand.

Rounds its operand using the report's rounding mode. It takes one numeric operand.

Rounds its operand to the nearest representable integer, rounding halfway cases away from zero. It takes one numeric operand.

Rounds its operand to the next representable integer toward zero. It takes one numeric operand.

Natural exponential. It takes one numeric operand.

Base-10 exponential. It takes one numeric operand.

Base-2 exponential. It takes one numeric operand.

Alias for log().

Natural logarithm. It takes one numeric operand.

Base-10 logarithm. It takes one numeric operand.

Base-2 logarithm. It takes one numeric operand.

This function raises the first operand to the power of its second operand. It takes two numeric operands. Operator ^ is a shortcut for this function.

Square. It takes one numeric operand.

Square root. It takes one numeric operand.

Arc-cosine function. It takes one numeric operand.

Arc-sine function. It takes one numeric operand.

Arc-tangent function. It takes one numeric operand.

Cosine function. It takes one numeric operand.

Cotangent function. It takes one numeric operand.

Cosecant function. It takes one numeric operand.

Secant. It takes one numeric operand.

Sine. It takes one numeric operand.

Tangent. It takes one numeric operand.

Concatenate strings. It takes two or more string operands.

Return the leftmost N characters of a string. It takes two operands, the first operand is a string, the second is the string length, a numeric integer.

Convert to lowercase. It takes one string operand.

Return characters from the middle of the string. It takes three operands, the first operand is a string, the second and third are numeric integer values, start offset and length, respectively. The offset is 1-based just like in BASIC, with the offset value 0 being identical to 1. Negative offsets count from the right end of the string, i.e. mid(s,-n,n) is equivalent to right(s,n).

Return the string converted lowecase, except the first letter of the first word, which will be uppercase. This function takes one string operand.

Return the rightmost N characters of a string. It takes two operands, the first operand is a string, the second is the string length, a numeric integer.

Return the number of characters in the string. It takes one string operand.

Convert to uppercase. It takes one string operand.

Change the date part of the first operand to the date part of the second operand. It takes two datetime operands.

Change the time part of the first operand to the date part of the second operand. It takes two datetime operands.

Return the current date. It takes zero operands.

Return the date part. It takes one datetime operand.

Return the day of month value as a number. It takes one datetime operand.

Returns the number of days in the month according to the year and month values of the operand. It takes one datetime operand.

Convert a datetime to string. The date part of the datetime is formatted according to the date format of the currently set locale. It takes one datetime operand.

Convert a datetime to formatted string. It takes two operands, one datetime and one string. It takes the second (string) operand as a format string and formats the datetime value according to the format string. If the second operand is NULL or empty string, this function behaves like the dtos() function. Otherwise it behaves like the format() function with the operands reversed.

Convert the time part of the datetime to seconds elapsed from 00:00:00. It takes one datetime operand.

Convert the parameter(s) to an interval subtype of the datetime type. It takes either one string operand, or six numeric operands.

In the first case, the string is parsed for interval values, like 1 year or 2 months, etc., and sets the specific datetime part values.

In the second case, the six numeric operands are the values for the datetime parts, in the order of years, months, days, hours, minutes and seconds.

Return the month value of a datetime. It takes one datetime operand.

Return the current timestamp in a datetime value. It takes zero operands.

The "current timestamp" is determined at the beginning of generating the report. This function returns the same stable value for the lifetime of the report.

Return a datetime with the time part of a datetime changed to the specified seconds after 00:00:00. It takes two operands, the first operand is a datetime, the second is a numeric integer.

Return the ISO-8601 week number of a datetime as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the new year. It takes one datetime operand.

Alias for stodt().

Convert a string to a datetime value. It takes one string operand.

This function is smart enough to recognize locale specific and standard ISO-8601 formats. It handles whole datetime, date-only and time-only values in the string.

Alias for stodt().

Return time part of the datetime operand. It takes one datetime operand.

Alias for stodt().

Return the week number of the operand as a decimal number, range 00 to 53, starting with the first Sunday as the first day of week 01. It takes one datetime operand.

Return the week number of the operand as a decimal number, range 00 to 53, starting with the first Monday as the first day of week 01. It takes one datetime operand.

This function returns the week number of the first operand as a decimal number, range 00 to 53, starting with the specified day number as the first day. (0 = Sunday, 1 = Monday, 2 = Tuesday, ...) It takes two operands, the first is a datetime, the second is a numeric integer.

Return the year value of the operand as a numeric value. It takes one datetime operand.

Add the operands. It takes two or more operands of different types and returns the sensible result for cases that make sense. It throws an error for invalid cases. Operator + is a shortcut for this function.

For numeric arguments, it's the arithmetic addition.

For string arguments, it is equivalent to concatenation, i.e. the concat() function.

Certain combinations of datetime and numeric arguments make sense.

Decrement by one. It takes one numeric or datetime operand. The operator -- is the shortcut for it, either as prefix or postfix operator.

Increment by one. It takes one numeric or datetime operand. The operator ++ is the shortcut for it, either as prefix or postfix operator.

Subtract the second, etc. operands from the first. It takes two or more operands of different types and returns the sensible result for cases that make sense. It throws an error for invalid cases. Operator - is a shortcut for this function.

For numeric arguments, it's simply the arithmetic subtraction.

For string arguments, it throws an error.

Certain combinations of datetime and numeric arguments make sense.

It takes two operands, the first operand is of any type, the second operand is a string. This function formats the first value according to the second operand as a format string. If the first operand doesn't match the expected type in the format string, an error is returned.

It an RLIB compatibility function and is a special case of the printf() function. See Formatting data.

This function takes one or more operands. The first operand is a string and used as the format string. Subsequent operands have to be of the expected type according to the format string, otherwise an error is returned. If everything is correct, it returns the formatted data as a string. See Formatting data.

It takes three numeric operands. The first operand is converted to a string with the length and number of decimal digits specified by the second and the third operands, respectively.

Numeric value. It takes one numeric or string operand.

If a string value is passed, and it can be converted to a numeric value successfully, then it returns the converted numeric value.

The value of a numeric operand is passed through as is.

Current row number of a break since its last break boundary. The row number restarts from 1 at every break boundary. It takes one string operand, the name of the break.

Return an artificially generated error. It takes one string operand, the error message. Used by unit tests but it may be useful in some other cases.

Parse an expression string. If it's correct, it is inserted into the parent expression in place of the function call. If there is a syntax error, the error is re-thrown for the main expression. It takes one string operand.

This is a pseudo-function. The grammar detects its use and converts the embedded expression string into a regular subexpression, like if it was inside parenthesis in the parent expression contents. This allows the subexpression to be optimized in the parent expression context.

Fox example, the expression 3 * eval('1 + 2') is optimized into the numeric constant 9.

Note, that the grammar transformation only takes place if there is no user defined function with the same name. In this case, the user defined function is used.

Move the decimal separator to the left by the specified number of digits. It takes two operands. The first operand may either be a string containing a numeric value, or a numeric. If it's a string, then it will be converted to numeric first. The second operand is numeric.

It is an RLIB compatibility function. The function divides the numeric value of the first operand with 10 to the power of the value of the second operand. One use case is that if the value of the first operand contains prices in cents, then fxpval(data, 2) puts the decimal separator to the correct place.

Ternary function. It takes three operands of which the first one is numeric, the second and third operands can be of any type. If the first operand is non-zero (i.e.: "true") then it returns the second operand, otherwise the third operand. The ternary operator exp1 ? exp2 : exp3 is a shortcut for this function.

Returns numeric 1 if the operand is datetime, 0 otherwise. It takes one operand of any type.

Returns numeric 1 if the operand is an error, 0 otherwise. It takes one operand of any type.

Returns numeric 1 if the operand is numeric and it represents a NAN value (not-a-number), 0 otherwise. It takes one operand of any type.

Returns numeric 1 if the operand is NULL, 0 otherwise. It takes one operand of any type.

Returns numeric 1 if the operand is a numeric value, 0 otherwise. It takes one operand of any type.

Returns numeric 1 if the operand is a string value, 0 otherwise. It takes one operand of any type.

Generate NULL value using the type of its operand. It takes one operand of any type.

Generate NULL of the datetime type. It takes zero operands.

Generate NULL of the numeric type. It takes zero operands.

Generate NULL of the string type. It takes zero operands.

Return the previous value. It takes one operand of any type.

The interesting use case for this function is non-constant expressions. It returns the operand's previous value, i.e. the value generated for the previous query row. If there is no previous value row, the result is an error. This function allows showing values carried over from the previous page to be shown in a header section of the current page.

Generate a pseudo-random numeric value between 0 and 1. It takes zero operands.

Return the row number of a query in the report. It takes either zero operands or one string operand. If zero operands are passed, it returns the current row number of the primary query. If a string operand is passed, then it returns the current row number of the query with that name. See Queries.

Translate the operand. It takes one string operand.

This function returns the translated version of the string operand according to translation and locale settings using dgettext() from Gettext.

Translate the operands using singular and plural variants and the number of the object in the statement. It takes three operands. The first two operands are strings, for the singular and plural strings. The third operand is the number that determines which translation form is used.

This function translates its operands according to the translation and locale settings using dngettext() from Gettext.

An expression may be iterative, where the new value is derived from the previous value of itself. See Expression self reference.

Examples cannot be understood without the context in which they are used. Complete variable examples are in the Variable node section of the Report XML description chapter.

Examples cannot be understood without the context in which they are used. Complete variable examples are in the Variable node section of the Report XML description chapter.

To print a string, the %s format string can be used. Examples for using it in the Text element format attribute can be found in the Format attribute examples.

Example expressions for the format() function:

format(query1.field1, '%s')
format(query1.field1, 'Look, there is a %s there!')

Example expressions for printf function:

printf('%s, 'query1.field1')
printf('Look, there is a %s there!', query1.field1)

Supplementary format string flags are supported. See the string flags in printf(3)

To print a number, the %d format string can be used. As opposed to the C printf format specifier where %d is used for integers, this is used for printing fractions, too. Examples for using it in the Text element format attribute can be found in the Format attribute examples.

The same format string can be used for the the format() function and the printf function, just like in the previous examples for strings.

Supplementary format string flags are supported. See the decimal and float/double format flags in printf(3)

RLIB approximated strftime() when printing a datetime value. OpenCReports uses strftime(). See the strftime() function description for the complete description of format string flags.

When a datetime field didn't have an explicit format string, RLIB used the US date format to print the datetime value. On the other hand, OpenCReports uses the locale specific date format if the report has a locale set.

This is an extension over RLIB, which didn't have such a notion. In OpenCReports, the new style flag is prefixed with !&.

The new style flag is the legacy flag prefixed with !#

There was way to format numeric data using the legacy formatting flags. The new style flag is prefixed with !$ and uses the flags of strfmon(). See the strfmon() function for details.

To print the correct currency name, the locale must be set for the report. Only one locale can be set, so a single currency name will be used for every value using monetary formatting.

The new style flag is the legacy flags prefixed with !@. Formatting a datetime value uses strftime().

Examples for using these in the Text element format attribute can be found in the Format attribute examples.

The format string format is the legacy format string embedded in !&{...}.

The format string format is the legacy format string embedded in !#{...}

The format string format is the same as the first generation. Instead of just having a prefix, the strfmon() format string is embedded in !${...}

Formatting monetary values uses strfmon(). See strfmon(3)

To print the correct currency name, the locale must be set for the report. Only one locale can be set, so a single currency name will be used for every value using monetary formatting.

The format string format is embedded in !@{...}. Formatting a datetime value uses strftime().

Examples for using these in the Text element format attribute can be found in the Format attribute examples.

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="&quot;mysource&quot;" ... />

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.

The size_unit attribute specifies report behaviour for size related settings:

<OpenCReport size_unit="'rlib'">
<OpenCReport size_unit="'points'">

Default is rlib which is the legacy RLIB behavior, where sizing of layout details are a mix of units, making it harder to design the report layout:

Note that RLIB only expected monospace fonts that have the same width for every character. It also expected that the character height is identical to the character width. The latter expectation is false for many monospace fonts, i.e. their height is usually greater than their width. Also, there are problems with field widths calculated in number of characters. Widths using a 12 point font (for example, used for regular text) is not the same as widths using a 20 point font used for text in a header line. Due to this, width of header and data lines will not align properly and it will show when using background color for both of them.

With proportional fonts (where the width of characters depend on their image, i.e. an "i" is thinner than an "m") width of text fields cannot reliably be set in a "number of characters" unit because it's not an exact value. There is a workaround for this in OpenCReports but it isn't available in RLIB so it's not backward compatible. See Text element width.

When size_unit is set to points, all size related settings in the report are in points, a.k.a. 1/72th inch. It's consistent and avoids the above described issues.

The report uses data from Queries through the report's Query attribute. When a query provides no data rows, an alternative section called NoData node with static information may be shown instead if it exists in the report. The report uses the first query declared in Queries if it's not explicitly set via Query attribute.

RLIB had a trick to disable showing the NoData node. This was enabled by specifying a query name that does not exist. This option controls the layout behaviour for that case.

<OpenCReport noquery_show_nodata="yes">
<OpenCReport noquery_show_nodata="no">

Default is true (or yes) when <OpenCReport> is the toplevel node, false (or no) when either <Part> or <Report> is the toplevel node for RLIB compatibility.

A report may specify its height through Report height. Multiple <Report> nodes may exist in the same <pd> section. For more information, see Part column and Report.

This option controls whether report height is applied after the last <Report> in the same <pd> node.

<OpenCReport report_height_after_last="yes">
<OpenCReport report_height_after_last="no">

Default is false.

Queries may be daisy-chained together as Follower queries in two ways, regular and N:1 followers. See the links for details.

When set to false, N:1 followers behave fully like LEFT OUTER JOIN in SQL, with duplicating data from the primary query if multiple matching rows exist in followers. When set to true, only the first matching row is used. The latter approximates the RLIB implementation.

<OpenCReport follower_match_single="yes">
<OpenCReport follower_match_single="no">

Default is yes in RLIB compatibility mode, i.e. when either <Part> or <Report> are used as the toplevel XML node for the report description. Otherwise the default is no.

This controls the precision for numeric computations. For more information, see Expressions

<OpenCReport precision_bits="512">

Default is 256.

This controls the rounding mode for numeric computations. Possible values are: nearest, to_minus_inf, to_inf, to_zero, away_from_zero, or faithful.

<OpenCReport rounding_mode="nearest">
<OpenCReport rounding_mode="to_minus_inf">
<OpenCReport rounding_mode="to_inf">
<OpenCReport rounding_mode="to_zero">
<OpenCReport rounding_mode="away_from_zero">
<OpenCReport rounding_mode="faithful">

Default is nearest. Note that according to the MPFR documentation, faithful is experimental.

This controls the language settings, like the decimal separator, weekday names, month names and similar. This setting is also used as the language of translation.

<OpenCReport locale="de_DE">

Default is C locale which approximates US English.

These two settings control the translation.

<OpenCReport
    translation_domain="mydomain"
    translation_directory="/path/to/translation/files">

Translation is based on GNU Gettext. A subdirectory tree is expected under the specified translation directory in the form of locale/LC_MESSAGES (e.g.: de_DE/LC_MESSAGES) with mydomain.mo files in them. These .mo files contain translated messages for a given language.

A MariaDB database connection may be declared in three ways. Either by using the database host and port, the database name, user name and password directly:

<Datasource
    name="mysource" type="mariadb"
    host="..." port="..."
    dbname="..." user="..." password="..." />

or alternatively, instead of the host and port, specifying the UNIX Domain Socket file for a local connection if it's not in the standard location:

<Datasource
    name="mysource" type="mariadb"
    unix_socket="..."
    dbname="..." user="..." password="..." />

or moving these details out to an external configuration file in an INI file format:

<Datasource
    name="mysource" type="mariadb"
    optionfile="myconn.cnf" group="myconn" />

In the last case, the configuration file myconn.cnf would contain something like this:

[myconn]
!include /etc/my.cnf
database=mydb
user=myuser
#password=
#host=
#port=
#unix_socket=

Please note that the INI group name [myconn] matches group="myconn" in the above datasource declaration.

The database name and user name are mandatory. The user password is optional, depending on the database security authentication setup.

The database host and port, or the socket file location are all optional. Without these, a local connection is attempted using the default settings. If the host name is specified but the port isn't, the remote host is used on the default port (as known by the local MariaDB database client library).

A PostgreSQL database connection may be declared in three ways. Either by using the database host and port, the database name, user name and password directly:

<Datasource
    name="mysource" type="postgresql"
    host="..." port="..."
    dbname="..." user="..." password="..." />

or alternatively, instead of the host and port, specifying the UNIX Domain Socket file for a local connection if it's not in the standard location:

<Datasource
    name="mysource" type="postgresql"
    unix_socket="..."
    dbname="..." user="..." password="..." />

or using a so called connection string:

<Datasource
    name="mysource" type="postgresql"
    connstr="..." />

For the connection string format, see the PostgreSQL documentation.

The database name and user name are mandatory. The user password is optional, depending on the database security authentication setup.

The database host and port, or the socket file location are all optional. Without these, a local connection is attempted using the default settings. If the host name is specified but the port isn't, the remote host is used on the default port (as known by the local PostgreSQL database client library).

There are also two optional parameters that control the behaviour of the PostgreSQL driver in OpenCReports, rather than being actual connection parameters to a PostgreSQL server. These parameters may be used with any of the above connection methods.

Examples (add the necessary connection parameters from the above):

<Datasource
    name="mysource" type="postgresql" ...
    usecursor="false"
/>

or

<Datasource
    name="mysource" type="postgresql" ...
    usecursor="true" fetchsize="4096" />

SQL queries added to the same PostgreSQL datasource (connection) will behave the same way. Either all of them are executed as is, or all of them will use a cursor.

The above described MariaDB and PostgreSQL database connection types are using their respective client libraries. There is a more generic way, i.e. ODBC. ODBC was invented by Microsoft in the 1990s for Windows. See Microsoft Open Database Connectivity (ODBC) In their solution, there's an abstract client library and individual database drivers adhere to the APIs offered by ODBC toplevel library. Since then, UNIX and UNIX-like systems also gained their ODBC client libraries in two different implementations, both of which are supported by OpenCReports: unixODBC and iODBC.

An ODBC database setup is done a differently. There are two system-wide configuration files. The first one is odbcinst.ini that lists the database drivers installed into the system. The second one is odbc.ini which references the first one and lists pre-defined database connections. These database connections are named. In ODBC speak, these are called Data Source Names or DSNs. The DSNs specify the low level connection parameters, like the database host and port, and optionally the user name and password, too.

Thus, an ODBC database connection may be declared in two ways. The first way is by using the DSN name, and optionally the user name and password:

<Datasource
    name="mysource" type="odbc"
    dbname="..." user="..." password="..." />

In this case, the dbname attribute is not the low level database name, but the ODBC abstract DSN name.

There's also a way to use the so called connection string which contain the same connection information:

<Datasource
    name="mysource" type="odbc"
    connstr="..." />

For the connection string format, see the public examples.

For a generic description of the CSV file format, see CSV file type.

A CSV file datasource is declared very simply:

<Datasource name="mysource" type="'csv'" />

In this case, the actual CSV file is not declared, only that a "query" using a CSV file will be listed later under <Queries>.

For a generic description of the expected JSON file format, see JSON file type.

Similarly to CSV, the JSON file datasource is also declared very simply:

<Datasource name="mysource" type="'json'" />

In this case, the actual JSON file is not declared, only that a "query" using a JSON file will be listed later under <Queries>.

Similarly to CSV and JSON, the XML file datasource is also declared very simply:

<Datasource name="mysource" type="'xml'" />

In this case, the actual XML file is not declared, only that a "query" using an XML file will be listed later under <Queries>.

Declaring the spreadsheet based file datasource is also very simple:

<Datasource
  name="mysource"
  type="'spreadsheet'"
  filename="'myfile.xlsx'" />

or

<Datasource
  name="mysource"
  type="'pandas'"
  filename="'myfile.xlsx'" />

Since the spreadsheet file may contain multiple sheets, the datasource declaration must specify the file name, and the query will need to specify the sheet label. An example can be seen under <Queries>.

If the sheets that the report uses are in different files, multiple spreadsheet datasources must be declared, one for each file. If the sheets are in the same file, then the same datasource can be used for multiple queries, one query for every sheet.

Arrays are global in-memory structures in the application that should be accessible to the OpenCReports library. For example, when using the C programming language, global non-static symbols are visible to libraries if the application is compiled with -rdynamic.

Similarly to file based datasources, the array datasource is declared very simply:

<Datasource name="mysource" type="'array'" />

In this case, the actual array is not declared, only that a "query" using an array will be listed later under <Queries>.

A C array is declared in this format:

const char *array[ROWS + 1][COLUMNS] = {
    { "column1", ... },
    { "value1",  ... },
    ...
};

The array is declared as a two-dimensional array of C strings. The first row of the array is the column names, [ROWS + 1] in the array declaration accounts for the title row.

All rows have the same number of columns. Column values may be NULL, in which case they will be treated the same as SQL NULLs in SQL query results.

Optionally, a column types array is declared separately:

#include <opencreport.h>

const enum ocrpt_result_type coltypes[COLUMNS] = {
    ...
};

If this array is present, it must have the same number of COLUMNS as the matching data array. The enum ocrpt_result_type usable in data array type declaration are OCRPT_RESULT_STRING, OCRPT_RESULT_NUMBER and OCRPT_RESULT_DATETIME.

SQL queries for MariaDB, PostgreSQL and ODBC datasources may be declared two ways, either as the XML value for <Query>:

<Query
    name="myquery"
    datasource="mysource">
SELECT * FROM some_table
</Query>

or as the value attribute:

<Query
    name="myquery"
    datasource="mysource"
    value="SELECT * FROM some_table" />

Note, that the XML attribute datasource="..." must match a previously declared datasource.

The SQL query can be any SELECT statement.

Queries for CSV, XML, JSON and spreadsheet datasources may be declared two ways. Either as the XML value for <Query>:

<Query name="myquery" datasource="mysource" >xmldata.xml</Query>

or as the value attribute:

<Query
    name="myquery"
    datasource="mysource"
    value="'xmldata.xml'" />

Example query for a spreadsheet:

<Query
    name="mysheet"
    datasource="mysource"
    value="'Sheet1'" />

Notes:

Queries for array datasources may be declared two ways. Either as the XML value for <Query>:

<Query
    name="myquery"
    datasource="mysource"
    coltypes="'coltypes'"
    rows="30"
    cols="6"
>array</Query>

or as the value attribute:

<Query
    name="myquery"
    datasource="mysource"
    value="'array'"
    coltypes="'coltypes'"
    rows="30"
    cols="6" />

Notes:

Failing to fulfill the above may cause crashes or wrong data to be used in the report.

Note that any attribute setting below may only use constant expressions or an query column reference from Independent queries. An environment variable (since it can't - or shouldn't - change during the report execution) is considered constant. See Expressions. This allows external control for the attributes in question.

<Part font_name="'Arial'">
<Part fontName="'Arial'">

<Part font_size="10">
<Part fontSize="10">

<Part size_unit="'rlib'">
<Part size_unit="'points'">

<Part noquery_show_nodata="yes">
<Part noquery_show_nodata="no">

<Part report_height_after_last="yes">
<Part report_height_after_last="no">

<Part orientation="'portrait'">
<Part orientation="'landscape'">

<Part top_margin="0.2">
<Part topMargin="0.2">
<Part bottom_margin="0.2">
<Part bottomMargin="0.2">
<Part left_margin="0.2">
<Part leftMargin="0.2">
<Part right_margin="0.2">
<Part rightMargin="0.2">

<Part paper_type="'A4'">
<Part paperType="'A4'">

<Part iterations="3">

<Part suppress="yes">

<Part suppressPageHeaderFirstPage="yes">

As described at the beginning of this section (see Report parts), a <Part> may contain one or more report rows (<pr>) which in turn may contain one or more columns (<pr>). See Part row and Part column. Apart from these, global page headers and footers may also be used for report parts.

<Part>
    <PageHeader>
        <Output>
            ...
        </Output>
    </PageHeader>
</Part>

<Part>
    <PageFooter>
        <Output>
            ...
        </Output>
    </PageFooter>
</Part>

<Part>
    <pr>
        <pd>
            ...
        </pd>
    </pr>
</Part>

Note that any attribute setting below may only use constant expressions or an query column reference from Independent queries. An environment variable (since it can't - or shouldn't - change during the report execution) is considered constant. See Expressions. This allows external control for the attributes in question.

<pr layout="'flow'">
<pr layout="'fixed'">

<pr newpage="yes">

<pr suppress="yes">

Note that any attribute setting below may only use constant expressions or an query column reference from Independent queries. An environment variable (since it can't - or shouldn't - change during the report execution) is considered constant. See Expressions. This allows external control for the attributes in question.

<pd width="60">

<pd height="120">

<pd border_width="2">

<pd border_color="'blue'">

<pd detail_columns="3">

<pd column_pad="0.2">

<pd suppress="yes">

Note that any attribute setting below may only use constant expressions or an query column reference from Independent queries. An environment variable (since it can't - or shouldn't - change during the report execution) is considered constant. See Expressions. This allows external control for the attributes in question.

<Report font_name="'Arial'">
<Report fontName="'Arial'">

<Report font_size="10">
<Report fontSize="10">

<Report size_unit="'rlib'">
<Report size_unit="'points'">

<Report noquery_show_nodata="yes">
<Report noquery_show_nodata="no>

<Report report_height_after_last="yes">
<Report report_height_after_last="no">

<Report orientation="'portrait'">
<Report orientation="'landscape'">

<Report top_margin="0.2">
<Report topMargin="0.2">
<Report bottom_margin="0.2">
<Report bottomMargin="0.2">
<Report left_margin="0.2">
<Report leftMargin="0.2">
<Report right_margin="0.2">
<Report rightMargin="0.2">

<Part paper_type="'A4'">
<Part paperType="'A4'">

<Report height="120">

<Report iterations="3">

<Report suppress="yes">

<Report suppressPageHeaderFirstPage="yes">

<Report query="query1">

<Report field_header_priority="'low'">
<Report field_header_priority="'high'">

<Report border_width="2">

<Report border_color="'blue'">

<Report detail_columns="3">

<Report column_pad="0.2">

This XML part below shows a complete example of nested breaks based on the real life example mentioned in Section 6.1.

<Report>

    <Breaks>

        <Break>

            <BreakHeader>
                <Output>
                    <Line>
                        <field value="query1.department" />
                    </Line>
                </Output>
            </BreakHeader>

            <BreakFooter>
                <Output>
                    <Line>
                        <literal>End of </literal>
                        <field value="query1.department" />
                    </Line>
                </Output>
            </BreakFooter>

            <BreakFields>
                <BreakField value="query1.department" />
            </BreakFields>

        </Break>

        <Break>

            <BreakHeader>
                <Output>
                    <Line>
                        <literal width="30" />
                        <field value="query1.paygrade" />
                    </Line>
                </Output>
            </BreakHeader>

            <BreakFooter>
                <Output>
                    <Line>
                        <literal width="30" />
                        <literal>End of </literal>
                        <field value="query1.paygrade" />
                    </Line>
                </Output>
            </BreakFooter>

            <BreakFields>
                <BreakField value="query1.paygrade" />
            </BreakFields>

        </Break>

    </Breaks>

    <Detail>

        <FieldHeaders>
            <Output>
                <Line>
                    <literal width="60" />
                    <literal>Employee name</literal>
                </Line>
            </Output>
        </FieldHeaders>

        <FieldDetails>
            <Output>
                <Line>
                    <literal width="60" />
                    <field value="query1.employee" />
                </Line>
            </Output>
        </FieldDetails>

    <Detail>

</Report>

Assuming that Size unit attribute is set to points, the indentation would be 30 and 60 points for certain elements (see the empty <literal>s) and the result would look like this:

Note that Expressions in attribute settings below depend on the parent node context. Some may only use constant expressions or query column references from Independent queries. <Output> nodes in <Report> context may also use report query column references.

<Output suppress="yes">

Note that Expressions in attribute settings below depend on the parent node context. Some may only use constant expressions or query column references from Independent queries. Child nodes of <Output> nodes in <Report> context may also use report query column references.

<Line font_name="'Arial'">
<Line fontName="'Arial'">

<Line font_size="10">
<Line fontSize="10">

<Line bold="yes">

<Line italic="yes">
<Line italics="yes">

<Line suppress="yes">

<Line color="'blue'">
<Line colour="'blue'">

<Line bgcolor="'blue'">
<Line bgcolour="'blue'">

Note that Expressions in attribute settings below depend on the parent node context. Some may only use constant expressions or query column references from Independent queries. Child nodes of <Output> nodes in <Report> context may also use report query column references.

<Line>
    <field value="'This text'" />
    <field>This text</field>
    <literal value="'This text'" />
    <literal>This text</literal>
</Line>

<field delayed="yes" />
<field precalculate="yes" />

<field value="query1.field1" format="'%s'" >

<field value="query1.field1"
       format="'Look, there is a %s there!'" >

<field value="query1.field1" format="'!&%s'" />

<field value="query1.field1"
       format="'Look, there is a !&%s there!'" >

<field value="query1.field1"
       format="'!&{%s}'" ... />

<field value="query1.field1"
       format="'%6.6s'" ... />

<field value="query1.field1"
       format="'!&%6.6s'" ... />

<field value="query1.field1"
       format="'!&{%6.6s}'" ... />

<field value="query1.field1"
       format="'%.3d'" >

<field value="query1.field1"
       format="'You have %.3d apples.'" >

<field value="val(query1.field1)"
       format="'%.2d'" />

<field value="query1.field1"
       format="'!#%.3d'" >

<field value="query1.field1"
       format="'You have !#%.3d apples.'" >

<field value="val(query1.field1)"
       format="'!#%.2d'" />

<field value="query1.field1"
       format="'!#{%.3d}'" >

<field value="query1.field1"
       format="'You have !#{%.3d} apples.'" >

<field value="val(query1.field1)"
       format="'!#%.2d'" />

<field value="query1.field1"
       format="'!$%=*#150n'" />

<field value="query1.field1"
       format="'!${%=*#150n}'" />

<field value="query1.field1"
       format="'!@%c'" />

<field value="query1.field1"
       format="'!@%Y-%m-%d'" ... />

<field value="query1.field1"
       format="'!@{%c}'" ... />

<field value="query1.field1"
       format="'!@{%Y-%m-%d}'" ... />

<field value="3" format="'%.2d'" width="6" />

<field value="3" format="'%.2d'"
       width="6" align="'center'" />

<Line color="'blue'">
<Line colour="'blue'">

<Line bgcolor="'blue'">
<Line bgcolour="'blue'">

<Part font_name="'Arial'">
<Part fontName="'Arial'">

<Part font_size="10">
<Part fontSize="10">

<field bold="yes" />

<field italic="yes" />
<field italics="yes" />

<field value="'This is my website'"
       link="'https://github.com/zboszor/OpenCReports'" />

<field value="'This is a long text...'"
       width="12" memo="yes" />

<field value="'This is a long text...'"
       width="12" memo="yes" memo_wrap_chars="yes" />

<field value="'This is a long text...'"
       width="12" memo="yes" memo_max_lines="20" />

<field value="'This is a field'"
       translate="yes" />

<field value="q.apples"
       format="'You have %d apples.'"
       translate="yes" />

<field value="'This is a long text...'"
       col="3" />

Note that Expressions in attribute settings below depend on the parent node context. Some may only use constant expressions or query column references from Independent queries. Child nodes of <Output> nodes in <Report> context may also use report query column references.

<HorizontalLine size="3" />

<HorizontalLine align="'center'"
                length="200" />

<HorizontalLine indent="15" />

<HorizontalLine length="150" />

<HorizontalLine font_size="14" />
<HorizontalLine fontSize="14" />

<HorizontalLine suppress="yes" />

<HorizontalLine color="'blue'" />
<HorizontalLine colour="'blue'" />
<HorizontalLine bgcolor="'blue'" />
<HorizontalLine bgcolour="'blue'" />

Note that Expressions in attribute settings below depend on the parent node context. Some may only use constant expressions or query column references from Independent queries. Child nodes of <Output> nodes in <Report> context may also use report query column references.

<Image value="'filename.jpg'" />

<Image value="'filename.jpg'"
       suppress="yes" />

<Image value="'filename.jpg'"
       type="'jpg'" />

<Image value="'filename.jpg'"
       width="100" />

<Image value="'filename.jpg'"
       height="100" />

<Image value="'filename.jpg'"
       text_width="8" />

<Image value="'filename.jpg'"
       textWidth="8" />

<Image value="'filename.jpg'"
       bgcolor="'red'" />

<Image value="'filename.jpg'"
       align="'center'" />

Note that Expressions in attribute settings below depend on the parent node context. Some may only use constant expressions or query column references from Independent queries. Child nodes of <Output> nodes in <Report> context may also use report query column references.

<Line>
    <Barcode suppress="yes" ... />
</Line>

<Line>
    <Barcode value="'1234567890128'" />
</Line>

<Barcode delayed="yes" />
<Barcode precalculate="yes" />

<Barcode value="'123456789012'" type="'ean-13'" />

<Barcode value="'...'" width="6" />

<Barcode value="'...'" height="6" />

<Barcode color="'blue'">
<Barcode colour="'blue'">

<Barcode bgcolor="'blue'">
<Barcode bgcolour="'blue'">

opencreport *
ocrpt_init(void);

This function loads the specified XML file into the report handler. It returns true for success, false for failure.

bool
ocrpt_parse_xml(opencreport *o,
                const char *filename);

This function parses the buffer as if it contained XML contents and loads the details into the report handler. It returns true for success, false for failure.

bool
ocrpt_parse_xml_from_buffer(opencreport *o,
                            const char *buffer,
                            size_t size);

enum ocrpt_format_type {
    OCRPT_OUTPUT_PDF = 1,
    OCRPT_OUTPUT_HTML,
    OCRPT_OUTPUT_TXT,
    OCRPT_OUTPUT_CSV,
    OCRPT_OUTPUT_XML,
    OCRPT_OUTPUT_JSON,
    OCRPT_OUTPUT_LAST
};
typedef enum ocrpt_format_type ocrpt_format_type;

void
ocrpt_set_output_format(opencreport *o,
                        ocrpt_format_type format);

ocrpt_format_type
ocrpt_get_output_format(opencreport *o);

const char *
ocrpt_get_output_format_name(ocrpt_format_type format);

Set output parameters for the report.

void
ocrpt_set_output_parameter(opencreport *o,
                           const char *param,
                           const char *value);

Possible parameters for the HTML output driver:

Possible parameters for the CSV output driver:

Note that some languages (e.g. German, Swedish and Hungarian) use comma as the decimal separator instead of the decimal dot. For these languages, either set csv_delimiter to something else, or don't enable either no_quotes or only_quote_strings.

Possible parameters for the XML output driver:

This function executes the report, constructs the result in memory. It returns true for success, false for failure. It is a failure if the output format is unset.

bool
ocrpt_execute(opencreport *o);

Dump the report output on the program's standard output channel.

void
ocrpt_spool(opencreport *o);

Get the report output. The application then can save it as a file.

const char *
ocrpt_get_output(opencreport *o, size_t *length);

Get the report content type for web publishing. The content type depends on the output type the report was executed with. It returns an array of ocrpt_string * pointers for potentially multiple HTTP header lines. The last pointer in the array is NULL.

const ocrpt_string **
ocrpt_get_content_type(opencreport *o);

Calling this function frees up the report handler structure and everything created for it, even the details that were created by the low level API.

void
ocrpt_free(opencreport *o);

This function reports the OpenCReports library version.

const char *
ocrpt_version(void);