ERRCODE TFormer_SetXmlDataFile ( HTFORM  pInstance,
LPCSTR  pszFileName 
)

Specifies a XML-File as DataSource.

Returns:
- ErrOk (0) in case of success
- Non-zero if error occurred
Parameters:
[in] pInstance The TFORMer-Instance provided by a previous call to TFormer_Init.
[in] pszFileName Data-File name
Remarks:
Usually the methods TFormer_SetVarValue and TFormer_NewRecord are used to hand over variable data to TFORMer Runtime. This DataSource enables TFORMer Runtime to use XML-files as a DataSource for printing a Job. The specified XML-file must comply to the formats recognized by TFORMer. The following XML formats can be used:
  • Variant 1 of the generic XML-format (this function).
  • Variant 2 of the generic XML-format (this function).
  • The XML-format used in current versions of Microsoft® Access (this function).
  • The XML-format used by TFORMer internally (see TFormer_SetDataFile).
Note:
Behavior if no input data was supplied: If no DataSource was specified (either by TFormer_SetXXXDataFile, TFormer_SetODBCData or via TFormer_NewRecord and TFormer_SetVarValue) the default data-file (located in the same directory as the FormLayout itself and generated by the last TFORMer Designer session) is used. If this default data-file does not exists no output will be produced. The name of the default data-file is path/FormName.xml.

A data file may be passed in the following ways:

  • Specify the filename directly.
  • Specify the filename of a ZIP-file (e.g. with WinZip) containing the required file.
  • BASE64-encode the content of the required file (see Convert class of .NET) and use this string instead of a filename.
  • BASE64-encode the content of a ZIP-file (see Convert class of .NET) containing the required file(s). Use this string instead of a filename.

Note:
BASE64 encoded strings must start with the sequence BASE64:. When passing a zipped file TFORMer expects a real WinZip compatible format. A zipped stream is not suitable! For more details please refer to the TFORMer Runtime DLL Programming Reference.

This is an example for the generic XML-format (Variant 1).
 <Root>
   <Records>
     <Record>
       <V Name="DataFieldName1">Value</V>
       <V Name="DataFieldName2">Value</V>
       <V Name="DataFieldName3">Value</V>
     </Record>
     <Record>
       <V Name="DataFieldName1">Value</V>
       <V Name="DataFieldName2">Value</V>
       <V Name="DataFieldName3">Value</V>
     </Record>
     :
     Further Data Records
     :
   </Records>
 </Root>
Description for XML-Elements in Variant 1
NameDescription
RootThis is the root element. It encloses all other elements of the XML-file.
RecordsThis element encloses all records.
RecordThis element represents one Record. Within a Record the single DataField-values are defined.
VData-Element. This element defines the name of the DataField (see Name) and the value of the DataField.
DataFieldNameName of the DataField (must be unique within a Record).
ValueThe actual value of the DataField.
The elements can be named arbitrarily. This means the terms Root, Records and Record can be selected at will. Only the order of the element-nodes is decisive: TFORMer interprets the lowest level of the XML-file as name/value pairs for DataFields, superordinate nodes always correspond to records.
This is an example for the generic XML-format (Variant 2).
Variant 2 is comparable to variant 1, but instead of using the syntax <V Name="DataFieldName">Value</V> you can specify DataField-values using the following syntax:
 <Root>
   <Records>
     <Record>
       <DataFieldName1>Value</DataFieldName1>
       <DataFieldName2>Value</DataFieldName2>
       <DataFieldName3>Value</DataFieldName3>
     </Record>
     <Record>
       <DataFieldName1>Value</DataFieldName1>
       <DataFieldName2>Value</DataFieldName2>
       <DataFieldName3>Value</DataFieldName3>
     </Record>
     :
     Further Data Records
     :
   </Records>
 </Root>
The XML files which are exported by Microsoft® Access look like this:
 <?xml version="1.0" encoding="UTF-8"?>
 <dataroot xmlns:od="urn:schemas-microsoft-com:officedata">
   <tblTableName>
     <DataFieldName1>Value</DataFieldName1>
     <DataFieldName2>Value</DataFieldName2>
     <DataFieldName3>Value</DataFieldName3>
   </tblTableName>
   <tblTableName>
     <DataFieldName1>Value</DataFieldName1>
     <DataFieldName2>Value</DataFieldName2>
     <DataFieldName3>Value</DataFieldName3>
   </tblTableName>
   :
   Further Data Records
   :
 </dataroot>
This is an example for the internal XML-format. TFORMer Designer uses this format to store DataField name/value pairs.
 <PSData>
   <Form>
     <Records>
       <Record Copies="1">
         <V Name="DataFieldName1">Value</V>
         <V Name="DataFieldName2">Value</V>
         <V Name="DataFieldName3">Value</V>
       </Record>
       <Record Copies="1">
         <V Name="DataFieldName1">Value</V>
         <V Name="DataFieldName2">Value</V>
         <V Name="DataFieldName3">Value</V>
       </Record>
     </Records>
   <ImportedVariables/>
   </Form>
 </PSData>
Description for XML-Elements in the internal TFORMer format
PSDataThis is the root element. It encloses all other elements within the XML-file.
FormThis element encloses all records for one FormLayout. It must be specified only once.
RecordsThis element encloses all records to be printed. It must be specified only once.
RecordThis element encloses all DataFields for one Record. For each Record there is one (optional) attribute named Copies. If this attribute is missing it defaults to 1 – meaning that this Record is used once. If you want to use the same data for multiple records you can specify NumberOfCopies using this attribute.
VData-Element. This element consists of the DataField-name (attribute Name) and the value.
DataFieldNameName of the DataField (must be unique within a Record).
ValueThe value of the DataField.
ImportedVariablesUsed internally by TFORMer.
Note:
Must be called after TFormer_SetFormName and before TFormer_Print.
See also:
TFormer_SetTxtDataFile, TFormer_SetImportFieldForRecordCopy.


© 2006-2009 - all rights reserved by TEC-IT Datenverarbeitung GmbH
Generated on Wed Sep 2 16:01:09 2009 for TFORMer Runtime DLL/Shared Library with doxygen 1.5.8