TFORMer SDK - DLL/Library  9
Basic Concept / Printing

Installation

Install TFORMer Designer (the graphical layout editor) and TFORMer SDK (the reporting and label printing core) using the setup applications. TFORMer SDK is available as DLL, as COM component, as .NET assembly, as JAVA class and as stand-alone application (TFPrint). Both the COM component and the .NET assembly of TFORMer SDK are registered automatically. The .NET assembly is automatically placed in the GAC and in the Bin directory of the installation folder. The Java package JTFORMer9.jar (which is compatible with the Java Runtime Edition - JRE version 1.8 or higher) is copied into the Bin directory: It includes all classes that you need to create a TFORMer application with the Java language.

Design a FormLayout

Use TFORMer Designer to create a FormLayout graphically. A FormLayout usually contains dynamic data which will be provided by your application during print-time (e.g. an article number for a product label or a ticket number for an e-ticket). TFORMer uses DataFields as place-holders for such dynamic data. These DataFields are declared and used within the FormLayout.

Check out the following paragraphs to learn how to print or export a FormLayout with data provided by your application!

Embed TFORMer SDK Into Your Application

Create a new C or C++ project (or choose any programming language which is able to use DLLs or shared libraries).

Microsoft Windows Operating Systems

You need to include the file TFormer.h and to define the preprocessor variable TECIT_DLLIMPORT: 

  #define TECIT_DLLIMPORT
  #include "TFormer.h"
  #undef  TECIT_DLLIMPORT

Link your application with TFORMer9.lib.

Linux/UNIX Operating Systems

When working on Linux or UNIX some additional lines of code are required: To use TFORMer SDK include the files TECITStd.h and TFormer.h into your source code. Make sure to define TECIT_DLLIMPORT, _TEC_UNIX and TEC_UNIX_BUILD before including the files. 

  #define TECIT_DLLIMPORT
  #define _TEC_UNIX
  #define TEC_UNIX_BUILD

  #include <TECITStd/TECITStd.h>
  #include <TFormer.h>

  #undef  TECIT_DLLIMPORT
  #undef  TECIT_DLLIMPORT
  #undef  _TEC_UNIX
  #undef  TEC_UNIX_BUILD

Link your application with the parameter -lTFORMer9: 

  $ gcc TFORMerSimpleX.c -o TFORMerSimpleX -ldl -lTFORMer9 -L/usr/local/lib -I/usr/local/include

License and Initialize TFORMer SDK

Licensing is not required for evaluation purposes. For production, apply a license key to TFORMer SDK before using any other properties or methods of TFORMer. This needs to be done only once, for example when initializing the application. 

  // License TFORMer SDK by calling one of the following methods:
  // - TFormer_License: provides the license data manually
  // - TFormer_LicenseBase64: provides the license data from base64 string
  // - TFormer_LicenseFile: provides the license data from TFORMer.ini license file
  // Example:
  TFormer_License ("<your activation key>", "<your name>", LICKIND_WORKSTATION, 1, "<options>", "yyyymmdd", "<base64signature>");

Now initialize TFORMer SDK: 

  HTFORM  hTForm  = NULL;
  // Allocate memory and retrieve TFORMer handle
  hTForm = TFormer_Init (NULL);

Select the FormLayout to be Used

When using a stand-alone FormLayout (.tff) only one function call is required:

  // Select the stand-alone FormLayout
  eCode = TFormer_SetRepositoryName (hTForm, "C:/Documents and Settings/All Users/Application Data/TEC-IT/TFORMer/9/Examples/Command Line/ODBCReportPDF/ODBCReportPDF.tff");
Note:
TFORMer Designer supports so-called stand-alone FormLayouts (which are created by default by TFORMer Designer) and Repository based FormLayouts (which enable you to organize a large number of FormLayouts in a structured way). Check out Repository / FormLayout for details.

Whenever properties or methods are requesting input files (e.g. FormLayouts, or file-based DataSources like XML or CSV files), these may be passed as usual via the filename or by using BASE64 encoded strings. In addition, files and BASE64 strings may be zipped to save bandwidth. Refer to Passing Files for details.

Provide JobData

As mentioned above a FormLayout usually contains DataFields which are used as placeholders for dynamic data. Before printing a FormLayout you need to provide data for these DataFields by assigning suitable JobData to the Job. Various methods are available for providing JobData.

Note:
The field names available in the JobData (e.g. the column names returned by a SQL-SELECT statement or the column names in a CSV file) must match the names of the DataFields used in a FormLayout. When using user-defined data sources (see user-defined data source below) the mapping between fields in the DataSource to DataFields in the FormLayout can be adjusted freely.

Provide JobData via Program Code

See also JobDataRecordSet

