General

General functions which are mandatory for most applications. More...

Defines
#define	ERRCODE   LONG
	Define the type for the error codes.
#define	ErrOk   S_OK
	Define error code for "no error" (ErrOk, 0)
Enumerations
enum	EVarType { eVarType_Text = 0, eVarType_Long = 1, eVarType_Float = 2, eVarType_Invalid }
	Defines the type of a DataField. More...
enum	EPrinterType {   ePrinterType_Default = 0, ePrinterType_Win32, ePrinterType_Repository, ePrinterType_Cups,   ePrinterType_PSFile, ePrinterType_HTML, ePrinterType_PDFFile, ePrinterType_PSPrinter,   ePrinterType_TxtPrinter, ePrinterType_TxtFile, ePrinterType_ImageBmp, ePrinterType_ImageGif,   ePrinterType_ImageJpg, ePrinterType_ImagePcx, ePrinterType_ImagePng, ePrinterType_ImageTga,   ePrinterType_ImageTifSingle, ePrinterType_ImageTifMultiPage, ePrinterType_ZPLPrinter, ePrinterType_ZPLFile,   ePrinterType_PDFA, ePrinterType_ZUGFeRD, ePrinterType_SVG, ePrinterType_SVGZ,   ePrinterType_Invalid }
	This enumeration specifies the type of output generated by TFORMer SDK. More...
enum	EVarUsage {   eVarUsage_NotUsed = 0, eVarUsage_Normal, eVarUsage_Calculated, eVarUsage_Parameter,   eVarUsage_Invalid }
	Describes the usage of a DataField within a FormLayout. More...
