Data Value


Functions

Boolean_t TecUtilDataValueSetByZoneVar (EntIndex_t Zone, EntIndex_t Var, LgIndex_t PointIndex, double Value)
  Assign a value to a field variable at a specific position.
void TecUtilDataValueShare (EntIndex_t SourceZone, EntIndex_t DestZone, EntIndex_t Var)
  Sets the properties of the variable so that it is shared between source and destination zones (using the source for values).
void TecUtilDataValueCopy (EntIndex_t SourceZone, EntIndex_t DestZone, EntIndex_t Var)
  Copies the data from the source zone's variable to the destination zone.
Boolean_t TecUtilDataValueAlloc (EntIndex_t Zone, EntIndex_t Var)
  Allocates the space needed for the variable.
Boolean_t TecUtilDataValueAutoLOD (EntIndex_t Zone, EntIndex_t Var, DataValueStructure_e DataValueStructure, const char *FileName, FileOffset_t Offset, Int64_t Stride, Boolean_t IsDataNativeByteOrder)
  Specifies where in the data file the data for the specified variable resides.
ArbParam_t TecUtilDataValueGetClientData (FieldData_pa FieldData)
  Return the custom load-on-demand client data from a field data handle.
Boolean_t TecUtilDataValueCustomLOD (EntIndex_t Zone, EntIndex_t Var, LoadOnDemandVarLoad_pf VariableLoad, LoadOnDemandVarUnload_pf VariableUnload, LoadOnDemandVarCleanup_pf VariableCleanup, FieldValueGetFunction_pf GetValueFunction, FieldValueSetFunction_pf SetValueFunction, ArbParam_t ClientData)
  Registers with Tecplot the load-on-demand callbacks and client data for a specific variable.
Boolean_t TecUtilDataValueUnload (EntIndex_t Zone, EntIndex_t Var)
  Instructs Tecplot to unload the variable.
Boolean_t TecUtilDataValueBranchShared (EntIndex_t Zone, EntIndex_t Var)
  Branch off a shared variable.
void TecUtilDataValueArraySetByRef (FieldData_pa DestFieldData, LgIndex_t DestOffset, LgIndex_t DestCount, void *SourceValueArray)
  Copies the specified number of values from the base of the source value array to the destination field data starting at the specified offset.
void TecUtilDataValueSetByRef (FieldData_pa FD, LgIndex_t PointIndex, double Value)
  Assign a value to a field variable at a specific position.
void TecUtilDataValueSetMinMaxByRef (FieldData_pa FieldData, double MinValue, double MaxValue)
  Set the minimum and maximum values for a tecplot variable using a field data reference.
void TecUtilDataValueSetMinMaxByZoneVar (EntIndex_t Zone, EntIndex_t Var, double MinValue, double MaxValue)
  Set the minimum and maximum values for a tecplot variable using a zone and variable number.
void TecUtilDataValueGetReadableRawPtr (EntIndex_t Zone, EntIndex_t Var, void **DataPtr, FieldDataType_e *FieldDataType)
  Get a read-only handle to the raw field data in the data set attached to the current frame.
void TecUtilDataValueGetWritableRawPtr (EntIndex_t Zone, EntIndex_t Var, void **DataPtr, FieldDataType_e *FieldDataType)
  Get a read/write handle to the raw field data in the data set attached to the current frame.
LgIndex_t TecUtilDataValueGetCountByRef (FieldData_pa FieldData)
  Gets the number of values associated with the field data reference.
double TecUtilDataValueGetByZoneVar (EntIndex_t Zone, EntIndex_t Var, LgIndex_t PointIndex)
  Get a field data value.
FieldData_pa TecUtilDataValueGetReadableNativeRef (EntIndex_t Zone, EntIndex_t Var)
  Get a read-only handle to the native data for the specified zone and variable in the data set attached to the current frame.
FieldData_pa TecUtilDataValueGetReadableDerivedRef (EntIndex_t Zone, EntIndex_t Var)
  Get a read-only handle to the derived data for the specified zone and variable in the data set attached to the current frame.
FieldData_pa TecUtilDataValueGetReadableNLRef (EntIndex_t Zone, EntIndex_t Var)
  Get a read-only handle to the node located data for the specified zone and variable in the data set attached to the current frame.
FieldData_pa TecUtilDataValueGetReadableCCRef (EntIndex_t Zone, EntIndex_t Var)
  Get a read-only handle to the cell centered data for the specified zone and variable in the data set attached to the current frame.
FieldData_pa TecUtilDataValueGetWritableNativeRef (EntIndex_t Zone, EntIndex_t Var)
  Get a native read/write handle to the data for the specified zone and variable in the data set attached to the current frame.
FieldValueGetFunction_pf TecUtilDataValueRefGetGetFunc (FieldData_pa FD)
  Get the low-level "get value" function associated with a field data handle.
FieldValueSetFunction_pf TecUtilDataValueRefGetSetFunc (FieldData_pa FD)
  Get the low-level "set value" function associated with a field data handle.
Boolean_t TecUtilDataValueGetZoneVarByRef (FieldData_pa FD, EntIndex_t *Zone, EntIndex_t *Var)
  Get a candidate zone and variable associated with the given field data reference.
FieldDataType_e TecUtilDataValueGetRefType (FieldData_pa FieldData)
  Get the field data type of a field data handle.
