Provide Data

Supply records from application code, import data, or use a data source defined in the layout.

Overview

Data supplies the values for the fields used by the selected FormLayout. Pass the instance handle returned by TFormer_Init to the data functions:

• From application code: start each record with TFormer_NewRecord, then set its field values with TFormer_SetVarValue. The SDK keeps these records in memory for output.

• From a file or database: use TFormer_SetTxtDataFile for CSV/text, TFormer_SetXmlDataFile for XML, or TFormer_SetODBCData for ODBC.

• From a data source defined in the layout: select it with TFormer_SetDatasourceName. Set any data-source parameters afterward with TFormer_SetDSParameterValue and before generating output.

Select the layout before adding or importing records. Changing the selection can discard cached data; see the individual functions. See Job / JobData for the complete output workflow.

Data Processing

Input data is processed record by record in the order supplied. Record processing and the need for new pages trigger the bands defined in the FormLayout:

• Report headers are processed at the start of the output, after the first record has been read.

• Detail bands are normally processed for each record.

• Group headers and footers are processed at group boundaries determined by the layout's Group By values.

• Page headers and footers are processed as pages begin and end.

• Report footers are processed after the last record.

Printing conditions and layout settings determine which bands are actually printed and where they appear.

Escape Sequences

It depends on TFormer_SetHandleEscapeSequences whether possible escape sequences in the values are translated into their corresponding binary representation. See Escape Sequences for details.

Record Copies

Each Record of a DataSource is usually considered exactly once for generating output. Use TFormer_SetImportFieldForRecordCopy to instruct TFORMer SDK to use a specific field of the DataSource which contains the copy counter. This feature is helpful whenever a single Record of a DataSource should be printed multiple times (e.g. if a certain number of identical labels should be printed).

Unknown DataFields in JobData

Additional fields in imported data are ignored if they are not defined in the layout or its repository project. When supplying values with TFormer_SetVarValue, set the ignore-undefined-fields output option before assigning values if unknown fields should be ignored.

Missing DataFields in JobData

If a field used by the layout is missing from an input record, its value depends on TFormer_SetReuseValues. if TFormer_SetReuseValues is set to

• true then the value of a DataField will be preserved between records. The last value will be reused in consecutive records until a new value is set.

• false (which is the default), then all DataFields are set to "" (empty string) or 0 (depending on the TFormer_ProjectVarItGetType) between records.

Missing JobData

If the application does not supply data to a new instance, TFORMer SDK uses the DataSource selected in the FormLayout. This need not be the special _Default_ source.

The _Default_ source reads the DataField values saved by TFORMer Designer alongside the layout in its companion .xml file. The SDK also falls back to that file when no source is selected in the layout. When this companion file supplies the input, it must contain at least one record to produce output.

Identifying the Required DataFields

To iterate through the DataFields of a Project, start with TFormer_GetFirstProjectVarIt and continue with TFormer_GetNextProjectVarIt. Use TFormer_ProjectVarItGetUsage to check whether each DataField is used in a particular FormLayout.

More Information

• JobDataRecordSet
  In-memory DataSource

• JobDataCsv
  CSV import

• JobDataXml
  XML import

• JobDataOdbc
  ODBC connectivity

• JobDataDataSource
  User-defined DataSource