Variables


Functions

Boolean_t TecUtilVarRename (EntIndex_t VarNum, const char *VarName)
  Rename a data set variable in Tecplot.
Boolean_t TecUtilVarIsSpatial (EntIndex_t Var)
  Test to see if a variable is spatial A spatial variable is X,Y, or Z in 3D, or X,Y in 2D.
Boolean_t TecUtilVariableIsLocked (EntIndex_t Var, VarLockMode_e *VarLockMode, char **LockOwner)
  Indicates if the variable is locked and optionally the mode in which it was locked and the current lock owner.
Boolean_t TecUtilVariableLockOn (EntIndex_t Var, VarLockMode_e VarLockMode, const char *LockOwner)
  Lock the variable from being altered according to the specified locking mode.
Boolean_t TecUtilVariableLockOff (EntIndex_t Var, const char *LockOwner)
  Unlock the variable.
void TecUtilVarGetMinMax (EntIndex_t Var, double *VarMin, double *VarMax)
  Gets the minimum and maximum values of a variable.
UniqueID_t TecUtilVarGetUniqueID (EntIndex_t Var)
  Gets a unique ID for a variable.
EntIndex_t TecUtilVarGetNumByUniqueID (UniqueID_t UniqueID)
  Gets a variable number, given a unique ID.
EntIndex_t TecUtilVarGetNumByAssignment (char Var)
  Gets the number (that is, the index) of a variable based on the variable assignment.
EntIndex_t TecUtilVarGetNumByName (const char *VarName)
  Gets the number (that is, the index) of a variable based on variable name.
VarStatus_e TecUtilVarGetStatus (EntIndex_t Zone, EntIndex_t Var)
  Gets the load status of a variable for a zone.
VarStatus_e TecUtilVarGetStatusByRef (FieldData_pa FieldData)
  Gets the load status of a variable for a zone.
Boolean_t TecUtilVarGetName (EntIndex_t VarNum, char **VName)
  Get the name of a variable in the data set attached to the current frame.
Boolean_t TecUtilVarGetEnabled (Set_pa *EnabledVars)
  Get the set of enabled variables.
Boolean_t TecUtilVarIsEnabled (EntIndex_t Var)
  Determine if a variable is enabled.

Function Documentation

Boolean_t TecUtilVarGetEnabled ( Set_pa *  EnabledVars  ) 

Get the set of enabled variables.

Variables are enabled/disabled when they are read in. There must be a data set attached to the current frame.

Parameters:
EnabledVars Set of enabled variables. Must not be NULL
Returns:
TRUE if successful, FALSE otherwise
Precondition:
Must have one or more frames.

EnabledVars Pointer must be a valid address and non-NULL.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilVarGetEnabled(EnabledVarsPtr)
    POINTER (EnabledVarsPtr, EnabledVars)

Python Syntax:

  Results = TecUtil.VarGetEnabled()

  Output:
    Results[0]    ReturnVal            boolean
    Results[1]    EnabledVars          sequence of ints

Get the set of enabled variables. It is assumed that a data set has been created:

   Set_pa set = NULL;
   TecUtilVarGetEnabled(&set);
   // Do something with set
   TecUtilSetDealloc(&set);

void TecUtilVarGetMinMax ( EntIndex_t  Var,
double *  VarMin,
double *  VarMax 
)

Gets the minimum and maximum values of a variable.

Parameters:
Var Index of the variable. Must be greater than zero and the variable must be enabled
VarMin Receives the minimum value of the variable. Must not be NULL
VarMax Receives the maximum value of the variable. Must not be NULL
Precondition:
Must have one or more frames.

Current frame must have a data set with at least one zone.

VarMin Pointer must be a valid address and non-NULL.

VarMax Pointer must be a valid address and non-NULL.

Fortran Syntax:
    SUBROUTINE TecUtilVarGetMinMax(
   &           Var,
   &           VarMin,
   &           VarMax)
    INTEGER*4       Var
    REAL*8          VarMin
    REAL*8          VarMax

