Access and modify Repositories or stand-alone FormLayouts. More...

Functions
ERRCODE	TFormer_AddNewProject (HTFORM pInstance, LPCSTR pszProjectName, LPCSTR pszProjectDesc)
	Creates and adds a new Project to the Repository.
ERRCODE	TFormer_DeleteProject (HTFORM pInstance, LPCSTR pszProjectName)
	Deletes a Project from the Repository.
ERRCODE	TFormer_AddNewForm (HTFORM pInstance, LPCSTR pszProjectName, LPCSTR pszFormName, LPCSTR pszFormDesc, LPCSTR pszFormDesign, LPCSTR pszFormFile)
	Adds a new Form to the given Project.
ERRCODE	TFormer_DeleteForm (HTFORM pInstance, LPCSTR pszProjectName, LPCSTR pszFormName)
	Deletes a FormLayout from the specified Project.
ERRCODE	TFormer_AddNewVar (HTFORM pInstance, LPCSTR pszProjectName, LPCSTR pszVarName, EVarType eVType)
	Adds a new DataField to the specified Project.
ERRCODE	TFormer_DeleteVar (HTFORM pInstance, LPCSTR pszProjectName, LPCSTR pszVarName)
	Deletes a DataField from the specified Project.
HPROJECT_ITERATOR	TFormer_GetFirstProjectIt (HTFORM pInstance, ERRCODE *peCode)
	Creates a new iterator and sets its position to the first Project within the Repository.
ERRCODE	TFormer_GetNextProjectIt (HPROJECT_ITERATOR hProjectIt)
	Moves the iterator to the next Project within the Repository.
LPCSTR	TFormer_ProjectItGetName (HPROJECT_ITERATOR hProjectIt, ERRCODE *peCode)
	Returns the name of the Project the iterator is pointing to.
LPCSTR	TFormer_ProjectItGetDescription (HPROJECT_ITERATOR hProjectIt, ERRCODE *peCode)
	Returns the description of the Project the iterator is pointing to.
void	TFormer_FreeProjectIt (HPROJECT_ITERATOR hProjectIt)
	Releases the Project iterator and frees any resources associated with it.
HFORM_ITERATOR	TFormer_GetFirstFormIt (HTFORM pInstance, LPCSTR pszProjectName, ERRCODE *peCode)
	Returns an iterator pointing to the first FormLayout in the specified Project.
ERRCODE	TFormer_GetNextFormIt (HFORM_ITERATOR hFormIt)
	Move the iterator to the next FormLayout within the Project.
LPCSTR	TFormer_FormItGetName (HFORM_ITERATOR hFormIt, ERRCODE *peCode)
	Returns the name of the FormLayout the iterator is pointing to.
LPCSTR	TFormer_FormItGetDescription (HFORM_ITERATOR hFormIt, ERRCODE *peCode)
	Returns the description of the FormLayout the iterator is pointing to.
void	TFormer_FreeFormIt (HFORM_ITERATOR hFormIt)
	Releases the FormLayout iterator and frees any resources associated with it.
HPROJECTVAR_ITERATOR	TFormer_GetFirstProjectVarIt (HTFORM pInstance, LPCSTR pszProjectName, ERRCODE *peCode)
	Returns an iterator pointing to the first DataField in the specified Project.
ERRCODE	TFormer_GetNextProjectVarIt (HPROJECTVAR_ITERATOR hProjectVarIt)
	Move the iterator to the next DataField within the Project.
LPCSTR	TFormer_ProjectVarItGetDetails (HPROJECTVAR_ITERATOR hProjectVarIt, ETFDataFormat eTFDataFormat, ERRCODE *peCode)
	Returns the details of DataField the iterator is pointing to.
LPCSTR	TFormer_ProjectVarItGetName (HPROJECTVAR_ITERATOR hProjectVarIt, ERRCODE *peCode)
	Returns the name of the DataField the iterator is pointing to.
LPCSTR	TFormer_ProjectVarItGetDescription (HPROJECTVAR_ITERATOR hProjectVarIt, ERRCODE *peCode)
	Returns the description of the DataField the iterator is pointing to.
LPCSTR	TFormer_ProjectVarItGetComment (HPROJECTVAR_ITERATOR hProjectVarIt, ERRCODE *peCode)
	Returns the comment of the DataField the iterator is pointing to.
