Database Tour Documentation
dataset_nvl function

Category:

Database related

General

Returns a substitution value if the field value is null.

Syntax

dataset_nvl(
  StepNo Integer,
  FieldName String,
  SubstVal <FieldType> 
): <FieldType>

dataset_nvl(
  StepNo Integer,
  FieldIndex Integer,
  SubstVal <FieldType>
): <FieldType>

Parameters

StepNo. Its meaning depends on the context in which the function is used:

Exporting to HTML using template context. HTML template can be filled with dynamic data in more than one step. For example, if your HTML document consists of several tables, which must be filled with database data from different datasets, you can fill them only in several export steps (usually, one dataset per step). That's why database related and some other functions have a StepNo parameter. When exporting a dataset to HTML using HTML template, it is also possible to specify an export step number (it is 1 by default). During the export procedure, only those expressions will be calculated where the StepNo parameter of expression function(s) is not present or matches with a step number, specified in export options. For example, the database_field_val(2, 'payment_sum')/100 expression will be calculated only in the second export step.

Reports context. StepNo parameter specifies the step (pass) in which the function must be calculated. Possible values: 1 or 2. When it equals to 1, the corresponding function will be calculated immediately when the expression is processed. When it equals to 2, report will run in double-pass mode and the corresponding function will be calculated only in the second pass of the report processing, i.e. after the report dataset reaches the last record. Using database functions in the second pass is useful, for example, when it is needing to put the report totals in the report or group headers.

Other contexts. Must be 1.

Combining different StepNo parameters in one expression (for example, database_field_val(1, 'total_sum') + database_field_val(2, 'payment_sum')) is possible, but such expression should be written so that functions with smaller StepNo will be calculated earlier.

FieldName is the name of the field which value to check.

FieldIndex is the field sequence number in the field mappings collection (data exporting context) or in the current dataset (reporting context).

SubstVal is the value to return if the field value is null. The type of SubstVal must match the type of the field.

Return value

Type: <FieldType> (depends on the database field type). Returns SubstVal, when value of the field is null, and the field value in another case.

Examples of using

dataset_nvl(1, 'Salary', 0)