TDMS .NET Library

Measurement Studio 2019 Help

Edition Date: May 2019

Part Number: 375857B-01

»View Product Info
Download Help (Windows Only)

May 7, 2019, 375857B-01

Technical Data Management Streaming (TDMS) is a file format based on the National Instruments TDM data model used to stream data to disk.

Note Note   This topic applies to the following editions: Enterprise, Professional.

You can use the TDMS .NET class library to describe, store, and read measurement data that is optimized for high-speed data streaming and post processing. You can use files created with the TDMS .NET class library in LabVIEW, LabWindows™/CVI™, and DIAdem, and the TDMS .NET class library can use files created by these applications.

Note Note   The National Instruments TDM data model supports two file formats, TDM and TDM Streaming ( .tdms ); however, Measurement Studio only supports the .tdms file format.

TDMS File Hierarchy

TDMS files organize data into three levels of hierarchy: TdmsFile, TdmsChannelGroup, and TdmsChannel. TdmsFile can contain several TdmsChannelGroup objects, and each TdmsChannelGroup can contain several TdmsChannel objects. The following outline illustrates a TDMS file hierarchy:

  • TdmsFile
    • TdmsChannelGroup
      • TdmsChannel
        • Data
      • TdmsChannel
        • Data
    • TdmsChannelGroup
      • TdmsChannel
        • Data
      • TdmsChannel
        • Data

You can define TdmsProperty for each level in the hierarchy: TdmsFile, TdmsChannelGroup, and TdmsChannel. With TdmsProperty, you define a Name, a TdmsPropertyDataType, and a value. For TdmsChannel, you use TdmsDataType to specify the data type.

TDMS File Format Version

When creating a new Tdms file, you can choose whether you want to use the TDMS 1.0 file format version or the TDMS 2.0 file format version. The TDMS 1.0 file format version is compatible with all versions of Tdms and Measurement Studio 8.6 and later. The TDMS 2.0 file format version is compatible with TDMS 2.0, which is installed by default with Measurement Studio 2009 and later. You can install TDMS 2.0 separately to read the TDMS 2.0 file format version with Measurement Studio 8.6 and later; however, TDMS 2.0 features are only available with Measurement Studio 2009 and later. Measurement Studio applications written with Measurement Studio 8.6 or 8.6.1 can read TDMS 2.0 file format versions without recompiling if you have installed TDMS 2.0.

The TDMS 2.0 file format version provides increased performance and additional features not supported by the TDMS 1.0 file format version. National Instruments recommends you use the TDMS 2.0 file format version unless you require the TDMS 1.0 file format version for backwards compatibility.

The TDMS 2.0 file format version provides the following features compared to TDMS 1.0:
  • Faster Windows file access
  • Improved streaming performance
  • Support for writing interleaved data
  • Support for endian conversion
  • Improved defragmenting
  • Improved compatibility between National Instruments TDMS applications

Converting Between File Formats

You can use the static TdmsFile.ConvertFileFormat method to convert a Tdms file between the TDMS 1.0 and TDMS 2.0 file format versions. The file must not currently be open by the Tdms API when you use this method.

For more information and to download the TDMS 2.0 installer, refer to TDMS 2.0 FAQ.

TDMS Collections

You can use methods, such as GetChannelGroups, GetChannels, or GetProperties, on a parent class to access a collection of objects associated with that parent object. You can use the resulting collection object to add new items or iterate through the list of items. Adding items through the collection updates the collection object, but requires that you first access the collection before modifying it. You can also add new items by using add methods such as AddChannelGroup, AddChannel, or AddProperty. Using the add methods requires fewer lines of code, but does not update existing collection objects. To obtain the updated collection object, you call GetChannelGroups, GetChannels, or GetProperties again.

The following example demonstrates two ways to add a TdmsChannelGroup to a TdmsFile.

VB.NET


' Delete any pre-existing TDMS files.
TdmsFile.Delete("C:\file.tdms")

' Create a new TDMS file. 
Dim file As TdmsFile = New TdmsFile("C:\file.tdms", New TdmsFileOptions())

' Add a channel group using the collection. 
Dim channelGroupName As String = "Group 1" 
Dim channelGroup As TdmsChannelGroup = New TdmsChannelGroup(channelGroupName)
Dim channelGroups As TdmsChannelGroupCollection = file.GetChannelGroups()
channelGroups.Add(channelGroup)

' Add a channel group using AddChannelGroup. This does not 
' update the channelGroups collection. 
Dim channelGroup2 As TdmsChannelGroup = file.AddChannelGroup("Group 2")

' Close the file.
file.Close()

C#


// Delete any pre-existing TDMS files.
TdmsFile.Delete(@"C:\file.tdms");

// Create a new TDMS file.
TdmsFile file = new TdmsFile(@"C:\file.tdms", new TdmsFileOptions());

// Add a channel group using the collection. 
string channelGroupName = "Group 1";
TdmsChannelGroup channelGroup = new TdmsChannelGroup(channelGroupName);
TdmsChannelGroupCollection channelGroups = file.GetChannelGroups();
channelGroups.Add(channelGroup);

// Add a channel group using AddChannelGroup. This does not 
// update the channelGroups collection.
TdmsChannelGroup channelGroup2 = file.AddChannelGroup("Group 2");

// Close the file.
file.Close();

Managing TDMS Files

TDMS files have a binary index file with the extension *.tdms_index. The tdms_index file includes consolidated information for all the attributes and pointers in the bulk data file and speeds up access to the data while reading. The tdms_index file is automatically re-created if deleted or removed.

You can create or open TDMS files for Read or ReadWrite access. If the file name specified already exists on disk, the existing file opens.

Any modifications made to TDMS objects, including writing data, is cached until the TdmsFile is saved. If AutoSave is true, the TdmsFile is automatically saved to disk after every change. If AutoSave is false, you must call Save explicitly to write the cached data to disk. Some operations in the TDMS .NET Library API require the TdmsFile to be saved before the operation can be performed to ensure that all information is up to date.

Each time TDMS data is written to disk, a block of data is recorded to the file, which may contain several channels. This prevents the data for a single channel from being written contiguously across multiple writes. Defragment reorganizes the file by channel to optimize read operations. In this way, you can take the performance penalty only once by defragmenting the TDMS file offline rather than with every read. For example, you can acquire and store data very rapidly and then defragment the file before performing any read operations.

WAS THIS ARTICLE HELPFUL?

Not Helpful