TDMS_AdvancedCreateFile
- Updated2023-02-21
- 4 minute(s) read
TDMS_AdvancedCreateFile
int TDMS_AdvancedCreateFile (char *filePath, TDMSFileFormat fileFormat, unsigned int options, char *name, char *description, char *title, char *author, TDMSFileHandle *file, size_t *sectorSize);
Purpose
Creates a file handle for a new .tdms file that you write using the advanced synchronous or asychronous I/O functions. Pass the new file handle to other TDM Streaming Library functions to modify the file contents.
Call the TDMS_AdvancedCloseFile function to close the file handle when you finish using the file.
Files created with this function store data in the file using the byte order of the system. Unlike the TDMS_CreateFileEx function, this function does not create a .tdms_index file.
 |
Note This function can only create files with a file format version of 2.0 or later. To create a version 1.0 file you must use the TDMS_CreateFileEx function. |
(Linux) This function is not supported.
Parameters
| Input | ||
| Name | Type | Description |
| filePath | char * | The path to the file to create. If this value is not an absolute pathname, then the pathname is relative to the current working directory. |
| fileFormat | TDMSFileFormat | The format of the file to create. This function requires you to specify the 2.0 file format version or later. Use the highest version of the file format supported by your system unless you have a specific need for a previous version. Some functionality in this library is available only when using newer versions of the file format. The 2.0 version of the TDM Streaming file format includes all features from version 1.0, as well as additional features. |
| options | unsigned int | Pass TDMS_CreateFileDisableBuffering 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_CreateFileDisableBuffering option is only supported on Windows operating systems and when using version 2.0 or later of the TDM Streaming file format. Pass TDMS_CreateFileEnableAsynchronousOperations 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_CreateFileDisableBuffering | TDMS_CreateFileEnableAsynchronousOperations To specify none of the flags, pass 0. (Real-Time Module) The TDMS_CreateFileDisableBuffering and TDMS_CreateFileEnableAsynchronousOperations flags are not supported. |
| name | char * | The value of the Name property of the file object. This property is stored in the file and can be accessed with the TDMS_SetFileProperty and TDMS_GetFileProperty functions. |
| description | char * | The value of the Description property of the file object. This property is stored in the file and can be accessed with the TDMS_SetFileProperty and TDMS_GetFileProperty functions. |
| title | char * | The value of the Title property of the file object. This property is stored in the file and can be accessed with the TDMS_SetFileProperty and TDMS_GetFileProperty functions. |
| author | char * | The value of the Author property of the file object. This property is stored in the file and can be accessed with the TDMS_SetFileProperty and TDMS_GetFileProperty functions. |
| 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
© 2016 National Instruments. All rights reserved.
Examples
Refer to the following examples that use the TDMS_AdvancedCreateFile function:
- TDM Streaming\Advanced Read and Write\TDMS Advanced Async Write\TDMS Advanced Async Write.cws
Open example - TDM Streaming\Advanced Read and Write\TDMS Advanced Async Write Throughput Test\TDMS Advanced Async Write Throughput Test.cws
Open example - TDM Streaming\Advanced Read and Write\TDMS Advanced Sync Write\TDMS Advanced Sync Write.cws
Open example