FieldDataType_e TecUtilDataValueGetType (EntIndex_t Zone, EntIndex_t Var)
  Queries for the data type of the variable.
ValueLocation_e TecUtilDataValueGetLocation (EntIndex_t Zone, EntIndex_t Var)
  Queries for the location of the variable.
ValueLocation_e TecUtilDataValueGetLocationByRef (FieldData_pa FieldData)
  Queries for the location of the data values associated with the field data reference.
void TecUtilDataValueArrayGetByRef (FieldData_pa SourceFieldData, LgIndex_t SourceOffset, LgIndex_t SourceCount, void *DestValueArray)
  Fetch an Array of values by reference.
double TecUtilDataValueGetByRef (FieldData_pa FieldData, LgIndex_t PointIndex)
  Get a field data value.
Boolean_t TecUtilDataValueGetMinMaxByZoneVar (EntIndex_t Zone, EntIndex_t Var, double *Min, double *Max)
  Get the minimum and maximum values for a tecplot variable using a zone and variable number.
void TecUtilDataValueGetMinMaxByRef (FieldData_pa FieldData, double *Min, double *Max)
  Get the minimum and maximum values for a tecplot variable using the field data reference.
Boolean_t TecUtilDataValueIsSharingOk (EntIndex_t SourceZone, EntIndex_t DestZone, EntIndex_t Var)
  Determine if it is ok to share a variable between zones.
Set_pa TecUtilDataValueGetShareZoneSet (EntIndex_t Zone, EntIndex_t Var)
  Gets the set of zones that share the variable with the specified zone.
EntIndex_t TecUtilDataValueGetShareCount (EntIndex_t Zone, EntIndex_t Var)
  Get a count for the number of times a particular variable is shared.
Boolean_t TecUtilDataValueIsPassive (EntIndex_t Zone, EntIndex_t Var)
  Determine if a variable is passive for a particular zone.

Function Documentation

Boolean_t TecUtilDataValueAlloc ( EntIndex_t  Zone,
EntIndex_t  Var 
)

Allocates the space needed for the variable.

This function is used in conjunction with deferred variable creation. See the SV_DEFERVARCREATION option for TecUtilDataSetAddZoneX() and TecUtilDataSetAddVarX() for details.

Since:
10.0-3-129
Parameters:
Zone The zone needing the variable allocated.
Var The variable to be allocated.
Returns:
TRUE if the variable was sucessfully allocated, FALSE otherwise.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilDataValueAlloc(
   &                   Zone,
   &                   Var)
    INTEGER*4       Zone
    INTEGER*4       Var

Python Syntax:

  Results = TecUtil.DataValueAlloc(Zone, Var)

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

Allocate the first variable of zone 3. Note that this example is only valid if the zone was added with the deferred variable creation option set to true.

   IsOk = TecUtilDataValueAlloc(3, 1);

See also:
TecUtilDataValueShare()

void TecUtilDataValueArrayGetByRef ( FieldData_pa  SourceFieldData,
LgIndex_t  SourceOffset,
LgIndex_t  SourceCount,
void *  DestValueArray 
)

Fetch an Array of values by reference.

This function fetches the specified number of values from the source field data starting at the specified source item offset and copies them to the base of the destination value array. The destination value array must be of the same data type as the source field data. In addition, data of type FieldDataType_Bit is currently not supported for array access. This function is Thread Safe.

Since:
10.0-3-12
Parameters:
SourceFieldData Field data containing the data to fetch.
SourceOffset Member offset in the source field data to begin fetching values.
SourceCount Number of values to fetch from the source field data.
DestValueArray Pre-allocated array large enough to hold the requested members. The first member is placed at the base of the array. The native type of the array must match that of the field data.
Python Syntax:
    This function is not supported in Python.

void TecUtilDataValueArraySetByRef ( FieldData_pa  DestFieldData,
LgIndex_t  DestOffset,
LgIndex_t  DestCount,
void *  SourceValueArray 
)

Copies the specified number of values from the base of the source value array to the destination field data starting at the specified offset.

The source value array must be of the same data type as the destination field data. In addition, data of type FieldDataType_Bit is currently not supported for array access. This function is Thread Safe.

Since:
10.0-3-12
Parameters:
DestFieldData Field data to receive the source values.
DestOffset Member offset in the destination field data to begin assigning values. DestOffset >= 1 and DestOffset <= DestCount.
DestCount Number of values to assign to the destination field data.
SourceValueArray An array containing the members to copy. The first member is assumed to be at the base of the array.
Python Syntax:
    This function is not supported in Python.

Boolean_t TecUtilDataValueAutoLOD ( EntIndex_t  Zone,
EntIndex_t  Var,
DataValueStructure_e  DataValueStructure,
const char *  FileName,
FileOffset_t  Offset,
Int64_t  Stride,
Boolean_t  IsDataNativeByteOrder 
)

Specifies where in the data file the data for the specified variable resides.

The variable must be laid out in memory using the structure specified. Using this information Tecplot will automatically load and unload the variable when Tecplot deems it necessary. It is the responsibility of the add-on to ensure that the file remains present and unaltered while Tecplot maintains a reference to this file as Tecplot may unload and subsequently reload the variable at unspecified times.

This function is used in conjunction with deferred variable creation. See the SV_DEFERVARCREATION option for TecUtilDataSetAddZoneX() and TecUtilDataSetAddVarX() for details.

