TDMS_AdvancedSyncRead

Download PDF

Updated2023-02-21
3 minute(s) read

int TDMS_AdvancedSyncRead (TDMSFileHandle file, void *samples, size_t numberOfSamples, TDMSDataType dataType, size_t *numberOfSamplesRead);

Purpose

Reads data from the specified file.

(Linux) This function is not supported.

Parameters

Input

Name Type Description

file TDMSFileHandle The file handle. You obtain this handle from TDMS_AdvancedOpenFile or TDMS_AdvancedCreateFile. You must not specify the enable asynchronous operations option when you open or create the file.

numberOfSamples

size_t

The number of samples to read.

Note If you specified the disable buffering option when you opened the file using TDMS_AdvancedOpenFile or TDMS_AdvancedCreateFile, then the number of samples should correspond to a number of bytes that is an even multiple of the sector size of the hard disk. This is necessary so that subsequent calls to this function will read from a position in the file that is aligned on a hard disk sector boundary. This requirement does not apply to the last call to this function that corresponds to a single call to TDMS_ConfigureAsyncReads. The sector size of the hard disk is available as an output parameter from TDMS_AdvancedOpenFile or TDMS_AdvancedCreateFile.

dataType TDMSDataType The data type of the samples to read. This function does not support reading samples of type string.

Output

Name Type Description

samples

void *

An array that receives the samples from the specified file.

This array must be large enough to hold at least the number of samples specified by the numberOfSamples parameter.

The type of this array should match the type of the samples you are reading. This function does not support reading samples of type string.

If the type of the samples you are reading is TDMS_Timestamp, you must pass an array of type CVIAbsoluteTime. Refer to the Absolute Time functions in the Utility Library for more information about this type.

Note The alignment of the pointer value passed for this parameter can significantly impact the performance of this read operation. The performance impact varies depending on the hardware being used. National Instruments recommends a minimal alignment of 512 bytes and a preferred alignment of 4096 bytes. Call TDMS_AllocateAlignedMemory to allocate aligned memory for this parameter.

numberOfSamplesRead size_t The number of samples actually read from the file. This value can be less than numberOfSamples if the end of the file is reached before the specified number of samples have been read.

Return Value

Name	Type	Description
status	int	Return value indicating whether the function was successful. Unless otherwise stated, zero represents successful execution and a negative number represents the error code. Error codes are defined in cvi\include\cvitdms.h.

Additional Information

Library: TDM Streaming Library

Include file: cvitdms.h

LabWindows/CVI compatibility: LabWindows/CVI 2013 and later

Example

Refer to TDM Streaming\Advanced Read and Write\TDMS Advanced Sync Read\TDMS Advanced Sync Read.cws for an example of using the TDMS_AdvancedSyncRead function.