Python Syntax:

  Results = TecUtil.VarGetMinMax(Var)

  Input:
                  Var                  int
  Output:
    Results[0]    VarMin               double
    Results[1]    VarMax               double

Get the minimum and maximum values of the first variable in a data set:

   double VarMin,VarMax;
   TecUtilVarGetMinMax(1,&VarMin,&VarMax);

Boolean_t TecUtilVarGetName ( EntIndex_t  VarNum,
char **  VName 
)

Get the name of a variable in the data set attached to the current frame.

There must be a data set attached to the current frame. This function is Thread Safe.

Parameters:
VarNum Number of the variable for which to get the variable name information. Must be greater than zero, and the variable must be enabled
VName Receives the name of the specified variable. Must not be NULL. You must free this string with TecUtilStringDealloc().
Returns:
TRUE if successful, FALSE if not.
Precondition:
Must have one or more frames.

Current frame must have a data set.

VarNum Must specify a valid variable.

VName Pointer must be a valid address and non-NULL.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilVarGetName(
   &                   VarNum,
   &                   VName,
   &                   VNameLength)
    INTEGER*4       VarNum
    CHARACTER*(*)   VName
    INTEGER*4       VNameLength

Python Syntax:

  Results = TecUtil.VarGetName(VarNum)

  Input:
                  VarNum               int
  Output:
    Results[0]    ReturnVal            boolean
    Results[1]    VName                string

Get the name of the first variable:

   char buffer[100];
   VarName_t Name;
   TecUtilVarGetName(1,&Name);
   sprintf(buffer,"The name of the first variable is %s",Name);
   TecUtilStringDealloc(&Name);

EntIndex_t TecUtilVarGetNumByAssignment ( char  Var  ) 

Gets the number (that is, the index) of a variable based on the variable assignment.

This function is Thread Safe.

Parameters:
Var Variable to get. The frame mode must be 2-D or 3-D.If the frame mode is 2-D, select one of 'X', 'Y', 'U', 'V', 'B', 'C', or 'S'.If the frame mode is 3-D, select one of 'X','Y','Z','U','V','W', 'B', 'C', or 'S'Table 0-1. Variable assignment identifiers (Var) and descriptions.
Var Description'X' X-axis variable'Y' Y-axis variable'Z' Z-axis variable'U' U-velocity variable'V' V-velocity variable'W' W-velocity variable'B' Blanking variable'C' Contouring variable'S' Scatter sizing variable
Returns:
The index (number) of the variable referenced by Var.
Precondition:
Must have one or more frames.

Current frame must have a data set.

If current frame's plot type is Sketch, Var must be 'B'.

If current frame's plot type is XY Line, Var must be 'B', 'X', or 'Y'.

If current frame's plot type is Polar Line, Var must be 'B', 'A', or 'R'.

If current frame's plot type is 2D Cartesian, Var must be one of 'X', 'Y', 'U', 'V', 'B', 'C', or 'S'.

If current frame's plot type is 3D Cartesian, Var must be one of 'X', 'Y', 'Z', 'U', 'V', 'W', 'B', 'C', or 'S'.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilVarGetNumByAssignment(Var)
    CHARACTER*(*) Var

Python Syntax:

  Results = TecUtil.VarGetNumByAssignment(Var)

  Input:
                  Var                  int
  Output:
    Results[0]    ReturnVal            int

Get the index of the 'X' variable:

   // frame mode must be 2-D or 3-D
   EntIndex_t i = TecUtilVarGetNumByAssignment('X');

EntIndex_t TecUtilVarGetNumByName ( const char *  VarName  ) 

Gets the number (that is, the index) of a variable based on variable name.

This function is Thread Safe.

Parameters:
VarName Name of the variable. Must not be NULL
Returns:
The index (number) of the variable with name VarName, otherwise TECUTILSETNOTMEMBER if the variable is not a member of the current frame's data set.
Precondition:
Must have one or more frames.

Current frame must have a data set.

VarName Pointer must be a valid address and non-NULL.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilVarGetNumByName(VarName)
    CHARACTER*(*) VarName