LPCSTR	TFormer_ProjectVarItGetCaption (HPROJECTVAR_ITERATOR hProjectVarIt, ERRCODE *peCode)
	Returns the caption of the DataField the iterator is pointing to.
LPCSTR	TFormer_ProjectVarItGetDisplayOrder (HPROJECTVAR_ITERATOR hProjectVarIt, ERRCODE *peCode)
	Returns the display-order of the DataField the iterator is pointing to.
void	TFormer_FreeProjectVarIt (HPROJECTVAR_ITERATOR hProjectVarIt)
	Releases the DataField iterator and frees any resources associated with it.
LPCSTR	TFormer_ProjectVarItGetDefValue (HPROJECTVAR_ITERATOR hProjectVarIt, ERRCODE *peCode)
	Returns the default-value of the DataField the iterator is pointing to.
EVarType	TFormer_ProjectVarItGetType (HPROJECTVAR_ITERATOR hProjectVarIt, ERRCODE *peCode)
	Returns the data-type of the DataField the iterator is pointing to.
EVarUsage	TFormer_ProjectVarItGetUsage (HTFORM pInstance, HPROJECTVAR_ITERATOR hProjectVarIt, ERRCODE *peCode)
	Returns the usage of the DataField specified by an iterator.
EVarUsage	TFormer_GetVarUsage (HTFORM pInstance, LPCSTR pszVarName, ERRCODE *peCode)
	Retrieves the usage of the DataField specified by its name.
HDATASOURCE_ITERATOR	TFormer_GetFirstDatasourceIt (HTFORM pInstance, LPCSTR pszProjectName, ERRCODE *peCode)
	Returns an iterator pointing to the first DataSource in the specified Project.
ERRCODE	TFormer_GetNextDatasourceIt (HDATASOURCE_ITERATOR hDatasourceIt)
	Move the iterator to the next DataSource within the Project.
LPCSTR	TFormer_DatasourceItGetName (HDATASOURCE_ITERATOR hDatasourceIt, ERRCODE *peCode)
	Returns the name of the DataSource the iterator is pointing to.
LPCSTR	TFormer_DatasourceItGetDescription (HDATASOURCE_ITERATOR hDatasourceIt, ERRCODE *peCode)
	Returns the description of the DataSource the iterator is pointing to.
void	TFormer_FreeDatasourceIt (HDATASOURCE_ITERATOR hDatasourceIt)
	Releases the DataSource iterator and frees any resources associated with it.
HDSPARAMETER_ITERATOR	TFormer_GetFirstDSParameterIt (HTFORM pInstance, LPCSTR pszProjectName, LPCSTR pszDatasourceName, ERRCODE *peCode)
	Returns an iterator pointing to the first DataSourceParameter of the specified DataSource in the specified Project.
ERRCODE	TFormer_GetNextDSParameterIt (HDSPARAMETER_ITERATOR hIt)
	Move the iterator to the next DataSourceParameter within the DataSource.
LPCSTR	TFormer_DSParameterItGetName (HDSPARAMETER_ITERATOR hIt, ERRCODE *peCode)
	Returns the name of the DataSourceParameter the iterator is pointing to.
LPCSTR	TFormer_DSParameterItGetDescription (HDSPARAMETER_ITERATOR hIt, ERRCODE *peCode)
	Returns the description of the DataSourceParameter the iterator is pointing to.
LPCSTR	TFormer_DSParameterItGetCaption (HDSPARAMETER_ITERATOR hIt, ERRCODE *peCode)
	Returns the caption of the DataSourceParameter the iterator is pointing to.
LPCSTR	TFormer_DSParameterItGetDisplayOrder (HDSPARAMETER_ITERATOR hIt, ERRCODE *peCode)
	Returns the display-order of the DataSourceParameter the iterator is pointing to.
LPCSTR	TFormer_DSParameterItGetDefValue (HDSPARAMETER_ITERATOR hIt, ERRCODE *peCode)
	Returns the default-value of the DataSourceParameter the iterator is pointing to.
void	TFormer_FreeDSParameterIt (HDSPARAMETER_ITERATOR hIt)
	Releases the DataSourceParameter iterator and frees any resources associated with it.

Detailed Description

Access and modify Repositories or stand-alone FormLayouts.

Overview

A Repository is represented by a master file (extension *.tfr) and a subfolder structure on the file system. It references an arbitrary number of user-defined Project objects. These user-defined Projects are used to divide a Repository into logical areas. Each Project is a container which holds DataField definitions, DataSource definitions and references an arbitrary number of FormLayout objects.

