Data Services


Functions

Boolean_t TecUtilZoneDelete (Set_pa ZoneList)
 
Boolean_t TecUtilDataSetDeleteZone (Set_pa ZoneList)
  Deletes the specified set of zones.
Boolean_t TecUtilDataSetDeleteVar (Set_pa VarList)
  Deletes the specified set of variables.
Boolean_t TecUtilDataSetDefVarLoadFinish (Boolean_t IsDataSetOk)
 
Boolean_t TecUtiltDataSetDefVarLoadFinish (Boolean_t IsDataSetOk)
 
Boolean_t TecUtilDataSetAddZone (const char *Name, LgIndex_t IMax, LgIndex_t JMax, LgIndex_t KMax, ZoneType_e ZoneType, FieldDataType_e *VarDataType_Array)
  Add a zone to the data set attached to the current frame.
Boolean_t TecUtilDataSetAddZoneX (ArgList_pa ArgList)
  Add a zone to the current data set.
Boolean_t TecUtilDataSetAddVarX (ArgList_pa ArgList)
  Add a variable to the current data set.
Boolean_t TecUtilDataSetAddVar (const char *VarName, FieldDataType_e *FieldDataType_Array)
  Add a variable to the current data set.
Boolean_t TecUtilDataSetAddPostConvInstr (const char *AddOnIDString, const char *Instructions, const char *RawData)
 
Boolean_t TecUtilDataValueCanMemMapData (EntIndex_t Zone, EntIndex_t Var, MemMapOffset_t Offset, Boolean_t IsDataNativeByteOrder)
 
Boolean_t TecUtilDataValueMemMapData (EntIndex_t Zone, EntIndex_t Var, int FileDescriptor, MemMapOffset_t Offset, Boolean_t IsDataNativeByteOrder)
 
ArbParam_t TecUtilDataNodeGetClientData (NodeMap_pa NodeMap)
  Return the custom load-on-demand client data from a node map handle.
Boolean_t TecUtilDataNodeAutoLOD (EntIndex_t Zone, const char *FileName, FileOffset_t Offset, Boolean_t IsDataNativeByteOrder)
  Specifies where in the data file the data for the specified node map resides.
Boolean_t TecUtilDataNodeCustomLOD (EntIndex_t Zone, LoadOnDemandNodeMapLoad_pf LoadCallback, LoadOnDemandNodeMapUnload_pf UnloadCallback, LoadOnDemandNodeMapCleanup_pf CleanupCallback, ArbParam_t ClientData)
  Registers with Tecplot the load-on-demand callbacks and client data for a node mapping for a specific zone.
Boolean_t TecUtilDataNodeAlloc (EntIndex_t Zone)
  Allocates the space needed for the node mapping.
LgIndex_t TecUtilTecPolyX (ArgList_pa ArgList)
  Writes the face map for polygonal and polyhedral zones to the data file.
Boolean_t TecUtilDataSetLockOn (const char *LockString)
  Lock the data set attached to the current frame.
Boolean_t TecUtilDataSetLockOff (const char *LockString)
  Unlock the data set attached to the current frame.
void TecUtilDataValueGetRawPtr (EntIndex_t Zone, EntIndex_t Var, void **DataPtr, FieldDataType_e *FieldDataType)
 
void TecUtilDataFaceNbrGetRawPtr (EntIndex_t Zone, LgIndex_t **FNPtr)
 
Boolean_t TecUtilDataSetGetInfo (char **DataSetTitle, EntIndex_t *NumZones, EntIndex_t *NumVars)
  Get the title, number of zones, and number of variables of the data set attached to the current frame.
Boolean_t TecUtilDataSetRequiresSaving (void)
 
FieldData_pa TecUtilDataValueGetWritableRef (EntIndex_t Zone, EntIndex_t Var)
 
FieldData_pa TecUtilDataValueGetReadableRef (EntIndex_t Zone, EntIndex_t Var)
 
FieldData_pa TecUtilDataValueGetRef (EntIndex_t Zone, EntIndex_t Var)
 
NodeMap_pa TecUtilDataNodeGetReadableRef (EntIndex_t Zone)
  Get a readable finite-element node map handle to the specified zone in the data set attached to the current frame.
NodeMap_pa TecUtilDataNodeGetWritableRef (EntIndex_t Zone)
  Get a writable finite-element node map handle to the specified zone in the data set attached to the current frame.
LgIndex_t TecUtilDataFaceNbrGetByZone (EntIndex_t Zone, LgIndex_t Element, LgIndex_t Face)
 
LgIndex_t TecUtilDataFaceNbrGetByRef (FaceNeighbor_pa FaceNeighbor, LgIndex_t Element, LgIndex_t Face)
 
ArbParam_t TecUtilDataFaceNbrGetClientData (FaceNeighbor_pa FaceNeighbor)
  Return the custom load-on-demand client data from a face neighbor handle.
Boolean_t TecUtilDataFaceNbrCustomLOD (EntIndex_t Zone, Boolean_t AutoAssignFN, LoadOnDemandFaceNeighborLoad_pf LoadCallback, LoadOnDemandFaceNeighborUnload_pf UnloadCallback, LoadOnDemandFaceNeighborCleanup_pf CleanupCallback, ArbParam_t ClientData)
  Registers with Tecplot the load-on-demand callbacks and client data for the face neighbors for a specific zone.