Since:
11.0-0-001
Parameters:
Zone The zone of the variable to have Tecplot automatically load on demand.
Var Variable to have Tecplot automatically load on demand.
DataValueStructure Specifies the structure type to which the data in the file conforms.
FileName Data file name containing the variable data laid out using Tecplot's binary block data format.
Offset Absolute offset to the start of the variable data in the file.
Stride The stride tells Tecplot how to skip through the file for nodal data. Only nodal data can specify a stride greater than one. A stride of one offers much higher load/unload performance than strides greater than one.
IsDataNativeByteOrder Indicates if the byte ordering of the data in the file matches the machine's native byte ordering.
Returns:
TRUE if the variable is setup for auto loading, FALSE otherwise.
See also:
TecUtilDataValueCustomLOD()
Python Syntax:
  Results = TecUtil.DataValueAutoLOD(Zone, Var, DataValueStructure, FileName, Offset, Stride, IsDataNativeByteOrder)

  Input:
                  Zone                 int
                  Var                  int
                  DataValueStructure   DataValueStructure_e  (defined in TecVals.py)
                  FileName             string
                  Offset               long
                  Stride               long
                  IsDataNativeByteOrder boolean
  Output:
    Results[0]    ReturnVal            boolean

Boolean_t TecUtilDataValueBranchShared ( EntIndex_t  Zone,
EntIndex_t  Var 
)

Branch off a shared variable.

The specified variable of the specified zone is branched so it is no longer shared with anything.

Parameters:
Zone Zone in which the shared variable is located.
Var Variable that will be branched
Returns:
TRUE if successful, FALSE otherwise.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilDataValueBranchShared(
   &                   Zone,
   &                   Var)
    INTEGER*4       Zone
    INTEGER*4       Var

Python Syntax:

  Results = TecUtil.DataValueBranchShared(Zone, Var)

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

Branch variable 2 in zone 1.

   TecUtilDataValueBranchShared(1, 2);

void TecUtilDataValueCopy ( EntIndex_t  SourceZone,
EntIndex_t  DestZone,
EntIndex_t  Var 
)

Copies the data from the source zone's variable to the destination zone.

The destination zone's variable must already be allocated or memory mapped and it may not be shared. Both zones must have the same structure (both Ordered with the same I,J, and K values; or both are finite-elements with the same element type and same number of nodes.

Parameters:
SourceZone The zone number where the data values are based.
DestZone The zone number where the data values will be copied from the source zone.
Var The variable to be copied.
Fortran Syntax:
    SUBROUTINE TecUtilDataValueCopy(
   &           SourceZone,
   &           DestZone,
   &           Var)
    INTEGER*4       SourceZone
    INTEGER*4       DestZone
    INTEGER*4       Var

Python Syntax:

  Results = TecUtil.DataValueCopy(SourceZone, DestZone, Var)

  Input:
                  SourceZone           int
                  DestZone             int
                  Var                  int
  Output:
    Results[0]    ReturnVal            NONE

Copy the values from variable 1 of zone 2 to zone 3.

   TecUtilDataValueCopy(2, 3, 1);

Boolean_t TecUtilDataValueCustomLOD ( EntIndex_t  Zone,
EntIndex_t  Var,
LoadOnDemandVarLoad_pf  VariableLoad,
LoadOnDemandVarUnload_pf  VariableUnload,
LoadOnDemandVarCleanup_pf  VariableCleanup,
FieldValueGetFunction_pf  GetValueFunction,
FieldValueSetFunction_pf  SetValueFunction,
ArbParam_t  ClientData 
)

Registers with Tecplot the load-on-demand callbacks and client data for a specific variable.

Tecplot will notify the add-on via the callbacks when the variable needs to be loaded, unloaded, and cleaned up or when a value needs to be fetched or submitted.

All callbacks must be written in a thread-safe manner so that Tecplot can make parallel requests to load (and/or unload) multiple variables. The easiest way to write thread-safe callbacks is to not use any shared state (i.e. global or static state) in order to perform the requested action but instead to use private client data to maintain all the information needed to perform the requested action.

It is important that GetValue and SetValue callbacks do NOT lock/unlock Tecplot or call TecUtil functions that require Tecplot to be locked as this will incur a performance penalty. GetValue and SetValue functions should be lightweight and fast.

Calls made back to Tecplot in response to a load, unload, or cleanup request should be limited to queries except in the case where data is being loaded into a variable. In addition, no state changes should be broadcast by the callbacks.

This function is used in conjunction with deferred variable creation. See the SV_DEFERVARCREATION option for TecUtilDataSetAddZoneX() and TecUtilDataSetAddVarX() for details.

Two methods for loading and accessing data are available for custom load-on-demand (see ADK Users Manual for details):

  • Custom Load Variable on Demand:
    The add-on supplied VariableLoad() callback is responsible for loading the entire variable data into the Tecplot prepared field data backing. Tecplot is responsible for allocating and freeing the space for the field data backing. In addition the add-on must supply the VariableCleanup() callback to receive notification when the variable source is no longer needed. Optionally the add-on may supply the VariableUnload() callback to receive notification of the variable being unloaded. Most add-ons should supply NULL for the VariableUnload() callback instructing Tecplot to assume responsibility for unloading the variable and re-loading it in an efficient form. The "Custom Load Variable on Demand" method is signified by passing NULL for the GetValueFunction() and SetValueFunction() callback parameters.
  • Custom Load Value on Demand:
    The add-on supplied GetValueFunction() and an optional SetValueFunction() are used by Tecplot to fetch and submit variable data. If the SetValueFunction() is not provided Tecplot will create its own copy of the variable when an attempt is made to modify the variable values (such as via a Tecplot Data Alter operation). The VariableLoad(), VariableUnload(), and VariableCleanup() callbacks are optional. The add-on may supply these callback to receive notification of Tecplot's intent or NULL if the add-on is not interested in the notifications.