The so-called GlobalProject is allocated by default and is exclusively used to define DataFields which are available for all FormLayouts regardless of their actual Project membership.

Note:: In contrast to a stand-alone FormLayout, the GlobalProject of a Repository can not store references to a FormLayout.

Examples

To open a stand-alone FormLayout do the following:

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

To open a Repository do the following:

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

Function Documentation

ERRCODE TFormer_AddNewForm	(	HTFORM	pInstance,
		LPCSTR	pszProjectName,
		LPCSTR	pszFormName,
		LPCSTR	pszFormDesc,
		LPCSTR	pszFormDesign,
		LPCSTR	pszFormFile
	)

Adds a new Form to the given Project.

Adds a new FormLayout to the Project specified by pszProjectName and creates the corresponding Project file. If pszFormFile is empty, this function creates an empty FormLayout. The name of the FormLayout must follow the Naming Rules.

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

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
pszProjectName	The name of the Project in the Repository.
pszFormName	The name of the FormLayout to be created.
pszFormDesc	The (optional) description of the FormLayout, may be empty or `NULL`
pszFormDesign	Design tool for editing this FormLayout (not used anymore).
pszFormFile	Template file for new FormLayout (optional).

ERRCODE TFormer_AddNewProject	(	HTFORM	pInstance,
		LPCSTR	pszProjectName,
		LPCSTR	pszProjectDesc
	)

Creates and adds a new Project to the Repository.

The Project-name must follow the Naming Rules.

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

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
pszProjectName	The name of the Project to be created
pszProjectDesc	The description of the Project, may be empty or `NULL`

Note:: For a stand-alone FormLayout this function is not available.

ERRCODE TFormer_AddNewVar	(	HTFORM	pInstance,
		LPCSTR	pszProjectName,
		LPCSTR	pszVarName,
		EVarType	eVType
	)

Adds a new DataField to the specified Project.

If no Project is specified, the DataField will be added to the global Project.

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

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
pszProjectName	The name of the Project (may be `NULL` for global DataFields)
pszVarName	The name of the DataField to be added.
eVType	The data-type of the DataField.

LPCSTR TFormer_DatasourceItGetDescription	(	HDATASOURCE_ITERATOR	hDatasourceIt,
		ERRCODE *	peCode
	)

Returns the description of the DataSource the iterator is pointing to.

The DataSource description may be empty.

The returned pointer is for temporary use only!

Returns:: The description of the DataSource the iterator is pointing to. This description is only valid if peCode is ErrOk (0).

Parameters:

hDatasourceIt	DataSource iterator (see TFormer_GetFirstDatasourceIt)
peCode	Error code, `ErrOk` (0) in case of success

LPCSTR TFormer_DatasourceItGetName	(	HDATASOURCE_ITERATOR	hDatasourceIt,
		ERRCODE *	peCode
	)

Returns the name of the DataSource the iterator is pointing to.

The returned pointer is for temporary use only!

Returns:: The name of the DataSource the iterator is pointing to. This name is only valid if peCode is ErrOk (0).

Parameters:

hDatasourceIt	DataSource iterator (see TFormer_GetFirstDatasourceIt)
peCode	Error code, `ErrOk` (0) in case of success

ERRCODE TFormer_DeleteForm	(	HTFORM	pInstance,
		LPCSTR	pszProjectName,
		LPCSTR	pszFormName
	)

Deletes a FormLayout from the specified Project.

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

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
pszProjectName	The name of the Project
pszFormName	The name of the FormLayout to be deleted

ERRCODE TFormer_DeleteProject	(	HTFORM	pInstance,
		LPCSTR	pszProjectName
	)

Deletes a Project from the Repository.

Deletes the Project as well as all DataFields and FormLayouts belonging to this Project from a Repository.

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

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
pszProjectName	The name of the Project to be deleted

Note:: Please note that this function does not delete files for a FormLayout (*.xmd), data-files (*.xml) or any subdirectories from the file-system. This function only modifies the Repository file itself.

ERRCODE TFormer_DeleteVar	(	HTFORM	pInstance,
		LPCSTR	pszProjectName,
		LPCSTR	pszVarName
	)

Deletes a DataField from the specified Project.

If no Project is specified, the DataField will be removed from the global Project.

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

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
pszProjectName	The name of the Project (may be `NULL` for global DataFields)
pszVarName	The name of the DataField to be deleted

