External types in a BIRT data-access event handler

This topic reviews the EGL external types that you use when coding a data-access event handler. For background information, see "EGL BIRT reports," "BIRT handler," and "BIRT data-access event handlers."

ColumnMetaData

A variable of type ColumnMetaData contains type and name information on each column in the data set. You receive such a variable when you work with a variable of type DataSetInstance and invoke the function getColumnMetaData.

The variable of type ColumnMetaData makes the following functions available:

getColumnCount returns the number of columns in a row of the data set.
```
 element.getColumnCount() returns (INT)
```
getColumnName returns the name of a column, which is identified by index number.
```
 element.getColumnName( index INT in ) returns (STRING)
```
getColumnDisplayName returns the display name of the column, which is identified by index number. The BIRT report designer uses the name when displaying the column in the Data Explorer view and to automatically generate column headings in a table when the column is dragged from the Data Explorer view and dropped in the table during the report-design process.
```
 element.getColumnDisplayName( index INT in ) returns (STRING)
```
The Java™ method associated with this EGL function is getColumnLabel.
getColumnAlias returns the alias of the column, which is identified by index number. The report designer can use this alias as a shorter or more recognizable name for a column when referring to it in the report design. For example, you can give a column named $FN as alias of firstName so that you can write row["firstName"] in an expression instead of row["$FN"].
```
 element.getColumnAlias( index INT in ) returns (STRING)
```
getColumnTypeName returns the type of the column, which is identified by an index number that represents the position of the column in the row. A returned value can be "Integer", "Double", "Decimal", "String", "Date", or "Any".
```
 element.getColumnTypeName( index INT in )returns (STRING)
```
The first column is number 1, not 0.
getColumnNativeTypeName returns the native type of the column, which is identified by an index number that represents the position of the column in the row. The native type is one of the valid types for the data source and depends on the type of data source. For a flat file, for example, the native type may be bigdecimal, time, timestamp, date, double, int, or string. For a JDBC data source, the supported native types depend on the type of database management system being accessed.
```
 element.getColumnNativeTypeName( index INT in )returns (STRING)
```
The first column is number 1, not 0.
isComputedColumn returns a Boolean to indicate whether the column is computed rather than retrieved from the data source. A computed column displays the result of an expression, typically involving one or more columns retrieved from the data source. For example, if each row retrieved from the data source contains columns named firstName and lastName, a computed column named fullName can be defined using the following expression:
```
 row["firstName"] + " " + row["lastName"]
```
You define a computed column for a data set when you are working in the Data Explorer view.
```
 element.isComputedColumn(index INT in) returns (BOOLEAN)
```

DataSetInstance

A variable of type DataSetInstance references a report element that represents a data set, which is a set of columns and is described in "BIRT handler." The variable makes the following functions available:

getName returns the name given to the data set, as expressed in the design file.
```
 element.getName()returns (STRING)
```
getExtensionID returns the value of the BIRT Open Data Access (ODA) extension ID. For a data source that uses an SQL query, for example, the value might be "org.eclipse.birt.report.data.oda.jdbc.JdbcSelectDataSet".
```
 element.getExtensionID()returns (STRING)
```
getExtensionProperty returns the value of a BIRT Open Data Access (ODA) extension property.
```
 element.getExtensionProperty(propertyName STRING in) returns (STRING)
```

setExtensionProperty sets the value of an ODA extension property.

 element.setExtensionProperty
   (propertyName STRING in, value STRING in)

getDataSource retrieves the data source specific to the data set.
```
 element.getDataSource () returns (DataSourceInstance)
```
getColumnMetaData retrieves a variable of type ColumnMetaData, which contains type and name information on each column in the data set. For further details on what kind of information is made available, see the section on getColumnMetaData.
```
 element.getColumnMetaData () returns (ColumnMetaData)
```

The variable of type DataSetInstance also makes the following field available:

queryText is a field of type STRING and holds the SQL query from which the report engine derives a data set. If an SQL query is unavailable, the value of queryText is an empty string.
In the next example, the report engine invokes an event handler (for event type beforeOpen and data set "dataSet") before opening an SQL query.
```
function setQuery( d DataSetInstance, c ReportContext ) 
   { eventType = beforeOpen, elementName = "dataSet" }
   queryStr string;
   if( region == "EUR" )
      queryStr = "select region, country, city from locations 
         where region = \"EUROPE\"";
   else 
      queryStr = "select region, country, city from locations 
         where region = \"ASIA\"";
	  end
	  d.queryText = queryStr;
end
```
In that example, the event handler sets one or another SQL query string in response to a business situation. The region variable is assumed to be declared and set globally, outside of the function.