Since:
11.0-0-001
Parameters:
Zone Zone containing the variable that will now be custom load-on-demand.
Var Variable that will now be custom load-on-demand.
VariableLoad Tecplot calls this callback when the variable is to be loaded. The VariableLoad() callback may never get called if the variable is not needed or it may get called immediately if load-on-demand capabilities are not available. Depending on the load-on-demand method the callback has different responsibilities:
  • If the variable is using the "Custom Load Variable on Demand" method (signified by passing NULL for the GetValueFunction() and SetValueFunction() callback parameters) the callback is responsible for loading the entire variable data into the Tecplot prepared field data backing using information from its private client to locate or generate the data.
  • If the variable is using the "Custom Load Value on Demand" method (signified by passing a non-NULL GetValueFunction() callback parameter) the callback is simply a notification that Tecplot is getting ready to fetch data via the GetValueFunction() or, if supplied, submit data via the SetValueFunction().
VariableUnload Most add-ons will supply NULL for this callback. Supplying NULL instructs Tecplot to handled the unloading (and subsequent reloading) of the variable without the intervention of the add-on. If the add-on does supply this callback, Tecplot calls it when the variable is to be unloaded. This query provides the add-on an opportunity to allow or deny a variable to be unloaded by returning TRUE or FALSE respectively. Unless there is a compelling reason, such as very expensive load costs (in which case NULL should probably be supplied for this callback), the add-on should honor Tecplot's request to unload the variable (i.e. the VariableUnload() callback should return TRUE). An add-on may also cleanup any private resources that are not needed when the variable is unloaded, however the add-on must still maintain enough information to load the variable again if requested by Tecplot. The VariableUnload() callback may never get called if the variable does not need to be unloaded nor will the VariableUnload() callback necessarily be called before the VariableCleanup() callback.
VariableCleanup Tecplot calls this callback when the variable is to be cleaned up. This allows the add-on to cleanup any private resources that were used in conjunction with identifying or loading this variable. After a variable is cleaned up Tecplot will never again request it to be loaded. Tecplot may or may not call the VariableUnload() callback before calling the VariableCleanup() callback. Additionally, the VariableCleanup() callback will be called even if the variable was never loaded.
GetValueFunction Tecplot calls this callback to fetch the value from the field data at the specified index. This callback is only registered by add-ons that are using the "Custom Load Value on Demand" method, otherwise pass NULL.
SetValueFunction Tecplot calls this callback to submit a value to the field data at the specified index. This callback is only registered by add-ons that are using the "Custom Load Value on Demand" method, otherwise pass NULL. By providing a SetValueFunction() callback the add-on is signifying it will store any changes to the field data until the variable is cleaned up. Most "Custom Load Value on Demand" add-ons should pass NULL for this callback and allow Tecplot to store variable modifications.
ClientData Private client data needed by the custom load-on-demand callbacks to perform the duties of loading, unloading, and cleaning up the variable or to perform the get or set requests. Tecplot stores the client data in the field data structure and must be retrieved by the callbacks using TecUtilDataValueGetClientData(). The client data should ONLY be retrieved in response to a custom load, unload, cleanup, get-value, or set-value callback. At no other time is the request valid.
Returns:
TRUE if successful, FALSE otherwise.
Following is an example of how to create a variable using the "Custom Load Value on Demand" method by registering a very simple GetValueFunction() that always returns zero without the overhead of allocating any data. 
   double *ZeroVariableGetValue(const FieldData_pa FieldData,
                                        LgIndex_t          PointIndex)
   {
     return 0.0;
   }

   .
   .
   .
   IsOk = TecUtilDataValueCustomLOD(3, 4, NULL, NULL, NULL,
                                    ZeroVariableGetValue, NULL, 0);