Note:: Deleting a DataField which is still in use by FormLayouts will make these FormLayouts unusable!

LPCSTR TFormer_DSParameterItGetCaption	(	HDSPARAMETER_ITERATOR	hIt,
		ERRCODE *	peCode
	)

Returns the caption of the DataSourceParameter the iterator is pointing to.

The caption is only used for informational purposes and for providing the end-user additional information describing the purpose of the DataSourceParameter.

The returned pointer is for temporary use only!

Returns:: The caption of the DataSourceParameter the iterator is pointing to. This caption is only valid if peCode is ErrOk (0).

Parameters:

hIt	DataSource parameter iterator (see TFormer_GetFirstDSParameterIt)
peCode	Error code, `ErrOk` (0) in case of success

LPCSTR TFormer_DSParameterItGetDefValue	(	HDSPARAMETER_ITERATOR	hIt,
		ERRCODE *	peCode
	)

Returns the default-value of the DataSourceParameter the iterator is pointing to.

The returned pointer is for temporary use only!

Returns:: The default value of the DataSourceParameter the iterator is pointing to. This value is only valid if peCode is ErrOk (0).

Parameters:

hIt	DataSource parameter iterator (see TFormer_GetFirstDSParameterIt)
peCode	Error code, `ErrOk` (0) in case of success

LPCSTR TFormer_DSParameterItGetDescription	(	HDSPARAMETER_ITERATOR	hIt,
		ERRCODE *	peCode
	)

Returns the description of the DataSourceParameter the iterator is pointing to.

The description is only used for informational purposes and for providing the end-user additional information describing the purpose of the DataSourceParameter.

The returned pointer is for temporary use only!

Returns:: The description of the DataSourceParameter the iterator is pointing to. This description is only valid if peCode is ErrOk (0).

Parameters:

hIt	DataSource parameter iterator (see TFormer_GetFirstDSParameterIt)
peCode	Error code, `ErrOk` (0) in case of success

LPCSTR TFormer_DSParameterItGetDisplayOrder	(	HDSPARAMETER_ITERATOR	hIt,
		ERRCODE *	peCode
	)

Returns the display-order of the DataSourceParameter the iterator is pointing to.

This value is used for assigning a display-order to a DataSourceParameter. A good example is an application which presents a sorted list of DataSourceParameters to the user.

The returned pointer is for temporary use only!

Returns:: The display-order of the DataSourceParameter the iterator is pointing to. The display-order is only valid if peCode is ErrOk (0).

Parameters:

hIt	DataSource parameter iterator (see TFormer_GetFirstDSParameterIt)
peCode	Error code, `ErrOk` (0) in case of success

LPCSTR TFormer_DSParameterItGetName	(	HDSPARAMETER_ITERATOR	hIt,
		ERRCODE *	peCode
	)

Returns the name of the DataSourceParameter the iterator is pointing to.

The returned pointer is for temporary use only!

Returns:: The name of the DataSourceParameter the iterator is pointing to. This name is only valid if peCode is ErrOk (0).

Parameters:

hIt	DataSource parameter iterator (see TFormer_GetFirstDSParameterIt)
peCode	Error code, `ErrOk` (0) in case of success

LPCSTR TFormer_FormItGetDescription	(	HFORM_ITERATOR	hFormIt,
		ERRCODE *	peCode
	)

Returns the description of the FormLayout the iterator is pointing to.

The FormLayout description may be empty.

The returned pointer is for temporary use only!

Returns:: The description of the FormLayout the iterator is pointing to. This description is only valid if peCode is ErrOk (0).

Parameters:

hFormIt	FormLayout iterator (see TFormer_GetFirstFormIt)
peCode	Error code, `ErrOk` (0) in case of success

LPCSTR TFormer_FormItGetName	(	HFORM_ITERATOR	hFormIt,
		ERRCODE *	peCode
	)

Returns the name of the FormLayout the iterator is pointing to.

The returned pointer is for temporary use only!

Returns:: The name of the FormLayout the iterator is pointing to. This name is only valid if peCode is ErrOk (0).

Parameters:

hFormIt	FormLayout iterator (see TFormer_GetFirstFormIt)
peCode	Error code, `ErrOk` (0) in case of success

void TFormer_FreeDatasourceIt ( HDATASOURCE_ITERATOR hDatasourceIt )

Releases the DataSource iterator and frees any resources associated with it.

Parameters:

hDatasourceIt DataSource iterator (see TFormer_GetFirstDatasourceIt)

