Provide Data

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. For a JobDataDataSource you have to set the option ignore-undefined-fields.

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

• JobDataCsv
  CSV import
• JobDataOdbc
  ODBC connectivity
• JobDataXml
  XML import
• JobDataRecordSet
  In-memory DataSource
• JobDataDataSource
  User-defined DataSource

---

Function Documentation

LPCSTR TFormer_GetDatasourceName	(	HTFORM	pInstance,
		ERRCODE *	peCode
	)

Provides the name of the active DataSource of the current FormLayout.

Use this function to get the name of the active DataSource of the current FormLayout. If the manual DataSource is the active one, this functions returns an empty string.

Returns:

- The name of the active DataSource of the current FormLayout. This name is only valid if peCode is ErrOk (0).

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
peCode	Error Code, ErrOk (0) in case of success

Note:

Must be called after TFormer_SetFormName.

See also:

TFormer_SetRepositoryName, TFormer_SetProjectName, TFormer_SetFormName, TFormer_SetDSParameterValue.

ERRCODE TFormer_NewRecord

(

HTFORM

pInstance

)

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

ERRCODE TFormer_ResetData

(

HTFORM

pInstance

)

Resets the data-cache.

All DataFields handed over to TFORMer with TFormer_SetVarValue, TFormer_NewRecord or TFormer_SetDataFile are cached internally. As long as this cache is not deleted with this function the cached values will be used for a Job. Call this method before starting a new Job.

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

Note:

If you change the Repository, the Project or the FormLayout the internal cache is deleted automatically.

See also:

TFormer_NewRecord, TFormer_SetVarValue, TFormer_SetDataFile

ERRCODE TFormer_SaveXml	(	HTFORM	pInstance,
		LPCSTR	pszFileName
	)

Saves the actual JobData as XML file in the internal TFORMer format.

All DataFields set by TFormer_SetTxtDataFile, TFormer_SetXmlDataFile, TFormer_SetODBCData or by TFormer_SetVarValue are cached internally. This function writes the cache to the specified file which can the be used with TFormer_SetDataFile.

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	Target filename

Note:

Can be called after TFormer_SetXmlDataFile, TFormer_SetTxtDataFile, TFormer_SetODBCData or after TFormer_NewRecord.

See also:

JobDataXml, JobData, Passing Files

TFormer_SetDataFile

ERRCODE TFormer_SetDataFile	(	HTFORM	pInstance,
		LPCSTR	pszFileName
	)

Sets a XML file (in the format used internally by TFORMer) as JobData.

The specified file conform to the internal TFORMer format and is created with the function TFormer_SaveXml. Normally this function is not required by users.

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	Filename (in internal TFORMer XML format)

Remarks:

Instead, check out the functions TFormer_SetTxtDataFile, TFormer_SetXmlDataFile or TFormer_SetODBCData.

See also:

JobDataXml, JobData, Passing Files

TFormer_SetRepositoryName, TFormer_SetFormName

ERRCODE TFormer_SetDatasourceName	(	HTFORM	pInstance,
		LPCSTR	pszDatasourceName
	)

Specifies the name of the user-defined DataSource to be used as JobData.

Use this function to specify the name of the user-defined DataSource which should be used as JobData for printing.

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
pszDatasourceName	The name of the DataSource as defined in the FormLayout

Note:

Cached data (set with TFormer_NewRecord and TFormer_SetVarValue or by importing data-files) are discarded.

See also:

JobDataDataSource, JobData, Passing Files

TFormer_SetDSParameterValue, TFormer_GetDatasourceName.

ERRCODE TFormer_SetDSParameterValue	(	HTFORM	pInstance,
		LPCSTR	pszParameterName,
		LPCSTR	pszValue
	)

Specifies the value of a DataSourceParameter.

Use this function to specify a value for a DataSourceParameter. A DataSourceParameter may be defined by the user with TFORMer Designer and can be used to control certain aspects of a DataSource during runtime (e.g. filenames, SQL statement or an ODBC-DSN).

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
pszParameterName	The name of the DataSourceParameter to be set
pszValue	The value to be set

Note:

Must be called before TFormer_Print, but after TFormer_SetDatasourceName or if a parameter of the active Datasource should be set, after TFormer_SetFormName.

See also:

TFormer_SetRepositoryName, TFormer_SetProjectName, TFormer_SetFormName, TFormer_SetDatasourceName, TFormer_GetDatasourceName.

ERRCODE TFormer_SetHandleEscapeSequences	(	HTFORM	pInstance,
		BOOL	bOn
	)

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

