Repository Access

This sample demonstrates functions to access or modify the information stored in a Repository.

#ifdef _WIN32
  #define TECIT_DLLIMPORT
  #include "TFormer.h"
  #undef  TECIT_DLLIMPORT
#else
  #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
#endif

//-------------------------------------------------------------------------------------------
// 
//-------------------------------------------------------------------------------------------
ERRCODE ConnectToStandAloneForm (HTFORM hTForm)
{
  ERRCODE eCode = ErrOk;

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

  return eCode;
}

//-------------------------------------------------------------------------------------------
// 
//-------------------------------------------------------------------------------------------
ERRCODE ConnectToRepository (HTFORM hTForm)
{
  ERRCODE eCode = ErrOk;

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

  return eCode;
}

//-------------------------------------------------------------------------------------------
// 
//-------------------------------------------------------------------------------------------
ERRCODE DataFieldUsageStandAloneForm (HTFORM hTForm)
{
  // A stand-alone FormLayout contains only the global Project, the global Project holds the FormLayout and all DataField definitions
  ERRCODE               eCode             = ErrOk;
  LPCSTR                pszProjectName    = NULL; // we want to iterate datafields of global Project
  HPROJECTVAR_ITERATOR  it                = NULL;
  LPCSTR                pszDataFieldName  = NULL;
  EVarUsage             eVarUsage         = eVarUsage_Invalid;
  BOOL                  bProjectVarValid  = FALSE;

  it                = TFormer_GetFirstProjectVarIt (hTForm, pszProjectName, &eCode);
  bProjectVarValid  = (it != NULL);

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

  // iterate all DataFields
  while (bProjectVarValid && eCode == ErrOk)
  {
    pszDataFieldName = TFormer_ProjectVarItGetName (it, &eCode);
    if (pszDataFieldName != NULL && eCode == ErrOk)
    {
      printf (pszDataFieldName);

      // Retrieve the usage of the DataFields in the FormLayout
      eVarUsage = TFormer_ProjectVarItGetUsage (hTForm, it, &eCode);
      switch (eVarUsage)
      { 
        case eVarUsage_Calculated: printf (" --> The value of this DataField is computed within the FormLayout"); break;
        case eVarUsage_Invalid   : printf (" --> Invalid usage - contact TEC-IT"); break;
        case eVarUsage_Normal    : printf (" --> The DataField is used within the FormLayout; its value can be set"); break;
        case eVarUsage_NotUsed   : printf (" --> This DataField is not used in this FormLayout"); break;
        case eVarUsage_Parameter : printf (" --> This is a system DataField (like the page number) used within the FormLayout"); break;
      }
      printf ("\n");
    }

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

  // release iterator
  TFormer_FreeProjectVarIt (it);

  return eCode;
}

//-------------------------------------------------------------------------------------------
// 
//-------------------------------------------------------------------------------------------
ERRCODE FetchFormLayoutStandAloneForm (HTFORM hTForm)
{
  ERRCODE         eCode             = ErrOk;
  HFORM_ITERATOR  itForm            = NULL;
  LPCSTR          pszFormDescription= NULL;
  BOOL            bFormValid        = FALSE;

  // Retrieve first form of the global Project   
  // A stand-alone FormLayout contains only the global Project, the global Project contains the FormLayout  
  LPCSTR          pszProjectName    = NULL; // use global project

  // Retrieve the first (and only) FormLayout
  itForm      = TFormer_GetFirstFormIt (hTForm, pszProjectName, &eCode);
  bFormValid  = (itForm != NULL);

  if (bFormValid && eCode == ErrOk)
  {
    pszFormDescription = TFormer_FormItGetDescription (itForm, &eCode);
    printf ("description: ");
    if (pszFormDescription != NULL && eCode == ErrOk)
      printf (pszFormDescription);
    printf ("\n");
  }    

  // release iterator
  TFormer_FreeFormIt (itForm);

  return eCode;
}

//-------------------------------------------------------------------------------------------
// 
//-------------------------------------------------------------------------------------------
ERRCODE IterateProjects (HTFORM hTForm)
{  
  ERRCODE           eCode           = ErrOk;
  HPROJECT_ITERATOR itProject       = NULL;
  LPCSTR            pszProjectName  = NULL;
  BOOL              bProjectValid   = FALSE;

  // Retrieve the first Project 
  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);

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

  TFormer_FreeProjectIt (itProject);  

  return eCode;
}

//-------------------------------------------------------------------------------------------
// 
//-------------------------------------------------------------------------------------------
ERRCODE IterateFormLayoutsRepository (HTFORM hTForm)
{
  ERRCODE           eCode           = ErrOk;
  HPROJECT_ITERATOR itProject       = NULL;
  BOOL              bProjectValid   = FALSE;
  LPCSTR            pszProjectName  = NULL;
  HFORM_ITERATOR    itForm          = NULL;
  BOOL              bFormValid      = FALSE;
  LPCSTR            pszFormName     = NULL;    

  // Retrieve the first Project 
  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);

      itForm    = TFormer_GetFirstFormIt (hTForm, pszProjectName, &eCode);
      bFormValid= (itForm != NULL);

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

      while (bFormValid && eCode == ErrOk)
      {
        pszFormName = TFormer_FormItGetName (itForm, &eCode);

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

        // Get the next FormLayout in this Project
        bFormValid = (TFormer_GetNextFormIt (itForm) == ErrOk);
      }

      TFormer_FreeFormIt (itForm);
    }

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

  TFormer_FreeProjectIt (itProject);  

  return eCode;
}

