Previous TopicNext Topic


DataSet

The DataSet element represents a result set retrieved from an external data provider. The DataSet element is an abstract element that includes data-access and report-related properties and other content common to all kinds of data sets. The DataSet script methods execute as methods of a JavaScript object that represents the data set.

Extends

DesignElement->ReportElement

Property summary

Inherited properties

comments, customXml, displayName, displayNameID, extends, name, propertyMasks, userProperties

Method summary

DataSet properties

The following sections describe the properties of the DataSet element.

cachedMetaData

Defines the cached derived data attributes of a data set. The BIRT designer uses the cached information until the user initiates refresh and reconciles with the latest derived data attributes provided by the connected data source. BIRT uses this property at report design time. The designer tool maintains its content.

cachedRowCount

Number of rows that are cached when data rows are retrieved from the data base..

columnHints

Defines the report-related data attributes of the result set's columns. A result set column can be defined with an alias. Aliases are useful in cases where a column name is awkward, or is used by multiple columns in a result set.

Column hints let the report developer customize the search and data extract experience. Such operations as searching the report, extracting data to a file, and exporting data to an OLAP system work on the actual data set's result set instead of on the presentation of the data.

The columnHints element provides a number of hints about result set columns. The hints override BIRT defaults for how columns are handled during viewing. You can provide hints for both retrieved columns and computed columns.

Column hints are keyed to the data set's primary result set using names. You must keep the hints in sync with the data set when either the data set definition, or underlying data source, changes.

BIRT uses the column hints in the following cases:

If the data set provides the requested column, BIRT continues processing the report. If not, BIRT issues a fatal run-time error.

computedColumns

A user-defined field produced as an expression of other columns within the data set's primary result set. It is not one of the fields retrieved directly from the underlying data provider.

dataSource

The database connection for this data set.

filter

An optional set of filters to apply to the result set before any other data transforms are applied. BIRT applies a data set's filter to each row of the retrieved result set. Do not use aggregation functions in the filter expression. The filter expression usually refers to at least one column from a data row, and may also refer to a report parameter or other scripting variable.

paramBindings

A list of data set parameter binding elements that bind data set input parameters to BIRT expressions. Each ParamBinding structure associates a parameter name with an expression.

BIRT differentiates between data set parameters and report parameters. BIRT does not automatically expose a data set input parameter as a report parameter. You can define a report parameter that matches a data set input parameter, in which case the input parameter binding associates the data set input parameter with the value of the report parameter.

The DataSet element provides a list of parameter binding elements that bind a value to each query parameter. The bind expression frequently includes a reference to a report parameter, configuration variable, or a row in an outer query. The expression can include any valid JavaScript expression.

parameters

Defines the data access attributes of the list of input and output parameters. Many data sets allow parameters, which can be input or output modes, or both. In some cases, you must define the parameters as part of the data set definition. For other data sets, the driver can provide the set of parameter definitions from the information contained in a data set query. In the latter case, a parameter definitions is derived data and is not stored in the parameter definition.

Some drivers refer to a parameter by position. Others refer to a parameter by name. For some data sets, the data set definition omits parameter definitions for optional parameters that are not used in the report. Not all parameter properties are required. If a property is omitted, BIRT assumes that the data set implementation can provide it at run time. If the driver cannot provide the information, a run-time error occurs.

BIRT only uses the parameters property definitions when the underlying data provider cannot provide the information. When there is a contradiction between the metadata of the data provider's parameters and parameters specified in a data set definition, the data provider's metadata takes precedence.

refTemplateParameter

A reference to the template parameter definition, applicable only when the data set derives from a template.

resultSet

Defines the data access attributes of the list of columns in the expected primary result set. The resultSet property is an optional list of result set column definitions, used only when the underlying data provider cannot provide the same information. When there is a contradiction between the metadata of the data provider's column set definitions and definitions specified in a data set, the data provider's metadata takes precedence.

DataSet methods

The following sections describe the methods of the DataSet element.

afterClose

A script that executes after BIRT closes the data set. Use the afterClose method to perform code-based cleanup.

afterOpen

A script that executes after BIRT opens the data set. Use the afterOpen method to perform any code-based initialization required for the data set.

beforeClose

A script that executes before BIRT closes the data set. Allows the application to perform code-based cleanup.

beforeOpen

A script that executes before BIRT opens the data set. Use the beforeOpen method to customize the data set properties.

onFetch

A script that executes after fetching each row before applying filters or calculating computed columns.


(c) Copyright Actuate Corporation 2006

Previous TopicNext Topic