TDMS Set Properties Function

LabVIEW 2017 Help

Edition Date: March 2017

Part Number: 371361P-01

»View Product Info
Download Help (Windows Only)

Owning Palette: TDM Streaming VIs and Functions

Requires: Base Development System

Copyright: (c) 2017 National Instruments. All rights reserved.

Sets the properties of the specified .tdms file, channel group, or channel. If you wire the group name and channel name inputs with values, the function writes the properties at the channel level. Wiring only the group name input with a value writes the properties at the channel group level. If both group name and channel name inputs contain no values, the properties become file-specific. If you wire the channel name input with a value, you must also wire a value to the group name input.

You must close the reference to the .tdms file or flush data to the .tdms file for changes to take effect.

Details  Example

property values specifies the property values of the specified channel group, channel, or .tdms file. This input accepts the following data types:
  • Signed or unsigned integers
  • Floating-point numbers, including the following specific data types:
    • Single-precision and double-precision floating-point numbers
    • Complex single-precision and double-precision floating-point numbers
    • (Windows) Extended-precision floating-point numbers
  • Timestamps
  • Booleans
  • Alphanumeric strings that do not contain null characters
  • Variants that contain any of the data types specified above
If you want to set more than one property using the same function, you can wire a 1D array of any of the previously specified data types to the property values input. Each value in the array corresponds to a single property. However, a single property cannot hold an array of values.
property names specifies the property names of the specified channel group, channel, or .tdms file.
tdms file specifies a reference number to the .tdms file on which to perform the operation. Use the TDMS Open function to open the refnum.
group name specifies the channel group to perform the operation on. If you wire a value to the channel name input, you must also wire a value to this input.
channel name specifies the channel to perform the operation on. If you wire a value to this input, you must also wire a value to the group name input.
error in describes error conditions that occur before this node runs. This input provides standard error in functionality.
tdms file out returns a TDMS file reference to the .tdms file on which you performed the operation.
group name out returns the name of the channel group on which you performed the operation.
channel name out returns the name of the channel on which you performed the operation.
error out contains error information. This output provides standard error out functionality.

TDMS Set Properties Details

This section lists all properties that you might encounter when you use a .tdms file. The first table lists all properties you might find in a .tdms file. The second table lists all properties that do not exist in a .tdms file but which you can use to perform certain actions. You can write these properties as waveform attributes to a .tdms file. However, some of these properties might not appear as waveform attributes when you read the waveform data from the .tdms file. The Available as a Waveform Attribute? column provides information about whether a property is available as a waveform attribute. If the data type of a property is not valid, LabVIEW treats the property as a customized property and the property will not perform as described in the table.

You can use the TDMS Get Properties function to obtain the values of these properties. Use the TDMS Set Properties function to change the values of these properties.

The following table lists all properties you might find in a .tdms file.

Property Name Data Type Access Available in File Format Versions Available as a Waveform Attribute? Description
name String Read/write 2.0 Yes Specifies the object name, such as the root name, group name, or channel name, in a .tdms file.
NI_ArrayColumn 32-bit signed integer numeric Read only 1.0 and 2.0 No Indicates the index of a column in a 2D array. This property appears in a .tdms file only if you write a 2D array of data to the file.
NI_ChannelLength 64-bit unsigned integer numeric Read only 1.0 and 2.0 Yes Represents the number of values in a channel of a .tdms file.
NI_DataType 16-bit unsigned integer numeric Read only 1.0 and 2.0 Yes Represents the data type of a channel. The value is an integer that corresponds to a LabVIEW type code.
NI_DigitalCompression Boolean Read only 1.0 and 2.0 No Indicates whether a digital table is compressed or not. A value of 1 indicates that the digital table is compressed. If the digital table is not compressed, this property does not appear.
NI_DigitalLine 32-bit signed integer numeric Read only 1.0 and 2.0 No Indicates the index of a row in a digital table.
NI_DigitalNumberOfLines 32-bit signed integer numeric Read only 1.0 and 2.0 No Indicates the number of rows in a digital table.
NI_Number_Of_Scales 32-bit unsigned integer numeric Read/write 2.0 No Specifies the number of scales to use when you read data from a .tdms file. For example, if a .tdms file has five scales and you set the value of NI_Number_Of_Scales to 4, LabVIEW applies only the first four scales to the data when you read the .tdms file.
NI_Scale[n]_config, where n represents the order of the scale and config represents the configuration of the scale. N/A Read/write 2.0 No Specifies the scaling information for the data in a .tdms file. You can create more than one scale in a .tdms file.
Note  National Instruments recommends you use the TDMS Create Scaling Information VI to create scales.
NI_Scaling_Status String Read/write 2.0 No Specifies whether LabVIEW scales data when reading the data from a .tdms file. If the value is unscaled and the .tdms file contains one or more scales, LabVIEW scales the data. If the value is scaled, LabVIEW does not scale the data.
unit_string String Read/write 1.0 and 2.0 No Specifies the unit of the channel data in a .tdms file.
wf_increment Double Read/write 1.0 and 2.0 No Represents the increment between two consecutive samples on the x-axis.
wf_samples 32-bit signed integer numeric Read/write 1.0 and 2.0 No Represents the number of samples in the first data chunk of the waveform you write to a .tdms file. The value must be greater than zero.
wf_start_offset Double Read only 1.0 and 2.0 No Frequency-domain data and histogram results use this value as the first value on the x-axis.
wf_start_time Timestamp Read only 1.0 and 2.0 No Represents the time at which the waveform was acquired or generated. This property can be zero if the time information is relative or the waveform is not in time domain.
wf_time_pref String Read only 1.0 and 2.0 No Indicates whether LabVIEW interprets the x-axis data in absolute time or relative time.
wf_xname String Read only 1.0 and 2.0 No Indicates the name of the x-axis of the waveform.
wf_xunit_string String Read only 1.0 and 2.0 No Indicates the unit text of the x-axis.