//-------------------------------------------------------------------------------------------
// 
//-------------------------------------------------------------------------------------------
ERRCODE IterateDataFieldsStandAloneForm (HTFORM hTForm)
{  
  ERRCODE               eCode             = ErrOk;
  LPCSTR                pszProjectName    = NULL; // we want to iterate datafields of global Project
  HPROJECTVAR_ITERATOR  it                = NULL;
  BOOL                  bProjectVarValid  = FALSE;
  EVarUsage             eVarUsage         = eVarUsage_Invalid;
  LPCSTR                pszDataFieldName  = NULL;

  it               = TFormer_GetFirstProjectVarIt (hTForm, pszProjectName, &eCode);
  bProjectVarValid = (it != NULL);

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

  // iterate all DataFields
  while (bProjectVarValid && (eCode == ErrOk))
  {
    // check, whether the DataField is editable
    eVarUsage = TFormer_ProjectVarItGetUsage (hTForm, it, &eCode);      
    if ((eVarUsage == eVarUsage_Normal) && (eCode == ErrOk))
    {
      // do something
      pszDataFieldName = TFormer_ProjectVarItGetName (it, &eCode);
      if (pszDataFieldName != NULL && eCode == ErrOk)
      {
        printf (pszDataFieldName);
        printf ("\n");
      }
    }

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

  // release iterator
  TFormer_FreeProjectVarIt (it);

  return eCode;
}

//-------------------------------------------------------------------------------------------
// 
//-------------------------------------------------------------------------------------------
void DataSourceOdbcModify ()
{
  // not supported by C API, included just for completeness
}

//-------------------------------------------------------------------------------------------
// 
//-------------------------------------------------------------------------------------------
void DataSourceCsvModify ()
{
  // not supported by C API, included just for completeness
}

//-------------------------------------------------------------------------------------------
// 
//-------------------------------------------------------------------------------------------
void DataSourceXmlModify ()
{
  // not supported by C API, included just for completeness
}

//-------------------------------------------------------------------------------------------
// 
//-------------------------------------------------------------------------------------------
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;
}

//-------------------------------------------------------------------------------------------
// 
//-------------------------------------------------------------------------------------------
ERRCODE IterateDataSources (HTFORM hTForm)
{  
  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);    

  return eCode;
}

//-------------------------------------------------------------------------------------------
// 
//-------------------------------------------------------------------------------------------
ERRCODE IterateDataSourcesStandAloneForm (HTFORM hTForm)
{  
  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);

  return eCode;
}

//-------------------------------------------------------------------------------------------
//
//-------------------------------------------------------------------------------------------
void ReportError (ERRCODE eCode, HTFORM hTForm, LPCSTR pszFunction)
{
  LPCSTR pszErrDescription = NULL;
  LPCSTR pszErrSource      = NULL;
  LPCSTR pszErrInformation = NULL;

  if (eCode == ErrOk)
    return;

  if (pszFunction)
    printf ("Error in %s\n", pszFunction);

  printf ("Error         : 0x%08x\n", eCode);

  if (hTForm)
  {  
    pszErrDescription   = TFormer_GetLastErrorDescription (hTForm);
    pszErrInformation   = TFormer_GetLastErrorInformation (hTForm);
    pszErrSource        = TFormer_GetLastErrorSource      (hTForm);

    if (pszErrDescription && pszErrDescription[0])
      printf("TFError       : %s\n", pszErrDescription);

    if (pszErrInformation && pszErrInformation[0])
      printf("TFInformation : %s\n", pszErrInformation);

    if (pszErrSource && pszErrSource[0])
      printf("TFSource      : %s\n", pszErrSource);
  }
}

//-------------------------------------------------------------------------------------------
// M A I N
//-------------------------------------------------------------------------------------------
// Call the various sample functions
//-------------------------------------------------------------------------------------------
void main ()
{
  ERRCODE eCode   = ErrOk;
  HTFORM  hTForm  = NULL;
  // Allocate memory and retrieve TFORMer handle 
  hTForm = TFormer_Init (NULL); 
  if (!hTForm)
    return;

  // Samples for stand-alone FormLayouts
  printf ("Stand-alone FormLayout samples\n");
  eCode = ConnectToStandAloneForm (hTForm);
  ReportError (eCode, hTForm, "ConnectToStandAloneForm");

  if (eCode == ErrOk)
  { 
    printf ("\nFetchFormLayout:\n");
    eCode = FetchFormLayoutStandAloneForm   (hTForm);
    ReportError (eCode, hTForm, "FetchFormLayoutStandAloneForm");

    printf ("\nDataFieldUsage:\n");
    eCode = DataFieldUsageStandAloneForm    (hTForm);
    ReportError (eCode, hTForm, "DataFieldUsageStandAloneForm");

    printf ("\nIterateDataFields:\n");
    eCode = IterateDataFieldsStandAloneForm (hTForm);
    ReportError (eCode, hTForm, "IterateDataFieldsStandAloneForm");

    printf ("\nIterateDataSources:\n");
    eCode = IterateDataSourcesStandAloneForm(hTForm);
    ReportError (eCode, hTForm, "IterateDataSourcesStandAloneForm");
  }

  // Samples for Repository files
  printf ("\n----------------------\nRepository samples\n");
  eCode = ConnectToRepository             (hTForm);
  ReportError (eCode, hTForm, "ConnectToRepository");
  if (eCode == ErrOk)
  {
    printf ("\nIterateProjects:\n");
    eCode = IterateProjects                 (hTForm);
    ReportError (eCode, hTForm, "IterateProjects");

    printf ("\nIterateFormLayoutsRepository:\n");
    eCode = IterateFormLayoutsRepository    (hTForm);
    ReportError (eCode, hTForm, "IterateFormLayoutsRepository");

    printf ("\nIterateDataSources:\n");
    eCode = IterateDataSources              (hTForm);
    ReportError (eCode, hTForm, "IterateDataSources");
  }

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