Python Syntax:

  Results = TecUtil.VarGetNumByName(VarName)

  Input:
                  VarName              string
  Output:
    Results[0]    ReturnVal            int

Get the index of the variable Rainfall:

   EntIndex_t i = TecUtilVarGetNumByName("Rainfall");

EntIndex_t TecUtilVarGetNumByUniqueID ( UniqueID_t  UniqueID  ) 

Gets a variable number, given a unique ID.

This function is Thread Safe.

Parameters:
UniqueID Unique ID of the variable
Returns:
The variable number of the variable represented by the unique ID. If there is no variable number for the given unique ID, the return value is TECUTILBADID.
Precondition:
Must have one or more frames.

Current frame must have a data set.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilVarGetNumByUniqueID(UniqueID)
    INTEGER*4 UniqueID

Python Syntax:

  Results = TecUtil.VarGetNumByUniqueID(UniqueID)

  Input:
                  UniqueID             long
  Output:
    Results[0]    ReturnVal            int

Get a variable number from a unique ID:

   {
     extern UniqueID_t ID; // previously initialized

     TecUtilLockStart(AddOnID);
     if ( TecUtilDataSetIsAvailable() )
       {
         EntIndex_t VarNum = TecUtilVarGetNumByUniqueID(ID);
         if (VarNum != TECUTILBADID)
           {
             ...
           }
       }
     TecUtilLockFinish(AddOnID);
   }

VarStatus_e TecUtilVarGetStatus ( EntIndex_t  Zone,
EntIndex_t  Var 
)

Gets the load status of a variable for a zone.

This function is Thread Safe.

Since:
12.0-1-3754
Parameters:
Zone Number of the zone for which to get the load status.
Var Number of the variable for which to get the load status.
Returns:
The load status of the variable. The return value can be one of the following: VarStatus_Passive, VarStatus_Custom, VarStatus_Map, VarStatus_Heap, VarStatus_NotLoaded VarStatus_Passive indicates that the variable is passive for the zone. Refer to the Data Format Guide for more information on passive variables. VarStatus_Custom indicates that the variable is loaded on-demand by value. Refer to TecUtilDataValueCustomLOD for more information on loading variables on-demand by value. VarStatus_Map indicates that the variable has been loaded and dumped out to a disk cache. VarStatus_Heap indicates that the variable is currently memory-resident. VarStatus_NotLoaded indicates that the variable is available for loading but is not yet loaded.
Precondition:
VALID_REF(FieldData) Pointer must be a valid address and non-NULL.

Current frame must have a data set with at least one zone.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilVarGetStatus(
   &           Zone,
   &           Var)
    INTEGER*4       Zone
    INTEGER*4       Var

Python Syntax:

  Results = TecUtil.VarGetStatus(Zone, Var)

  Input:
                  Zone                 int
                  Var                  int
  Output:
    Results[0]    ReturnVal            VarStatus_e  (defined in TecVals.py)

Get the load status of the third variable of the second zone:

   EntIndex_t  zone = 2;
   EntIndex_t  var  = 3;
   VarStatus_e status;
   status = TecUtilVarGetStatus(zone, var);

VarStatus_e TecUtilVarGetStatusByRef ( FieldData_pa  FieldData  ) 

Gets the load status of a variable for a zone.

This function is Thread Safe.

Since:
12.0-1-5558
Parameters:
FieldData Handle to the field data. Use TecUtilDataValueGetReadableNativeRef(), TecUtilDataValueGetReadableDerivedRef(), TecUtilDataValueGetReadableNLRef(), TecUtilDataValueGetReadableCCRef(), or TecUtilDataValueGetWritableNativeRef() to get readable or writable handles to the field data.
Returns:
The load status of the variable. The return value can be one of the following: VarStatus_Passive, VarStatus_Custom, VarStatus_Map, VarStatus_Heap, VarStatus_NotLoaded VarStatus_Passive indicates that the variable is passive for the zone. Refer to the Data Format Guide for more information on passive variables. VarStatus_Custom indicates that the variable is loaded on-demand by value. Refer to TecUtilDataValueCustomLOD for more information on loading variables on-demand by value. VarStatus_Map indicates that the variable has been loaded and dumped out to a disk cache. VarStatus_Heap indicates that the variable is currently memory-resident. VarStatus_NotLoaded indicates that the variable is available for loading but is not yet loaded.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilVarGetStatusByRef(
   &                   FieldDataPtr)
    POINTER         (FieldDataPtr, FieldData)

