DataSource

Overview

TFORMer Designer allows to define a DataSource as part of a FormLayout. Such an user-defined DataSource can be used for printing directly from within TFORmer Designer or may be re-used by TFORmer SDK for providing JobData (see JobDataDataSource).

A DataSource defines how data is retrieved (e.g. from an ODBC database), the field-mappings (see DataSource Field Mapping), computed fields (see ComputedField) and optional data source parameters (see DataSourceParameter). Each DataSource is identified by its unique name. Optional DataSourceParameters can be defined to control certain aspects (like filenames, SQL statement or an ODBC-DSN) during runtime.

By default TFORMer Designer creates a DataSource named _Default_. This DataSource is used for printing as long as neither a DataSource is specified for JobData nor the FormLayout has an active DataSource set in design. This DataSource retrieves the data from the file that is stored along with the FormLayout file (extension .xml) and contains the DataField values entered during the last TFORMer Designer session.

The available DataSource-classes are DataSourceCsv, DataSourceOdbc and DataSourceXml.

Escape Sequences

It depends on TFormer_SetHandleEscapeSequences whether possible escape sequences in the values are translated into their corresponding binary representation. See Escape Sequences for details.

Record Copies

Each Record of a DataSource is usually considered exactly once for generating output. Use TFormer_SetImportFieldForRecordCopy to instruct TFORMer SDK to use a specific field of the DataSource which contains the copy counter. This feature is helpful whenever a single Record of a DataSource should be printed multiple times (e.g. if a certain number of identical labels should be printed).

Computed Fields

Computations can be centralized in the DataSource instead of performing the computations in the FormLayout. The result of a ComputedField is available in the DataSource like any other source-field.

Examples

Sample code that iterates all DataSource of a given Repository:

ERRCODE IterateDataSourcesProject (HTFORM hTForm, LPCSTR pszProjectName)
{
  ERRCODE               eCode             = ErrOk;
  HDATASOURCE_ITERATOR  itDataSource      = NULL;
  BOOL                  bDataSourceValid  = FALSE;
  LPCSTR                pszDataSourceName = NULL;
  HDSPARAMETER_ITERATOR itDSParam         = NULL;
  BOOL                  bDSParamValid     = FALSE;
  LPCSTR                pszDSParamName    = NULL;

  itDataSource      = TFormer_GetFirstDatasourceIt (hTForm, pszProjectName, &eCode);
  bDataSourceValid  = (itDataSource != NULL);  

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

  while (bDataSourceValid && eCode == ErrOk)
  {
    pszDataSourceName = TFormer_DatasourceItGetName (itDataSource, &eCode);

    if (pszDataSourceName != NULL && eCode == ErrOk)
      printf ("datasource name: '%s'\n", pszDataSourceName);

    // Print information for the DataSourceParameters of the DataSource
    if (eCode == ErrOk)
    {
      itDSParam     = TFormer_GetFirstDSParameterIt (hTForm, pszProjectName, pszDataSourceName, &eCode);
      bDSParamValid = (itDSParam != NULL);

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

      while (bDSParamValid && eCode == ErrOk)
      {
        pszDSParamName = TFormer_DSParameterItGetName (itDSParam, &eCode);
        if (pszDSParamName != NULL && eCode == ErrOk)
          printf ("  parameter name: '%s'\n", pszDSParamName);
        
        // retrieve next DSParam      
        bDSParamValid = (TFormer_GetNextDSParameterIt (itDSParam) == ErrOk);
      }

      TFormer_FreeDSParameterIt (itDSParam);    
    }
    
    // retrieve next DataSource    
    bDataSourceValid = (TFormer_GetNextDatasourceIt (itDataSource) == ErrOk);
  }

  TFormer_FreeDatasourceIt (itDataSource);
  
  return eCode;
}

  // Connect to a Repository (extension *.tfr)
  // Examples are usually installed in
  // - Windows Vista: C:/Program Data/TEC-IT/TFORMer/8/Examples
  // - Older Microsoft Windows versions: C:/Documents and Settings/All Users/Application Data/TEC-IT/TFORMer/8/Examples
  eCode = TFormer_SetRepositoryName   (hTForm, "C:/Documents and Settings/All Users/Application Data/TEC-IT/TFORMer/8/Examples/Demo Repository/Demos.tfr");

  ERRCODE           eCode           = ErrOk;
  HPROJECT_ITERATOR itProject       = NULL;
  BOOL              bProjectValid   = FALSE;
  LPCSTR            pszProjectName  = NULL;

  // Iterate the DataSources of the global Project
  // If a Repository is used, the global Project and additional user-defined Projects may exist
  printf ("Global project\n");
  eCode = IterateDataSourcesProject (hTForm, NULL);
  if (eCode != ErrOk)
    return eCode;

  // Iterate additional Projects
  // Additional Projects are only possible when using a Repository  
  itProject     = TFormer_GetFirstProjectIt (hTForm, &eCode);  
  bProjectValid = (itProject != NULL);

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

  while (bProjectValid && eCode == ErrOk)
  {
    pszProjectName = TFormer_ProjectItGetName (itProject, &eCode);

    if (pszProjectName != NULL && eCode == ErrOk)
    {
      printf ("project name: '%s'\n", pszProjectName);

      // Iterate the DataSources of the Project    
      eCode = IterateDataSourcesProject (hTForm, pszProjectName);
    }

    // Get the next Project    
    bProjectValid = (TFormer_GetNextProjectIt (itProject) == ErrOk);
  }

  TFormer_FreeProjectIt (itProject);    