FaceNeighbor_pa TecUtilDataFaceNbrGetReadableRef (EntIndex_t Zone)
  Get a readable face neighbor handle to the specified zone in the data set attached to the current frame.
void TecUtilDataFaceNbrAssignArrayByRef (FaceNeighbor_pa FaceNeighbor, LgIndex_t DestOffset, LgIndex_t NumNeighbors, const LgIndex_t *NeighborElems)
  Copies the specified number of local one-to-one cell face neighbors from the base of the neighbor element array to the currently open face neighbor assignment sequence starting at the specified destination offset.
Boolean_t TecUtilDataFaceNbrAssignByRef (FaceNeighbor_pa FaceNeighbor, LgIndex_t Element, LgIndex_t Face, Boolean_t NbrsCompObscure, LgIndex_t NumNeighbors, const LgIndex_t *NeighborElems, const EntIndex_t *NeighborZones)
  Sets the boundary connection face neighbors within an open face neighbor assignment sequence for the specified element and face.
SetValueReturnCode_e TecUtilZoneSetBoundary (const char *Attribute, Set_pa ZoneSet, double DValue, ArbParam_t IValue)
 
SetValueReturnCode_e TecUtilZoneSetIJKMode (const char *Attribute, const char *SubAttribute, Set_pa ZoneSet, ArbParam_t IValue)
 

Function Documentation

void TecUtilDataFaceNbrAssignArrayByRef ( FaceNeighbor_pa  FaceNeighbor,
LgIndex_t  DestOffset,
LgIndex_t  NumNeighbors,
const LgIndex_t *  NeighborElems 
)

Copies the specified number of local one-to-one cell face neighbors from the base of the neighbor element array to the currently open face neighbor assignment sequence starting at the specified destination offset.

The face neighbor element array should be organized as follows: E1F1 E1F2 ... E1Fm E2F1 E2F2 ... EnFm where n is the number of elements and m is the number of faces per element. In the above layout E1F1 is the neighboring element of element 1 face 1. This function is Thread Safe.

Note:
If TecUtilDataFaceNbrAssignArrayByRef() is used in conjunction with TecUtilDataFaceNbrAssignByRef() then the local one-to-one face neighbors must be delivered via TecUtilDataFaceNbrAssignArrayByRef() before delivering discrete boundary connection face neighbors via TecUtilDataFaceNbrAssignByRef().
Since:
11.3-0-020
Parameters:
FaceNeighbor Face neighbor handle that was passed to a custom face neighbor load callback.
DestOffset Offset in Tecplot's face neighbor array to begin assigning the supplied neighbor elements.
NumNeighbors Number of neighbor elements to assign to Tecplot's face neighbor array.
NeighborElems An array containing the one based cell face neighbor elements to copy. The first element is assumed to be at the base of the array.
Python Syntax:
  Results = TecUtil.DataFaceNbrAssignArrayByRef(FaceNeighbor, DestOffset, NumNeighbors, NeighborElems)

  Input:
                  FaceNeighbor         opaque pointer
                  DestOffset           int
                  NumNeighbors         int
                  NeighborElems        list of ints
  Output:
    Results[0]    ReturnVal            NONE

Boolean_t TecUtilDataFaceNbrAssignByRef ( FaceNeighbor_pa  FaceNeighbor,
LgIndex_t  Element,
LgIndex_t  Face,
Boolean_t  NbrsCompObscure,
LgIndex_t  NumNeighbors,
const LgIndex_t *  NeighborElems,
const EntIndex_t *  NeighborZones 
)

Sets the boundary connection face neighbors within an open face neighbor assignment sequence for the specified element and face.

This function is Thread Safe.

Parameters:
FaceNeighbor Face neighbor handle that was passed to a custom face neighbor load callback.
Element The one based element number (starts at one).
Face The one based face for which the face neighbor information is desired.
NbrsCompObscure Set to TRUE if the supplied neighbors completely obscure the face.
NumNeighbors Number of neighbors for this face.
NeighborElems Array containing the one based element numbers of the neighbors.
NeighborZones Array containing the one based zone numbers of the neighbors for global neighbors or NULL for local neighbors.
Returns:
TRUE if successful in assigning to the open face neighbor assignment sequence, FALSE otherwise.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilDataFaceNbrAssignByRef(
   &                   FaceNeighborPtr,
   &                   Element,
   &                   Face,
   &                   NbrsCompObscure,
   &                   NumNeighbors,
   &                   NeighborElems,
   &                   NeighborZones)
    POINTER         (FaceNeighborPtr, FaceNeighbor)
    INTEGER*4       Element
    INTEGER*4       Face
    INTEGER*4       NbrsCompObscure
    INTEGER*4       NumNeighbors
    INTEGER*4       NeighborElems
    INTEGER*4       NeighborZones

Python Syntax:

  Results = TecUtil.DataFaceNbrAssignByRef(FaceNeighbor, Element, Face, NbrsCompObscure, NumNeighbors, NeighborElems, NeighborZones)

  Input:
                  FaceNeighbor         opaque pointer
                  Element              int
                  Face                 int
                  NbrsCompObscure      boolean
                  NumNeighbors         int
                  NeighborElems        list of ints
                  NeighborZones        list of ints
  Output:
    Results[0]    ReturnVal            boolean

