EGL BIRT handler

An EGL BIRT handler part contains event handlers, which are functions invoked during report creation. For an overview of EGL support for BIRT, see "Creating reports with BIRT" in the Programmer's Guide.

In each event handler, the parameter list is specific to the type of event to which the function responds. Here is an outline of the BIRT handler part:

handler myBIRTHandler type BIRTHandler
   function myEventHandler01 (parameterList)
      {eventType = eventType, elementName="name01"...} end 	 
   function myEventHandler02 (parameterList)
      {eventType = eventType, elementName="name02"...} end
end

As shown in that outline, the use of the eventType and elementName property (and other event-handler properties, as appropriate) indicate that the function is an event handler.

Before we describe the eventType property, we outline how to use the BIRT handler part in the EGL code; for example, in a program:

Create a variable that is based on a handler part
Code a statement that associates the variable with an EGL BIRT report
Optionally, use the variable to assign a data source that will be used during report creation
Create the report

As a consequence of these steps, the BIRT report engine can invoke a set of event handlers during report creation.

Here is an example program:

package EGLDataSources;

program arrayProg type BasicProgram {}
	
	 function main()
     arr customer[0];
		  cust customer;
		  
		  cust.customerNumber = 102;
		  cust.firstName = "Jonathan";
     cust.lastName = "Swift";
     arr.appendElement(cust);
		  
     cust.customerNumber = 103;
     cust.firstName = "Mark";
     cust.lastName = "Twain";
		  arr.appendElement(cust);
     
     designFile string = "eglDataSourcesRpt.rptdesign";
     rptFile string = "eglDataSourcesArrayRpt.pdf";

     myHandler arrayHandler = new arrayHandler;
     rpt BIRTReport = new BIRTReport
         (designFile, null, rptFile, "pdf", myHandler);
		
     myHandler.setCustomerArray(arr);
     rpt.createReportFromDesign();
	end
end

record customer type basicrecord
	customerNumber int;
	firstName string;
	lastName string;
end

The program acts as follows:

Creates an array, as well as a variable based on a handler part
Associates that variable and two file names with an EGL BIRT report
Assigns a data source
Creates the report output.

Event types

The name of an event handler is not meaningful to the BIRT report engine. Instead, the way that the event handler is defined (its parameter types and properties) determines when the handler is invoked. The event type (the value of the eventType property) is the most important factor in determining the time of invocation.

Before we list the available event types, we need to clarify some phrasing:

A data source is a representation of the source of data. A data source may include either JDBC database-connection details or a file name, in which cases the report engine retrieves the business data from the database or file. Alternatively, the data source may represent a scripted data source, which means that the report engine retrieves the business data from your EGL program. An example of a scripted data source is an array of records. When a scripted data source is in use, you write an event handler that provides a row of data at a time to the report.
A data set is a set of columns that the report engine derives from a file, SQL query, or stored procedure; or is a set of columns provided to the report engine by way of a scripted data source, in which the data set is called a scripted data set.
The words row and column are used even for data that is not derived from a relational database. Here are two examples:
- The first line of a non-XML text file has comma-separated column names; the second line either has comma-separated column types or is a row with comma-separated column data; and each subsequent line is a row with comma-separated column data.
- In an array of records, each record constitutes a row, and a field in a given record is a column.

The event types come from the EventTypeKind enumeration, which has the available values listed here in the order in which they occur, with indentations to show the relationship of one event to the next:

  beforeOpen (for a data source of any kind)
  openEvent (for a scripted data source)
  afterOpen (for the data source referenced in the previous
                      beforeOpen event)
          beforeOpen (for a data set derived
                      from the data source just referenced)
          openEvent (for a scripted data set just referenced)
          afterOpen (for the data set referenced
                      in the previously listed beforeOpen event)
              [loop until all rows are retrieved for the data set just referenced: ]
                  fetchEvent (fetch a row from a scripted data set)
                  onFetch (invoked for a data set
                      in response to a fetch)
              [end loop]
              [for each row retrieved from the data set,
               loop until all report elements are created: ]
                  onCreate (invoked when a report element
                     used for layout is being created)
                  onPageBreak (invoked if a page break is specified)
              [end loop]
           beforeClose (for the data set whose data was just fetched)
           closeEvent (for a scripted data set just referenced)
           afterCloseDataSet (for the data set referenced
                      in the previously listed beforeClose event)
  beforeClose (for the data source just referenced)
  closeEvent (for a scripted data source just referenced)
  afterCloseDataSource (for the data source referenced
                      in the previously listed beforeClose event)

The meaning of most events is suggested by the event name. For example, the beforeOpen event (for a data source) occurs before a data source is open:

For access of a relational database, the event occurs before the report engine connects to the database.
For a reading of an XML or other file, the event occurs before the file is open
For a scripted data source, the event occurs soon after an EGL create function runs to start the BIRT engine

Each event type whose name ends with the word "event" (that is, openEvent, fetchEvent, and closeEvent) operates only on a scripted data source or data set.

Let us clarify the meaning of fetchEvent and onFetch events. As mentioned before, fetchEvent is specific to a scripted data set, whereas onFetch can be used for any data set, including a scripted one. You can use the fetchEvent event to provide content for a row that your program is providing to the report engine, and you can use the onFetch event to review data from a single row that was retrieved by the report engine (or that you just provided to the report engine). Each event handler is invoked repeatedly by the report engine until all rows are retrieved.

When the event type is fetchEvent, the event handler must return a Boolean value, and the following rules apply:

The event handler provides a row of data with each invocation that returns the value TRUE
If the event handler responds with the value FALSE, the effects are twofold: first, the report engine does not process data for that invocation even if the handler assigned one or more column values; and second, the report engine stops invoking the fetchEvent event handler.

When the event type is onFetch, the event handler can access the most recently retrieved row, but cannot update the row and does not return a Boolean value.

Parameter types in event handlers

The parameter types required for a given event handler depend on the event type. Seen another way, the event type indicates the types of arguments that the BIRT report engine submits to the event handler at run time. The next table lists the event types in alphabetical order, along with the related parameter types in parameter order.


Event types	Parameter types
afterCloseDataSet	DataSetInstance
afterCloseDataSource	DataSourceInstance
afterOpen (for a data set)	DataSetInstance, ReportContext
afterOpen (for a data source)	DataSourceInstance, ReportContext
beforeClose (for a data set)	DataSetInstance, ReportContext
beforeClose (for a data source)	DataSourceInstance, ReportContext
beforeOpen (for a data set)	DataSetInstance, ReportContext
beforeOpen (for a data source)	DataSourceInstance, ReportContext
closeEvent (for a data set supplied by EGL code)	DataSetInstance
closeEvent (for a data source supplied by EGL code)	DataSourceInstance
fetchEvent (for a data set supplied by EGL code)	DataSetInstance, UpdatableDataSetRow (the function returns a Boolean)
onCreate	The type of a report element used for layout (for example, LabelInstance); and then, ReportContext
onFetch (for a data set)	DataSetInstance, DataSetRow, ReportContext
onPageBreak	First, the type of report element (for example, LabelInstance) used for a layout that is anywhere on the page preceding the page break; and second, ReportContext
openEvent (for a data set supplied by EGL code)	DataSetInstance
openEvent (for a data source supplied by EGL code)	DataSourceInstance

We can distinguish between event handlers that respond to the runtime creation of report-layout elements such as labels and images, and event handlers that respond to some aspect of data access. The former kind of event handler is accessed for onCreate or onPageBreak events; the latter kind is accessed for any other kind of event. For details, see "BIRT data-access event handlers" and "BIRT report-layout event handlers."