ERRCODE TFormer_SetImportFieldForRecordCopy	(	HTFORM	pInstance,
		LPCSTR	pszFieldName,
		BOOL	bIsAttribute
	)

Specifies which DataField in the input controls the number of Record copies.

TFORMer allows you to specify how often one Record of a DataSource should be used for printing (see also TFormer_SetRecordCopy). This functions specifies which DataField holds the number of copies for each Record of the DataSource.

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
pszFieldName	The DataField name which holds the Record-copy counter. NULL if none should be used (default: NULL).
bIsAttribute	Specifies if the given DataField name is the name of an attribute field. Used only for XML-Imports.

Note:

Must be called before TFormer_SetTxtDataFile, TFormer_SetXmlDataFile or TFormer_SetODBCData

See also:

TFormer_SetTxtDataFile, TFormer_SetXmlDataFile, TFormer_SetODBCData

ERRCODE TFormer_SetODBCData	(	HTFORM	pInstance,
		LPCSTR	pszDSN,
		LPCSTR	pszUser,
		LPCSTR	pszPwd,
		LPCSTR	pszSQLSelect
	)

Specifies an SQL-SELECT statement (ODBC) as JobData.

The column names returned by the SQL statement must match the DataField names in the FormLayout.

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
pszDSN	DSN of the ODBC connection
pszUser	User-Name for ODBC connection (may be NULL or an empty string)
pszPwd	Password for the ODBC connection (may be NULL or an empty string)
pszSQLSelect	SQL-SELECT statement for retrieving data.

See also:

JobDataOdbc, JobData

TFormer_SetTxtDataFile, TFormer_SetXmlDataFile, TFormer_SetImportFieldForRecordCopy

ERRCODE TFormer_SetRecordCopy	(	HTFORM	pInstance,
		UINT	nRecordCopy
	)

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

ERRCODE TFormer_SetReuseValues	(	HTFORM	pInstance,
		BOOL	bReuse
	)

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

ERRCODE TFormer_SetTxtDataFile	(	HTFORM	pInstance,
		LPCSTR	pszFileName,
		CHAR	cSeparator,
		CHAR	cTextQualifier
	)

Specifies a text file (CSV, TSV, ...) as JobData.

The column names used in the text file must match the DataField names in the FormLayout

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	Text/CSV/TSV filename
cSeparator	DataField separator (e.g. , or ;)
cTextQualifier	Text qualifier (e.g. "\'" or " - default is none)

See also:

JobDataCsv, JobData, Passing Files

TFormer_SetXmlDataFile, TFormer_SetODBCData, TFormer_SetImportFieldForRecordCopy

ERRCODE TFormer_SetVarValue	(	HTFORM	pInstance,
		LPCSTR	szVarName,
		LPCSTR	szVarValue
	)

Sets the value of a DataField.

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
szVarName	The name of the DataField for which the value should be set.
szVarValue	The value for the given DataField.

Remarks:

Must be called for each DataField after a call to TFormer_NewRecord. All data is passed to TFORMer as string - TFORMer converts this string automatically into the specified data-type (see EVarType). If a validation rule is violated (see TFORMer Designer), an error code is returned. If this function is not called for a DataField used in a FormLayout, then the content of this DataField depends on TFormer_SetReuseValues.

If you want to identify the DataFields which are available in a Project or FormLayout, please use the function TFormer_GetFirstProjectVarIt.

Note:

This function will test if

• the given value confirms to the validation rules set in TFORMer Designer
• the given value can be converted to the type of the DataField (Float, Long). A conversion to String is always possible.
  
  If one of this conditions is not met, an error will be returned. Detailed information about the error can be obtained by calling TFormer_GetLastErrorDescription, TFormer_GetLastErrorInformation, TFormer_GetLastErrorSource.

See also:

TFormer_SetReuseValues, TFormer_NewRecord

ERRCODE TFormer_SetXmlDataFile	(	HTFORM	pInstance,
		LPCSTR	pszFileName
	)

Specifies a XML file as JobData.

The element (or attribute) names in the XML file must match the DataField names in the FormLayout.

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

See also:

JobDataXml, JobData, Passing Files

TFormer_SetTxtDataFile, TFormer_SetODBCData, TFormer_SetImportFieldForRecordCopy

ERRCODE TFormer_SetXmlDataFileEx	(	HTFORM	pInstance,
		LPCSTR	pszFileName,
		LPCSTR	pszXsltFileName,
		LPCSTR	pszXsltTFC
	)

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_SetODBCData, TFormer_SetXmlDataFile, TFormer_SetImportFieldForRecordCopy