Python Syntax:

  Results = TecUtil.VarGetStatusByRef(FieldData)

  Input:
                  FieldData            opaque pointer
  Output:
    Results[0]    ReturnVal            VarStatus_e  (defined in TecVals.py)

Get the load status of the third variable of the second zone:

   EntIndex_t  zone = 2;
   EntIndex_t  var  = 3;
   FieldData_pa FieldData = TecUtilDataValueGetReadableNativeRef(zone, var);
   VarStatus_s status = TecUtilVarGetStatusByRef(FieldData);

UniqueID_t TecUtilVarGetUniqueID ( EntIndex_t  Var  ) 

Gets a unique ID for a variable.

A unique ID is an integer that uniquely identifies a variable. An addon can use these IDs to internally keep track of a set of variables. TecUtilVarGetNumByUniqueID() can be used to convert between a unique ID and a variable number. This function is Thread Safe.

Parameters:
Var Variable number to query.
Returns:
A unique ID for a variable.
Precondition:
Must have one or more frames.

Current frame must have a data set.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilVarGetUniqueID(Var)
    INTEGER*4 Var

Python Syntax:

  Results = TecUtil.VarGetUniqueID(Var)

  Input:
                  Var                  int
  Output:
    Results[0]    ReturnVal            long

Get the unique ID for variable 1:

   {
     TecUtilLockStart(AddOnID);
     if ( TecUtilDataSetIsAvailable() && TecUtilVarIsEnabled(1) )
       {
         UniqueID_t ID = TecUtilVarGetUniqueID(1);
         ...
       }
     TecUtilLockFinish(AddOnID);
   }

Boolean_t TecUtilVariableIsLocked ( EntIndex_t  Var,
VarLockMode_e *  VarLockMode,
char **  LockOwner 
)

Indicates if the variable is locked and optionally the mode in which it was locked and the current lock owner.

Since:
11.0-0-321
Parameters:
Var Offset of the variable in question.
VarLockMode Reference to a variable locking mode enumeration. If NULL the argument is ignored otherwise the current locking mode is placed into the location pointed to by the reference.
LockOwner Reference to a lock owner string pointer. If NULL the argument is ignored otherwise the a copy of the lock owner string is placed into the location pointed to by the reference. It is the client's responsibility to free the resulting lock owner string with TecUtilStringDealloc() when finished with it.
Returns:
TRUE if the variable is locked, FALSE otherwise.
Precondition:
Must have one or more frames.

VarLockMode Pointer must be a valid address or NULL.

LockOwner Pointer must be a valid address or NULL.

See also:
TecUtilVariableLockOn(), TecUtilVariableLockOff().
Python Syntax:
  Results = TecUtil.VariableIsLocked(Var)

  Input:
                  Var                  int
  Output:
    Results[0]    ReturnVal            boolean
    Results[1]    VarLockMode          VarLockMode_e  (defined in TecVals.py)
    Results[2]    LockOwner            string

Boolean_t TecUtilVariableLockOff ( EntIndex_t  Var,
const char *  LockOwner 
)

Unlock the variable.

The variable must have been previously locked by the same lock owner.

Since:
11.0-0-321
Parameters:
Var Offset of the variable to unlock. The offset used to lock the variable may not be the same as variables could be deleted or inserted into the For help tracking variables see TecUtilVarGetUniqueID() and TecUtilVarGetNumByUniqueID().
LockOwner A unique non-zero length string identifying the lock owner. Add-ons can use the ADDON_NAME define for this value. This string must match that of the variable locker.
Returns:
TRUE if the variable could be unlocked, FALSE otherwise.
Precondition:
Must have one or more frames.

