The default is 256 bits of floating point precision. The expression string must evaluate to a numeric value, the integer part will be used to set the number of precision bits for numeric calculations.

void
ocrpt_set_numeric_precision_bits(opencreport *o,
                                 const char *expr_string);

The report XML description may set the numeric precision. This function allows the application to query it.

mpfr_prec_t
ocrpt_get_numeric_precision_bits(opencreport *o);

The expression string must evaluate to a string value. Possible values are: nearest, to_minus_inf, to_inf, to_zero, away_from_zero and faithful. The default is nearest.

void
ocrpt_set_rounding_mode(opencreport *o,
                        const char *expr_string);

Setting up the translation needs two parameters: the so called translation domain and the toplevel directory for the translations. It relies on GNU Gettext.

void
ocrpt_bindtextdomain(opencreport *o,
                     const char *domainname,
                     const char *dirname);

Setting up the translation needs two parameters: the so called translation domain and the toplevel directory for the translations. It relies on GNU Gettext. This function allows setting the translation from a supplemental query. The passed in expressions strings must evaluate to string values, with potential fallbacks to plain strings in case of parse errors or if the expressions may be interpreted as query columns but no such column names exist in any query.

void
ocrpt_bindtextdomain_from_expr(opencreport *o,
                               const char *domain_expr,
                               const char *dir_expr);

Setting the locale for the report does not affect the main program or other threads. A locale setting includes the language and the country. The UTF-8 suffix is necessary. E.g.: en_GB.UTF-8 or de_DE.UTF-8

void
ocrpt_set_locale(opencreport *o,
                 const char *locale);

This function allows setting the locale from a supplementary query of the report. It is used by the report XML parser code and it's a lower priority setting than the previous function: the application executing the report may need to be run a different locale. The expression string must evaluate to a string value that's a valid locale string.

void
ocrpt_set_locale_from_expr(opencreport *o,
                           const char *expr_string);

A customized monetary printing function was implemented for the purposes of the report which MPFR doesn't provide. It is used in OpenCReports both internally and by unit tests.

ssize_t
ocrpt_mpfr_strfmon(opencreport *o,
                   char *s, size_t maxsize,
                   const char *format, ...);

Add a datasource of the specific type to the report handler with the associated source_name, using optional connection parameters.

ocrpt_datasource *
ocrpt_datasource_add(opencreport *o,
                     const char *source_name,
                     const char *type,
                     const ocrpt_input_connect_parameter *conn_params);

The pointer to connection parameters can be NULL for array, csv, json, and xml datasource types.

ocrpt_input_connect_parameter conn_params[] = {
    { .param_name = "group", .param_value = "..." },
    { .param_name = "optionfile", .param_value = "..." },
    { .param_name = NULL }
};

ocrpt_input_connect_parameter conn_params[] = {
    { .param_name = "dbname", .param_value = "..." },
    { .param_name = "host", .param_value = "..." },
    { .param_name = "port", .param_value = "..." },
    { .param_name = "unix_socket", .param_value = "..." },
    { .param_name = "user", .param_value = "..." },
    { .param_name = "password", .param_value = "..." },
    { .param_name = NULL }
};

ocrpt_input_connect_parameter conn_params[] = {
    { .param_name = "connstr", .param_value = "..." },
    { .param_name = NULL }
};

ocrpt_input_connect_parameter conn_params[] = {
    { .param_name = "unix_socket", .param_value = "..." },
    { .param_name = "dbname", .param_value = "..." },
    { .param_name = "user", .param_value = "..." },
    { .param_name = "password", .param_value = "..." },
    { .param_name = NULL }
};

ocrpt_input_connect_parameter conn_params[] = {
    { .param_name = "dbname", .param_value = "..." },
    { .param_name = "host", .param_value = "..." },
    { .param_name = "port", .param_value = "..." },
    { .param_name = "user", .param_value = "..." },
    { .param_name = "password", .param_value = "..." },
    { .param_name = NULL }
};

ocrpt_input_connect_parameter conn_params[] = {
    { .param_name = "connstr", .param_value = "..." },
    { .param_name = NULL }
};

ocrpt_input_connect_parameter conn_params[] = {
    { .param_name = "dbname", .param_value = "..." },
    { .param_name = "user", .param_value = "..." },
    { .param_name = "password", .param_value = "..." },
    { .param_name = NULL }
};

ocrpt_input_connect_parameter conn_params[] = {
    { .param_name = "filename", .param_value = "..." },
    { .param_name = NULL }
};

Find the data source using its name. It returns NULL if the named data source is not found.

ocrpt_datasource *
ocrpt_datasource_get(opencreport *o,
                     const char *source_name);

Set the encoding of a datasource in case if it's not already UTF-8, so data provided by it is automatically converted.

void
ocrpt_datasource_set_encoding(ocrpt_datasource *source,
                              const char *encoding);

Free a datasource from the opencreport structure it was added to. It's not needed to be called, all datasources are automatically free with ocrpt_free()

void
ocrpt_datasource_free(ocrpt_datasource *source);

Add a direct (application internal) data based query to the report handler.

ocrpt_query *
ocrpt_query_add_data(ocrpt_datasource *source,
                     const char *name,
                     const void *data,
                     int32_t rows, int32_t cols,
                     const int32_t *types,
                     int32_t types_cols);

The built-in array datasource interprets void *data as a two-dimensional array containing pointers to C strings, a.k.a.

char *array[rows + 1][cols]

The first row of the array are the column (field) names. The types array contains cols (or fewer) number of enum ocrpt_result_type elements to indicate the column data types.

If the types pointer is NULL, the column values are treated as string data. This is how RLIB worked.

The call is only successful if the datasource is direct data based. See Section 10.1.3.9 and Datasource input driver details.

Add a "symbolic" (discoverable by name) data based query.

ocrpt_query *
ocrpt_query_add_symbolic_data(ocrpt_datasource *source,
                              const char *name,
                              const char *data_name,
                              int32_t rows, int32_t cols,
                              const char *types_name,
                              int32_t types_cols);

Symbols of the application can be discovered via dlsym() if the application was built with the compiler option -rdynamic.

The call is only successful if the datasource is symbolic data based. See Section 10.1.3.10 and Datasource input driver details.