Following is an example of how to create a variable using the "Custom Load Variable on Demand" method by registering some simple load/unload/cleanup callbacks. 

   typedef struct
     {
       char      *DataFileName;
       long       SeekOffset;
       LgIndex_t  NumValues;
       ... other information needed to load variable data
     } MyVariableClientData_s;

   Boolean_t MyVariableLoader(FieldData_pa FieldData)
   {
     REQUIRE(VALID_REF(FieldData));

     MyVariableClientData_s *MyClientData = (MyVariableClientData_s *)TecUtilDataValueGetClientData(FieldData);

     // open the data file
     FILE *MyDataFile = fopen(MyClientData->DataFileName, "rb");
     Boolean_t IsOk = (MyDataFile != NULL);

     // seek to the place in the file where the variable data is located
     IsOk = IsOk && (fseek(MyDataFile, MyClientData->SeekOffset, SEEK_SET) == 0);
     if (IsOk)
       {
         // load the data into the variable's field data
         IsOk = ReadMyDataInfoVariable(MyDataFile, MyClientData, FieldData);
       }

     // cleanup
     if (MyDataFile != NULL)
       fclose(MyDataFile);

     ENSURE(VALID_BOOLEAN(IsOk));
     return IsOk;
   }

   Boolean_t MyVariableUnload(FieldData_pa FieldData)
   {
     REQUIRE(VALID_REF(FieldData));

     // We don't have any private data to cleanup (i.e in addition to the
     // private client data which we don't cleanup here) so all we have to do
     // is return TRUE or FALSE letting Tecplot know that it can or can not
     // unload the variable.
     Boolean_t Result = TRUE; // ...tell Tecplot to go ahead and unload the variable

     ENSURE(VALID_BOOLEAN(Result));
     return Result;
   }

   void MyVariableCleanup(FieldData_pa FieldData)
   {
     REQUIRE(VALID_REF(FieldData));

     MyVariableClientData_s *MyClientData = (MyVariableClientData_s *)TecUtilDataValueGetClientData(FieldData);

     // cleanup privately allocated resources
     free(MyClientData->DataFileName);
     free(MyClientData);
   }

   .
   .
   .
   MyVariableClientData_s *MyClientData = (MyVariableClientData_s *)malloc(sizeof(MyVariableClientData_s));
   const char *MyDataFileName = "MyDataFileName.dat";
   MyClientData->MyDataFileName = (char *)malloc(strlen(MyDataFileName)+1);
   strcpy(MyClientData->MyDataFileName, MyDataFileName);
   MyClientData->SeekOffset = ... determined somewhere else
   MyClientData->NumValues = ... determined somewhere else
   ... initialize any other client data information needed to load variable data
   IsOk = TecUtilDataValueCustomLOD(3, 4,
                                    MyVariableLoader,
                                    MyVariableUnload, // most add-ons should pass NULL instead of MyVariableUnload
                                    MyVariableCleanup,
                                    NULL, // passing NULL for GetValue function signifies load-variable-on-demand
                                    NULL,
                                    (ArbParam_t)MyClientData);

Python Syntax:

    This function is not supported in Python.

See also:
TecUtilDataValueAutoLOD(), TecUtilDataValueSetMinMaxByZoneVar(), TecUtilMemoryChangeNotify()

double TecUtilDataValueGetByRef ( FieldData_pa  FieldData,
LgIndex_t  PointIndex 
)

Get a field data value.

To use this function you must have already obtained a handle to field data. This function is Thread Safe.

Parameters:
FieldData A field data reference usually obtained via a call to one of the following functions: TecUtilDataValueGetReadableNativeRef(), TecUtilDataValueGetReadableDerivedRef(), TecUtilDataValueGetReadableNLRef(), or TecUtilDataValueGetReadableCCRef().
PointIndex Position in the array of field data values. Position starts at one. If FieldData came from an IJ- or IJK-ordered zone then the position is calculated by treating the two- or three-dimensional array as a one-dimensional array.
Returns:
The value at a given position in field data FieldData
Fortran Syntax:
    REAL*8 FUNCTION TecUtilDataValueGetByRef(
   &                   FieldDataPtr,
   &                   PointIndex)
    POINTER         (FieldDataPtr, FieldData)
    INTEGER*4       PointIndex

Python Syntax:

  Results = TecUtil.DataValueGetByRef(FieldData, PointIndex)

  Input:
                  FieldData            opaque pointer
                  PointIndex           int
  Output:
    Results[0]    ReturnVal            double

Get the first twenty data values for the second variable in zone 5:

   FieldData_pa fd = TecUtilDataValueGetReadableNativeRef(5, 2);
   LgIndex_t numpts = TecUtilDataValueGetCountByRef(fd);
   if ( fd )
     {
       int ii;
       for ( ii = 1; ii <= numpts; ii++ )
         {
           double val = TecUtilDataValueGetByRef(fd, ii);
           // do something with val
         }
     }

See also:
TecUtilDataValueRefGetGetFunc() for obtaining a function as a high performance alternative.

double TecUtilDataValueGetByZoneVar ( EntIndex_t  Zone,
EntIndex_t  Var,
LgIndex_t  PointIndex 
)

Get a field data value.

This function does not require you to obtain the handle to the field data as does TecUtilDataValueGetByRef(), however, this function is not very efficient. Use TecUtilDataValueGetByRef() if you are getting multiple values from the same zone.

Parameters:
Zone The zone number
Var The variable number
PointIndex Position in the array of field data values. Position starts at one. If FieldData came from an IJ- or IJK-ordered zone then the position is calculated by treating the two- or three-dimensional array as a one-dimensional array
Returns:
The variable value at a specific point in a zone.
Fortran Syntax:
    REAL*8 FUNCTION TecUtilDataValueGetByZoneVar(
   &                   Zone,
   &                   Var,
   &                   PointIndex)
    INTEGER*4       Zone
    INTEGER*4       Var
    INTEGER*4       PointIndex

Python Syntax:

  Results = TecUtil.DataValueGetByZoneVar(Zone, Var, PointIndex)

  Input:
                  Zone                 int
                  Var                  int
                  PointIndex           int
  Output:
    Results[0]    ReturnVal            double

Get the twenty-first value of the second variable of zone 5:

   double dd = TecUtilDataValueGetByZoneVar(5, 2, 21);
   // Use val.

ArbParam_t TecUtilDataValueGetClientData ( FieldData_pa  FieldData  ) 

