Central to EGL's support for Business Intelligence and
Reporting Tools (BIRT) is the external type called BIRTReport. This
topic describes how to create a variable of that type and how to use
it to create output.
For an overview of EGL's support for BIRT, see "Creating Reports
with BIRT" in the Programmer's Guide.
Declaring a variable of type BIRTReport
When
you declare a report (a variable of type BIRTReport), you can include
some or all of the details needed to create output. You can then invoke
report-specific fields and functions, either to add details that were
not included in the declaration or to change details. In any case,
you specify a variety of details and only later do you invoke a function
that creates output for a specific report.
The following syntax
lets you specify details when you declare the report:
myReport BIRTReport = new BIRTReport
(designFile, documentFile, reportFile,
outputFormat, reportHandler);
- myReport
- The variable name.
- designFile
- The name of the design file. If you are creating output from a
document file rather than a design file, any name you specify is ignored,
but for clarity, you can specify null instead of
a file name.
See also "Rules for specifying file names" later in
this topic.
- documentFile
- The name of the document file. If you are creating output from
a design file, any name you specify is ignored, but for clarity, you
can specify null instead of a file name.
See
also "Rules for specifying file names" later in this topic.
- reportFile
- The name of the report file. If you are creating a document file
and not output, any name you specify is ignored, but for clarity,
you can specify null instead of a file name.
See
also "Rules for specifying file names" later in this topic.
- outputFormat
- If you are creating output, specify "HTML", "PDF", or a variable
that resolves to one of those strings. The default value is "HTML."
If you are creating only a document file, any setting is ignored,
but for clarity, you can specify null instead of
an output format.
- reportHandler
- Name of a variable that is based on a BIRT handler part. The handler
part contains functions that respond to events at run time. If you
are not using a BIRT handler part, specify null instead
of a variable name.
Each field but the last is of type STRING? (the
question mark indicates that null is valid). The
last field is of type ANY.
The following syntax gives no details,
requiring you to set fields, as described later:
myReport BIRTReport{};
- myReport
- The variable name.
That second syntax is equivalent to the following
one:
myReport BIRTReport = new BIRTReport();
Report-specific fields and functions
Each
variable of type BIRTReport provides access to fields that let you
specify the name of the design file, document file, report file, or
output format. The reference to each field is preceded by a report
name such as myReport. Here's an example statement:
myReport.designFile = "C:/myDesignFile.rptDesign";
Here
are the fields, each of type STRING:
- designFile
- The name of the design file. If you are creating output from a
document file rather than a design file, any name you specify is ignored,
but for clarity, you can specify null instead of
a file name or can avoid specifying a name at all.
See also "Rules
for specifying file names" later in this topic.
- documentFile
- The name of the document file. If you are creating output from
a design file, any name you specify is ignored, but for clarity, you
can specify null instead of a file name or can
avoid specifying a name at all.
See also "Rules for specifying file
names" later in this topic.
- reportFile
- The name of the report file. If you are creating a document file
and not output, any name you specify is ignored, but for clarity,
you can specify null instead of a file name.
If
you do not specify a name but invoke createReportFromDesign or createReportFromDocument,
the report engine assigns a name when creating the output.
See
also "Rules for specifying file names" later in this topic.
- outputFormat
- If you are creating output, set the field to "HTML" or "PDF" or
to an expression that resolves to one of those strings. The default
value is "HTML." If you are creating only a document file, any setting
is ignored, but for clarity, you can specify null instead
of an output format.
Each variable of type BIRTReport also provides
access to a set of functions:
- To get the default value, if any, of a report parameter. The report
designer declares parameters when working in the BIRT Report Designer,
Data Explorer view.
- To set the value of a report parameter before the report is created.
- To assign a report handler.
- To create the report by invoking one of three create functions,
which let you produce output in PDF or HTML format or let you produce
only a document file. If you assigned field values, report-parameter
values, or a report handler, your changes take effect only when you
subsequently invoke a report-specific create function. Note that assigning
report-parameter values has no effect if you create a report from
a document file, because the document file reflects the parameter
values that were in place when the file was created.
Each function is qualified by a report name such as
myReport,
as in the following example:
myReport.setParameterValue("CustomerNumber", 500);
We
first look at the functions that handle report parameters. The following
function,
setParameterValue, assigns a value to
a specified parameter:
myReport.setParameterValue
(parameterName STRING in, parameterValue ANY in);
- parameterName
- The name of the parameter.
- parameterValue
- The parameter value.
The function
getParameterDefaultValue retrieves
the default parameter value specified at design time, even if the
handler function
setParameterValue overrides the
default at run time. Note that to avoid an error, you must set the
design file name before invoking this function. Here is the invocation:
myReport.getParameterDefaultValue
(parameterName STRING in) returns (parameterValue);
- parameterName
- The name of the parameter.
- parameterValue
- The parameter value, which is of type ANY.
Next, we review the function that sets a
report handler:
myReport.setReportHandler (reportHandler ANY in);
- reportHandler
- Name of a variable that is based on a BIRT handler part. The handler
part contains functions that respond to runtime events. If you are
not using a BIRT handler part, either specify null or
do not call this function.
Last, here are the three create functions,
none of which take arguments:
- myReport.createReportFromDesign () creates output
from a design file and uses information you specify in fields and
functions, if any, but does not store a document file.
- myReport.createReportFromDocument () creates output
from an existing document file, converting an existing report from
an intermediate format into HTML or PDF.
- myReport.createDocument () creates a document file
from a design file and uses information you specify in fields and
functions.
Rules for specifying file names
When you
specify file names for use in the EGL code that supports BIRT, several
rules apply:
- You may express a name in UNIX format;
for example, C:/myFolder/myFile.rptDesign. Alternatively, you can
use a Windows format but
must take into account the use of a backslash as an escape character
in EGL; for example, C:\\myDirectory\\myDesignFile.rptDesign.
- You may express a file name relative to the project in which the
file resides.
- You may use a literal string or a variable.
In several cases (as described earlier), the EGL runtime
assigns a name, and the file is written to the default temporary-file
directory:
- On UNIX systems, the directory
is /tmp or /var/tmp
- On Microsoft 2000/XP,
the directory is C:\\temp
The file name begins with the string "BIRTReport". That
string is followed by a set of characters that are assigned by the
EGL system code. The file extension is appropriate to the file type
and is .rptdocument, .PDF, or .HTML.