Note:: Release the iterator after use! Memory leaks may occur otherwise.

void TFormer_FreeDSParameterIt ( HDSPARAMETER_ITERATOR hIt )

Releases the DataSourceParameter iterator and frees any resources associated with it.

Parameters:

hIt	DataSourceParameter iterator (see TFormer_GetFirstDSParameterIt)

Note:: Release the iterator after use! Memory leaks may occur otherwise.

void TFormer_FreeFormIt ( HFORM_ITERATOR hFormIt )

Releases the FormLayout iterator and frees any resources associated with it.

Parameters:

hFormIt FormLayout iterator (see TFormer_GetFirstFormIt)

Note:: Release the iterator after use! Memory leaks may occur otherwise.

void TFormer_FreeProjectIt ( HPROJECT_ITERATOR hProjectIt )

Releases the Project iterator and frees any resources associated with it.

Parameters:

hProjectIt Project iterator (see TFormer_GetFirstProjectIt)

Note:: Release the iterator after use! Memory leaks may occur otherwise.

void TFormer_FreeProjectVarIt ( HPROJECTVAR_ITERATOR hProjectVarIt )

Releases the DataField iterator and frees any resources associated with it.

Parameters:

hProjectVarIt DataField iterator (see TFormer_GetFirstProjectVarIt)

Note:: Release the iterator after use! Memory leaks may occur otherwise.

HDATASOURCE_ITERATOR TFormer_GetFirstDatasourceIt	(	HTFORM	pInstance,
		LPCSTR	pszProjectName,
		ERRCODE *	peCode
	)

Returns an iterator pointing to the first DataSource in the specified Project.

Creates a new DataSource iterator and sets its position to the first DataSource in the Project specified by pszProjectName. To get the name of the DataSource call TFormer_DatasourceItGetName.

Returns:: Iterator in case of success, NULL in case of an error (check peCode in this case)

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
pszProjectName	The name of the Project within the Repository.
peCode	Error code, `ErrOk` (0) in case of success

Note:: Release the iterator after use with TFormer_FreeDatasourceIt ! Memory leaks may occur otherwise.

HDSPARAMETER_ITERATOR TFormer_GetFirstDSParameterIt	(	HTFORM	pInstance,
		LPCSTR	pszProjectName,
		LPCSTR	pszDatasourceName,
		ERRCODE *	peCode
	)

Returns an iterator pointing to the first DataSourceParameter of the specified DataSource in the specified Project.

Creates a new DataSourceParameter iterator and sets its position to the first DataSourceParameter in the DataSource specified by pszDatasourceName. To enumerate DataSourceParameters of a global DataSource, set pszProjectName to NULL or an empty string. To retrieve the name of the DataSourceParameter call TFormer_DSParameterItGetName.

Returns:: Iterator in case of success, NULL in case of an error (check peCode in this case)

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
pszProjectName	The name of the Project within the Repository.
pszDatasourceName	The name of the DataSource within the Project.
peCode	Error code, `ErrOk` (0) in case of success

Note:: Release the iterator after use with TFormer_FreeDSParameterIt! Memory leaks may occur otherwise.

See also:: TFormer_GetNextDSParameterIt

HFORM_ITERATOR TFormer_GetFirstFormIt	(	HTFORM	pInstance,
		LPCSTR	pszProjectName,
		ERRCODE *	peCode
	)

Returns an iterator pointing to the first FormLayout in the specified Project.

Creates a new FormLayout iterator and sets its position to the first FormLayout in the Project specified by pszProjectName. To get the name of the FormLayout call TFormer_FormItGetName.

Returns:: Iterator in case of success, NULL in case of an error (check peCode in this case)

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
pszProjectName	The name of the Project within the Repository.
peCode	Error code, `ErrOk` (0) in case of success

Note:: Release the iterator after use with TFormer_FreeFormIt! Memory leaks may occur otherwise.

HPROJECT_ITERATOR TFormer_GetFirstProjectIt	(	HTFORM	pInstance,
		ERRCODE *	peCode
	)

Creates a new iterator and sets its position to the first Project within the Repository.

This function is used for enumerating Projects within the actual Repository. It returns an iterator and sets its position to the first Project. Use TFormer_ProjectItGetName and TFormer_ProjectItGetDescription to retrieve the name and description of the actual Project.

Returns:: Iterator in case of success, NULL in case of an error (check peCode in this case)

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
peCode	Error code, `ErrOk` (0) in case of success