Sample code that iterates all DataSource-objects of a given stand-alone FormLayout:

ERRCODE IterateDataSourcesProject (HTFORM hTForm, LPCSTR pszProjectName)
{
  ERRCODE               eCode             = ErrOk;
  HDATASOURCE_ITERATOR  itDataSource      = NULL;
  BOOL                  bDataSourceValid  = FALSE;
  LPCSTR                pszDataSourceName = NULL;
  HDSPARAMETER_ITERATOR itDSParam         = NULL;
  BOOL                  bDSParamValid     = FALSE;
  LPCSTR                pszDSParamName    = NULL;

  itDataSource      = TFormer_GetFirstDatasourceIt (hTForm, pszProjectName, &eCode);
  bDataSourceValid  = (itDataSource != NULL);  

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

  while (bDataSourceValid && eCode == ErrOk)
  {
    pszDataSourceName = TFormer_DatasourceItGetName (itDataSource, &eCode);

    if (pszDataSourceName != NULL && eCode == ErrOk)
      printf ("datasource name: '%s'\n", pszDataSourceName);

    // Print information for the DataSourceParameters of the DataSource
    if (eCode == ErrOk)
    {
      itDSParam     = TFormer_GetFirstDSParameterIt (hTForm, pszProjectName, pszDataSourceName, &eCode);
      bDSParamValid = (itDSParam != NULL);

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

      while (bDSParamValid && eCode == ErrOk)
      {
        pszDSParamName = TFormer_DSParameterItGetName (itDSParam, &eCode);
        if (pszDSParamName != NULL && eCode == ErrOk)
          printf ("  parameter name: '%s'\n", pszDSParamName);
        
        // retrieve next DSParam      
        bDSParamValid = (TFormer_GetNextDSParameterIt (itDSParam) == ErrOk);
      }

      TFormer_FreeDSParameterIt (itDSParam);    
    }
    
    // retrieve next DataSource    
    bDataSourceValid = (TFormer_GetNextDatasourceIt (itDataSource) == ErrOk);
  }

  TFormer_FreeDatasourceIt (itDataSource);
  
  return eCode;
}

  // Connect to a stand-alone FormLayout (extension *.tff)
  // Examples are usually installed in
  // - Windows Vista or later: C:/Program Data/TEC-IT/TFORMer/8/Examples
  // - Older Microsoft Windows versions: C:/Documents and Settings/All Users/Application Data/TEC-IT/TFORMer/8/Examples
  eCode = TFormer_SetRepositoryName   (hTForm, "C:/Documents and Settings/All Users/Application Data/TEC-IT/TFORMer/8/Examples/Command Line/ODBCReportPDF/ODBCReportPDF.tff");

  ERRCODE eCode = ErrOk;

  // Iterate the DataSources of the global Project
  // If a stand-alone FormLayout is used, the global Project is the only Project
  eCode = IterateDataSourcesProject (hTForm, NULL);

More Information

See also:

ComputedField

Related documentation:

• DataSourceCsv
• DataSourceXml
• DataSourceOdbc
• DataSourceParameter
• ComputedField
• DataSource Field Mapping