This is the most direct method to pass data to TFORMer SDK. The DataFields in the FormLayout are populated via the according name/value assignments in the code. 

  // Clear the Data Cache
  eCode = TFormer_ResetData         (hTForm);

  // Create a new Record
  eCode = TFormer_NewRecord         (hTForm);
  // Populate the Record with key/value pairs to define the DataField values
  eCode = TFormer_SetVarValue       (hTForm, "Field1", "Value1");
  eCode = TFormer_SetVarValue       (hTForm, "Field2", "Value2");
  eCode = TFormer_SetVarValue       (hTForm, "Field3", "Value3");

  // Create and add more Records
  // ...

Load JobData From CSV Files

See also JobDataCsv 

  // Here we import a CSV and specify separator and qualifier character
  eCode = TFormer_SetTxtDataFile (hTForm, "path/data.csv", ',', '"');

Load JobData From XML Files

See also JobDataXml 

  // Use the XML file InputData.XML as data source
  eCode = TFormer_SetXmlDataFile (hTForm, "path/data.xml");

Load JobData From a Database

See also JobDataOdbc 

  // Here we import data from an ODBC connection using the specified SQL SELECT statement
  eCode = TFormer_SetODBCData (
      hTForm,
      "DSN=TFORMer_Sample",
      NULL, /* User */
      NULL, /* Password */
      "SELECT * FROM tbl_Example"
  );

Load JobData From a User-Defined Data Source

See also JobDataDataSource

Last but not least TFORMer Designer offers the possibility to specify a "user-defined" DataSource as part of a FormLayout. Such a DataSource defines how data is retrieved (e.g. from an ODBC database) and it specifies the mappings between fields in the DataSource and DataFields in the FormLayout. If you want to use such a user-defined DataSource for JobData retrieval, select the DataSource by name as shown below. Use optional DataSourceParameters to control certain aspects (like the filename, SQL SELECT statement or DSN) of the DataSource during runtime. 

  // The DataSource named myTextDataSource must be defined in the FormLayout or Repository
  // Retrieve data using the predefined data source myTextDataSource
  eCode = TFormer_SetDatasourceName   (hTForm, "myTextDataSource");
  // Set the DataSourceParameter named parFile
  eCode = TFormer_SetDSParameterValue (hTForm, "parFile", "/YourPath/InputData.txt");

Generate Output

Print on a Printer

Use TFormer_SetPrinterName to specify the target printer. Provide an empty string, if you want to send the output to the default printer. 

  // Select the printer name on Windows or Linux (CUPS printer name), use NULL for the default printer
  eCode = TFormer_SetPrinterName  (hTForm, pszPrinterName, NULL);

  // Print
  eCode = TFormer_Print           (hTForm);

Export as PDF, PostScript, HTML, ZPL-II or as an Image

Instead of printing on a printer, you can export the output as a PDF, PostScript, HTML, ASCII or image file. ZPL-II (the ZEBRA printer language) generation is supported, too. Instead of setting a printer name, set the name and type of the output file. 

  // Select PDF output
  eCode = TFormer_SetPrinterType  (hTForm, ePrinterType_PDFFile);
  // To /temp/out.pdf
  eCode = TFormer_SetOutputName   (hTForm, "/temp/out.pdf");
  // Generate PDF
  eCode = TFormer_Print           (hTForm);

Generate Output as an In-Memory Stream

Starting with TFORMer version 7 it is possible to generate the output as an in-memory stream. No output or temporary files are required, the performance for creating the output is dramatically improved. Currently PDF- and image-output (excluding multi-page TIFF) are generated completely in-memory.

Use Multiple Streams

// Define the call-back function for streaming
ERRCODE __stdcall StreamCallback (BYTE* pBuffer, INT nSizeBuffer, DWORD dwFlags, LPARAM lParam)
{
  ERRCODE eCode = ErrOk;
  if      (dwFlags == eWriteCallBack_Data)
  {
    // Process data (copy or write the data to the stream)
  }
  else if (dwFlags == eWriteCallBack_Close)
  {
    // Close the current stream
  }
  else if (dwFlags == eWriteCallBack_Open)
  {
    // Open a new stream, the name which is set in TFormer_SetOutputName is provided via pBuffer (UTF8 encoded)
  }

  return eCode;
}

  // Generate a PNG image named StreamToFileExample.png
  // The provided OutputName is passed to call-back function
  // If multiple pages are generated page numbers will get appended (e.g. StreamToFileExample_002.png)
  eCode = TFormer_SetOutputName   (hTForm, "StreamToFileExample.png");
  eCode = TFormer_SetPrinterType  (hTForm, ePrinterType_ImagePng);

  // Generate PDF
  // Instead of #TFormer_Print use #TFormer_PrintToStream and provide the callback function.
  eCode = TFormer_PrintToStream   (hTForm, StreamCallback, (LPARAM)0);

Clean Up

Clean up all resources allocated by TFORMer SDK: 

  // Free resources used by TFORMer SDK
  TFormer_Exit (hTForm);

More Information

© 2006-2026 - all rights reserved by TEC-IT Datenverarbeitung GmbH
Generated on Fri Feb 6 2026 10:32:55 for TFORMer SDK - DLL/Library with doxygen 1.7.6.1