Note:: Release the iterator after use with TFormer_FreeProjectIt! Memory leaks may occur otherwise.

HPROJECTVAR_ITERATOR TFormer_GetFirstProjectVarIt	(	HTFORM	pInstance,
		LPCSTR	pszProjectName,
		ERRCODE *	peCode
	)

Returns an iterator pointing to the first DataField in the specified Project.

Creates a new DataField iterator and sets its position to the first DataField in the Project specified by pszProjectName. If pszProjectName is NULL or empty the DataField of the global Project are iterated. To get the name of the DataField call TFormer_ProjectVarItGetName.

Returns:: Iterator in case of success, NULL in case of an error (check peCode in this case)

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
pszProjectName	The name of the Project within the Repository.
peCode	Error code, `ErrOk` (0) in case of success

Note:: Release the iterator after use with TFormer_FreeProjectVarIt! Memory leaks may occur otherwise.

This example iterates all DataFields within the global Project.

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

See also:: TFormer_GetNextProjectVarIt, TFormer_ProjectVarItGetUsage

ERRCODE TFormer_GetNextDatasourceIt ( HDATASOURCE_ITERATOR hDatasourceIt )

Move the iterator to the next DataSource within the Project.

This function is used for enumerating data sources within a Project. Use TFormer_DatasourceItGetName and TFormer_DatasourceItGetDescription to retrieve the name and description of the actual DataSource.

Returns:: ErrOk (0) if iterator was moved to the next DataSource, non-zero if an error occurred or there are no more data sources in the Project

Parameters:

hDatasourceIt DataSource iterator (see TFormer_GetFirstDatasourceIt)

Note:: Release the iterator after use with TFormer_FreeDatasourceIt ! Memory leaks may occur otherwise.

ERRCODE TFormer_GetNextDSParameterIt ( HDSPARAMETER_ITERATOR hIt )

Move the iterator to the next DataSourceParameter within the DataSource.

This function is used for enumerating DataSourceParameters within a DataSource. Use TFormer_DSParameterItGetName and TFormer_DSParameterItGetDescription to retrieve the name and description of the DataSourceParameter.

Returns:: ErrOk (0) if the iterator was moved to the next DataSourceParameter, non-zero if an error occurred or there are no more DataSourceParameters in the DataSource

Parameters:

hIt	DataSource parameter iterator (see TFormer_GetFirstDSParameterIt)

Note:: Release the iterator after use with TFormer_FreeDSParameterIt! Memory leaks may occur otherwise.

See also:: TFormer_GetFirstDSParameterIt

ERRCODE TFormer_GetNextFormIt ( HFORM_ITERATOR hFormIt )

Move the iterator to the next FormLayout within the Project.

This function is used for enumerating FormLayouts within a Project. Use TFormer_FormItGetName and TFormer_FormItGetDescription to retrieve the name and description of the actual FormLayout.

Returns:: ErrOk (0) if iterator was moved to the next FormLayout, non-zero if an error occurred or there are no more FormLayouts in the Project

Parameters:

hFormIt FormLayout iterator (see TFormer_GetFirstFormIt)

Note:: Release the iterator after use with TFormer_FreeFormIt! Memory leaks may occur otherwise.

ERRCODE TFormer_GetNextProjectIt ( HPROJECT_ITERATOR hProjectIt )

Moves the iterator to the next Project within the Repository.

This function is used for enumerating Projects within the actual Repository. Use TFormer_ProjectItGetName and TFormer_ProjectItGetDescription to retrieve the name and description of the actual Project.

Returns:: ErrOk (0) in iterator was moved to next Project, non-zero if an error occurred or there are no more Projects

Parameters:

hProjectIt Project iterator (see TFormer_GetFirstProjectIt)

Note:: Release the iterator after use with TFormer_FreeProjectIt! Memory leaks may occur otherwise.

ERRCODE TFormer_GetNextProjectVarIt ( HPROJECTVAR_ITERATOR hProjectVarIt )

Move the iterator to the next DataField within the Project.

This function is used for enumerating DataFields within a Project. Use TFormer_ProjectVarItGetName and TFormer_ProjectVarItGetDescription to retrieve the name and description of the DataField.

Returns:: ErrOk (0) if iterator was moved to the next DataField, non-zero if an error occurred or there are no more DataFields in the Project

Parameters:

hProjectVarIt DataField iterator (see TFormer_GetFirstProjectVarIt)