Add a file based query to the report handler.

ocrpt_query *
ocrpt_query_add_file(ocrpt_datasource *source,
                     const char *name,
                     const char *filename,
                     const int32_t *types,
                     int32_t types_cols);

The call is only successful if the datasource is file based. See Section 10.1.3.11 and Datasource input driver details.

The types array pointer may be NULL. For file based datasource types that don't support data type specifiers internally (or they are optional and omitted), this means that the column values are of the string data type. This is how RLIB worked. In this case, conversion functions like Section 4.12.4, Section 4.10.16 and Section 4.10.10 are needed to process the values using their actual data type.

When the types array pointer is not NULL, it is used to set the data type specifiers for built-in file based datasources, even if the file contains type specifiers.

The JSON file format expected by OpenCReports is defined in JSON file type.

The XML file format expected by OpenCReports is defined in XML file type.

Add an SQL statement based query to the report handler.

ocrpt_query *
ocrpt_query_add_sql(ocrpt_datasource *source,
                    const char *name,
                    const char *querystr);

The call is only successful if the datasource is SQL based. See Section 10.1.3.12 and Datasource input driver details.

bool
ocrpt_datasource_is_data(ocrpt_datasource *source);

bool
ocrpt_datasource_is_symbolic_data(ocrpt_datasource *source);

bool
ocrpt_datasource_is_file(ocrpt_datasource *source);

bool
ocrpt_datasource_is_sql(ocrpt_datasource *source);

Find a query using its name.

ocrpt_query *
ocrpt_query_get(opencreport *o,
                const char *name);

Create (first call) or get the ocrpt_query_result array from a query. Output parameter cols returns the number of columns in the result array. It must be re-run after ocrpt_navigate_next() since the previously returned pointer becomes invalid.

ocrpt_query_result *
ocrpt_query_get_result(ocrpt_query *q,
                       int32_t *cols);

Using the ocrpt_query_result * result from ocrpt_query_get_result(), the column names can be discovered from a query.

const char *
ocrpt_query_result_column_name(ocrpt_query_result *qr,
                               int32_t col);

Using the ocrpt_query_result * result from ocrpt_query_get_result(), get a pointer to the column data in its internal (hidden) representation.

ocrpt_result *
ocrpt_query_result_column_result(ocrpt_query_result *qr,
                                 int32_t col);

Add a follower query to the leader query. The leader is the primary query and the follower will run in parallel with it until the leader runs out of rows. In case the leader has more rows than the follower, then for rows in the leader where there are no follower rows, the follower fields are set to NULL.

bool
ocrpt_query_add_follower(ocrpt_query *leader,
                         ocrpt_query *follower);

Add an N:1 follower query to the leader query. The leader is the primary query and rows from the follower will be matched using the match expression. If there are multiple rows in the follower matching the leader row, then the leader row will be listed that many times. For rows in the leader where there are no matching rows in the follower, the follower fields are set to NULL. It is similar to LEFT OUTER JOIN in SQL databases. For creating an ocrpt_expr expression pointer, see the next section.

bool
ocrpt_query_add_follower_n_to_1(ocrpt_query *leader,
                                ocrpt_query *follower,
                                ocrpt_expr *match);

Call the ocrpt_input::refresh() method for datasources that support it. It returns true if all queries were successfully refreshed.

bool
ocrpt_query_refresh(opencreport *o);

Free a query and remove it from the report handler. It's optional. ocrpt_free() frees the queries added to the opencreport structure.

void
ocrpt_query_free(ocrpt_query *q);

Start query (or query set) navigation. q should be the primary query of the report.

void
ocrpt_query_navigate_start(ocrpt_query *q);