Return the custom load-on-demand client data from a field data handle.

The client data should ONLY be retrieved in response to a custom load, unload, cleanup, get-value, or set-value callback. At no other time is the request valid. This function is Thread Safe.

Parameters:
FieldData Custom load-on-demand field data handle.
Returns:
Client data for the custom load-on-demand add-on.
Python Syntax:
    This function is not supported in Python.


   double MyGetValueFunction(const FieldData_pa FieldData,
                                     LgIndex_t          PointIndex)
   {
     double Result;
     MyClientData_s *MyClientData = (MyClientData_s *)TecUtilDataValueGetClientData(FieldData);

     // calculate or extract the requested value from the client data
       .
       .
       .

     return Result;
   }

See also:
TecUtilDataValueCustomLOD()

LgIndex_t TecUtilDataValueGetCountByRef ( FieldData_pa  FieldData  ) 

Gets the number of values associated with the field data reference.

Since:
11.0-0-353
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 number of values associated with the field data reference.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilDataValueGetCountByRef(FieldDataPtr)
   &                   FieldDataPtr)
    POINTER         (FieldDataPtr, FieldData)

Python Syntax:

  Results = TecUtil.DataValueGetCountByRef(FieldData)

  Input:
                  FieldData            opaque pointer
  Output:
    Results[0]    ReturnVal            int

Determine how many values are associated with the second variable of zone 5. 

   FieldData_pa FD = TecUtilDataValueGetReadableNativeRef(5, 2);
   LgIndex_t NumValues = TecUtilDataValueGetCountByRef(FD);

ValueLocation_e TecUtilDataValueGetLocation ( EntIndex_t  Zone,
EntIndex_t  Var 
)

Queries for the location of the variable.

This function is Thread Safe.

Parameters:
Zone The zone number.
Var The variable number
Returns:
The value location of the variable.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilDataValueGetLocation(
   &                   Zone,
   &                   Var)
    INTEGER*4       Zone
    INTEGER*4       Var

Python Syntax:

  Results = TecUtil.DataValueGetLocation(Zone, Var)

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

Get the value location of variable 2 in zone 5:

   ValueLocation_e ValLoc = TecUtilDataValueGetLocation(5, 2);

See also:
TecUtilDataValueGetLocationByRef

ValueLocation_e TecUtilDataValueGetLocationByRef ( FieldData_pa  FieldData  ) 

Queries for the location of the data values associated with the field data reference.

This function is Thread Safe.

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 value location of the variable.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilDataValueGetLocationByRef(FieldDataPtr)
   &                   FieldDataPtr)
    POINTER         (FieldDataPtr, FieldData)

Python Syntax:

  Results = TecUtil.DataValueGetLocationByRef(FieldData)

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

See also:
TecUtilDataValueGetLocation

void TecUtilDataValueGetMinMaxByRef ( FieldData_pa  FieldData,
double *  Min,
double *  Max 
)

Get the minimum and maximum values for a tecplot variable using the field data reference.

This function is Thread Safe.

Parameters:
FieldData A field data reference usually obtained via a call to one of the following functions: TecUtilDataValueGetReadableNativeRef(), TecUtilDataValueGetReadableDerivedRef(), TecUtilDataValueGetReadableNLRef(), or TecUtilDataValueGetReadableCCRef().
Min Returned minimum value.
Max Returned maximum value.
Returns:
TRUE if the min/max value could be retrieved, FALSE otherwise.
Fortran Syntax:
    SUBROUTINE TecUtilDataValueGetMinMaxByRef(
   &           FieldDataPtr,
   &           Min,
   &           Max)
    POINTER         (FieldDataPtr, FieldData)
    REAL*8          Min
    REAL*8          Max

Python Syntax:

  Results = TecUtil.DataValueGetMinMaxByRef(FieldData)

  Input:
                  FieldData            opaque pointer
  Output:
    Results[0]    Min                  double
    Results[1]    Max                  double

Get the minimum and maximum values for the third variable in zone 2 in the current data set.

   FieldData_pa FD;
   double       Min;
   double       Max;

   FD = TecUtilDataValueGetReadableNativeRef(2,3);
   TecUtilDataValueGetMinMaxByRef(FD,&Min,&Max);

See also:
TecUtilDataValueGetYMinMaxByZoneVar(), TecUtilDataValueSetMinMaxByZoneVar()

Boolean_t TecUtilDataValueGetMinMaxByZoneVar ( EntIndex_t  Zone,
EntIndex_t  Var,
double *  Min,
double *  Max 
)

Get the minimum and maximum values for a tecplot variable using a zone and variable number.

Since:
11.0-0-007
Parameters:
Zone The zone number of the variable to be examinined for min/max values.
Var The variable number to be examinined for min/max values.
Min Returned minimum value.
Max Returned maximum value.
Returns:
TRUE if the min/max value could be retrieved, FALSE otherwise.
Fortran Syntax:
    SUBROUTINE TecUtilDataValueGetMinMaxByZoneVar(
   &           Zone,
   &           Var,
   &           Min,
   &           Max)
    INTEGER*4       Zone
    INTEGER*4       Var
    REAL*8          Min
    REAL*8          Max

Python Syntax:

  Results = TecUtil.DataValueGetMinMaxByZoneVar(Zone, Var)

  Input:
                  Zone                 int
                  Var                  int
  Output:
    Results[0]    ReturnVal            boolean
    Results[1]    Min                  double
    Results[2]    Max                  double

