Configured Data Sources

A configured data source stores input settings as part of a form layout or repository. It can define a CSV filename and separators, an XML filename, or an ODBC connection and SQL query. Each source has a unique name. The layout creator can define the source in TFORMer Designer.

Use JobDataDataSource in .NET, Java or COM to select that definition by name and supply it as the JobData for a Job. TFORMer retrieves the data using the stored settings, field mappings and expressions.

This differs from JobDataCsv, JobDataXml and JobDataOdbc, where the application supplies the input settings directly. Choose a configured source when the layout already defines how its data should be retrieved.

For a complete example using the supplied picking-list layout, see .NET, Java or COM.

The definition and its use have different roles:

• DataSource and its CSV, XML and ODBC subclasses describe the stored settings. In .NET, these classes also let you inspect and modify the definition, including parameters and field mappings.
• JobDataDataSource selects a definition for a job and supplies runtime parameter values. These values do not change the stored parameter defaults.

Select a Source Explicitly

Select the source explicitly when your application must use a particular input.

• Empty source name: TFORMer uses the source selected in the layout. This need not be the special _Default_ source. If no source is selected in the layout, TFORMer uses the layout's companion XML file.
• Manual data for a stand-alone layout: For a .tff layout, selecting _Default_ reads the data saved by TFORMer Designer in the layout's companion XML file. This explicit selection applies to stand-alone layouts, not to layouts in named repository projects.

If the companion XML file is the data source and is absent, its saved records are not available for output. This does not mean that an ODBC source requires a companion XML file.

When deploying the layout, provide the files or database access required by the selected source; do not rely on saved Designer data being present on the target system.

Supply Data Source Parameters

Data source parameters provide values used by the stored definition, such as a filename, an ODBC connection string or part of an SQL selection. They are separate from the layout's data-field names.

1. Define the parameter in the configured source and give it a default value.
2. Use GetDSParam("ParameterName") in the appropriate expression in that definition.
3. Select the source and supply the runtime value before generating output.

The parameter must already exist in the selected source. Supplying a runtime value does not create a definition; an unknown name causes an error when the job applies its parameters. Parameters you do not override retain their defined defaults.

These values are used by TFORMer's expression processing. They are not SQL bound parameters: constructing SQL this way does not automatically quote or escape values. Validate any untrusted values before using them in a query.

For a filename parameter called InputFile, the complete stored expression is <Expr>GetDSParam("InputFile")</Expr>, for example as the value of DataSourceCsv.Filename in .NET. The function call alone is not a complete filename expression. Supply the actual filename as the runtime parameter value, not the expression. Parameters can also be used in query expressions or computed fields.

Map Source Fields to Layout Fields

A configured source can map an input field to a differently named layout field. For example, ItemDescription can supply ProductName. Set up the mapping in TFORMer Designer or through the definition API (DSFieldMapping in .NET).

Stored mappings do not automatically apply when switching to direct CSV, XML or ODBC input. With direct input, returned field names must match the layout fields; use SQL aliases where necessary for direct ODBC input.

Prepare Values with Computed Fields

A configured source can define computed fields to combine, trim or calculate values before passing them to the layout. The result is available like another source field and can be mapped to a layout field.

These fields may use aggregation, such as a running sum or average. An aggregation filter controls which records contribute to that calculation; it does not remove those records from the output.

In .NET, the definition is represented by ComputedField. This is separate from expressions in the layout itself.

Handle Escape Sequences

For configured CSV, XML and ODBC sources, enable escape-sequence handling in the source definition (DataSource.HandleEscapeSequences in .NET), not the direct-input job-data setting. Escape handling is disabled by default; when enabled, \n in a value becomes a newline.

Set Copies per Record

To select a source field containing each record's copy count, use the definition's CopyColumnName. This is separate from the job-level copy count. Direct-input APIs and records supplied in code use different record-copy settings; choose the setting for the input mechanism you use.

Choose a Configured CSV File at Runtime

Use this approach when a layout already defines a CSV source and you want to choose a different input file for each job, keeping its separators and field mappings. For direct import without a stored definition, use CSV and Text Input instead.

1. In TFORMer Designer, prepare your layout with a CSV source named ImportFromCSV. Set its separator, qualifier and field mappings to match your CSV files.
2. Define a source parameter named InputFile with a valid CSV path as its default. Use it in the source's filename definition as described under Supply Data Source Parameters. The complete stored expression is <Expr>GetDSParam("InputFile")</Expr>.

3. Follow the setup instructions and adapt the existing complete program for .NET, Java or COM:

   Existing example	CSV variant
   Source name ODBC	ImportFromCSV
   Parameter name PickingListParameter	InputFile
   Parameter value "2"	Full CSV path, for example "C:/Data/orders.csv" on Windows or "/data/orders.csv" on Linux

   Keep the SDK setup, PDF output and error handling. The picking-list layout, Access database, DSN prerequisites and picking-list result check do not apply to this CSV variant.

4. Run the adapted program with your layout path and a new PDF path in a writable directory. Open the PDF and check that it contains the records from the selected CSV file. To use another input file, change the runtime parameter value; the stored default remains unchanged.

The executing account needs read access to the CSV file. If output fails, check the reported error, source and parameter names, full file path, CSV format and field mappings.