Navigate the query (or query set) to the next row. Returns false if there was no more rows. in which case the ocrpt_query_result arrays for all queries in the query set (returned by previous ocrpt_query_get_result() calls contain invalid data.

bool
ocrpt_query_navigate_next(ocrpt_query *q);

These functions expose an implementation detail of the data traversal in OpenCReports. There is a 3-row data cache in which there is always the current row. One past row is kept so e.g. break boundaries can be detected and there is one row read-ahead to detect the end-of-data condition early. These functions allow to switch back and forth in the 3-row data cache, making the previous or next row the "current" one momentarily. The query must always be the primary query of the report. Used by unit tests that don't use ocrpt_execute().

void
ocrpt_query_navigate_use_prev_row(ocrpt_query *q);

void
ocrpt_query_navigate_use_next_row(ocrpt_query *q);

For direct (application internal) data based data sources and queries, OpenCReports needs a way to to find the data pointer and the supplementary type identifier array. These are language specific. The below ones are the C specific ones. An override function is also provided to set a new discovery function. The discovery function should return the dimensions for both the (usuall 2D array) data and the 1D types array. It also returns whether types must be freed by the caller.

typedef void
(*ocrpt_query_discover_func)(const char *,
                             void **,
                             int32_t *,
                             int32_t *,
                             const char *,
                             void **,
                             int32_t *,
                             bool *);

void
ocrpt_query_set_discover_func(ocrpt_query_discover_func func);

extern ocrpt_query_discover_func ocrpt_query_discover_array;

void
ocrpt_query_discover_array_c(const char *arrayname,
                             void **array,
                             int32_t *rows,
                             int32_t *cols,
                             const char *typesname,
                             void **types,
                             int32_t *types_cols,
                             bool *free_types);

Note that the C specific generic discovery function does not and cannot return the array dimensions, since there is no official API related to dlsym() that would return the size associated with a symbol. It's up to the application writers to come up with a smarter (application specific) discovery function that also returns the array dimensions. With such a smart discovery function, one can specify the array and the column types array name without the related dimensions, i.e. the rows and cols specifiers in Array queries and File based queries.

This function parses an expression string and creates an expression tree. It returns a pointer to the ocrpt_expr structure.

If an error occurs, it returns NULL and optionally returns the error message in err pointer if it's not NULL.

ocrpt_expr *
ocrpt_expr_parse(opencreport *o,
                 const char *expr_string,
                 char **err);

The returned pointer must be freed with ocrpt_expr_free().

This function parses an expression string, creates an expression tree and binds it to a report. It returns a pointer to the ocrpt_expr structure.

If an error occurs, it returns NULL and optionally returns the error message in err pointer if it's not NULL.

ocrpt_expr *
ocrpt_report_expr_parse(ocrpt_report *r,
                        const char *expr_string,
                        char **err);

The returned pointer is automatically freed by ocrpt_free()

Free an expression parse tree. If it was bound to the passed-in ocrpt_report, this association is also deleted. Alternatively, the expression doesn't need to be freed if it was bound to a report when it was parsed, as it will be automatically freed when freeing either the report, or the global opencreport structure.

void
ocrpt_expr_free(ocrpt_expr *e);

Get the original expression string from an expression parse tree.

const char *
ocrpt_expr_get_expr_string(ocrpt_expr *e);

This function resolves variable (identifier) references in the expression. This is needed to bind query columns to expressions that use them.

void
ocrpt_expr_resolve(ocrpt_expr *e);

This function optimizes an expression so it may needs fewer computation steps during report execution.

void
ocrpt_expr_optimize(ocrpt_expr *e);

This function evaluates the expression. It returns the expression's ocrpt_result result structure. The result must not be freed with ocrpt_result_free(). It will be done by ocrpt_expr_free()

For expressions with query column references, this function must be called after ocrpt_query_navigate_next otherwise the result is not valid.

ocrpt_result *
ocrpt_expr_eval(ocrpt_expr *e);

This function returns the expression result if it was already evaluated. The result must not be freed with ocrpt_result_free(). It will be done by ocrpt_expr_free(). Used by unit tests.

ocrpt_result *
ocrpt_expr_get_result(ocrpt_expr *e);

Print an expression tree in its processed form on the standard output. Used by unit tests.

void
ocrpt_expr_print(ocrpt_expr *e);

Print an expression tree with subexpressions and their results in its processed form on the standard output. Used by unit tests.

void
ocrpt_expr_result_deep_print(ocrpt_expr *e);

This function returns the number of expression nodes. Used by unit tests to validate optimizazion.

int32_t
ocrpt_expr_nodes(ocrpt_expr *e);

OpenCReports keeps track of the last three query rows and computes three result values for expressions for internal reasons. These functions initialize the type for either the current result or all results of the expression.

enum ocrpt_result_type {
    OCRPT_RESULT_ERROR,
    OCRPT_RESULT_STRING,
    OCRPT_RESULT_NUMBER,
    OCRPT_RESULT_DATETIME
};

bool ocrpt_expr_init_result(ocrpt_expr *e,
                            enum ocrpt_result_type type);

void ocrpt_expr_init_results(ocrpt_expr *e,
                             enum ocrpt_result_type type);

ocrpt_result *
ocrpt_expr_make_error_result(ocrpt_expr *e,
                             const char *format, ...);

Set whether the iterative expression's first value is computed from its base expression or from its result expression.

void
ocrpt_expr_set_iterative_start_value(ocrpt_expr *e,
                                     bool start_with_init);

Get the current value of an expression in a C base type. Used by parsing report description XML files and unit tests.

const char *
ocrpt_expr_get_string(ocrpt_expr *e);

long
ocrpt_expr_get_long(ocrpt_expr *e);

double
ocrpt_expr_get_double(ocrpt_expr *e);

Used by unit tests.

void
ocrpt_expr_set_string(ocrpt_expr *e,
                            const char *s);

void
ocrpt_expr_set_long(ocrpt_expr *e,
                          long l);

void
ocrpt_expr_set_double(ocrpt_expr *e,
                            double d);

Expressions use OCRPT_EXPR_RESULTS number of values. With these functions, any of them can be set. Used by unit tests.

void
ocrpt_expr_set_nth_result_string(ocrpt_expr *e,
                                       int which,
                                       const char *s);

void
ocrpt_expr_set_nth_result_long(ocrpt_expr *e,
                                     int which,
                                     long l);

void
ocrpt_expr_set_nth_result_double(ocrpt_expr *e,
                                       int which,
                                       double d);

Compare the current value of an expression with its previous value and return true if they are equal. It's used to implement Report breaks.

bool
ocrpt_expr_cmp_results(ocrpt_expr *e);

void
ocrpt_expr_set_delayed(ocrpt_expr *e,
                       bool delayed);

If e contains r.value, the expression rvalue will be used to resolve this reference.

void
ocrpt_expr_set_field_expr(ocrpt_expr *e,
                          ocrpt_expr *rvalue);

The returned pointer must be freed with ocrpt_result_free().

ocrpt_result *
ocrpt_result_new(opencreport *o);

enum ocrpt_result_type
ocrpt_result_get_type(ocrpt_result *result);

Copy expression result from source to destination. Both results must have been created for the same opencreport structure, either explicitly with ocrpt_result_new() or implicitly with an expression parsed for this opencreport structure or a report structure owned by it.

void
ocrpt_result_copy(ocrpt_result *dst,
                  ocrpt_result *src);

Used by unit tests.

void
ocrpt_result_print(ocrpt_result *r);

void
ocrpt_result_free(ocrpt_result *r);

Using the ocrpt_result * result from a query column or an expression, detect whether the column value is NULL.

bool
ocrpt_result_isnull(ocrpt_result *result);

Using the ocrpt_result * result from a query column or an expression, detect whether the column value is numeric.

bool
ocrpt_result_isnumber(ocrpt_result *result);

Using the ocrpt_result * result from a query column or an expression, get the numeric column value. It returns NULL if the column is:

mpfr_ptr
ocrpt_result_get_number(ocrpt_result *result);

Using the ocrpt_result * result from a query column or an expression, detect whether the column value is string.

bool
ocrpt_result_isstring(ocrpt_result *result);

Using the ocrpt_result * result from a query column or an expression, get the string column value. It returns NULL if the column is

ocrpt_string *
ocrpt_result_get_string(ocrpt_result *result);

Using the ocrpt_result * result from a query column or an expression, detect whether the column value is datetime.

bool
ocrpt_result_isdatetime(ocrpt_result *result);

Using the ocrpt_result * result from a query column or an expression, get the datetime column value. It returns NULL if the column is

const struct tm *
ocrpt_result_get_datetime(ocrpt_result *result);

Using the ocrpt_result * result from a query column or an expression, detect whether the datetime column value is interval.

bool
ocrpt_result_datetime_is_interval(ocrpt_result *result);

Using the ocrpt_result * result from a query column or an expression, detect whether the datetime column value has valid date.

bool
ocrpt_result_datetime_is_date_valid(ocrpt_result *result);

Using the ocrpt_result * result from a query column or an expression, detect whether the datetime column value has valid time.

bool
ocrpt_result_datetime_is_time_valid(ocrpt_result *result);

Using this function, any variable type except OCRPT_VARIABLE_CUSTOM may be created. For a custom variable, see the next function.

enum ocrpt_var_type {
    OCRPT_VARIABLE_INVALID,
    OCRPT_VARIABLE_EXPRESSION,
    OCRPT_VARIABLE_COUNT,
    OCRPT_VARIABLE_COUNTALL,
    OCRPT_VARIABLE_SUM,
    OCRPT_VARIABLE_AVERAGE,
    OCRPT_VARIABLE_AVERAGEALL,
    OCRPT_VARIABLE_LOWEST,
    OCRPT_VARIABLE_HIGHEST,
    OCRPT_VARIABLE_CUSTOM
};
typedef enum ocrpt_var_type ocrpt_var_type;

ocrpt_var *
ocrpt_variable_new(ocrpt_report *r,
                   ocrpt_var_type type,
                   const char *name,
                   const char *expr,
                   const char *ignoreexpr,
                   const char *reset_on_break_name,
                   bool precalculate);

Create a custom variable of the specified type with the specified subexpressions.

ocrpt_var *
ocrpt_variable_new_full(ocrpt_report *r,
                        enum ocrpt_result_type type,
                        const char *name,
                        const char *baseexpr,
                        const char *ignoreexpr,
                        const char *intermedexpr,
                        const char *intermed2expr,
                        const char *resultexpr,
                        const char *reset_on_break_name,
                        bool precalculate);

Get the type of the variable.

ocrpt_var_type
ocrpt_variable_get_type(ocrpt_var *v);

Get subexpressions of a previously created basic or custom variable.

ocrpt_expr *
ocrpt_variable_baseexpr(ocrpt_var *v);

ocrpt_expr *
ocrpt_variable_ignoreexpr(ocrpt_var *v);

ocrpt_expr *
ocrpt_variable_intermedexpr(ocrpt_var *v);

ocrpt_expr *
ocrpt_variable_intermed2expr(ocrpt_var *v);

ocrpt_expr *
ocrpt_variable_resultexpr(ocrpt_var *v);

bool
ocrpt_variable_get_precalculate(ocrpt_var *var);

Resolve subexpressions of a variable so it can be evaluated correctly.

void
ocrpt_variable_resolve(ocrpt_var *v);

After evaluation, the result is in the expression returned by ocrpt_variable_resultexpr().

void
ocrpt_variable_evaluate(ocrpt_var *v);

Iterate over variables of a report. The first call needs the iterator list pointer to be set to NULL.

ocrpt_var *
ocrpt_variable_get_next(ocrpt_report *r,
                     ocrpt_list **list);

Create a break. No need to free it, ocrpt_free() does it.

ocrpt_break *
ocrpt_break_new(ocrpt_report *r,
                const char *name);

Set break attributes from expression strings for headernewpage and suppressblank. There is a 3rd flag accepted in the report XML DTD called newpage which is not represented (ignored) in the API, because it's also ignored in RLIB and is only handled for RLIB compatibility.

void
ocrpt_break_set_headernewpage(ocrpt_break *br,
                              const char *headernewpage);

void
ocrpt_break_set_suppressblank(ocrpt_break *br,
                              const char *suppressblank);

headernewpage="yes" instructs the layout to render <BreakHeader> on a new page.

suppressblank="yes" instructs the layout to suppress <BreakHeader> if any of the <BreakField>s are NULL value or an empty string, if the break field is of the string type.

Get the pointer to the break using its name.

ocrpt_break *
ocrpt_break_get(ocrpt_report *r,
                const char *name);

Get the name of the break using its structure pointer.

const char *
ocrpt_break_get_name(ocrpt_break *br);

bool
ocrpt_break_add_breakfield(ocrpt_break *br,
                           ocrpt_expr *bf);

Iterate over breaks of a report. The first call needs the iterator list pointer to be set to NULL.

ocrpt_break *
ocrpt_break_get_next(ocrpt_report *r,
                     ocrpt_list **list);

void
ocrpt_break_resolve_fields(ocrpt_break *br);

bool
ocrpt_break_check_fields(ocrpt_break *br);

The second parameter evaluate allows skipping evaluating the breakfield values. (This is an optimization in case it's executed after ocrpt_break_check_fields() which already evaluated the breakfields.)

bool
ocrpt_break_check_blank(ocrpt_break *br,
                        bool evaluate);

void
ocrpt_break_reset_vars(ocrpt_break *br);

Add a user defined function by specifying the name, the function pointer that contains the implementation, the number of operands (0 or greater for fixed number or operands, -1 is varying number of operands) and the function mathematical properties that help optimizing it.

bool
ocrpt_function_add(opencreport *o,
                   const char *fname,
                   ocrpt_function_call func,
                   void *user_data,
                   int32_t n_ops,
                   bool commutative,
                   bool associative,
                   bool left_associative,
                   bool dont_optimize);

Adding a user defined function with a name of a pre-existing function will override it.

OpenCReports functions are called with the parameters as declared below.

#define OCRPT_FUNCTION_PARAMS \
    ocrpt_expr *e, void *user_data

OpenCReports functions may be declared with these convenience symbols below.

#define OCRPT_FUNCTION(name) \
    void name(OCRPT_FUNCTION_PARAMS)

#define OCRPT_STATIC_FUNCTION(name) \
    static void name(OCRPT_FUNCTION_PARAMS)

The above function (ocrpt_function_add()) is called with a function pointer which has this type:

typedef void
(*ocrpt_function_call)(OCRPT_FUNCTION_PARAMS);

const ocrpt_function *
ocrpt_function_get(opencreport *o,
                   const char *fname);

In an expression tree, functions are represented as subexpressions with operands. This call may be used by OpenCReports functions to inspect whether the number of operands is in the expected range.

int32_t
ocrpt_expr_get_num_operands(ocrpt_expr *e);

This function is used by OpenCReports functions internally to compute the result from its operands.

ocrpt_result *
ocrpt_expr_operand_get_result(ocrpt_expr *e,
                              int32_t opnum);

ocrpt_part *
ocrpt_part_new(opencreport *o);

ocrpt_part_row *
ocrpt_part_new_row(ocrpt_part *p);

ocrpt_part_column *
ocrpt_part_row_new_column(ocrpt_part_row *pr);

ocrpt_report *
ocrpt_part_column_new_report(ocrpt_part_column *pd);

Iterators for getting report parts, part rows, columns in rows and reports in columns. Every iterator function must be called the first time with the list pointer set to NULL.

ocrpt_part *
ocrpt_part_get_next(opencreport *o,
                    ocrpt_list **list);

ocrpt_part_row *
ocrpt_part_row_get_next(ocrpt_part *p,
                        ocrpt_list **list);

ocrpt_part_column *
ocrpt_part_column_get_next(ocrpt_part_row *pr,
                           ocrpt_list **list);

ocrpt_report *
ocrpt_report_get_next(ocrpt_part_column *pd,
                      ocrpt_list **list);

Set the main query for a report either by the query structure pointer, or from expression. The expression must resolve to a string value, with fallback to a plain string.

void
ocrpt_report_set_main_query(ocrpt_report *r,
                            const ocrpt_query *query);

void
ocrpt_report_set_main_query_from_expr(ocrpt_report *r,
                                    const char *expr_string);

See Report query name. Unlike with the XML description, where the first globally declared query is used for the report if its main query is not set, the default via the low level API is unset.

The row number starts from 1.

long
ocrpt_report_get_query_rownum(ocrpt_report *r);

void
ocrpt_report_resolve_variables(ocrpt_report *r);

void
ocrpt_report_evaluate_variables(ocrpt_report *r);

void
ocrpt_report_resolve_breaks(ocrpt_report *r);

void
ocrpt_report_resolve_expressions(ocrpt_report *r);

void
ocrpt_report_evaluate_expressions(ocrpt_report *r);

Get the part's <Output> sections for <PageHeader> or <PageFooter>.

ocrpt_output *
ocrpt_layout_part_page_header(ocrpt_part *p);

ocrpt_output *
ocrpt_layout_part_page_footer(ocrpt_part *p);

Set the report pointer for the part's <Output> sections for <PageHeader> or <PageFooter>.

void
ocrpt_layout_part_page_header_set_report(ocrpt_part *p,
                                         ocrpt_report *r);

void
ocrpt_layout_part_page_footer_set_report(ocrpt_part *p,
                                         ocrpt_report *r);

Get the report's <Output> sections for <NoData>, <ReportHeader>, <ReportFooter>, <FieldHeaders> or <FieldDetails>.

ocrpt_output *
ocrpt_layout_report_nodata(ocrpt_report *r);

ocrpt_output *
ocrpt_layout_report_header(ocrpt_report *r);

ocrpt_output *
ocrpt_layout_report_footer(ocrpt_report *r);

ocrpt_output *
ocrpt_layout_report_field_header(ocrpt_report *r);

ocrpt_output *
ocrpt_layout_report_field_details(ocrpt_report *r);

struct ocrpt_output_element;
typedef struct ocrpt_output_element ocrpt_output_element;

ocrpt_output_element *
ocrpt_output_element_get_next(ocrpt_output *output, ocrpt_list **iter);

bool
ocrpt_output_element_is_line(ocrpt_output_element *elem);

bool
ocrpt_output_element_is_hline(ocrpt_output_element *elem);

bool
ocrpt_output_element_is_image(ocrpt_output_element *elem);

bool
ocrpt_output_element_is_barcode(ocrpt_output_element *elem);

struct ocrpt_line_element;
typedef struct ocrpt_line_element ocrpt_line_element;

ocrpt_line_element *
ocrpt_line_element_get_next(ocrpt_line *line, void **iter);

bool
ocrpt_line_element_is_text(ocrpt_line_element *elem);

bool
ocrpt_line_element_is_image(ocrpt_line_element *elem);

bool
ocrpt_line_element_is_barcode(ocrpt_line_element *elem);

Get the break's <Output> sections for <BreakHeader> or <BreakFooter>.

ocrpt_output *
ocrpt_break_get_header(ocrpt_break *br);

ocrpt_output *
ocrpt_break_get_footer(ocrpt_break *br);

Note that part (page) header and footer, and report header and footer sections must be constant expressions. Other sections may depend on data derived from query columns. See Expressions.

ocrpt_expr *
ocrpt_output_set_suppress(ocrpt_output *output,
                          const char *expr_string);

ocrpt_expr *
ocrpt_output_get_suppress(ocrpt_output *output);

ocrpt_line *
ocrpt_output_add_line(ocrpt_output *output);

Note that settings in the part (page) header and footer sections must be constant expressions. Settings in other sections may depend on data derived from query columns. See Expressions.

ocrpt_expr *
ocrpt_line_set_font_name(ocrpt_line *line,
                         const char *expr_string);

ocrpt_expr *
ocrpt_line_get_font_name(ocrpt_line *line);

ocrpt_expr *
ocrpt_line_set_font_size(ocrpt_line *line,
                         const char *expr_string);

ocrpt_expr *
ocrpt_line_get_font_size(ocrpt_line *line);

ocrpt_expr *
ocrpt_line_set_bold(ocrpt_line *line,
                    const char *expr_string);

ocrpt_expr *
ocrpt_line_get_bold(ocrpt_line *line);

ocrpt_expr *
ocrpt_line_set_italic(ocrpt_line *line,
                      const char *expr_string);

ocrpt_expr *
ocrpt_line_get_italic(ocrpt_line *line);

ocrpt_expr *
ocrpt_line_set_suppress(ocrpt_line *line,
                        const char *expr_string);

ocrpt_expr *
ocrpt_line_get_suppress(ocrpt_line *line);

ocrpt_expr *
ocrpt_line_set_color(ocrpt_line *line,
                     const char *expr_string);

ocrpt_expr *
ocrpt_line_get_color(ocrpt_line *line);

ocrpt_expr *
ocrpt_line_set_bgcolor(ocrpt_line *line,
                       const char *expr_string);

ocrpt_expr *
ocrpt_line_get_bgcolor(ocrpt_line *line);

ocrpt_text *
ocrpt_line_add_text(ocrpt_line *line);

Note that settings in the part (page) header and footer sections must be constant expressions. Settings in other sections may depend on data derived from query columns. See Expressions.

ocrpt_expr *
ocrpt_text_set_value_string(ocrpt_text *text,
                            const char *string);

ocrpt_expr *
ocrpt_text_set_value_expr(ocrpt_text *text,
                          const char *expr_string);

ocrpt_expr *
ocrpt_text_get_value(ocrpt_text *text);

ocrpt_expr *
ocrpt_text_set_value_delayed(ocrpt_text *text,
                             const char *expr_string);


ocrpt_expr *
ocrpt_text_get_value_delayed(ocrpt_text *text);

ocrpt_expr *
ocrpt_text_set_format(ocrpt_text *text,
                      const char *expr_string);

ocrpt_expr *
ocrpt_text_get_format(ocrpt_text *text);

ocrpt_expr *
ocrpt_text_set_translate(ocrpt_text *text,
                         const char *expr_string);

ocrpt_expr *
ocrpt_text_get_translate(ocrpt_text *text);

ocrpt_expr *
ocrpt_text_set_width(ocrpt_text *text,
                     const char *expr_string);

ocrpt_expr *
ocrpt_text_get_width(ocrpt_text *text);

ocrpt_expr *
ocrpt_text_set_alignment(ocrpt_text *text,
                         const char *expr_string);

ocrpt_expr *
ocrpt_text_get_alignment(ocrpt_text *text);

ocrpt_expr *
ocrpt_text_set_color(ocrpt_text *text,
                     const char *expr_string);

ocrpt_expr *
ocrpt_text_get_color(ocrpt_text *text);

ocrpt_expr *
ocrpt_text_set_bgcolor(ocrpt_text *text,
                       const char *expr_string);

ocrpt_expr *
ocrpt_text_get_bgcolor(ocrpt_text *text);

ocrpt_expr *
ocrpt_text_set_font_name(ocrpt_text *text,
                         const char *expr_string);

ocrpt_expr *
ocrpt_text_get_font_name(ocrpt_text *text);

ocrpt_expr *
ocrpt_text_set_font_size(ocrpt_text *text,
                         const char *expr_string);

ocrpt_expr *
ocrpt_text_get_font_size(ocrpt_text *text);

ocrpt_expr *
ocrpt_text_set_bold(ocrpt_text *text,
                    const char *expr_string);

ocrpt_expr *
ocrpt_text_get_bold(ocrpt_text *text);

ocrpt_expr *
ocrpt_text_set_italic(ocrpt_text *text,
                      const char *expr_string);

ocrpt_expr *
ocrpt_text_get_italic(ocrpt_text *text);

ocrpt_expr *
ocrpt_text_set_link(ocrpt_text *text,
                    const char *expr_string);

ocrpt_expr *
ocrpt_text_get_link(ocrpt_text *text);

ocrpt_expr *
ocrpt_text_set_memo(ocrpt_text *text,
                    const char *expr_string);

ocrpt_expr *
ocrpt_text_get_memo(ocrpt_text *text);

ocrpt_expr *
ocrpt_text_set_memo_wrap_chars(ocrpt_text *text,
                               const char *expr_string);

ocrpt_expr *
ocrpt_text_get_memo_wrap_chars(ocrpt_text *text);

ocrpt_expr *
ocrpt_text_set_memo_max_lines(ocrpt_text *text,
                              const char *expr_string);

ocrpt_expr *
ocrpt_text_get_memo_max_lines(ocrpt_text *text);

ocrpt_hline *
ocrpt_output_add_hline(ocrpt_output *output);

Note that settings in the part (page) header and footer sections must be constant expressions. Settings in other sections may depend on data derived from query columns. See Expressions.

ocrpt_expr *
ocrpt_hline_set_size(ocrpt_hline *hline,
                     const char *expr_string);

ocrpt_expr *
ocrpt_hline_get_size(ocrpt_hline *hline);

ocrpt_expr *
ocrpt_hline_set_alignment(ocrpt_hline *hline,
                      const char *expr_string);

ocrpt_expr *
ocrpt_hline_get_alignment(ocrpt_hline *hline);

ocrpt_expr *
ocrpt_hline_set_indentation(ocrpt_hline *hline,
                       const char *expr_string);

ocrpt_expr *
ocrpt_hline_get_indentation(ocrpt_hline *hline);

ocrpt_expr *
ocrpt_hline_set_length(ocrpt_hline *hline,
                       const char *expr_string);

ocrpt_expr *
ocrpt_hline_get_length(ocrpt_hline *hline);

ocrpt_expr *
ocrpt_hline_set_font_size(ocrpt_hline *hline,
                          const char *expr_string);

ocrpt_expr *
ocrpt_hline_get_font_size(ocrpt_hline *hline);

ocrpt_expr *
ocrpt_hline_set_suppress(ocrpt_hline *hline,
                         const char *expr_string);

ocrpt_expr *
ocrpt_hline_get_suppress(ocrpt_hline *hline);

ocrpt_expr *
ocrpt_hline_set_color(ocrpt_hline *hline,
                      const char *expr_string);

ocrpt_expr *
ocrpt_hline_get_color(ocrpt_hline *hline);

ocrpt_barcode *
ocrpt_output_add_barcode(ocrpt_output *output);

ocrpt_barcode *
ocrpt_line_add_barcode(ocrpt_line *line);

ocrpt_image *
ocrpt_output_add_image(ocrpt_output *output);

ocrpt_image *
ocrpt_line_add_image(ocrpt_line *line);

Note that settings in the part (page) header and footer sections must be constant expressions. Settings in other sections may depend on data derived from query columns. See Expressions.

ocrpt_expr *
ocrpt_image_set_value(ocrpt_image *image,
                      const char *expr_string);

ocrpt_expr *
ocrpt_image_get_value(ocrpt_image *image);

ocrpt_expr *
ocrpt_image_set_suppress(ocrpt_image *image,
                         const char *expr_string);

ocrpt_expr *
ocrpt_image_get_suppress(ocrpt_image *image);

ocrpt_expr *
ocrpt_image_set_type(ocrpt_image *image,
                     const char *expr_string);

ocrpt_expr *
ocrpt_image_get_type(ocrpt_image *image);

ocrpt_expr *
ocrpt_image_set_width(ocrpt_image *image,
                      const char *expr_string);

ocrpt_expr *
ocrpt_image_get_width(ocrpt_image *image);

ocrpt_expr *
ocrpt_image_set_height(ocrpt_image *image,
                       const char *expr_string);

ocrpt_expr *
ocrpt_image_get_height(ocrpt_image *image);

ocrpt_expr *
ocrpt_image_set_alignment(ocrpt_image *image,
                      const char *expr_string);

ocrpt_expr *
ocrpt_image_get_alignment(ocrpt_image *image);

ocrpt_expr *
ocrpt_image_set_bgcolor(ocrpt_image *image,
                        const char *expr_string);

ocrpt_expr *
ocrpt_image_get_bgcolor(ocrpt_image *image);

ocrpt_expr *
ocrpt_image_set_text_width(ocrpt_image *image,
                           const char *expr_string);

ocrpt_expr *
ocrpt_image_get_text_width(ocrpt_image *image);

void
ocrpt_output_add_image_end(ocrpt_output *output);

typedef void
(*ocrpt_part_cb)(opencreport *,
                 ocrpt_part *,
                 void *data);

bool
ocrpt_add_part_added_cb(opencreport *o,
                        ocrpt_part_cb func,
                        void *data);

typedef void
(*ocrpt_report_cb)(opencreport *,
                   ocrpt_report *,
                   void *data);

bool
ocrpt_add_report_added_cb(opencreport *o,
                          ocrpt_report_cb func,
                          void *data);

typedef void
(*ocrpt_cb)(opencreport *,
            void *data);

bool
ocrpt_add_precalculation_done_cb(opencreport *o,
                                 ocrpt_cb func,
                                 void *data);

bool
ocrpt_part_add_iteration_cb(ocrpt_part *r,
                            ocrpt_part_cb func,
                            void *data);

bool
ocrpt_part_add_iteration_cb2(opencreport *o,
                             ocrpt_part_cb func,
                             void *data);

The second variant adds the callback in the opencreport structure context, making the callback apply to every report part. It's for RLIB compatibility.

bool
ocrpt_report_add_start_cb(ocrpt_report *r,
                          ocrpt_report_cb func,
                          void *data);

bool
ocrpt_report_add_start_cb2(opencreport *o,
                           ocrpt_report_cb func,
                           void *data);

The second variant adds the callback in the opencreport structure context, making the callback apply to every report. It's for RLIB compatibility.

bool
ocrpt_report_add_done_cb(ocrpt_report *r,
                         ocrpt_report_cb func,
                         void *data);

bool
ocrpt_report_add_done_cb2(opencreport *o,
                          ocrpt_report_cb func,
                          void *data);

The second variant adds the callback in the opencreport structure context, making the callback apply to every report. It's for RLIB compatibility.

bool
ocrpt_report_add_new_row_cb(ocrpt_report *r,
                            ocrpt_report_cb func,
                            void *data);

bool
ocrpt_report_add_new_row_cb2(opencreport *o,
                             ocrpt_report_cb func,
                             void *data);

The second variant adds the callback in the opencreport structure context, making the callback apply to every report. It's for RLIB compatibility.

bool
ocrpt_report_add_iteration_cb(ocrpt_report *r,
                              ocrpt_report_cb func,
                              void *data);

bool
ocrpt_report_add_iteration_cb2(opencreport *o,
                               ocrpt_report_cb func,
                               void *data);

The second variant adds the callback in the opencreport structure context, making the callback apply to every report. It's for RLIB compatibility.

bool
ocrpt_report_add_precalculation_done_cb(ocrpt_report *r,
                                        ocrpt_report_cb func,
                                        void *data);

bool
ocrpt_report_add_precalculation_done_cb2(opencreport *o,
                                         ocrpt_report_cb func,
                                         void *data);

The second variant adds the callback in the opencreport structure context, making the callback apply to every report. It's for RLIB compatibility.

typedef void
(*ocrpt_break_trigger_cb)(opencreport *,
                          ocrpt_report *,
                          ocrpt_break *,
                          void *);

bool
ocrpt_break_add_trigger_cb(ocrpt_break *br,
                           ocrpt_break_trigger_cb func,
                           void *data);

typedef ocrpt_result *
(*ocrpt_env_query_func)(opencreport *,
                        const char *);

extern ocrpt_env_query_func
ocrpt_env_get;

void
ocrpt_env_set_query_func(ocrpt_env_query_func func);

ocrpt_result *
ocrpt_env_get_c(opencreport *o,
                const char *env);

Set an "m" domain variable. If such a variable name didn't exist yet, and value is not NULL, then the variable is set. If value is NULL, the variable is removed. Such an explicit variable takes precedence over the environment variable of the same name when used in expressions.

void
ocrpt_set_mvariable(opencreport *o,
                    const char *name,
                    const char *value);

The returned path contains only single directory separators and doesn't contains symlinks.

char *
ocrpt_canonicalize_path(const char *path);

Add a new directory path to the list of search paths. It's useful to find files referenced with relative path.

void
ocrpt_add_search_path(opencreport *o,
                      const char *path);

Add a new directory path from an expression string to the list of search paths. It's useful to find files referenced with relative path. The expression must evaluate to a string value. It is evaluated at the beginning of the report execution. This function may be used explicitly but it's also used when parsing the <Path> nodes in a report XML description.

void
ocrpt_add_search_path_from_expr(opencreport *o,
                                const char *expr_string);

Resolve expressions added by ocrpt_add_search_path_from_expr(). It's used internally when executing the report.

void
ocrpt_resolve_search_paths(opencreport *o);

Find a file and return the canonicalized path to it. This function takes the search paths into account.

char *
ocrpt_find_file(opencreport *o,
                const char *filename);

Note that search paths added by ocrpt_add_search_path() and ocrpt_add_search_path_from_expr() are used in their order of appearance when searching for files during executing the report.

The function fills in the ocrpt_color structure with RGB values in Cairo values (0.0 ... 1.0).

If the color name starts with # or 0x or 0X then it must be in HTML notation.

Otherwise, the color name is looked up in the color name database in a case insensitive way. If found, the passed-in ocrpt_color structure is filled with the RGB color value of that name.

If not found or the passed-in color name is NULL, depending on the the expected usage (foreground or background color), the ocrpt_color structure is filled with either white or black.

void
ocrpt_get_color(opencreport *o,
                const char *cname,
                ocrpt_color *color,
                bool bgcolor);

const ocrpt_paper *
ocrpt_get_system_paper(void);

const ocrpt_paper *
ocrpt_get_paper_by_name(const char *paper);

Set global paper using an ocrpt_paper structure. The contents of the structure is copied.

void
ocrpt_set_paper(opencreport *o,
                const ocrpt_paper *paper);

Set paper for the report using a paper name. If the paper name is unknown, the system default paper is set.

void
ocrpt_set_paper_by_name(opencreport *o,
                        const char *paper);

const ocrpt_paper *
ocrpt_get_paper(opencreport *o);

Get the next ocrpt_paper structure in the iterator. For the first call, the iterator pointer must be NULL. It returns NULL when there are no more papers known to the system.

const ocrpt_paper *
ocrpt_paper_next(opencreport *o,
                 void **iter);

typedef void *
(*ocrpt_mem_malloc_t)(size_t);

typedef void *
(*ocrpt_mem_realloc_t)(void *,
                       size_t);

typedef void *
(*ocrpt_mem_reallocarray_t)(void *,
                            size_t,
                            size_t);

typedef void
(*ocrpt_mem_free_t)(const void *);

typedef char *
(*ocrpt_mem_strdup_t)(const char *);

typedef char *
(*ocrpt_mem_strndup_t)(const char *,
                       size_t);

typedef void
(*ocrpt_mem_free_size_t)(void *,
                         size_t);

extern ocrpt_mem_malloc_t ocrpt_mem_malloc0;
extern ocrpt_mem_realloc_t ocrpt_mem_realloc0;
extern ocrpt_mem_reallocarray_t ocrpt_mem_reallocarray0;
extern ocrpt_mem_free_t ocrpt_mem_free0;
extern ocrpt_mem_strdup_t ocrpt_mem_strdup0;
extern ocrpt_mem_strndup_t ocrpt_mem_strndup0;

void *
ocrpt_mem_malloc(size_t sz);

void *
ocrpt_mem_realloc(void *ptr,
                  size_t sz);

void *
ocrpt_mem_reallocarray(void *ptr,
                       size_t nmemb,
                       size_t sz);

void
ocrpt_mem_free(const void *ptr);

void *
ocrpt_mem_strdup(const char *ptr);

void *
ocrpt_mem_strndup(const char *ptr,
                  size_t sz);

It'a convenience alias for ocrpt_mem_free().

void
ocrpt_strfree(const char *s);

void
ocrpt_mem_set_alloc_funcs(ocrpt_mem_malloc_t rmalloc,
                          ocrpt_mem_realloc_t rrealloc,
                          ocrpt_mem_reallocarray_t rreallocarray,
                          ocrpt_mem_free_t rfree,
                          ocrpt_mem_strdup_t rstrdup,
                          ocrpt_mem_strndup_t rstrndup);

size_t
ocrpt_list_length(ocrpt_list *l);

ocrpt_list *
ocrpt_makelist1(const void *data);

This function can be used with variable number of arguments.

ocrpt_list *
ocrpt_makelist(const void *data1, ...);

ocrpt_list *
ocrpt_list_last(const ocrpt_list *l);

ocrpt_list *
ocrpt_list_nth(const ocrpt_list *l, uint32_t n);

ocrpt_list *
ocrpt_list_append(ocrpt_list *l,
                  const void *data);

This function make appending to the list work O(1) instead of O(n).

ocrpt_list *
ocrpt_list_end_append(ocrpt_list *l,
                      ocrpt_list **e,
                      const void *data);

ocrpt_list *
ocrpt_list_prepend(ocrpt_list *l,
                   const void *data);

ocrpt_list *
ocrpt_list_remove(ocrpt_list *l,
                  const void *data);

ocrpt_list *
ocrpt_list_end_remove(ocrpt_list *l,
                      ocrpt_list **endptr,
                      const void *data);

This can be used to iterate through a list. It returns NULL if the passed-in link is the last list in the list or it's an empty list.

ocrpt_list *
ocrpt_list_next(ocrpt_list *l);

void *
ocrpt_list_get_data(ocrpt_list *l);

void
ocrpt_list_free(ocrpt_list *l);

void
ocrpt_list_free_deep(ocrpt_list *l,
                     ocrpt_mem_free_t freefunc);

Create a new string from a C string. The ownership of the input string may be taken over, or the original string's contents are copied.

ocrpt_string *
ocrpt_mem_string_new(const char *str,
                     bool copy);

Create a new string with specified allocated length so future growth can be done without reallocation. The input string is always copied.

ocrpt_string *
ocrpt_mem_string_new_with_len(const char *str,
                              size_t len);

ocrpt_string *
ocrpt_mem_string_new_vnprintf(size_t len,
                              const char *format,
                              va_list va);

ocrpt_string *
ocrpt_mem_string_new_printf(const char *format, ...);

Resize the string to the specified allocated length.

ocrpt_string *
ocrpt_mem_string_resize(ocrpt_string *string,
                        size_t len);

char *
ocrpt_mem_string_free(ocrpt_string *string,
                      bool free_str);

void
ocrpt_mem_string_append_len(ocrpt_string *string,
                            const char *str,
                            const size_t len);

void
ocrpt_mem_string_append_len_binary(ocrpt_string *string,
                                   const char *str,
                                   const size_t len);

void
ocrpt_mem_string_append(ocrpt_string *string,
                        const char *str);

void
ocrpt_mem_string_append_c(ocrpt_string *string,
                          const char c);

void
ocrpt_mem_string_append_printf(ocrpt_string *string,
                               const char *format, ...);