LockOwner String must have a valid address and non-zero length.

See also:
TecUtilVariableLockOn(), TecUtilVariableIsLocked().
Python Syntax:
  Results = TecUtil.VariableLockOff(Var, LockOwner)

  Input:
                  Var                  int
                  LockOwner            string
  Output:
    Results[0]    ReturnVal            boolean

Boolean_t TecUtilVariableLockOn ( EntIndex_t  Var,
VarLockMode_e  VarLockMode,
const char *  LockOwner 
)

Lock the variable from being altered according to the specified locking mode.

The variable can only be locked if it isn't already locked.

Since:
11.0-0-321
Parameters:
Var Current offset of the variable to lock. The offset may change over the course of a Tepclot session as other variables are deleted or inserted into the dataset. For help tracking variables see TecUtilVarGetUniqueID() and TecUtilVarGetNumByUniqueID().
VarLockMode Variable locking mode. The possible values are: VarLockMode_ValueChange (prevents modification of values in a variable but permits deletion), and VarLockMode_Delete (prevents deletion of a varaible but permits modification).
LockOwner A unique non-zero length string identifying the lock owner. Add-ons can use the ADDON_NAME define for this value.
Returns:
TRUE if the variable could be locked, FALSE otherwise.
Precondition:
Must have one or more frames.

LockOwner String must have a valid address and non-zero length.

See also:
TecUtilVariableLockOff(), TecUtilVariableIsLocked().
Python Syntax:
  Results = TecUtil.VariableLockOn(Var, VarLockMode, LockOwner)

  Input:
                  Var                  int
                  VarLockMode          VarLockMode_e  (defined in TecVals.py)
                  LockOwner            string
  Output:
    Results[0]    ReturnVal            boolean

Boolean_t TecUtilVarIsEnabled ( EntIndex_t  Var  ) 

Determine if a variable is enabled.

This function is Thread Safe.

Returns:
TRUE, if a variable is enabled, otherwise, FALSE.
Precondition:
Must have one or more frames.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilVarIsEnabled(Var)
    INTEGER*4 Var

Python Syntax:

  Results = TecUtil.VarIsEnabled(Var)

  Input:
                  Var                  int
  Output:
    Results[0]    ReturnVal            boolean

Check if the first variable is enabled:

   if (TecUtilVarIsEnabled(1))
     {
       // sure is!
     }

Boolean_t TecUtilVarIsSpatial ( EntIndex_t  Var  ) 

Test to see if a variable is spatial A spatial variable is X,Y, or Z in 3D, or X,Y in 2D.

Parameters:
Var Variable of interest. This variable must be an enabled variable.
Returns:
TRUE if variable is spatial FALSE otherwise.
Precondition:
Must have one or more frames.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilVarIsSpatial(
    INTEGER*4       Var

Since:
11.3-17-013
Python Syntax:
  Results = TecUtil.VarIsSpatial(Var)

  Input:
                  Var                  int
  Output:
    Results[0]    ReturnVal            boolean

Boolean_t TecUtilVarRename ( EntIndex_t  VarNum,
const char *  VarName 
)

Rename a data set variable in Tecplot.

Parameters:
VarNum The number of the variable to be renamed. The variable must be greater than zero and the variable must be enabled
VarName A string containing the new variable name. The name will be trimmed of any leading or trailing whitespace and truncated to be no more than 128 characters in length.
Returns:
TRUE if successful, FALSE if not.
Precondition:
Must have one or more frames.

VarName Pointer must be a valid address and non-NULL.

Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilVarRename(
   &                   VarNum,
   &                   VarName)
    INTEGER*4       VarNum
    CHARACTER*(*)   VarName

Python Syntax:

  Results = TecUtil.VarRename(VarNum, VarName)

  Input:
                  VarNum               int
                  VarName              string
  Output:
    Results[0]    ReturnVal            boolean

Rename the first variable (assumed to be enabled for this example):

   TecUtilVarRename(1,"NewNameForVariable1");

Generated on Tue Mar 12 02:24:45 2013 for Tecplot by  doxygen 1.5.5