TDMS_AdvancedOpenFile

Download PDF

Updated2023-02-21
4 minute(s) read

int TDMS_AdvancedOpenFile (char *filePath, int readOnly, unsigned int options, TDMSFileHandle *file, size_t *sectorSize);

Purpose

Opens a file handle for an existing .tdms file that you will read or write using the advanced synchronous or asychronous I/O functions. Pass the file handle to other TDM Streaming Library functions to read or modify the file contents.

Call the TDMS_AdvancedCloseFile function to close the file handle when you finish using the file.

Files opened with this function store data in the file using the byte order of the system. Unlike the TDMS_OpenFileEx function, this function does not create a .tdms_index file. If you use this function to open an existing .tdms file that has a corresponding .tdms_index file, this function removes the .tdms_index file.

Note This function can only open files with a file format version of 2.0 or later. To open a version 1.0 file you must use the TDMS_OpenFileEx function.

(Linux) This function is not supported.

Parameters

Input
Name	Type	Description
filePath	char *	The path to the file that will be opened. If this value is not an absolute pathname, then the pathname is relative to the current working directory.
readOnly	int	Specify a nonzero value or select True in the function panel to allow only read access to the file. Specify 0 or select False in the function panel to allow read and write access to the file. If the current user does not have write privileges for the file or if the file is marked read-only, pass a nonzero value for this parameter.
options	unsigned int	Pass TDMS_OpenFileDisableBuffering if you want the TDM Streaming Library to write to and read from this file without Windows system buffering. If you disable system buffering, you must read and write data in multiples of the sector size of the hard disk. This is necessary so that reads and writes will operate on file positions that are aligned on a hard disk sector boundary. By disabling system buffering you can speed up data transfers in certain situations. If you have a small amount of data to transfer you might not notice a difference if you disable buffering. If the file is located on a Redundant Array of Independent Disks (RAID), consider accessing the file without buffering to speed up data transfers. To read the same set of data repeatedly from the computer, consider enabling buffering. The TDMS_OpenFileDisableBuffering option is only supported on Windows operating systems and when using version 2.0 or later of the TDM Streaming file format. Pass TDMS_OpenFileEnableAsynchronousOperations if you want to enable asynchronous reads and writes for the .tdms file. If you do not specify this flag you must use synchronous reads and writes instead. To specify two or more flags, combine them with the bitwise OR operator as shown: TDMS_OpenFileDisableBuffering \| TDMS_OpenFileEnableAsynchronousOperations To specify none of the flags, pass 0. (Real-Time Module) The TDMS_OpenFileDisableBuffering and TDMS_OpenFileEnableAsynchronousOperations flags are not supported.
Output
Name	Type	Description
file	TDMSFileHandle	The handle for the .tdms file. Pass this handle to TDM Streaming Library functions that require a file. Call TDMS_AdvancedCloseFile to close the file handle when you finish using the file.
sectorSize	size_t	The sector size of the hard disk. If you specify the disable buffering option for the options parameter, then several TDM Streaming library functions require you to specify read or write positions and read or write sizes that are based on the sector size of the hard disk. For example, read or write positions must correspond to sector boundaries and read or write sizes must be multiples of the sector size. This parameter provides the sector size which you can use for this purpose. The sector size is not available on all platforms. This function returns 0 for the sector size if it is not available. You can pass NULL for this parameter if you do not want this information.

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

Examples

Refer to the following examples that use the TDMS_AdvancedOpenFile function:

TDM Streaming\Advanced Read and Write\TDMS Advanced Async Read\TDMS Advanced Async Read.cws

Open example
TDM Streaming\Advanced Read and Write\TDMS Advanced Async Read Throughput Test\TDMS Advanced Async Read Throughput Test.cws

Open example
TDM Streaming\Advanced Read and Write\TDMS Advanced Sync Read\TDMS Advanced Sync Read.cws

Open example

LabWindows/CVI