Boolean_t TecUtilDataFaceNbrCustomLOD ( EntIndex_t  Zone,
Boolean_t  AutoAssignFN,
LoadOnDemandFaceNeighborLoad_pf  LoadCallback,
LoadOnDemandFaceNeighborUnload_pf  UnloadCallback,
LoadOnDemandFaceNeighborCleanup_pf  CleanupCallback,
ArbParam_t  ClientData 
)

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

Tecplot will notify the add-on via the callbacks when the face neighbors need to be loaded, unloaded, and cleaned up.

All callbacks must be written in a thread-safe manner so that Tecplot can make parallel requests to load (and/or unload) multiple zone's face neighbors. The easiest way to write thread-safe callbacks is not to 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.

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 face neighbor. In addition, no state changes should be broadcast by the callbacks.

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

The method for loading and accessing face neighbor data with custom load-on-demand is similar to custom load-on-demand for field data (see ADK Users Manual for details): The add-on supplied LoadCallback() callback is responsible for loading the entire face neighbor data into the Tecplot prepared face neighbor backing. Tecplot is responsible for allocating and freeing the space for the face neighbor backing. In addition, the add-on must supply the CleanupCallback() callback to receive notification of when the face neighbor is no longer needed. Optionally, the add-on may supply the UnloadCallback() callback to receive notification of when the face neighbor is being unloaded. Most add-ons should supply NULL for the UnloadCallback() callback, instructing Tecplot to assume responsibility for unloading the face neighbor and re-loading it in an efficient form. This function is Thread Safe.

