General

General functions which are mandatory for most applications.

Calling Convention

The Native C API functions and streaming callback are declared with __stdcall. On 32-bit Windows, match this calling convention when implementing a callback or declaring a foreign-language binding. On Linux/UNIX, the SDK headers define __stdcall as empty.

The license types for the TFORMer SDK (see TFormer_License).

#define LICKIND_WORKSTATION 1

Workstation license.

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

#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_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_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_SERVER 6

Server license.

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

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 data type.

• eVarType_Long
  An integer number. When reading a DataField of this type from a JobData it is converted automatically to an integer.

• 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.

• eVarType_Invalid
  Invalid, internal use only.

Numeric conversion is permissive and can ignore non-numeric characters. Validate numeric strings in your application if strict format checking is required.

Naming Conventions

A DataField name must begin with an ASCII letter (A to Z or a to z) or an underscore. The remaining characters may be ASCII letters, digits (0 to 9) or underscores. Spaces, tabs, hyphens, accented letters and other special characters are not allowed. See Naming Rules for naming rules and examples.

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

A validation rule is an expression that checks whether a DataField value meets a condition. Define the rule and its validation message in the FormLayout or Repository with TFORMer Designer (recommended). The native C API applies these stored definitions; it does not provide functions for editing validation rules or messages.

Validation rules are evaluated when records are read during output generation. If a rule is violated, the SDK reports an error and includes any configured validation message in the additional error information. Check the return code of TFormer_Print or TFormer_PrintToStream, then use TFormer_GetLastErrorInformation to retrieve the additional error information.

TFORMer Designer displays an error message for invalid data.

DataField Enumeration

To iterate through the available DataField objects, use TFormer_GetFirstProjectVarIt and TFormer_GetNextProjectVarIt.

To find a particular DataField, compare each name returned by TFormer_ProjectVarItGetName with the required name. Release the iterator with TFormer_FreeProjectVarIt after use.

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);

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).

enum EVarUsage

Describes the usage of a DataField within a FormLayout.

enum ETFDataFormat

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

XML)

#define ERRCODE LONG

Define the type for the error codes.

#define ErrOk S_OK

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

#define ERR_TF_LICENSE_EXPIRED 27019

Error code for "TFORMer license is expired".