TFORMer SDK retrieves data used for printing a Job with the help of JobData.
More...
Functions |
ERRCODE | TFormer_SetDatasourceName (HTFORM pInstance, LPCSTR pszDatasourceName) |
| Specifies the name of the user-defined DataSource to be used as JobData.
|
LPCSTR | TFormer_GetDatasourceName (HTFORM pInstance, ERRCODE *peCode) |
| Provides the name of the active DataSource of the current FormLayout.
|
ERRCODE | TFormer_SetDSParameterValue (HTFORM pInstance, LPCSTR pszParameterName, LPCSTR pszValue) |
| Specifies the value of a DataSourceParameter.
|
ERRCODE | TFormer_SetDataFile (HTFORM pInstance, LPCSTR pszFileName) |
| Sets a XML file (in the format used internally by TFORMer) as JobData.
|
ERRCODE | TFormer_ResetData (HTFORM pInstance) |
| Resets the data-cache.
|
ERRCODE | TFormer_NewRecord (HTFORM pInstance) |
| Appends a new Record to the DataSource.
|
ERRCODE | TFormer_SetRecordCopy (HTFORM pInstance, UINT nRecordCopy) |
| Sets the number of copies for the actual Record.
|
ERRCODE | TFormer_SetVarValue (HTFORM pInstance, LPCSTR szVarName, LPCSTR szVarValue) |
| Sets the value of a DataField.
|
ERRCODE | TFormer_SetReuseValues (HTFORM pInstance, BOOL bReuse) |
| Selects if DataField values should be reused in consecutive Records.
|
ERRCODE | TFormer_SetHandleEscapeSequences (HTFORM pInstance, BOOL bOn) |
| Selects whether escape sequences like \n or \x40 should be translated by TFORMer.
|
ERRCODE | TFormer_SetImportFieldForRecordCopy (HTFORM pInstance, LPCSTR pszFieldName, BOOL bIsAttribute) |
| Specifies which DataField in the input controls the number of Record copies.
|
ERRCODE | TFormer_SetTxtDataFile (HTFORM pInstance, LPCSTR pszFileName, CHAR cSeparator, CHAR cTextQualifier) |
| Specifies a text file (CSV, TSV, ...) as JobData.
|
ERRCODE | TFormer_SetODBCData (HTFORM pInstance, LPCSTR pszDSN, LPCSTR pszUser, LPCSTR pszPwd, LPCSTR pszSQLSelect) |
| Specifies an SQL-SELECT statement (ODBC) as JobData.
|
ERRCODE | TFormer_SetXmlDataFile (HTFORM pInstance, LPCSTR pszFileName) |
| Specifies a XML file as JobData.
|
ERRCODE | TFormer_SetXmlDataFileEx (HTFORM pInstance, LPCSTR pszFileName, LPCSTR pszXsltFileName, LPCSTR pszXsltTFC) |
| Specifies a XML file as JobData and transforms it with the given XSLT.
|
ERRCODE | TFormer_SaveXml (HTFORM pInstance, LPCSTR pszFileName) |
| Saves the actual JobData as XML file in the internal TFORMer format.
|
Detailed Description
TFORMer SDK retrieves data used for printing a Job with the help of JobData.
Overview
TFORMer SDK retrieves data used for printing a
Job with the help of
JobData.
JobData is used to provide values for the DataFields used in a
FormLayout.Different types of
JobData classes are supported:
- Importing data using JobDataCsv, JobDataXml or JobDataOdbc.
Each of these connects to the specified file or database and reads the data Record by Record.
- Provide the data via code using JobDataDataSource.
This is the preferred method for passing data to TFORMer SDK from within an application. The JobDataDataSource is constructed in memory and filled with an arbitrary number of records. Each Record contains pairs of DataField-names/DataField-values.
- A JobDataDataSource defined by the user in the FormLayout.
Such a DataSource defines how data is retrieved (e.g. from an ODBC database), the field-mappings (see DataSource Field Mapping) and optional parameters (see DataSourceParameter).
Data Processing
JobData is always iterated Record by Record, the order of the Records is not changed. All DataFields available in a Record are processed.
- Usually each Record triggers the printing of the detail band(s) in the FormLayout.
- Report headers are printed at the top of the first page (above the first page header) after the first Record was read.
- Report footers are printed at the bottom of the last page after the last Record was read.
- Page headers and page footers are printed when required, no Record is needed to trigger them.
- Note:
- TFORMer requires at least one Record to produce output.
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
If the
JobData provides more DataFields than defined (either in the stand-alone
FormLayout or in the
Project of the
Repository), these additional fields will be ignored.
Missing DataFields in JobData
If a
DataField, which is used in the
FormLayout, is not present in the
JobData 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.
- Note:
- DataFields which are computed with post- or pre-evaluations within a FormLayout will not be cleared (see TFormer_ProjectVarItGetUsage).
Missing or Empty JobData
If no (or an empty)
JobData was specified then
TFORMer SDK uses the default
DataSource for printing the Job. The default data is stored in an extra file located in the same directory as the FormLayout itself and is named
FormlayoutName.xml
. It contains the
DataField values used during the last
TFORMer Designer session.If no file with default data exists
TFORMer SDK produces no output.
Identifying the Required DataFields
In order to identify all DataFields in a
Project or in a
FormLayout use the functions
TFormer_GetFirstProjectVarIt and
TFormer_GetNextProjectVarIt. If you want to know, whether a returned
DataField is actually used in the FormLayout use the function
TFormer_ProjectVarItGetUsage.
More Information
Function Documentation
Appends a new Record to the DataSource.
A Record is a collection of name/value pairs. This pair holds the name of a DataField (first member of the pair) and its value (second member of the pair). Call this function before you set DataField values for the new Record.
- Returns:
- ErrOk (0) in case of success, non-zero if an error occurred
- Parameters:
-
pInstance | The TFORMer instance provided by a previous call to TFormer_Init |
- See also:
- TFormer_SetRecordCopy, TFormer_SetVarValue, TFormer_ResetData
Selects whether escape sequences like \n or \x40 should be translated by TFORMer.
The default value is FALSE
. That means TFORMer uses DataField values exactly as provided, no escape sequence handling will be performed.
- Returns:
- ErrOk (0) in case of success, non-zero if an error occurred
- Parameters:
-
pInstance | The TFORMer instance provided by a previous call to TFormer_Init |
bOn | TRUE if escape sequences should be translated |
- See also:
- TFormer_SetVarValue
-
Escape Sequences
Sets the number of copies for the actual Record.
The value provided with this function specifies how often this Record is used for printing. May be called after TFormer_NewRecord. If TFormer_SetRecordCopy is not set, then the default value 1 will be used.
- Returns:
- ErrOk (0) in case of success, non-zero if an error occurred
- Parameters:
-
pInstance | The TFORMer instance provided by a previous call to TFormer_Init |
nRecordCopy | The number of copies for the current Record. |
- Note:
- Do not mix up this method with TFormer_SetNumberOfCopies
- See also:
- TFormer_NewRecord, TFormer_SetVarValue
Selects if DataField values should be reused in consecutive Records.
- If 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. This allows you to omit TFormer_SetVarValue for a DataField if the value should be the same as in the previous Record.
- If set to
FALSE
(which is the default), then all DataFields are set to "" (empty string) or 0 (depending on the DataFieldType) between Records. It is recommended to set all DataFields for each Record.
- Returns:
- ErrOk (0) in case of success, non-zero if an error occurred
- Parameters:
-
pInstance | The TFORMer instance provided by a previous call to TFormer_Init |
bReuse | Should data be reused for each Record? |
- See also:
- TFormer_NewRecord, TFormer_SetVarValue
Specifies a XML file as JobData and transforms it with the given XSLT.
This function is similar to TFormer_SetXmlDataFile but transforms the XML file with the specified XSLT before being used as JobData.
- Returns:
- ErrOk (0) in case of success, non-zero if an error occurred
- Parameters:
-
pInstance | The TFORMer instance provided by a previous call to TFormer_Init |
pszFileName | XML filename |
pszXsltFileName | XSLT filename, if NULL then no transformation is performed |
pszXsltTFC | XSLT TFC filename. Internal Use ONLY (generates TFC File from given xml file) |
- Warning:
- Internal use only!
- See also:
- TFormer_SetTxtDataFile, TFormer_SetImportFieldForRecordCopy, TFormer_SetXmlDataFile