In addition to the properties in the table above, a .tdms file might also contain other waveform attributes.

The following table lists all properties that do not exist in a .tdms file, but you can use them to perform certain actions.

Property Name Data Type Access Available in File Format Versions Available as a Waveform Attribute? Description
NI_DiskCacheSize 32-bit unsigned integer numeric Read/write 2.0 Yes You can use the NI_DiskCacheSize property to improve the .tdms data writing performance by allocating a specific amount of cache size in memory for the data. LabVIEW writes .tdms data in bytes per file. This property is valid only when the disable buffering? input of the TDMS Open function is TRUE. The default value for this property is approximately 2 MB. Wire a different value to the property values input of the TDMS Set Properties function to change the cache size. A greater value for the NI_DiskCacheSize property usually can improve the writing performance; however, a greater value also requires more computer resources.
NI_DiskGapSize 32-bit unsigned integer numeric Read/write 2.0 Yes You can use the NI_DiskGapSize property to improve the .tdms data reading performance when reading discontinuous data. This property is valid only when the disable buffering? input of the TDMS Open function is TRUE. The value of the NI_DiskGapSize property is a multiple of the sector size of the local hard disk. The default value for this property is 10. If the data gap in the .tdms file is less than the value of the NI_DiskGapSize property, the TDMS Read function can read all data from the file at one time. If the data gap in the .tdms file is greater than the value of the NI_DiskGapSize property, the TDMS Read function reads each piece of data one at a time until this function finishes reading all data. Wire a value to the property values input of the TDMS Set Properties function to change the gap size.
Note  Obtaining the optimal reading and writing performance is a trial-and-error process. The same configuration might not return the same optimal performance on different computers. You might need to adjust the property values after you deploy an application from one computer to another.
NI_InMemoryFileSize 64-bit signed integer numeric Read only 2.0 Yes You can use the NI_InMemoryFileSize property to return the file size of the .tdms file in memory.
NI_InMemoryWriteBlockSize 64-bit signed integer numeric Read/write 2.0 Yes You can use the NI_InMemoryWriteBlockSize property to allocate the block size in memory for writing data. The default value for this property is 10 MB. The value range for this property is [1 KB, 1 GB]. A higher value for this property usually can improve the in-memory writing performance by allocating fewer blocks; however, a greater value also requires more computer resources. You must set this property before the write operation begins. Otherwise, LabVIEW returns an error.
NI_MinimumBufferSize 32-bit unsigned integer numeric Read/write 1.0 and 2.0 Yes You can use the NI_MinimumBufferSize property to improve the .tdms data writing performance by writing to a file less often. This property can reduce the size of a .tdms file by controlling the number of times the data is written to disk. The NI_MinimumBufferSize property is valid only if the data layout input of the TDMS Write function is decimated. By default, the value of the NI_MinimumBufferSize property is zero. If you set the value at the group level, this function also sets the value of underlying channels whose value is zero. If you set the value at the file level, this function also sets the value of underlying groups and channels whose value is zero. Use of this property and the NI_DiskCacheSize property affects file buffering with .tdms files.
NI_UpdateChannelName String Write only 1.0 and 2.0 Yes You can use the TDMS Set Properties function to rename groups and channels in .tdms files. Wire NI_UpdateGroupName to the property names input if you want to rename a group and wire NI_UpdateChannelName to the property names input if you want to rename a channel. Wire the new group or channel names to the property values input and wire the group or channel names that you want to replace to the group name or channel name input. If the groups or channels you wire to group name or channel name do not exist, LabVIEW creates new groups or channels with the new names.
NI_UpdateGroupName

Example

Refer to the TDMS Write Time Domain Data VI in the labview\examples\File IO\TDMS\Standard Read and Write directory for an example of using the TDMS Set Properties function.

WAS THIS ARTICLE HELPFUL?

Not Helpful