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 JTFORMer8.jar (which is compatible with the Java Runtime Edition - JRE version 1.5 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. Most likely a FormLayout 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 as well as 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 TFORMer8.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 -lTFORMer8:

  $ gcc TFORMerSimpleX.c -o TFORMerSimpleX -ldl -lTFORMer8 -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.

  TFormer_License ("John Doe", LICKIND_WORKSTATION, 1, "00000000000000000000000000000000"); 

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/8/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 place holders 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

This is the most direct method to pass data to TFORMer SDK. In this case the names and values of the DataFields used in a FormLayout are provided directly. The example below sets the values for the DataFields ArticleNo, ArticleName and ArticlePrice.

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

  // Create a new Record 
  eCode = TFormer_NewRecord           (hTForm);
  // Add some name/value pairs for the DataField values to the Record
  eCode = TFormer_SetVarValue         (hTForm, "ArticleNo",     "12001234");
  eCode = TFormer_SetVarValue         (hTForm, "ArticleName",   "Speaker System HF1");
  eCode = TFormer_SetVarValue         (hTForm, "ArticlePrice",  "498.98");                   

  // Create a Second Record 
  eCode = TFormer_NewRecord           (hTForm);                                           
  // This Record should be printed two times
  eCode = TFormer_SetRecordCopy       (hTForm, 2);
  // Add some name/value pairs for the DataField values to the Record
  eCode = TFormer_SetVarValue         (hTForm, "ArticleNo",     "12021231");                 
  eCode = TFormer_SetVarValue         (hTForm, "ArticleName",   "Record Box 12 CDs"); 
  eCode = TFormer_SetVarValue         (hTForm, "ArticlePrice",  "8.85");                   

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

• Job / JobData
• Repository / FormLayout
• Samples
• General Information

• Distribution & Deployment