Note:: Release the iterator after use with TFormer_FreeProjectVarIt! Memory leaks may occur otherwise.

See also:: TFormer_GetFirstProjectVarIt, TFormer_ProjectVarItGetUsage

EVarUsage TFormer_GetVarUsage	(	HTFORM	pInstance,
		LPCSTR	pszVarName,
		ERRCODE *	peCode
	)

Retrieves the usage of the DataField specified by its name.

A FormLayout utilizes user- or system DataFields as place-holders for dynamic data. Values for such DataFields are usually provided by the user (entered manually in TFORMer Designer) or imported from a DataSource. Each DataField can be used on its own, as part of expressions (e.g. in a text- or bar-code element) or it may be computed within the FormLayout itself (e.g. pre- and post-expressions). This method queries the FormLayout and returns an enumeration (see EVarUsage) regarding the use of a specific DataField in the FormLayout.

Returns:: The usage of the DataField in the current FormLayout. This value is only valid if peCode is ErrOk (0).

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
pszVarName	The name of the DataField
peCode	Error code, `ErrOk` (0) in case of success

See also:: DataField

Sample: To query all DataField-objects within a stand-alone FormLayout refer to the code below. The same principle can be used for a Repository-based FormLayout.

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

LPCSTR TFormer_ProjectItGetDescription	(	HPROJECT_ITERATOR	hProjectIt,
		ERRCODE *	peCode
	)

Returns the description of the Project the iterator is pointing to.

The Project description may be empty.

The returned pointer is for temporary use only!

Returns:: The description of the Project the iterator is pointing to. This description is only valid if peCode is ErrOk (0).

Parameters:

hProjectIt	Project iterator (see TFormer_GetFirstProjectIt)
peCode	Error code, `ErrOk` (0) in case of success

LPCSTR TFormer_ProjectItGetName	(	HPROJECT_ITERATOR	hProjectIt,
		ERRCODE *	peCode
	)

Returns the name of the Project the iterator is pointing to.

The returned pointer is for temporary use only!

Returns:: The name of the Project the iterator is pointing to. This name is only valid if peCode is ErrOk (0).

Parameters:

hProjectIt	Project iterator (see TFormer_GetFirstProjectIt)
peCode	Error code, `ErrOk` (0) in case of success

LPCSTR TFormer_ProjectVarItGetCaption	(	HPROJECTVAR_ITERATOR	hProjectVarIt,
		ERRCODE *	peCode
	)

Returns the caption of the DataField the iterator is pointing to.

The caption is only used for informational purposes and for providing the end-user additional information describing the purpose of the DataField.

The returned pointer is for temporary use only!

Returns:: The caption of the DataField the iterator is pointing to. This caption is only valid if peCode is ErrOk (0).

Parameters:

hProjectVarIt	DataField iterator (see TFormer_GetFirstProjectVarIt)
peCode	Error code, `ErrOk` (0) in case of success

LPCSTR TFormer_ProjectVarItGetComment	(	HPROJECTVAR_ITERATOR	hProjectVarIt,
		ERRCODE *	peCode
	)

Returns the comment of the DataField the iterator is pointing to.

The comment is only used for informational purposes and for providing the end-user additional information describing the purpose of the DataField.

The returned pointer is for temporary use only!

Returns:: The comment of the DataField the iterator is pointing to. This comment is only valid if peCode is ErrOk (0).

Parameters:

hProjectVarIt	DataField iterator (see TFormer_GetFirstProjectVarIt)
peCode	Error code, `ErrOk` (0) in case of success

LPCSTR TFormer_ProjectVarItGetDefValue	(	HPROJECTVAR_ITERATOR	hProjectVarIt,
		ERRCODE *	peCode
	)

Returns the default-value of the DataField the iterator is pointing to.

The default value is the standard-value of a DataField when creating data manually or automatically within TFORMer Designer. The default value is only used by TFORMer Designer. When a DataSource is used to pass data to TFORMer SDK and a DataField is not set by this DataSource the value of the DataField will be an empty string ("") or 0. See also TFormer_SetReuseValues.

The returned pointer is for temporary use only!

Returns:: The default value of the DataField the iterator is pointing to. This value is only valid if peCode is ErrOk (0).

Parameters:

hProjectVarIt	DataField iterator (see TFormer_GetFirstProjectVarIt)
peCode	Error code, `ErrOk` (0) in case of success

