TFormer_GetVarUsage

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

EVarUsage TFormer_GetVarUsageW(HTFORM pInstance, LPCWSTR 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

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