Get the minimum and maximum values for the third variable in zone 2 in the current data set.

   double Min;
   double Max;
   TecUtilDataValueGetMinMaxByZoneVar(2,3,&Min,&Max);

See also:
TecUtilDataValueSetMinMaxByZoneVar()

FieldData_pa TecUtilDataValueGetReadableCCRef ( EntIndex_t  Zone,
EntIndex_t  Var 
)

Get a read-only handle to the cell centered data for the specified zone and variable in the data set attached to the current frame.

This function is Thread Safe.

Since:
11.2-0-397
Parameters:
Zone Number of the zone for which to get the field data
Var Number of the variable for which to get the field data
Returns:
A read-only field data handle to the cell centered data for the specified zone and variable in the data set attached to the current frame or NULL if Tecplot was interrupted or was not able to load or derive the data.
Fortran Syntax:
    SUBROUTINE TecUtilDataValueGetReadableCCRef(
   &           Zone,
   &           Var,
   &           ResultPtr)
    INTEGER*4       Zone
    INTEGER*4       Var
    POINTER         (ResultPtr, Result)

Python Syntax:

  Results = TecUtil.DataValueGetReadableCCRef(Zone, Var)

  Input:
                  Zone                 int
                  Var                  int
  Output:
    Results[0]    ReturnVal            opaque pointer

Function that loads the values of a field variable into a supplied double precision array. Assume the array is already dimensioned correctly and the dataset, zone, and variable exist. 

 static void ReadVals(double     Var[],
                      EntIndex_t ZoneNum,
                      EntIndex_t VarNum)
 {
   FieldData_pa FieldData = TecUtilDataValueGetReadableCCRef(ZoneNum, VarNum);
   if (FieldData)
     {
       int i;
       LgIndex_t NumValues = TecUtilDataValueGetCountByRef(FieldData);

       // Remember that the GetByRef function is 1-based....
       for (i = 0; i < NumPointsInZone; i++)
         Var[i] = TecUtilDataValueGetByRef(FieldData, i+1);
     }
 }

See also:
TecUtilDataValueGetReadableNativeRef(), TecUtilDataValueGetReadableDerivedRef(), TecUtilDataValueGetReadableNLRef(), TecUtilDataValueGetWritableNativeRef()

FieldData_pa TecUtilDataValueGetReadableDerivedRef ( EntIndex_t  Zone,
EntIndex_t  Var 
)

Get a read-only handle to the derived data for the specified zone and variable in the data set attached to the current frame.

This function is Thread Safe.

Since:
11.2-0-397
Parameters:
Zone Number of the zone for which to get the field data
Var Number of the variable for which to get the field data
Returns:
A read-only field data handle to the derived data for the specified zone and variable in the data set attached to the current frame or NULL if Tecplot was interrupted or was not able to load or derive the data.
Fortran Syntax:
    SUBROUTINE TecUtilDataValueGetReadableDerivedRef(
   &           Zone,
   &           Var,
   &           ResultPtr)
    INTEGER*4       Zone
    INTEGER*4       Var
    POINTER         (ResultPtr, Result)

Python Syntax:

  Results = TecUtil.DataValueGetReadableDerivedRef(Zone, Var)

  Input:
                  Zone                 int
                  Var                  int
  Output:
    Results[0]    ReturnVal            opaque pointer

Function that loads the values of a field variable into a supplied double precision array. Assume the array is already dimensioned correctly and the dataset, zone, and variable exist. 

 static void ReadVals(double     Var[],
                      EntIndex_t ZoneNum,
                      EntIndex_t VarNum)
 {
   FieldData_pa FieldData = TecUtilDataValueGetReadableDerivedRef(ZoneNum, VarNum);
   if (FieldData)
     {
       int i;
       LgIndex_t NumValues = TecUtilDataValueGetCountByRef(FieldData);

       // Remember that the GetByRef function is 1-based....
       for (i = 0; i < NumPointsInZone; i++)
         Var[i] = TecUtilDataValueGetByRef(FieldData, i+1);
     }
 }

See also:
TecUtilDataValueGetReadableNativeRef(), TecUtilDataValueGetReadableNLRef(), TecUtilDataValueGetReadableCCRef(), TecUtilDataValueGetWritableNativeRef()

FieldData_pa TecUtilDataValueGetReadableNativeRef ( EntIndex_t  Zone,
EntIndex_t  Var 
)

Get a read-only handle to the native data for the specified zone and variable in the data set attached to the current frame.

This function is Thread Safe.

Since:
11.2-0-397
Parameters:
Zone Number of the zone for which to get the field data
Var Number of the variable for which to get the field data
Returns:
A read-only field data handle to the native data for the specified zone and variable in the data set attached to the current frame or NULL if Tecplot was not able to load the data.
Fortran Syntax:
    SUBROUTINE TecUtilDataValueGetReadableNativeRef(
   &           Zone,
   &           Var,
   &           ResultPtr)
    INTEGER*4       Zone
    INTEGER*4       Var
    POINTER         (ResultPtr, Result)

Python Syntax:

  Results = TecUtil.DataValueGetReadableNativeRef(Zone, Var)

  Input:
                  Zone                 int
                  Var                  int
  Output:
    Results[0]    ReturnVal            opaque pointer