enum	ETFDataFormat { eTFDataFormat_XML, eTFDataFormat_Invalid }
	Describes the desired format for requested data (e.g. More...
Functions
HTFORM	TFormer_Init (HTFRepository hRepository)
	Allocates and initializes internal memory.
ERRCODE	TFormer_Exit (HTFORM pInstance)
	Frees system resources previously allocated with TFormer_Init.
void	TFormer_License (LPCSTR pszLicensee, DWORD dwKind, LONG nLicenses, LPCSTR pszLicenseKey)
	License this TFORMer SDK instance.
License Types
The license types for the TFORMer SDK (see TFormer_License).
#define	LICKIND_WORKSTATION   1
	Workstation license.
#define	LICKIND_SITE   2
	Site license.
#define	LICKIND_DEVELOPER   3
	Developer license.
#define	LICKIND_OFFICE   4
	Office license.
#define	LICKIND_WORKGROUP   5
	Workgroup license.
#define	LICKIND_SERVER   6
	Server license.

---

Detailed Description

General functions which are mandatory for most applications.

---

Define Documentation

#define ERRCODE   LONG

Define the type for the error codes.

#define ErrOk   S_OK

Define error code for "no error" (ErrOk, 0)

#define LICKIND_DEVELOPER   3

Developer license.

Supports the use of TFORMer SDK in client-applications for a certain number of redistributions.

#define LICKIND_OFFICE   4

Office license.

Supports a certain number of installations or users within one facility or site (located at a single postal address).

#define LICKIND_SERVER   6

Server license.

Supports a certain number of total users for a (web-)server based installation.

#define LICKIND_SITE   2

Site license.

Supports a certain number of installations or users within one facility or site (located at a single postal address).

#define LICKIND_WORKGROUP   5

Workgroup license.

Supports a certain number of installations or users within one facility or site (located at a single postal address).

#define LICKIND_WORKSTATION   1

Workstation license.

Supports exactly one installation on a machine which is identified via the system-id.

---

Enumeration Type Documentation

enum EPrinterType

This enumeration specifies the type of output generated by TFORMer SDK.

Choose between direct printing (Win32, Repository, Cups, PostscriptPrinter, TextPrinter, ZPLPrinter) and other supported output formats (PostscriptFile, HtmlFile, PdfFile, TextFile, ZPL-file or the various image formats).

See also:

Output Format Prefixes, TFormer_SetOutputName, TFormer_SetPrinterType, TFormer_SetPrinterName

Enumerator:

ePrinterType_Default	The default output device type. The output device which will be used depends on the type of the FormLayout to be printed. Repository based FormLayout A printer of type Repository will be used. Without the specification of a PrinterName the default printer within this Repository (named _Default_) is used. Stand-alone FormLayout A printer of type Win32 will be used on Microsoft Windows. For Linux and UNIX a printer of type Cups will be used.
ePrinterType_Win32	Direct printing to a Windows printer via GDI-calls (Microsoft Windows only).
ePrinterType_Repository	The printer as defined in the Repository or stand-alone FormLayout. In the later case only the printer _Default_ is used (which maps to the default printer of the current user). To use other printers set the PrinterType to Win32.
ePrinterType_Cups	A CUPS printer (Linux and UNIX only).
ePrinterType_PSFile	This printer type generates PostScript output as file. The PostScript header and footer used for each page may be customized. See Footer.ps and Header.ps in the TFORMer installation directory for details.
ePrinterType_HTML	This printer type generates HTML output as file. Some aspects of the index page and the footer appended to each generated HTML page may be customized. See Footer.html and Template.html in the TFORMer installation directory for details.
ePrinterType_PDFFile	This printer type generates PDF output as file.
ePrinterType_PSPrinter	This printer type sends PostScript output directly to the specific printer. The PostScript header and footer used for each generated page may be customized. See Footer.ps and Header.ps in the TFORMer installation directory for details.
ePrinterType_TxtPrinter	This printer type sends ASCII output directly to the specific printer.
ePrinterType_TxtFile	This printer type generates ASCII output as file.
ePrinterType_ImageBmp	This printer type generates BMP image files (one image file per page). The specified filename may contain #-characters as placeholders for the page-number.
ePrinterType_ImageGif	This printer type generates GIF image files (one image file per page). The specified filename may contain #-characters as placeholders for the page-number.
ePrinterType_ImageJpg	This printer type generates JPG image files (one image file per page). The specified filename may contain #-characters as placeholders for the page-number.
ePrinterType_ImagePcx	This printer type generates PCX image files (one image file per page). The specified filename may contain #-characters as placeholders for the page-number.
ePrinterType_ImagePng	This printer type generates PNG image files (one image file per page). The specified filename may contain #-characters as placeholders for the page-number.
ePrinterType_ImageTga	This printer type generates TGA image files (one image file per page). The specified filename may contain #-characters as placeholders for the page-number.
ePrinterType_ImageTifSingle	This printer type generates TIFF image files (one image file per page). The specified filename may contain #-characters as placeholders for the page-number.
ePrinterType_ImageTifMultiPage	This printer type generates multi-page TIFF image files (one image contains all output pages).
ePrinterType_ZPLPrinter	This printer type sends ZPL-II (ZEBRA Printer Language) output directly to the specific printer.
ePrinterType_ZPLFile	This printer type generates ZPL-II (ZEBRA Printer Language) output as file.
ePrinterType_PDFA	This printer type generates PDF/A output as file.
ePrinterType_ZUGFeRD	This printer type generates ZUGFeRD PDF/A-3 output as file and attaches the given ZUGFeRD-invoice.xml to it (see http://www.zugferd.de).
ePrinterType_SVG	This printer type generates SVG (Scalable Vector Graphics) output as file.
ePrinterType_SVGZ	This printer type generates SVGZ (Compressed Scalable Vector Graphics) output as file.
ePrinterType_Invalid	Invalid or unspecified printer type. Do not use this value (internal use only).

enum ETFDataFormat

Describes the desired format for requested data (e.g.

XML)

See also:

TFormer_GetPrintResult, TFormer_ProjectVarItGetDetails

Enumerator:

eTFDataFormat_XML
eTFDataFormat_Invalid

enum EVarType

Defines the type of a DataField.

Overview

A DataField is a place-holder for dynamic content in a FormLayout. One FormLayout can use an arbitrary number of DataFields (0..n). TFORMer Designer requires that a DataField is defined before it can be used. This definition takes place directly in the FormLayout (in the case of a stand-alone FormLayout) or in a user-defined Project (or the GlobalProject ) of a Repository.

A DataField can be printed as text, as bar-code or may be used to provide the filename for image elements in the FormLayout. Besides this, a DataField can be used in element expressions and printing conditions.

Data Type

The type of a DataField influences its use in expressions within a FormLayout and the conversion method when reading a DataField from a JobData. 3 different data types are supported:

• eVarType_Text
  A text (string or character). This is the recommended TFormer_ProjectVarItGetType!
• eVarType_Long
  An integer number. When reading a DataField of this type from a JobData it is converted automatically to an integer. In case of conversion errors the result is 0 (no error or exception will be raised).
• eVarType_Float
  A floating point number. When reading a DataField of this type from a JobData it is converted automatically to a floating point number. In case of conversion errors the result is 0 (no error or exception will be raised).
• eVarType_Invalid
  Invalid, internal use only.

Naming Conventions

The name of a DataField must comply with JavaScript rules for valid identifiers (see Naming Rules). In short a name must begin with a letter or an underscore. Within the name letters, underscores and digits are allowed. Special characters (e.g. white spaces, tabs, hyphens, German Umlauts, ...) are invalid.

Usually DataField names are not suitable for representing them to end-users. Refer to additional properties like Caption, Description, Comment and DisplayOrder for such purposes.

Data Field Values

For printing a FormLayout it is required to provide the DataField values via JobData. When a JobData is used to pass data to TFORMer SDK and a DataField is not set by this JobData the value of the DataField will be an empty string ("") or 0 (see also TFormer_SetReuseValues).

Data Field Default Values

The DefaultValue is the standard value of a DataField. The DefaultValue is only used by TFORMer Designer.

Validating DataFields

Use ValidationRules for validating values for DataField objects.

ValidationRules are expressions which are used to check if the value of a DataField meets a certain criteria. Whenever a DataField value violates the assigned ValidationRule an error message is displayed (in TFORMer Designer) or an exception is raised (TFORMer SDK).

DataField Enumeration

In order to programmatically access the DataFields in a FormLayout you may either use the method TFormer_GetFirstProjectVarIt or you may iterate through all available DataField objects using TFormer_GetFirstProjectVarIt and TFormer_GetNextProjectVarIt. If you want to know, whether the returned DataField is actually used in the FormLayout use the method TFormer_ProjectVarItGetUsage.

To determine if a specific DataField is used in a FormLayout iterate all data-fields of the Project and query the usage:

  // Enumerate all DataFields in the Project
  HPROJECTVAR_ITERATOR  it                = TFormer_GetFirstProjectVarIt (hTForm, pszProjectName, &eCode);
  BOOL                  bProjectVarValid  = (it != NULL);
  LPCSTR                pszDataFieldName  = NULL;

  // TYPE_E_ELEMENTNOTFOUND should not be treated as error
  if (eCode == TYPE_E_ELEMENTNOTFOUND)
    eCode = ErrOk;  

  // iterate all DataFields  
  while (bProjectVarValid && (eCode == ErrOk))
  {
    // Query the DataField usage in the given FormLayout
    EVarUsage eVarUsage = TFormer_ProjectVarItGetUsage (hTForm, it, &eCode);      
    if ((eVarUsage == eVarUsage_Normal) && (eCode == ErrOk))
    {
      pszDataFieldName = TFormer_ProjectVarItGetName (it, &eCode);
      if (pszDataFieldName != NULL && eCode == ErrOk)
        printf ("  %s\n", pszDataFieldName);
    }

    // get next DataField
    bProjectVarValid = (TFormer_GetNextProjectVarIt (it) == ErrOk);
  }
  // release iterator
  TFormer_FreeProjectVarIt (it);

Enumerator:

eVarType_Text	A text (string or character). This is the recommended DataFieldType.
eVarType_Long	An integer number. When reading a DataField of this type from a JobData it is converted automatically to an integer. In case of conversion errors the result is 0 (no error or exception will be raised).
eVarType_Float	A floating point number. When reading a DataField of this type from a JobData it is converted automatically to a floating point number. In case of conversion errors the result is 0 (no error or exception will be raised).
eVarType_Invalid	Invalid, internal use only.

enum EVarUsage

Describes the usage of a DataField within a FormLayout.

Enumerator:

eVarUsage_NotUsed	The DataField is defined within the Project but is not used in the FormLayout.
eVarUsage_Normal	A normal DataField. The DataField is in use by the FormLayout, its value is not modified. The DataField is just used as part of expressions or directly in text-, bar-code or picture elements. Therefore the value for this DataField may be provided by an external application or by the user.
eVarUsage_Calculated	The DataField is computed automatically. The DataField is in use by the FormLayout and its value is modified. Usually this is done via pre- or post-expressions. Therefore the value for this DataField may not be provided by an external application or by the user.
eVarUsage_Parameter	This is a writable system-DataField used by the FormLayout. The value of this system-DataField may be provided by an external application or by the user (e.g. tfDocumentName).
eVarUsage_Invalid	Invalid.

---

Function Documentation

ERRCODE TFormer_Exit

(

HTFORM

pInstance

)

Frees system resources previously allocated with TFormer_Init.

Frees system resources allocated by TFormer_Init. Call this function before exiting your application or if TFORMer SDK should be unloaded from memory. After this call the TFORMer SDK must be initialized again (with TFormer_Init) before using it.

Returns:

ErrOk (0) in case of success, non-zero if an error occurred

Parameters:

pInstance

The instance provided by a previous call to TFormer_Init

Note:

It is not required to call this function after each print-job.

See also:

TFormer_Init

HTFORM TFormer_Init

(

HTFRepository

hRepository

)

Allocates and initializes internal memory.

This function must be called after loading the TFORMer library. All other calls to the library must be performed after TFormer_Init. Each thread of your application (if multi-threaded) must call TFormer_Init and must use the returned handle for subsequent calls.

Returns:

Non-zero if successful, NULL if an error occurred

Parameters:

hRepository

Provide NULL in all cases. This parameter is used internally by TEC-IT to provide a handle to an already opened Repository.

Note:

Do not use the same handle from within different threads of your application.

Do not forget to free allocated memory by calling TFormer_Exit.

See also:

TFormer_Exit

void TFormer_License	(	LPCSTR	pszLicensee,
		DWORD	dwKind,
		LONG	nLicenses,
		LPCSTR	pszLicenseKey
	)

License this TFORMer SDK instance.

The licensing method needs to be called prior to any call generating output (e.g. TFormer_Print). It is recommended to call this method once immediately after loading the TFORMer SDK. You will receive the license information from TEC-IT Datenverarbeitung GmbH after ordering (https://www.tec-it.com/order). All license values must be specified exactly as received from TEC-IT. The license kind, the number of licenses and the licensee string are checked against the license key.

Returns:

always returns ErrOk (0) - even if the license key is invalid

Parameters:

pszLicensee	Licensee name (provided by TEC-IT)
dwKind	License kind (provided by TEC-IT)
nLicenses	Number of licenses (provided by TEC-IT)
pszLicenseKey	License key (provided by TEC-IT)

See also:

Refer to Licensing TFORMer for more information on licensing.