Here is the example program introduced and described in "EGL BIRT handler":

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

In the next code, the scripted data set (a data set provided by the EGL code) is composed of fields in each element of a dynamic array. A scripted data set could be any set of fields that you provide to the report engine by your use of event handlers whose event types are openEvent and fetchEvent.

package EGLDataSources;  

Handler arrayHandler type BIRTHandler 
   index int;
   customerArr customer[];	

   function setCustomerArray(a customer[])
      customerArr = a;	
   end 	 	

   function openFunction( d DataSetInstance )
      { eventType = openEvent, elementName = "myDataSet" }
      index = 0; 	
   end

   function fetchFunction(d DataSetInstance, row UpdatableDataSetRow )
      returns( boolean ) 	
      { eventType = fetchEvent, elementName = "myDataSet" } 		

      index = index + 1; 		

      if( index <= customerArr.getSize() )
         row.setColumnValue( "customer_num", customerArr[index].customerNumber ); 			
         row.setColumnValue( "fname", customerArr[index].firstName );
         row.setColumnValue( "lname", customerArr[index].lastName );
         return (TRUE); 		
      else 			
         return (FALSE); 		
      end
   end
end

Note that data-set column names (such as customer_num, fName, and lName) can be different from the corresponding EGL field names (such as customerNumber, firstName, and lastName).

For additional details, see the section on DataSetRow and UpdatableDataSetRow.

DataSetRow

A variable of type DataSetRow references a row of data provided by the report engine. The variable makes the following functions available:

getDataSet returns the data set.

 element.getDataSet()returns (DataSetInstance)

getColumnValue returns the value of a column, which is identified by index number.
```
 element.getColumnValue(index INT in)returns (ANY)
```
The first column is number 1, not 0.
getColumnValue returns the value of a column, which is identified by name.
```
 element.getColumnValue(columnName STRING in) returns (ANY)
```

Those functions are also available to a variable of type UpdatableDataSetRow.

DataSourceInstance

A variable of type DataSourceInstance references a report element that represents a data source, which is a representation of the source of data, as described in "BIRT handler." The variable makes the following functions available:

getName returns the name given to the data source, as expressed in the design file.
```
 element.getName()returns (STRING)
```
getExtensionID returns the value of the BIRT Open Data Access (ODA) extension ID. For a JDBC data source, for example, the value might be "org.eclipse.birt.report.data.oda.jdbc".
```
 element.getExtensionID()returns (STRING)
```
getExtensionProperty returns the value of a BIRT Open Data Access (ODA) extension property such as the following:
- odaDriverClass (for the driver class used for JDBC access of a relational database)
- odaUser (for the user ID used to connect to the database)
- odaPassword (for the password used to connect to the database)
```
 element.getExtensionProperty(propertyName STRING in) returns (STRING)
```

setExtensionProperty sets the value of an ODA extension property.

 element.setExtensionProperty
   (propertyName STRING in, value STRING in)

You might use the parameter of type DataSourceInstance to set the user ID and password used by the BIRT report engine to connect to a relational database. Here is the example code, which assumes that the variables userName and password are global and were set outside of the function:

   function setUser( d DataSourceInstance, c ReportContext ) 
      { eventType = beforeOpen, elementName = "myDataSource" }
      d.setExtensionProperty( "odaUser", userName );
      d.setExtensionProperty( "odaPassword", password );
   end

ReportContext

An event-handler parameter of type ReportContext provides access to the report parameters. Two functions are available:

setParameterValue sets the value of a report parameter, which is identified by name:

 reportContext.setParameterValue
 ( parameterName STRING in, parameterValue ANY in )

Similarly, getParameterValue gets the value of a report parameter:

 reportContext.getParameterValue
 ( parameterName STRING in) returns (ANY)

UpdatableDataSetRow

A variable of type UpdatableDataSetRow provides a row of data to the report engine. The variable can use any of the functions described in relation to DataSetRow.

Two setter functions are also available:

setColumnValue sets the value of a column, which is identified by an index number.
```
 element.setColumnValue(index INT in, value ANY in)
```
The first column is number 1, not 0.
setColumnValue sets the value of a column, which is identified by a name.
```
 element.setColumnValue(columnName STRING in, value ANY in)
```