Function that loads the values of a field variable into a supplied double precision array. Assume the array is already dimensioned correctly and the dataset, zone, and variable exist. 

 static void ReadVals(double     Var[],
                      EntIndex_t ZoneNum,
                      EntIndex_t VarNum)
 {
   FieldData_pa FieldData = TecUtilDataValueGetReadableNativeRef(ZoneNum, VarNum);
   if (FieldData)
     {
       int i;
       LgIndex_t NumValues = TecUtilDataValueGetCountByRef(FieldData);

       // Remember that the GetByRef function is 1-based....
       for (i = 0; i < NumPointsInZone; i++)
         Var[i] = TecUtilDataValueGetByRef(FieldData, i+1);
     }
 }

See also:
TecUtilDataValueGetReadableDerivedRef(), TecUtilDataValueGetReadableNLRef(), TecUtilDataValueGetReadableCCRef(), TecUtilDataValueGetWritableNativeRef()

FieldData_pa TecUtilDataValueGetReadableNLRef ( EntIndex_t  Zone,
EntIndex_t  Var 
)

Get a read-only handle to the node located data for the specified zone and variable in the data set attached to the current frame.

This function is Thread Safe.

Since:
11.2-0-397
Parameters:
Zone Number of the zone for which to get the field data
Var Number of the variable for which to get the field data
Returns:
A read-only field data handle to the node located data for the specified zone and variable in the data set attached to the current frame or NULL if Tecplot was interrupted or was not able to load or derive the data.
Fortran Syntax:
    SUBROUTINE TecUtilDataValueGetReadableNLRef(
   &           Zone,
   &           Var,
   &           ResultPtr)
    INTEGER*4       Zone
    INTEGER*4       Var
    POINTER         (ResultPtr, Result)

Python Syntax:

  Results = TecUtil.DataValueGetReadableNLRef(Zone, Var)

  Input:
                  Zone                 int
                  Var                  int
  Output:
    Results[0]    ReturnVal            opaque pointer

Function that loads the values of a field variable into a supplied double precision array. Assume the array is already dimensioned correctly and the dataset, zone, and variable exist. 

 static void ReadVals(double     Var[],
                      EntIndex_t ZoneNum,
                      EntIndex_t VarNum)
 {
   FieldData_pa FieldData = TecUtilDataValueGetReadableNLRef(ZoneNum, VarNum);
   if (FieldData)
     {
       int i;
       LgIndex_t NumValues = TecUtilDataValueGetCountByRef(FieldData);

       // Remember that the GetByRef function is 1-based....
       for (i = 0; i < NumPointsInZone; i++)
         Var[i] = TecUtilDataValueGetByRef(FieldData, i+1);
     }
 }

See also:
TecUtilDataValueGetReadableNativeRef(), TecUtilDataValueGetReadableDerivedRef(), TecUtilDataValueGetReadableCCRef(), TecUtilDataValueGetWritableNativeRef()

void TecUtilDataValueGetReadableRawPtr ( EntIndex_t  Zone,
EntIndex_t  Var,
void **  DataPtr,
FieldDataType_e *  FieldDataType 
)

Get a read-only handle to the raw field data in the data set attached to the current frame.

If possible this function provides direct access to a Tecplot variable's internal representation. If performance is not a concern consider using TecUtilDataValueGetByRef(), TecUtilDataValueSetByRef(). If high performance is essential then use TecUtilDataValueArrayGetByRef(), and TecUtilDataValueArraySetByRef() which provide nearly equivalent preformance to direct access. Alternatively for high performance consider using the field data's accessor functions by calling TecUtilDataValueRefGetGetFunc() and TecUtilDataValueRefGetSetFunc(). Note that these high performance functions are a very thin layer over a Tecplot variable's internal representation and unlike the raw field data pointer provided by this function, they are always available. This function is Thread Safe.

Note:
The array is read-only thefore be sure not to change any value. Do not assume that raw data internal to Tecplot remains in the same location at all times. Always call this function again after any event where Tecplot itself may move/alter the raw data.
Since:
11.0-0-007
Parameters:
Zone Number of the zone for which to get the raw field data.
Var Number of the variable for which to get the raw field data.
DataPtr Receives the address of the raw field data. May return NULL if the type is too complex. If the type is too complex, you may use TecUtilDataValueRefGetGetFunc() and TecUtilDataValueRefGetSetFunc() to get functions that will deal with the data at a lower level than TecUtilDataValueGetByRef() and TecUtilDataValueSetByRef().
FieldDataType Receives the data type of the raw field data. The following table shows the possible values for FieldDataType along with the corresponding data type that DataPtr references:
     FieldDataType            DataPtr references
     -------------------------------------------
     FieldDataType_Float      float *
     FieldDataType_Double     double *
     FieldDataType_Int32      Int32_t *
     FieldDataType_Int16      Int16_t *
     FieldDataType_Byte       char *
     FieldDataType_Bit        UInt32_t *
     FieldDataType_Invalid    too complex

Fortran Syntax:

    SUBROUTINE TecUtilDataValueGetReadableRawPtr(
   &           Zone,
   &           Var,
   &           DataPtr,
   &           FieldDataType)
    INTEGER*4       Zone
    INTEGER*4       Var
    POINTER         (DataPtrPtr, DataPtr)
    INTEGER*4       FieldDataType

Python Syntax:

    This function is not supported in Python.

Get the first and second value v