Data Field Handling

Empty or Missing Datafield Values

By default, a data field missing from a job-data record is set to an empty string or 0, according to its field type. If value reuse is enabled, the field retains the previous record's value until a new value is supplied. TFPrint uses CLyes (the default) to clear fields between records and CLno to reuse prior values.

Unknown Data Field Names

Additional data fields in imported job data that are not defined in the form layout or repository project are ignored. When supplying data programmatically through a JobDataRecordSet, enable the ignore-undefined-fields option; otherwise an unknown field name returns an error.

See ignore-undefined-fields for values and the distinction between the native C API and job-based APIs.

Escape Sequences in Data Field Values

Escape-sequence handling is disabled by default, so data-field values are imported exactly as supplied. When escape handling is enabled for the job data, the sequence \n is translated to a newline character.

For records supplied in code and direct CSV, XML or ODBC input, use JobData.HandleEscapeSequences in .NET, the HandleEscapeSequences property of the job-data object in COM, or setHandleEscapeSequences(true) in Java. In the native C API, call TFormer_SetHandleEscapeSequences before assigning field values or importing data. TFPrint uses ESC[yes|no] for direct input and defaults to ESCno.

For a source defined in the layout, see Handle Escape Sequences.

The following sequences describe the actual data received by the SDK, not a programming-language string literal. A programming language or shell may require additional escaping. For example, C# "Line 1\\nLine 2" passes the literal sequence \n to the SDK; C# "Line 1\nLine 2" already contains a newline and does not need SDK escape handling.

Supported Sequences

Sequence in the data	Result
`\'`	Single quotation mark
`\"`	Double quotation mark
`\\`	Backslash
`\b`	Backspace
`\f`	Form feed
`\n`	Newline (line feed)
`\r`	Carriage return
`\t`	Horizontal tab
`\v`	Vertical tab
`\ddd`	One to three octal digits (`0` to `7`), with a value at most 255 (`377` octal); for example, `\101` becomes `A`.
`\xdd`	Exactly two hexadecimal digits after a lowercase `x`; for example, `\x41` becomes `A`. Hexadecimal digits may use either case.

The SDK does not translate \u Unicode escapes. Supply Unicode characters directly using the encoding supported by your input mechanism. Translating a control character does not guarantee that the selected data-field type or output format can use it.

Unrecognized and Incomplete Sequences

The escape translator does not report an error for unrecognized sequences: it removes the backslash and retains the following character. A final backslash with no following character disappears. Numeric sequences need special care: a valid numeric prefix can be translated even when more characters follow.

Input with escape handling enabled	Result
`\q`	`q`
`\999`	`999`
`\609`	`09`: octal `\60` becomes `0`, followed by the remaining `9`.
`\129`	A newline followed by `9`: octal `\12` is translated first.
`\400`	`400`: the octal value exceeds 255.
`\xgg` or `\x1`	`xgg` or `x1`: two hexadecimal digits are required.
`\u0041`	`u0041`, not `A`.
Input consisting of a single `\`	Empty string

If escape handling is enabled, write \\ wherever the input must retain a literal backslash, such as in a Windows path.