Since:
11.3-0-020
Parameters:
Zone Zone for which the face neighbor will now be custom load-on-demand.
AutoAssignFN Indicates if Tecplot should auto assign any remaining face neighbors after the add-on has supplied the boundary connection face neighbors. This is useful when an add-on only needs to deliver a few specific neighbors. See TecUtilDataFaceNbrAssignArrayByRef() and TecUtilDataFaceNbrAssignByRef() for details. Add-ons that wish to supply all the face neighbor connections should set this value to FALSE.
LoadCallback Tecplot calls this callback when the face neighbor is to be loaded. The LoadCallback() callback may never get called if the face neighbor is not needed or it may get called immediately if load-on-demand capabilities are not available. This callback is called asynchronously.
UnloadCallback Most add-ons will supply NULL for this callback. Supplying NULL instructs Tecplot to handle the unloading (and subsequent reloading) of the face neighbor without the intervention of the add-on. If the add-on does supply this callback, Tecplot calls it when the face neighbor is to be unloaded. This query provides the add-on an opportunity to allow or deny a face neighbor 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 face neighbor (i.e. the UnloadCallback() callback should return TRUE). An add-on may also cleanup any private resources that are not needed when the face neighbor is unloaded, however the add-on must still maintain enough information to load the face neighbor again if requested by Tecplot. The UnloadCallback() callback may never get called if the face neighbor does not need to be unloaded nor will the UnloadCallback() callback necessarily be called before the CleanupCallback() callback. This callback is called asynchronously.
CleanupCallback Tecplot calls this callback when the face neighbor 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 face neighbor. After a face neighbor is cleaned up Tecplot will never again request it to be loaded. Tecplot may or may not call the UnloadCallback() callback before calling the CleanupCallback() callback. Additionally, the CleanupCallback() callback will be called even if the face neighbor was never loaded. This callback is called asynchronously.
ClientData Private client data needed by the custom load-on-demand callbacks to perform the duties of loading, unloading, and cleaning up the face neighbor. Tecplot stores the client data in the face neighbor structure and must be retrieved by the callbacks using TecUtilDataFaceNbrGetClientData(). The client data should ONLY be retrieved in response to a custom load, unload, or cleanup callback. At no other time is the request valid.
Returns:
TRUE if successful, FALSE otherwise.
Following is an example of how to create a face neighbor using the Custom Load on Demand. 
   typedef struct
     {
       char* DataFileName;
       long  SeekOffset;
       ... other information needed to load face neighbor data
     } MyFaceNbrClientData_s;

   Boolean_t MyFaceNbrLoader(FaceNeighbor_pa FaceNeighbor)
   {
     REQUIRE(VALID_REF(FaceNeighbor));

     MyFaceNbrClientData_s *MyClientData = (MyFaceNbrClientData_s *)TecUtilDataFaceNbrGetClientData(FaceNeighbor);

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

     // seek to the place in the file where the face neighbor data is located
     IsOk = IsOk && (fseek(MyDataFile, MyClientData->SeekOffset, SEEK_SET) == 0);
     if (IsOk)
       {
         // load the data into the zone's face neighbor
         IsOk = ReadMyFaceNbrDataIntoZone(MyDataFile,
                                          MyClientData,
                                          FaceNeighbor);
       }

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

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

   Boolean_t MyFaceNbrUnload(FaceNeighbor_pa FaceNeighbor)
   {
     REQUIRE(VALID_REF(FaceNeighbor));

     // 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 face neighbor.
     Boolean_t Result = TRUE; // ...tell Tecplot to go ahead and unload the face neighbor

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

   void MyFaceNbrCleanup(FaceNeighbor_pa FaceNeighbor)
   {
     REQUIRE(VALID_REF(FaceNeighbor));

     MyFaceNbrClientData_s *MyClientData = (MyFaceNbrClientData_s *)TecUtilDataFaceNbrGetClientData(FaceNeighbor);

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

   .
   .
   .
   MyFaceNbrClientData_s *MyClientData = (MyFaceNbrClientData_s *)malloc(sizeof(MyFaceNbrClientData_s));
   const char *MyDataFileName = "MyDataFileName.dat";
   MyClientData->MyDataFileName = (char *)malloc(strlen(MyDataFileName)+1);
   strcpy(MyClientData->MyDataFileName, MyDataFileName);
   MyClientData->SeekOffset = ... determined somewhere else
   ...initialize any other client data information needed to load face neighbor data
   IsOk = TecUtilDataFaceNbrCustomLOD(3,
                                      TRUE,            // AutoAssignFN
                                      MyFaceNbrLoader,
                                      MyFaceNbrUnload, // most add-ons should pass NULL instead of MyFaceNbrUnload
                                      MyFaceNbrCleanup,
                                      (ArbParam_t)MyClientData);

Python Syntax:

    This function is not supported in Python.

See also:
TecUtilDataConnectShare(), TecUtilDataFaceNbrAssignArrayByRef(), TecUtilDataFaceNbrAssignByRef(), TecUtilMemoryChangeNotify()

LgIndex_t TecUtilDataFaceNbrGetByRef ( FaceNeighbor_pa  FaceNeighbor,
LgIndex_t  Element,
LgIndex_t  Face 
)

Deprecated:
Please use TecUtilDataFaceNbrGetNbrByRef() instead.

Python Syntax:

  Results = TecUtil.DataFaceNbrGetByRef(FaceNeighbor, Element, Face)

  Input:
                  FaceNeighbor         opaque pointer
                  Element              int
                  Face                 int
  Output:
    Results[0]    ReturnVal            int

LgIndex_t TecUtilDataFaceNbrGetByZone ( EntIndex_t  Zone,
LgIndex_t  Element,
LgIndex_t  Face 
)

Deprecated:
Please use TecUtilDataFaceNbrGetNbrByRef() instead.

Python Syntax:

  Results = TecUtil.DataFaceNbrGetByZone(Zone, Element, Face)

  Input:
                  Zone                 int
                  Element              int
                  Face                 int
  Output:
    Results[0]    ReturnVal            int

ArbParam_t TecUtilDataFaceNbrGetClientData ( FaceNeighbor_pa  FaceNeighbor  ) 

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

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

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


     Boolean_t MyFaceNbrLoader(FaceNeighbor_pa FaceNeighbor)
     {
       Boolean_t Result;
       MyClientData_s *MyClientData = (MyClientData_s *)TecUtilDataFaceNbrGetClientData(FaceNeighbor);

       // load the custom face neighbor using client data
       .
       .
       .

     return Result;
   }

See also:
TecUtilDataFaceNbrCustomLOD()

void TecUtilDataFaceNbrGetRawPtr ( EntIndex_t  Zone,
LgIndex_t **  FNPtr 
)

Deprecated:
There is no replacement for this function. Please do not access face neighbors using raw pointers, use TecUtilDataFaceNbrGetReadableRef() or TecUtilDataFaceNbrGetWriteableRef() instead.

Python Syntax:

    This function is not supported in Python.

FaceNeighbor_pa TecUtilDataFaceNbrGetReadableRef ( EntIndex_t  Zone  ) 

Get a readable face neighbor handle to the specified zone in the data set attached to the current frame.

This function is Thread Safe.

Parameters:
Zone Number of the zone for which to get the readable face neighbor handle.
Returns:
The face neighbor handle to the specified zone in the data set attached to the current frame or NULL if it was not able to load it.
Fortran Syntax:
    SUBROUTINE TecUtilDataFaceNbrGetReadableRef(
   &           Zone,
   &           ResultPtr)
    INTEGER*4       Zone
    POINTER         (ResultPtr, Result)

Python Syntax:

  Results = TecUtil.DataFaceNbrGetReadableRef(Zone)

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

Boolean_t TecUtilDataNodeAlloc ( EntIndex_t  Zone  ) 

Allocates the space needed for the node mapping.

This function is used in conjunction with deferred node map creation. See the SV_DEFERNODEMAPCREATION option for TecUtilDataSetAddZoneX() for details.

Since:
11.3-0-010
Parameters:
Zone The zone needing the node mapping allocated.
Returns:
TRUE if the node mapping was successfully allocated, FALSE otherwise.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilDataNodeAlloc(
   &                   Zone)
    INTEGER*4       Zone

Python Syntax:

  Results = TecUtil.DataNodeAlloc(Zone)

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

Allocate the node map of zone 3.

   IsOk = TecUtilDataNodeAlloc(3);

See also:
TecUtilDataConnectShare(), TecUtilDataNodeCustomLOD()

Boolean_t TecUtilDataNodeAutoLOD ( EntIndex_t  Zone,
const char *  FileName,
FileOffset_t  Offset,
Boolean_t  IsDataNativeByteOrder 
)

Specifies where in the data file the data for the specified node map resides.

The node map must be laid out in memory exactly as expected by Tecplot where zero based node numbers for each element are specified consecutively. Using this information Tecplot will automatically load and unload the node map 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 node map at unspecified times.

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

Since:
11.3-0-010
Parameters:
Zone The zone number of the node map to have Tecplot automatically load on demand.
FileName Data file name containing the node map data laid out using Tecplot's binary data format.
Offset Absolute offset to the start of the node map data in the file.
IsDataNativeByteOrder Indicates if the byte ordering of the data in the file matches the machine's native byte ordering.
Returns:
TRUE if the node map is setup for auto loading, FALSE otherwise.
See also:
TecUtilDataNodeCustomLOD()
Python Syntax:
  Results = TecUtil.DataNodeAutoLOD(Zone, FileName, Offset, IsDataNativeByteOrder)

  Input:
                  Zone                 int
                  FileName             string
                  Offset               long
                  IsDataNativeByteOrder boolean
  Output:
    Results[0]    ReturnVal            boolean

Boolean_t TecUtilDataNodeCustomLOD ( EntIndex_t  Zone,
LoadOnDemandNodeMapLoad_pf  LoadCallback,
LoadOnDemandNodeMapUnload_pf  UnloadCallback,
LoadOnDemandNodeMapCleanup_pf  CleanupCallback,
ArbParam_t  ClientData 
)

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

Tecplot will notify the add-on via the callbacks when the node mapping needs to be loaded, unloaded, and cleaned up.

All callbacks must be written in a thread-safe manner so that Tecplot can make parallel requests to load (and/or unload) multiple node mappings. The easiest way to write thread-safe callbacks is not to 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.

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 node mapping. In addition, no state changes should be broadcast by the callbacks.

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

The method for loading and accessing node map data with custom load-on-demand is similar to custom load-on-demand for field data (see ADK Users Manual for details): The add-on supplied LoadCallback() callback is responsible for loading the entire node map data into the Tecplot prepared node map backing. Tecplot is responsible for allocating and freeing the space for the node map backing. In addition, the add-on must supply the CleanupCallback() callback to receive notification of when the node map is no longer needed. Optionally, the add-on may supply the UnloadCallback() callback to receive notification of when the node map is being unloaded. Most add-ons should supply NULL for the UnloadCallback() callback, instructing Tecplot to assume responsibility for unloading the node map and re-loading it in an efficient form.

Since:
11.3-0-010
Parameters:
Zone Zone for which the node map will now be custom load-on-demand.
LoadCallback Tecplot calls this callback when the node map is to be loaded. The LoadCallback() callback may never get called if the node map is not needed or it may get called immediately if load-on-demand capabilities are not available. This callback is called asynchronously.
UnloadCallback Most add-ons will supply NULL for this callback. Supplying NULL instructs Tecplot to handle the unloading (and subsequent reloading) of the node map without the intervention of the add-on. If the add-on does supply this callback, Tecplot calls it when the node map is to be unloaded. This query provides the add-on an opportunity to allow or deny a node map 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 node map (i.e. the UnloadCallback() callback should return TRUE). An add-on may also cleanup any private resources that are not needed when the node map is unloaded, however the add-on must still maintain enough information to load the node map again if requested by Tecplot. The UnloadCallback() callback may never get called if the node map does not need to be unloaded nor will the UnloadCallback() callback necessarily be called before the CleanupCallback() callback. This callback is called asynchronously.
CleanupCallback Tecplot calls this callback when the node map 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 node map. After a node map is cleaned up Tecplot will never again request it to be loaded. Tecplot may or may not call the UnloadCallback() callback before calling the CleanupCallback() callback. Additionally, the CleanupCallback() callback will be called even if the node map was never loaded. This callback is called asynchronously.
ClientData Private client data needed by the custom load-on-demand callbacks to perform the duties of loading, unloading, and cleaning up the node map. Tecplot stores the client data in the node map structure and must be retrieved by the callbacks using TecUtilDataNodeGetClientData(). The client data should ONLY be retrieved in response to a custom load, unload, or cleanup callback. At no other time is the request valid.
Returns:
TRUE if successful, FALSE otherwise.
Following is an example of how to create a node map using the Custom Load on Demand. 
   typedef struct
     {
       char* DataFileName;
       long  SeekOffset;
       ... other information needed to load node map data
     } MyNodeMapClientData_s;

   Boolean_t MyNodeMapLoader(NodeMap_pa NodeMap)
   {
     REQUIRE(VALID_REF(NodeMap));

     MyNodeMapClientData_s *MyClientData = (MyNodeMapClientData_s *)TecUtilDataNodeGetClientData(NodeMap);

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

     // seek to the place in the file where the node map data is located
     IsOk = IsOk && (fseek(MyDataFile, MyClientData->SeekOffset, SEEK_SET) == 0);
     if (IsOk)
       {
         // load the data into the zone's node map
         IsOk = ReadMyNodeMapDataIntoZone(MyDataFile, MyClientData, NodeMap);
       }

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

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

   Boolean_t MyNodeMapUnload(NodeMap_pa NodeMap)
   {
     REQUIRE(VALID_REF(NodeMap));

     // 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 node map.
     Boolean_t Result = TRUE; // ...tell Tecplot to go ahead and unload the node map

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

   void MyNodeMapCleanup(NodeMap_pa NodeMap)
   {
     REQUIRE(VALID_REF(NodeMap));

     MyNodeMapClientData_s *MyClientData = (MyNodeMapClientData_s *)TecUtilDataNodeGetClientData(NodeMap);

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

   .
   .
   .
   MyNodeMapClientData_s *MyClientData = (MyNodeMapClientData_s *)malloc(sizeof(MyNodeMapClientData_s));
   const char *MyDataFileName = "MyDataFileName.dat";
   MyClientData->MyDataFileName = (char *)malloc(strlen(MyDataFileName)+1);
   strcpy(MyClientData->MyDataFileName, MyDataFileName);
   MyClientData->SeekOffset = ... determined somewhere else
   ...initialize any other client data information needed to load node map data
   IsOk = TecUtilDataNodeCustomLOD(3,
                                   MyNodeMapLoader,
                                   MyNodeMapUnload, // most add-ons should pass NULL instead of MyNodeMapUnload
                                   MyNodeMapCleanup,
                                   (ArbParam_t)MyClientData);

Python Syntax:

    This function is not supported in Python.

See also:
TecUtilDataNodeAlloc(), TecUtilDataConnectShare(), TecUtilDataNodeArraySetByRef(), TecUtilMemoryChangeNotify()

ArbParam_t TecUtilDataNodeGetClientData ( NodeMap_pa  NodeMap  ) 

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

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

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


     Boolean_t MyNodeMapLoader(NodeMap_pa NodeMap)
     {
       Boolean_t Result;
       MyClientData_s *MyClientData = (MyClientData_s *)TecUtilDataNodeGetClientData(NodeMap);

       // load the custom node map using client data
       .
       .
       .

     return Result;
   }

See also:
TecUtilDataNodeCustomLOD()

NodeMap_pa TecUtilDataNodeGetReadableRef ( EntIndex_t  Zone  ) 

Get a readable finite-element node map handle to the specified zone in the data set attached to the current frame.

This function is Thread Safe.

Parameters:
Zone Number of the zone for which to get the readable node map handle. This must be a finite-element zone
Returns:
The finite-element node map handle to the specified zone in the data set attached to the current frame or NULL if it was not able to load it.
Fortran Syntax:
    SUBROUTINE TecUtilDataNodeGetReadableRef(
   &           Zone,
   &           ResultPtr)
    INTEGER*4       Zone
    POINTER         (ResultPtr, Result)

Python Syntax:

  Results = TecUtil.DataNodeGetReadableRef(Zone)

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

NodeMap_pa TecUtilDataNodeGetWritableRef ( EntIndex_t  Zone  ) 

Get a writable finite-element node map handle to the specified zone in the data set attached to the current frame.

This function is Thread Safe.

Parameters:
Zone Number of the zone for which to get the writable node map handle. This must be a finite-element zone
Returns:
The finite-element node map handle to the specified zone in the data set attached to the current frame or NULL if it was not able to load it and create a writable copy.
Fortran Syntax:
    SUBROUTINE TecUtilDataNodeGetWritableRef(
   &           Zone,
   &           ResultPtr)
    INTEGER*4       Zone
    POINTER         (ResultPtr, Result)

Python Syntax:

  Results = TecUtil.DataNodeGetWritableRef(Zone)

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

Boolean_t TecUtilDataSetAddPostConvInstr ( const char *  AddOnIDString,
const char *  Instructions,
const char *  RawData 
)

Deprecated:
Please use TecUtilDataSetAddJournalCommand() instead.

Python Syntax:

  Results = TecUtil.DataSetAddPostConvInstr(AddOnIDString, Instructions, RawData)

  Input:
                  AddOnIDString        string
                  Instructions         string
                  RawData              string
  Output:
    Results[0]    ReturnVal            boolean

Boolean_t TecUtilDataSetAddVar ( const char *  VarName,
FieldDataType_e *  FieldDataType_Array 
)

Add a variable to the current data set.

Call TecUtilStateChanged() after adding a variable. This function is superceded by TecUtilDataSetAddVarX().

Parameters:
VarName Name of the variable being added.
FieldDataType_Array This is an array of the data types to use for each zone (i.e., it must be dimensioned by the number of zones). If you pass NULL, the data types of the variables in variable 1 of the existing data set are used. The possible choices are: FieldDataType_Float, FieldDataType_Double, FieldDataType_Int32, FieldDataType_Int16, FieldDataType_Byte, or FieldDataType_Bit.
Returns:
Returns TRUE if the variable was added successfully, otherwise FALSE.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilDataSetAddVar(
   &                   VarName,
   &                   VarFieldDataType)
    CHARACTER*(*)   AddOnIDString
    INTEGER*4       VarFieldDataType(1)

Python Syntax:

  Results = TecUtil.DataSetAddVar(VarName, FieldDataType_Array)

  Input:
                  VarName              string
                  FieldDataType_Array  list of TecVals.FieldDataType_e constants
  Output:
    Results[0]    ReturnVal            boolean

Note:
VarFieldDataType is an INTEGER*4 array dimensioned by the number of zones.
Add a variable to the current data set:

   if ( TecUtilDataSetAddVar("New Variable", NULL) )
     {
       // New variable is always last variable. 
       EntIndex_t newvar;
       TecUtilDataSetGetInfo(NULL, NULL, &newvar);
       // Fill new var with values for all zones. 
       .
       .
       .
       // Inform Tecplot a variable has been added. 
       TecUtilStateChanged(StateChange_VarsAdded,
                           (ArbParam_t)NULL);
     }

Boolean_t TecUtilDataSetAddVarX ( ArgList_pa  ArgList  ) 

Add a variable to the current data set.

Make sure and call TecUtilStateChanged() after adding variables. Note that all settings for variable properties apply ONLY to those specific variables created in the existing set of zones.

Parameters:
ArgList Set of Arglist entries. This is built using calls to TecUtilArgListAppendXXXX functions.

Arglist Values

SV_NAME
Type: char *
Arg Function: TecUtilArgListAppendString()
Required: Yes
Notes: Name of newly created variable.

SV_VARDATATYPE
Type: FieldDataType_e *
Arg Function: TecUtilArgListAppendArray()
Default: NULL
Required: No
Notes: Array of FieldDataType_e dimensioned by the number of zones currently defined in the dataset where each member specifies type of data. If you set this to NULL then FieldData_Float is used if this is the first variable in the dataset otherwise the type from the first variable for each zone is used.

SV_VALUELOCATION
Type: ValueLocation_e *
Arg Function: TecUtilArgListAppendArray()
Default: NULL
Required: No
Notes: Array of ValueLocation_e dimensioned by the number of zones currently defined in the dataset where each member specifies the data value location. If NULL then ValueLocation_Nodal is used.

SV_TRYSHAREVARWITHALLZONES
Type: Boolean_t
Arg Function: TecUtilArgListAppendInt()
Default: FALSE
Required: No
Notes: A boolean property that instructs Tecplot to share the variable with all applicable zones in the dataset. This option is mutually exclusive with SV_DEFERVARCREATION. To use variable sharing with SV_DEFERVARCREATION you must use TecUtilDataValueShare().

SV_DEFERVARCREATION
Type: Boolean_t
Arg Function: TecUtilArgListAppendInt()
Default: FALSE
Required: No
Notes: Indicates if the creation of the variable should be deferred until the variable data is ready to be populated or shared. A data loader should allocate, share, auto or custom load the variable with TecUtilDataValueAlloc(), TecUtilDataValueShare(), TecUtilDataValueAutoLOD(), or TecUtilDataValueCustomLOD() before returning control to Tecplot. Any variables that have not been allocated, shared, auto or custom loaded will become passive variables. Passive variables always return zero for every point but do not participate in Tecplot's min/max calculations such as when Tecplot is choosing good contour levels based on the available data. This option is mutually exclusive with SV_VARSHAREZONELIST.


Returns:
TRUE if the variable was added, FALSE otherwise.
Fortran Syntax:
    INTEGER*4 FUNCTION TecUtilDataSetAddVarX(ArgListPtr)
    POINTER (ArgListPtr, ArgList)

Python Syntax:

  Results = TecUtil.DataSetAddVarX(ArgList)

  Input:
                  ArgList              dictionary
  Output:
    Results[0]    ReturnVal            boolean

Add a variable called "newvar" to the dataset.

   ArgList_pa ArgList;
   FieldDataType_e *VarDataType;   // dimension by zone 
   ValueLocation_e *ValueLocation; // dimension by zone 
   
   TecUtilLockStart(AddOnID);
   
   ...
   
   //
   // Allocate and populate VarDataType and ValueLocation
   // with the appropriate value for each zone.
   
   ...
   
   // collect the function arguments 
   ArgList = TecUtilArgListAlloc();
   TecUtilArgListAppendString(ArgList,
                              SV_NAME,
                              "newvar");
   TecUtilArgListAppendArray(ArgList,
                             SV_VARDATATYPE,
                             (void *)VarDataType);
   TecUtilArgListAppendArray(ArgList,
                             SV_VALUELOCATION,
                             (void *)ValueLocation);
   TecUtilArgListAppendInt(ArgList,
                           SV_SHAREVARWITHALLZONES,
                           FALSE);
   
   // add the variable for all zones in the dataset 
   TecUtilDataSetAddVarX(ArgList);
   
   // cleanup 
   TecUtilArgListDealloc(&ArgList);
   
   // Inform Tecplot that a variable was added 
   
   VarsAdded = TecUtilSetAlloc(FALSE);
   if (VarsAdded)
     {
       EntIndex_t NumVars;
       TecUtilDataSetGetInfo((char **)NULL,
                             (EntIndex_t *)NULL,
                             &NumVars);
       TecUtilSetAddMember(VarsAdded,NumVars,FALSE);
       TecUtilStateChanged(StateChange_VarsAdded,
                           (ArbParam_t)VarsAdded);
       TecUtilSetDealloc(&VarsAdded);
     }
   
   ...
   
   // cleanup VarDataType and ValueLocation allocations 
   
   TecUtilLockFinish(AddOnID);

See also:
TecUtilDataSetAddZoneX()

Boolean_t TecUtilDataSetAddZone ( const char *  Name,
LgIndex_t  IMax,
LgIndex_t  JMax,
LgIndex_t  KMax,
ZoneType_e  ZoneType,
FieldDataType_e *  VarDataType_Array 
)

Add a zone to the data set attached to the current frame.

This function call does not load any data into the zone. In the case of finite-element zones, this function also does not assign values to the connectivity list. This function only allocates space for the zone. Call TecUtilStateChanged() after adding a zone.

Parameters:
Name Name of the zone.
IMax I-Dimension of the zone if ordered. If the zone is finite-element then IMax is the number of data points.
JMax J-Dimension of the zone if ordered. If the zone is finite-element then IMax is the number of data points, JMax is the number of elements, and KMax is the number of faces. KMax is only used for FEPolygon and FEPolyhedron fe zone types.
KMax K-Dimension of the zone. If the zone is a finite-element polyhedral or polygon, KMax is the number of faces. KMax is not used for other finite-element zone types.
ZoneType The possible values are: ZoneType_Ordered, ZoneType_FETriangle, ZoneType_FEQuad, ZoneType_FETetra, ZoneType_FEBrick, ZoneType_FELineSeg, ZoneType_FEPolygon or ZoneType_FEPolyhedron For polytope zones you must subsequently give the face mapping a data backing by calling TecUtilDataFaceMapAlloc() or TecUtilDataConnectShare() or give it deferred load-on-demand status by calling TecUtilDataFaceMapCustomLOD().
VarDataType_Array This is an array of the data types to use for each variable. If you set this to NULL then the data types of the variables in zone 1 of the existing data set are used or FieldDataType_Float if this is the first zone. The possible values are: FieldDataType_Float, FieldDataType_Double, FieldDataType_Int32, FieldDataType_Int16, FieldDataType_Byte, or FieldDataType_Bit.
Returns:
Returns TRUE if the zone was successfully added, otherwise FALSE.
Add a 10 by 10 by 10 zone to the current data set:

Fortran Syntax:

    INTEGER*4 FUNCTION TecUtilDataSetAddZone(
   &                   ZoneName,
   &                   IMax,
   &                   JMax,
   &                   KMax,
   &                   ZoneType,
   &                   VarFieldDataType)
    CHARACTER*(*)   AddOnIDString
    INTEGER*4       IMax
    INTEGER*4       JMax
    INTEGER*4       KMax
    INTEGER*4       ZoneType
    INTEGER*4       VarFieldDataType(1)

Python Syntax:

  Results = TecUtil.DataSetAddZone(Name, IMax, JMax, KMax, ZoneType, VarDataType_Array)

  Input:
                  Name                 string
                  IMax                 int
                  JMax                 int
                  KMax                 int
                  ZoneType             ZoneType_e  (defined in TecVals.py)
                  VarDataType_Array    list of TecVals.FieldDataType_e constants
  Output:
    Results[0]    ReturnVal            boolean

Note:
VarFieldDataType is an INTEGER*4 array dimensioned by the number of variables.
   if ( TecUtilDataSetAddZone("New Ordered Zone", 10, 10, 1,
                              ZoneType_Ordered, NULL) )
     {
       Set_pa zones_added = TecUtilSetAlloc(TRUE);
       // new zone is always last zone 
       EntIndex_t newzone;
       TecUtilDataSetGetInfo(NULL, &newzone, NULL);
       // fill new zone with values for all variables 
       .
       .
       .
       // inform Tecplot of new zone 
       TecUtilSetAddMember(zones_added, newzone, TRUE);
       TecUtilStateChanged(StateChange_ZonesAdded,
                           (ArbParam_t)zones_added);
       TecUtilSetDealloc(&zones_added);
     }

Boolean_t TecUtilDataSetAddZoneX ( ArgList_pa  ArgList  ) 

Add a zone to the current data set.

This function was extended from TecUtilDataSetAddZone() to allow addition of zones in locations where zombie zones currently exist in a data set. For a simpler, less flexible interface use TecUtilDataSetAddZone() instead. Be sure to call TecUtilStateChanged() after adding zones. Note that all settings for variable properties apply ONLY to those specific variables in this newly created zone and do not apply to any other variables in other zones created in the future.

Parameters:
ArgList Set of Arglist entries. This is built using calls to TecUtilArgListAppendXXXX functions.

Arglist Values

SV_NAME
Type: char *
Arg Function: TecUtilArgListAppendString()
Required: Yes
Notes: The name of the zone to create.

SV_PARENTZONE
Type: LgIndex_t
Arg Function: TecUtilArgListAppendInt()
Default: 0
Required: No
Notes: A value of zero indicates that this zone is not associated with a parent zone otherwise a value greater than zero is considered this zone's parent. A zone may not specify itself as its own parent. With a parent zone association, Tecplot can generate surface-restricted streamtraces.

SV_STRANDID
Type: LgIndex_t
Arg Function: TecUtilArgListAppendInt()
Default: 0
Required: No
Notes: If 0 no strand ID is assigned to the zone otherwise values greater than zero are used to assoicated zones with a particular strand.

SV_SOLUTIONTIME
Type: double
Arg Function: TecUtilArgListAppendDouble()
Default: 0.0
Required: No
Notes: The solution time for the zone.

SV_ZONETYPE
Type: ZoneType_e
Arg Function: TecUtilArgListAppendInt()
Default: ZoneType_Ordered
Required: No
Notes: The possible values are: ZoneType_Ordered, ZoneType_FETriangle,