TDMS_AdvancedAsyncRead

int TDMS_AdvancedAsyncRead (TDMSFileHandle file, void *samples, size_t numberOfSamples, TDMSDataType dataType, TDMSAsyncReadCallbackPtr callback, void *callbackData, int *readProcessFinished);

Purpose

Reads data from the specified .tdms file asynchronously.

This function can issue additional asynchronous reads while executing previously issued asynchronous reads in the background. When the number of asynchronous reads in the background reaches the maximum value, this function waits until a previously issued asynchronous read completes before issuing an additional asynchronous read. If the previously issued asynchronous read does not complete within the timeout value, this function returns error code TDMS_OperationTimedOut. Call TDMS_ConfigureAsyncReads to configure the maximum number of asynchronous reads and the timeout value.

Call TDMS_GetAsyncReadStatus to query the number of pending asynchronous reads.

(Linux) This function is not supported.

(Real-Time Module) 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 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.
callback	TDMSAsyncReadCallbackPtr	The function that the library calls when the asynchronous read operation is complete or fails due to an error. The library calls this function asynchronously in a worker thread. The TDM Streaming Library always calls your callbacks in the same order in which you issue the corresponding calls to this function. The function you pass for this parameter must have the following prototype: void CVICALLBACK Callback (TDMSFileHandle file, int error, void *samples, size_t numSamplesRead, void *callbackData); Upon entry to the callback, the file parameter contains the same file handle passed to this function. The error parameter contains an error code value indicating the reason the read operation failed or zero if the read operation succeeded. The samples parameter contains the same array pointer passed to this function. The numSamplesRead parameter contains the number of samples actually read from the file. This value can be less than the numberOfSamples value passed to this function. This happens when the number of samples remaining from the total passed to the totalSamplesToRead parameter of TDMS_ConfigureAsyncReads is less the value of numberOfSamples passed to this function. The callbackData parameter of the callback contains the value you provide in the callbackData parameter of this function. You can use this parameter to pass any additional information you choose. Note  Return from this function as soon as possible to avoid blocking other asynchronous operations on the same file. If needed, you can use PostDeferredCallToThread or the Thread Pool functions to process this event in a different thread. From within this callback function, you must also avoid calling any functions in the TDM Streaming Library to perform an operation using the same file or any channel groups or channels within that file. The TDM Streaming Library will return an error in that case in order to prevent a deadlock.
callbackData	void *	Specifies a pointer to user-defined data that the TDM Streaming Library will pass to your callback as the callbackData parameter. Do not pass the address of a local variable or any other variable or memory that might not be valid when the callback is executed. If you do not need callback data you can pass NULL for this parameter.
Output
Name	Type	Description
samples	void *	An array that receives the samples from the specified file. Because the read operation is asynchronous the array will not contain the samples read from the file immediately after this function call returns. Instead you must wait until the asynchronous operation completes before referencing the array contents. You can be notified when the asynchronous operation completes using the callback parameter. 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.
readProcessFinished	int	Indicates whether this call completes the read operations configured by a corresponding call to TDMS_ConfigureAsyncReads. This value will be zero if additional calls to this function are needed and non-zero if no additional calls are needed. You can use this value to determine when to exit a loop that calls this function on each iteration. The read operations configured by a corresponding call to TDMS_ConfigureAsyncReads are complete if this function reaches the end of the file or finishes reading the number of samples specified by the totalSamplesToRead parameter of TDMS_ConfigureAsyncReads.

Return Value

Additional Information

Library: TDM Streaming Library

Include file: cvitdms.h

LabWindows/CVI compatibility: LabWindows/CVI 2013 and later

© 2016 National Instruments. All rights reserved.