BIRT Reports

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.