LPCSTR TFormer_ProjectVarItGetDescription	(	HPROJECTVAR_ITERATOR	hProjectVarIt,
		ERRCODE *	peCode
	)

Returns the description of the DataField the iterator is pointing to.

The description is only used for informational purposes and for providing the end-user additional information describing the purpose of the DataField.

The returned pointer is for temporary use only!

Returns:: The description of the DataField the iterator is pointing to. This description is only valid if peCode is ErrOk (0).

Parameters:

hProjectVarIt	DataField iterator (see TFormer_GetFirstProjectVarIt)
peCode	Error code, `ErrOk` (0) in case of success

LPCSTR TFormer_ProjectVarItGetDetails	(	HPROJECTVAR_ITERATOR	hProjectVarIt,
		ETFDataFormat	eTFDataFormat,
		ERRCODE *	peCode
	)

Returns the details of DataField the iterator is pointing to.

The returned pointer is for temporary use only!

Returns:: The details of the DataField the iterator is pointing to. This returned value is only valid if peCode is ErrOk (0).

Parameters:

hProjectVarIt	DataField iterator (see TFormer_GetFirstProjectVarIt)
eTFDataFormat	Specifies the format of the data to be returned
peCode	Error code, `ErrOk` (0) in case of success

LPCSTR TFormer_ProjectVarItGetDisplayOrder	(	HPROJECTVAR_ITERATOR	hProjectVarIt,
		ERRCODE *	peCode
	)

Returns the display-order of the DataField the iterator is pointing to.

This value is used for assigning a display-order to a DataField. A good example is an application which presents a sorted list of DataFields to the user.

The returned pointer is for temporary use only!

Returns:: The display-order of the DataField the iterator is pointing to. The display-order is only valid if peCode is ErrOk (0).

Parameters:

hProjectVarIt	DataField iterator (see TFormer_GetFirstProjectVarIt)
peCode	Error code, `ErrOk` (0) in case of success

LPCSTR TFormer_ProjectVarItGetName	(	HPROJECTVAR_ITERATOR	hProjectVarIt,
		ERRCODE *	peCode
	)

Returns the name of the DataField the iterator is pointing to.

The caption is only used for informational purposes and for providing the end-user additional information describing the purpose of the DataField.

The returned pointer is for temporary use only!

Returns:: The name of the DataField the iterator is pointing to. This name is only valid if peCode is ErrOk (0).

Parameters:

hProjectVarIt	DataField iterator (see TFormer_GetFirstProjectVarIt)
peCode	Error code, `ErrOk` (0) in case of success

EVarType TFormer_ProjectVarItGetType	(	HPROJECTVAR_ITERATOR	hProjectVarIt,
		ERRCODE *	peCode
	)

Returns the data-type of the DataField the iterator is pointing to.

Returns:: The data-type of the DataField the iterator is pointing to. This value is only valid if peCode is ErrOk (0).

Parameters:

hProjectVarIt	DataField iterator (see TFormer_GetFirstProjectVarIt)
peCode	Error code, `ErrOk` (0) in case of success

EVarUsage TFormer_ProjectVarItGetUsage	(	HTFORM	pInstance,
		HPROJECTVAR_ITERATOR	hProjectVarIt,
		ERRCODE *	peCode
	)

Returns the usage of the DataField specified by an iterator.

A FormLayout utilizes user- or system DataFields as place-holders for dynamic data. Values for such DataFields are usually provided by the user (entered manually in TFORMer Designer) or imported from a DataSource. Each DataField can be used on its own, as part of expressions (e.g. in a text- or bar-code element) or it may be computed within the FormLayout itself (e.g. pre- and post-expressions). This method queries the FormLayout and returns an enumeration (see EVarUsage) regarding the use of a specific DataField in the FormLayout.

Returns:: The usage of the DataField in the current FormLayout. This value is only valid if peCode is ErrOk (0).

Parameters:

pInstance	The TFORMer instance provided by a previous call to TFormer_Init
hProjectVarIt	DataField iterator (see TFormer_GetFirstProjectVarIt)
peCode	Error code, `ErrOk` (0) in case of success

See also:: TFormer_GetFirstProjectVarIt, TFormer_GetNextProjectVarIt

© 2006-2021 - all rights reserved by TEC-IT Datenverarbeitung GmbH
Generated on Wed Nov 17 2021 12:13:03 for TFORMer SDK - DLL/Library with doxygen 1.7.6.1

Functions

Detailed Description

Overview

Examples

Function Documentation