DIAdem Connectivity Library Help

January 2010

This help file contains function reference about the DIAdem Connectivity Library functions.

For more information about this help file, refer to the following topics:

Using Help

Important Information

Technical Support and Professional Services

To comment on National Instruments documentation, refer to the National Instruments Web site.

© 2006–2010 National Instruments Corporation. All rights reserved.


Using Help

Conventions

Navigating Help

Searching Help

Printing Help File Topics


Conventions

This help file uses the following formatting and typographical conventions:

» | The » symbol leads you through nested menu items and dialog box options to a final action. The sequence File»Page Setup»Options directs you to pull down the File menu, select the Page Setup item, and select Options from the last dialog box.
 | This icon denotes a note, which alerts you to important information.
bold | Bold text denotes items that you must select or click in the software, such as menu items and dialog box options. Bold text also denotes parameter names.
green | Underlined text in this color denotes a link to a help topic, help file, or Web address.
italic | Italic text denotes variables, emphasis, cross–references, or an introduction to a key concept. Italic text also denotes text that is a placeholder for a word or value that you must supply.
monospace | Text in this font denotes text or characters that you should enter from the keyboard, sections of code, programming examples, and syntax examples. This font is also used for the proper names of disk drives, paths, directories, programs, subprograms, subroutines, device names, functions, operations, variables, filenames, and extensions.
monospace bold | Bold text in this font denotes the messages and responses that the computer automatically prints to the screen. This font also emphasizes lines of code that are different from the other examples.
monospace italic | Italic text in this font denotes text that is a placeholder for a word or value that you must supply.


Navigating Help (Windows Only)

To navigate this help file, use the Contents, Index, and Search tabs to the left of this window or use the following toolbar buttons located above the tabs:

  • Hide—Hides the navigation pane from view.
  • Locate—Locates the currently displayed topic in the Contents tab, allowing you to view related topics.
  • Back—Displays the previously viewed topic.
  • Forward—Displays the topic you viewed before clicking the Back button.
  • Options—Displays a list of commands and viewing options for the help file.


Searching Help (Windows Only)

Use the Search tab to the left of this window to locate content in this help file. If you want to search for words in a certain order, such as "related documentation," add quotation marks around the search words as shown in the example. Searching for terms on the Search tab allows you to quickly locate specific information and information in topics that are not included on the Contents tab.

Wildcards

You also can search using asterisk (*) or question mark (?) wildcards. Use the asterisk wildcard to return topics that contain a certain string. For example, a search for "prog*" lists topics that contain the words "program," "programmatically," "progress," and so on.

Use the question mark wildcard as a substitute for a single character in a search term. For example, "?ext" lists topics that contain the words "next," "text," and so on.

Note Wildcard searching will not work on Simplified Chinese, Traditional Chinese, Japanese, and Korean systems.

Nested Expressions

Use nested expressions to combine searches to further refine a search. You can use Boolean expressions and wildcards in a nested expression. For example, "example AND (program OR VI)" lists topics that contain "example program" or "example VI." You cannot nest expressions more than five levels.

Boolean Expressions

Click the [image] button to add Boolean expressions to a search. The following Boolean operators are available:

  • AND (default)—Returns topics that contain both search terms. You do not need to specify this operator unless you are using nested expressions.
  • OR—Returns topics that contain either the first or second term.
  • NOT—Returns topics that contain the first term without the second term.
  • NEAR—Returns topics that contain both terms within eight words of each other.

Search Options

Use the following checkboxes on the Search tab to customize a search:

  • Search previous results—Narrows the results from a search that returned too many topics. You must remove the checkmark from this checkbox to search all topics.
  • Match similar words—Broadens a search to return topics that contain words similar to the search terms. For example, a search for "program" lists topics that include the words "programs," "programming," and so on.
  • Search titles only—Searches only in the titles of topics.


Printing Help File Topics (Windows Only)

Complete the following steps to print an entire book from the Contents tab:

  1. Right-click the book.
  2. Select Print from the shortcut menu to display the Print Topics dialog box.
  3. Select the Print the selected heading and all subtopics option.
    Note Select Print the selected topic if you want to print the single topic you have selected in the Contents tab.
  4. Click the OK button.

Printing PDF Documents

This help file may contain links to PDF documents. To print PDF documents, click the print button located on the Adobe Acrobat Viewer toolbar.


DIAdem Connectivity Library

DIAdem Connectivity Library Overview

This section describes the functions in the DIAdem Connectivity Library. The DIAdem Connectivity Library provides functions that you can use to log test data in National Instruments DIAdem file format (.tdm). You can then load the files directly into DIAdem for analysis.

The DIAdem Connectivity Library contains functions to manage files; add channels and channel groups to a file; store data values within a channel; read data values from a channel; and get and set properties on files, channel groups, and channels.


DIAdem Connectivity Library Functions

Function Tree, DIAdem Connectivity Library

Class/Panel Name | Function Name
Object Management |
Create File | DDC_CreateFile
Add Channel Group | DDC_AddChannelGroup
Add Channel | DDC_AddChannel
Save File | DDC_SaveFile
Close File | DDC_CloseFile
Open File | DDC_OpenFileEx
Advanced |
Remove Channel Group | DDC_RemoveChannelGroup
Remove Channel | DDC_RemoveChannel
Close Channel Group | DDC_CloseChannelGroup
Close Channel | DDC_CloseChannel
Obsolete |
Open File | DDC_OpenFile
Data Storage |
Set Data Values | DDC_SetDataValues
Append Data Values | DDC_AppendDataValues
Replace Data Values | DDC_ReplaceDataValues
Data Retrieval |
Enumeration |
Get Num Channel Groups | DDC_GetNumChannelGroups
Get Channel Groups | DDC_GetChannelGroups
Get Num Channels | DDC_GetNumChannels
Get Channels | DDC_GetChannels
Get Num Data Values | DDC_GetNumDataValues
Get Data Values | DDC_GetDataValues
Get Data Type | DDC_GetDataType
Properties |
File |
Set File Property | DDC_SetFileProperty
Get File Property | DDC_GetFileProperty
Get File String Property Length | DDC_GetFileStringPropertyLength
Create File Property | DDC_CreateFileProperty
File Property Exists | DDC_FilePropertyExists
Get Num File Properties | DDC_GetNumFileProperties
Get File Property Names | DDC_GetFilePropertyNames
Get File Property Type | DDC_GetFilePropertyType
Channel Group |
Set Channel Group Property | DDC_SetChannelGroupProperty
Get Channel Group Property | DDC_GetChannelGroupProperty
Get Channel Group String Property Length | DDC_GetChannelGroupStringPropertyLength
Create Channel Group Property | DDC_CreateChannelGroupProperty
Channel Group Property Exists | DDC_ChannelGroupPropertyExists
Get Num Channel Group Properties | DDC_GetNumChannelGroupProperties
Get Channel Group Property Names | DDC_GetChannelGroupPropertyNames
Get Channel Group Property Type | DDC_GetChannelGroupPropertyType
Channel |
Set Channel Property | DDC_SetChannelProperty
Get Channel Property | DDC_GetChannelProperty
Get Channel String Property Length | DDC_GetChannelStringPropertyLength
Create Channel Property | DDC_CreateChannelProperty
Channel Property Exists | DDC_ChannelPropertyExists
Get Num Channel Properties | DDC_GetNumChannelProperties
Get Channel Property Names | DDC_GetChannelPropertyNames
Get Channel Property Type | DDC_GetChannelPropertyType
Type-Safe Functions for Non-C Users |
Data Storage |
Set Data Values UInt8 | DDC_SetDataValuesUInt8
Set Data Values Int16 | DDC_SetDataValuesInt16
Set Data Values Int32 | DDC_SetDataValuesInt32
Set Data Values Float | DDC_SetDataValuesFloat
Set Data Values Double | DDC_SetDataValuesDouble
Set Data Values String | DDC_SetDataValuesString
Set Data Values Timestamp Components | DDC_SetDataValuesTimestampComponents
Append Data Values UInt8 | DDC_AppendDataValuesUInt8
Append Data Values Int16 | DDC_AppendDataValuesInt16
Append Data Values Int32 | DDC_AppendDataValuesInt32
Append Data Values Float | DDC_AppendDataValuesFloat
Append Data Values Double | DDC_AppendDataValuesDouble
Append Data Values String | DDC_AppendDataValuesString
Append Data Values Timestamp Components | DDC_AppendDataValuesTimestampComponents
Replace Data Values UInt8 | DDC_ReplaceDataValuesUInt8
Replace Data Values Int16 | DDC_ReplaceDataValuesInt16
Replace Data Values Int32 | DDC_ReplaceDataValuesInt32
Replace Data Values Float | DDC_ReplaceDataValuesFloat
Replace Data Values Double | DDC_ReplaceDataValuesDouble
Replace Data Values String | DDC_ReplaceDataValuesString
Replace Data Values Timestamp Components | DDC_ReplaceDataValuesTimestampComponents
Data Retrieval |
Get Data Values UInt8 | DDC_GetDataValuesUInt8
Get Data Values Int16 | DDC_GetDataValuesInt16
Get Data Values Int32 | DDC_GetDataValuesInt32
Get Data Values Float | DDC_GetDataValuesFloat
Get Data Values Double | DDC_GetDataValuesDouble
Get Data Values String | DDC_GetDataValuesString
Get Data Values Timestamp Components | DDC_GetDataValuesTimestampComponents
Properties |
File |
Set File Property UInt8 | DDC_SetFilePropertyUInt8
Set File Property Int16 | DDC_SetFilePropertyInt16
Set File Property Int32 | DDC_SetFilePropertyInt32
Set File Property Float | DDC_SetFilePropertyFloat
Set File Property Double | DDC_SetFilePropertyDouble
Set File Property String | DDC_SetFilePropertyString
Set File Property Timestamp Components | DDC_SetFilePropertyTimestampComponents
Get File Property UInt8 | DDC_GetFilePropertyUInt8
Get File Property Int16 | DDC_GetFilePropertyInt16
Get File Property Int32 | DDC_GetFilePropertyInt32
Get File Property Float | DDC_GetFilePropertyFloat
Get File Property Double | DDC_GetFilePropertyDouble
Get File Property String | DDC_GetFilePropertyString
Get File Property Timestamp Components | DDC_GetFilePropertyTimestampComponents
Create File Property UInt8 | DDC_CreateFilePropertyUInt8
Create File Property Int16 | DDC_CreateFilePropertyInt16
Create File Property Int32 | DDC_CreateFilePropertyInt32
Create File Property Float | DDC_CreateFilePropertyFloat
Create File Property Double | DDC_CreateFilePropertyDouble
Create File Property String | DDC_CreateFilePropertyString
Create File Property Timestamp Components | DDC_CreateFilePropertyTimestampComponents
Get File Property Name From Index | DDC_GetFilePropertyNameFromIndex
Get File Property Name Length From Index | DDC_GetFilePropertyNameLengthFromIndex
Channel Group |
Set Channel Group Property UInt8 | DDC_SetChannelGroupPropertyUInt8
Set Channel Group Property Int16 | DDC_SetChannelGroupPropertyInt16
Set Channel Group Property Int32 | DDC_SetChannelGroupPropertyInt32
Set Channel Group Property Float | DDC_SetChannelGroupPropertyFloat
Set Channel Group Property Double | DDC_SetChannelGroupPropertyDouble
Set Channel Group Property String | DDC_SetChannelGroupPropertyString
Set Channel Group Property Timestamp Components | DDC_SetChannelGroupPropertyTimestampComponents
Get Channel Property UInt8 | DDC_GetChannelGroupPropertyUInt8
Get Channel Property Int16 | DDC_GetChannelGroupPropertyInt16
Get Channel Property Int32 | DDC_GetChannelGroupPropertyInt32
Get Channel Property Float | DDC_GetChannelGroupPropertyFloat
Get Channel Property Double | DDC_GetChannelGroupPropertyDouble
Get Channel Property String | DDC_GetChannelGroupPropertyString
Get Channel Group Property Timestamp Components | DDC_GetChannelPropertyTimestampComponents
Create Channel Group Property UInt8 | DDC_CreateChannelGroupPropertyUInt8
Create Channel Group Property Int16 | DDC_CreateChannelGroupPropertyInt16
Create Channel Group Property Int32 | DDC_CreateChannelGroupPropertyInt32
Create Channel Group Property Float | DDC_CreateChannelGroupPropertyFloat
Create Channel Group Property Double | DDC_CreateChannelGroupPropertyDouble
Create Channel Group Property String | DDC_CreateChannelGroupPropertyString
Create Channel Group Property Timestamp Components | DDC_CreateChannelGroupPropertyTimestampComponents
Get Channel Group Property Name From Index | DDC_GetChannelGroupPropertyNameFromIndex
Get Channel Group Property Name Length From Index | DDC_GetChannelGroupPropertyNameLengthFromIndex
Channel |
Set Channel Property UInt8 | DDC_SetChannelPropertyUInt8
Set Channel Property Int16 | DDC_SetChannelPropertyInt16
Set Channel Property Int32 | DDC_SetChannelPropertyInt32
Set Channel Property Float | DDC_SetChannelPropertyFloat
Set Channel Property Double | DDC_SetChannelPropertyDouble
Set Channel Property String | DDC_SetChannelPropertyString
Set Channel Property Timestamp Components | DDC_SetChannelPropertyTimestampComponents
Get Channel Property UInt8 | DDC_GetChannelPropertyUInt8
Get Channel Property Int16 | DDC_GetChannelPropertyInt16
Get Channel Property Int32 | DDC_GetChannelPropertyInt32
Get Channel Property Float | DDC_GetChannelPropertyFloat
Get Channel Property Double | DDC_GetChannelPropertyDouble
Get Channel Property String | DDC_GetChannelPropertyString
Get Channel Property Timestamp Components | DDC_GetChannelPropertyTimestampComponents
Create Channel Property UInt8 | DDC_CreateChannelPropertyUInt8
Create Channel Property Int16 | DDC_CreateChannelPropertyInt16
Create Channel Property Int32 | DDC_CreateChannelPropertyInt32
Create Channel Property Float | DDC_CreateChannelPropertyFloat
Create Channel Property Double | DDC_CreateChannelPropertyDouble
Create Channel Property String | DDC_CreateChannelPropertyString
Create Channel Property Timestamp Components | DDC_CreateChannelPropertyTimestampComponents
Get Channel Property Name From Index | DDC_GetChannelPropertyNameFromIndex
Get Channel Property Name Length From Index | DDC_GetChannelPropertyNameLengthFromIndex
Miscellaneous |
Get Library Error Description | DDC_GetLibraryErrorDescription
Free Memory | DDC_FreeMemory


DIAdem Connectivity Library Error Codes

If an error condition occurs during a call to any of the functions in the DIAdem Connectivity Library, the status return value contains the error code. This code is a nonzero value that specifies the type of error that occurred. Error codes are negative numbers. The following table lists the currently defined error codes and their associated meanings.

Error codes are defined in nilibddc.h.

Code | Defined Constant | Error Message
-6201 | DDC_OutOfMemory | The library could not allocate memory.
-6202 | DDC_InvalidArgument | An invalid argument was passed to the library.
-6203 | DDC_InvalidDataType | An invalid data type was passed to the library.
-6204 | DDC_UnexpectedError | An unexpected error occurred in the library.
-6205 | DDC_UsiCouldNotBeLoaded | The USI engine could not be loaded.
-6206 | DDC_InvalidFileHandle | An invalid file handle was passed to the library.
-6207 | DDC_InvalidChannelGroupHandle | An invalid channel group handle was passed to the library.
-6208 | DDC_InvalidChannelHandle | An invalid channel handle was passed to the library.
-6209 | DDC_FileDoesNotExist | The file passed to the library does not exist.
-6210 | DDC_CannotWriteToReadOnlyFile | The file passed to the library is read only and cannot be modified.
-6211 | DDC_StorageCouldNotBeOpened | The storage could not be opened.
-6212 | DDC_FileAlreadyExists | The file passed to the library already exists and cannot be created.
-6213 | DDC_PropertyDoesNotExist | The property passed to the library does not exist.
-6214 | DDC_PropertyDoesNotContainData | The property passed to the library does not have a value.
-6215 | DDC_PropertyIsNotAScalar | The value of the property passed to the library is an array and not a scalar.
-6216 | DDC_DataObjectTypeNotFound | The object type passed to the library does not exist.
-6217 | DDC_NotImplemented | The current implementation does not support this operation.
-6218 | DDC_CouldNotSaveFile | The file could not be saved.
-6219 | DDC_MaximumNumberOfDataValuesExceeded | The request would exceed the maximum number of data values for a channel.
-6220 | DDC_InvalidChannelName | An invalid channel name was passed to the library.
-6221 | DDC_DuplicateChannelName | The channel group already contains a channel with this name.
-6222 | DDC_DataTypeNotSupported | The current implementation does not support this data type.
-6223 | DDC_TDMStreamingPluginMustBeInstalled | The TDM Streaming plug-in must be installed for this operation.
-6224 | DDC_FileAccessDenied | File access denied.
-6225 | DDC_InvalidTimeValue | The specified time value is invalid.
-6226 | DDC_ReplaceNotSupportedForSavedTDMSData | The replace operation is not supported on data that has already been saved to a TDM Streaming file.
-6227 | DDC_PropertyDataTypeMismatch | The data type of the property does not match the expected data type.
-6228 | DDC_ChannelDataTypeMismatch | The data type of the channel does not match the expected data type.


DDC_AddChannel

int DDC_AddChannel (DDCChannelGroupHandle channelGroup, DDCDataType dataType, const char *name, const char *description, const char *unitString, DDCChannelHandle *channel);

Purpose

Adds a new channel to a channel group. A valid channel group should contain one or more channels.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The handle of the channel group that will contain the new channel.
dataType DDCDataType The data type of the new channel. The data for this channel must match the specified data type.

If you choose DDC_Timestamp as the data type of a new channel, you must use the CVIAbsoluteTime type when you read or write data to that channel. You can use this type with DDC_SetDataValues, DDC_AppendDataValues, DDC_ReplaceDataValues, and DDC_GetDataValues. Refer to the Absolute Time functions in the Utility Library for more information about this data type.

If you choose DDC_Timestamp as the data type of a new channel, you must use the timestamp component functions when you read or write data to that channel. The timestamp component functions include DDC_SetDataValuesTimestampComponents, DDC_AppendDataValuesTimestampComponents, DDC_ReplaceDataValuesTimestampComponents, and DDC_GetDataValuesTimestampComponents.
name | const char * | The value of the Name property of the channel object. This property is stored in the channel and can be accessed with the DDC_SetChannelProperty and DDC_GetChannelProperty functions.
description | const char * | The value of the Description property of the channel object. This property is stored in the channel and can be accessed with the DDC_SetChannelProperty and DDC_GetChannelProperty functions.
unitString | const char * | The value of the Unit String property of the channel object. This property is stored in the channel and can be accessed with the DDC_SetChannelProperty and DDC_GetChannelProperty functions.
Output
Name | Type | Description
channel DDCChannelHandle The handle for the new channel. Pass this handle to other DIAdem Connectivity Library functions that require a channel.

This handle will automatically be discarded when the containing file handle is closed with DDC_CloseFile. To discard the channel handle explicitly, call the DDC_CloseChannel function.

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 nilibddc.h.


DDC_AddChannelGroup

int DDC_AddChannelGroup (DDCFileHandle file, const char *name, const char *description, DDCChannelGroupHandle *channelGroup);

Purpose

Adds a new channel group to a file. A valid file should contain one or more channel groups.

Parameters

Input
Name | Type | Description
file | DDCFileHandle | The handle of the file that will contain the new channel group. You obtain this handle from the DDC_OpenFile or DDC_CreateFile function.
name | const char * | The value of the Name property of the channel group object. This property is stored in the channel group and can be accessed with the DDC_SetChannelGroupProperty and DDC_GetChannelGroupProperty functions.
description | const char * | The value of the Description property of the channel group object. This property is stored in the channel group and can be accessed with the DDC_SetChannelGroupProperty and DDC_GetChannelGroupProperty functions.
Output
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The handle for the new channel group. Pass this handle to other DIAdem Connectivity Library functions that require a channel group. This handle will automatically be discarded when the containing file handle is closed with DDC_CloseFile. To discard the channel group handle explicitly, call the DDC_CloseChannelGroup function.

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 nilibddc.h.


DDC_AppendDataValues

int DDC_AppendDataValues (DDCChannelHandle channel, void *values, size_t numberOfValues);

Purpose

Appends data values for the specified channel. DDC_AppendDataValues adds new data values after existing data values.

Note Note If you are using this library from a language other than C or C++, you should consider using the type-safe version of this function.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The handle of the channel that contains the new data values.
values void * An array of data values.

The type of this array must match the data type of the specified channel. You can call DDC_GetDataType to get the data type of a channel.

If the data type of the specified channel is DDC_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.

If the data type of the specified channel is string, you must pass an array of type character pointer (char *). The following code illustrates one way to pass an array of strings:

char *values[] = {"one", "two", "three", "four", "five"};
DDC_AppendDataValues (channel, values, 5);

If the data type of the specified channel is DDC_Timestamp, you must call DDC_AppendDataValuesTimestampComponents instead of this function.
numberOfValues | size_t | The number of values in the array specified by the values parameter.

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 nilibddc.h.


DDC_AppendDataValuesTimestampComponents

int DDC_AppendDataValuesTimestampComponents (DDCChannelHandle channel, unsigned int year[], unsigned int month[], unsigned int day[], unsigned int hour[], unsigned int minute[], unsigned int second[], double milliSecond[], size_t numValues);

Purpose

Appends data values for the specified channel. DDC_AppendDataValuesTimestampComponents adds new data values after existing data values.

Specify the timestamp values by passing separate arrays for each component of a timestamp. DDC_AppendDataValuesTimestampComponents constructs each complete timestamp value by combining the corresponding entries from each of the separate arrays.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The handle of the channel that contains the new data values. The data type of the specified channel must be DDC_Timestamp.
year | unsigned integer [] | An array of values containing the year component of the timestamp values. This function combines each year value with the corresponding values from the other timestamp component arrays to construct a single timestamp value. The year represents local calendar time. Values less than 1970 are not supported on Windows 2000. Values less than 1601 are not supported on Windows XP or later.
month | unsigned integer [] | An array of values containing the month component of the timestamp values. This function combines each month value with the corresponding values from the other timestamp component arrays to construct a single timestamp value. The month represents local calendar time. Valid values are 1 (January) through 12 (December).
day | unsigned integer [] | An array of values containing the day component of the timestamp values. This function combines each day value with the corresponding values from the other timestamp component arrays to construct a single timestamp value. The day of the month represents local calendar time. Valid values are 1 through 31.
hour | unsigned integer [] | An array of values containing the hour component of the timestamp values. This function combines each hour value with the corresponding values from the other timestamp component arrays to construct a single timestamp value. The hour represents local calendar time. Valid values are 0 through 23.
minute | unsigned integer [] | An array of values containing the minute component of the timestamp values. This function combines each minute value with the corresponding values from the other timestamp component arrays to construct a single timestamp value. The minute represents local calendar time. Valid values are 0 through 59.
second | unsigned integer [] | An array of values containing the second component of the timestamp values. This function combines each second value with the corresponding values from the other timestamp component arrays to construct a single timestamp value. The second represents local calendar time. Valid values are 0 through 59.
millisecond | double [] | An array of values containing the milliseconds component of the timestamp values. This function combines each millisecond value with the corresponding values from the other timestamp component arrays to construct a single timestamp value. The millisecond represents local calendar time. You can specify only non-negative values.
numberOfValues | size_t | The number of values in each of the timestamp components arrays.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_AppendDataValues[type]

int DDC_AppendDataValuesUInt8 (DDCChannelHandle channel, unsigned char values[], size_t numValues);

int DDC_AppendDataValuesInt16 (DDCChannelHandle channel, short values[], size_t numValues);

int DDC_AppendDataValuesInt32 (DDCChannelHandle channel, long values[], size_t numValues);

int DDC_AppendDataValuesFloat (DDCChannelHandle channel, float values[], size_t numValues);

int DDC_AppendDataValuesDouble (DDCChannelHandle channel, double values[], size_t numValues);

int DDC_AppendDataValuesString (DDCChannelHandle channel, const char *values[], size_t numValues);

Purpose

Appends data values for the specified channel. DDC_AppendDataValues[type] adds new data values after existing data values.

The DIAdem Connectivity Library provides the following typesafe functions to append data values for a channel. The function you use depends on the data type of the specified channel.

DDC_AppendDataValuesUInt8
DDC_AppendDataValuesInt16
DDC_AppendDataValuesInt32
DDC_AppendDataValuesFloat
DDC_AppendDataValuesDouble
DDC_AppendDataValuesString

If the data type of the specified channel is DDC_Timestamp, you must call DDC_AppendDataValuesTimestampComponents.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The handle of the channel that contains the new data values. The data type of the specified channel must match the data type in the function name.
values | depends on the function | An array of data values. When calling DDC_AppendDataValuesString, you must pass an array of type character pointer (char *). The following code illustrates one way to pass an array of strings: char *values[] = {"one", "two", "three", "four", "five"}; DDC_AppendDataValuesString (channel, values, 5);
numValues | size_t | The number of values in the array specified by the values parameter.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_ChannelGroupPropertyExists

int DDC_ChannelGroupPropertyExists (DDCChannelGroupHandle channelGroup, const char *property, int *exists);

Purpose

Determines whether the specified channel group property exists.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The channel group handle.
property | const char * | The name of the channel group property.
Output
Name | Type | Description
exists | int | A boolean value indicating whether the channel group property exists. 0 = Does not exist 1 = Does exist

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 nilibddc.h.


DDC_ChannelPropertyExists

int DDC_ChannelPropertyExists (DDCChannelHandle channel, const char *property, int *exists);

Purpose

Determines whether the specified channel property exists.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The channel handle.
property | const char * | The name of the channel property.
Output
Name | Type | Description
exists | int | A boolean value indicating whether the channel property exists. 0 = Does not exist 1 = Does exist

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 nilibddc.h.


DDC_CloseChannel

int DDC_CloseChannel (DDCChannelHandle channel);

Purpose

Closes a channel handle.

Channel handles are automatically closed when the containing file handle is closed. You should call this function only if you want to close a channel handle explicitly.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The handle of the channel to be closed.

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 nilibddc.h.


DDC_CloseChannelGroup

int DDC_CloseChannelGroup (DDCChannelGroupHandle channelGroup);

Purpose

Closes a channel group handle.

Channel group handles are automatically closed when the containing file handle is closed. You should call this function only if you want to close a channel group handle explicitly.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The handle of the channel group to be closed.

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 nilibddc.h.


DDC_CloseFile

int DDC_CloseFile (DDCFileHandle file);

Purpose

Closes a file handle. This function also closes all open channel group and channel handles for the specified file.

This function does not save the file before closing the file handle. Call DDC_SaveFile to save the file.

Parameters

Input
Name | Type | Description
file | DDCFileHandle | The handle of the file to be closed. You obtain this handle from the DDC_OpenFile or DDC_CreateFile function.

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 nilibddc.h.


DDC_CreateChannelGroupProperty

int DDC_CreateChannelGroupProperty (DDCChannelGroupHandle channelGroup, const char *property, DDCDataType dataType, void *value);

Purpose

Creates a new property for the specified channel group.

Note Note If you are using this library from a language other than C or C++, you should consider using the type-safe version of this function.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The channel group handle.
property | const char * | The name of the new channel group property.
dataType DDCDataType The data type of the new channel group property.

If you choose DDC_Timestamp as the data type of a new channel group property, you must use the CVIAbsoluteTime type when you set or get the value of that property. You can use this type with DDC_SetChannelGroupProperty and DDC_GetChannelGroupProperty. Refer to the Absolute Time functions in the Utility Library for more information about this data type.

If you choose DDC_Timestamp as the data type of a new channel group property, you must call DDC_CreateChannelGroupPropertyTimestampComponents instead of this function. You can set and get the value of the property by calling DDC_SetChannelGroupPropertyTimestampComponents and DDC_GetChannelGroupPropertyTimestampComponents.
value | void * | The value of the new channel group property.

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 nilibddc.h.


DDC_CreateChannelGroupPropertyTimestampComponents

int DDC_CreateChannelGroupPropertyTimestampComponents (DDCChannelGroupHandle channelGroup, const char *property, unsigned int year, unsigned int month, unsigned int day, unsigned int hour, unsigned int minute, unsigned int second, double milliSecond);

Purpose

Creates a new property of data type DDC_Timestamp for the specified channel group. Specify the timestamp value by passing separate values for each component of the timestamp.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The channel group handle.
property | const char * | The name of the new channel group property.
year | unsigned integer | The year component of the timestamp value. The year represents local calendar time. Values less than 1970 are not supported on Windows 2000. Values less than 1601 are not supported on Windows XP or later.
month | unsigned integer | The month component of the timestamp value. The month represents local calendar time. Valid values are 1 (January) through 12 (December).
day | unsigned integer | The day component of the timestamp value. The day of the month represents local calendar time. Valid values are 1 through 31.
hour | unsigned integer | The hour component of the timestamp value. The hour represents local calendar time. Valid values are 0 through 23.
minute | unsigned integer | The minute component of the timestamp value. The minute represents local calendar time. Valid values are 0 through 59.
second | unsigned integer | The second component of the timestamp value. The second represents local calendar time. Valid values are 0 through 59.
millisecond | double | The milliseconds component of the timestamp value. The millisecond represents local calendar time. You can specify only non-negative values.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_CreateChannelGroupProperty[type]

int DDC_CreateChannelGroupPropertyUInt8 (DDCChannelGroupHandle channelGroup, const char *property, unsigned char value);

int DDC_CreateChannelGroupPropertyInt16 (DDCChannelGroupHandle channelGroup, const char *property, short value);

int DDC_CreateChannelGroupPropertyInt32 (DDCChannelGroupHandle channelGroup, const char *property, long value);

int DDC_CreateChannelGroupPropertyFloat (DDCChannelGroupHandle channelGroup, const char *property, float value);

int DDC_CreateChannelGroupPropertyDouble (DDCChannelGroupHandle channelGroup, const char *property, double value);

int DDC_CreateChannelGroupPropertyString (DDCChannelGroupHandle channelGroup, const char *property, const char *value);

Purpose

Creates a new property for the specified channel group.

The DIAdem Connectivity Library provides the following typesafe functions to create a property for a channel group. The function you use depends on the data type of the specified channel.

DDC_CreateChannelGroupPropertyUInt8
DDC_CreateChannelGroupPropertyInt16
DDC_CreateChannelGroupPropertyInt32
DDC_CreateChannelGroupPropertyFloat
DDC_CreateChannelGroupPropertyDouble
DDC_CreateChannelGroupPropertyString

If the data type of the new property is DDC_Timestamp, you must call DDC_CreateChannelGroupPropertyTimestampComponents.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The channel group handle.
property | const char * | The name of the new channel group property.
value | depends on the function | The value of the new channel group property.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_CreateChannelProperty

int DDC_CreateChannelProperty (DDCChannelHandle channel, const char *property, DDCDataType dataType, void *value);

Purpose

Creates a new property for the specified channel.

Note Note If you are using this library from a language other than C or C++, you should consider using the type-safe version of this function.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The channel handle.
property | const char * | The name of the new channel property.
dataType DDCDataType The data type of the new channel property.

If you choose DDC_Timestamp as the data type of a new channel property, you must use the CVIAbsoluteTime type when you set or get the value of that property. You can use this type with DDC_SetChannelProperty and DDC_GetChannelProperty. Refer to the Absolute Time functions in the Utility Library for more information about this data type.

If you choose DDC_Timestamp as the data type of a new channel property, you must call DDC_CreateChannelPropertyTimestampComponents instead of this function. You can set and get the value of the property by calling DDC_SetChannelPropertyTimestampComponents and DDC_GetChannelPropertyTimestampComponents.
value | void * | The value of the new channel property.

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 nilibddc.h.


DDC_CreateChannelPropertyTimestampComponents

int DDC_CreateChannelPropertyTimestampComponents (DDCChannelHandle channel, const char *property, unsigned int year, unsigned int month, unsigned int day, unsigned int hour, unsigned int minute, unsigned int second, double milliSecond);

Purpose

Creates a new property of data type DDC_Timestamp for the specified channel. Specify the timestamp value by passing separate values for each component of the timestamp.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The channel handle.
property | const char * | The name of the new channel property.
year | unsigned integer | The year component of the timestamp value. The year represents local calendar time. Values less than 1970 are not supported on Windows 2000. Values less than 1601 are not supported on Windows XP or later.
month | unsigned integer | The month component of the timestamp value. The month represents local calendar time. Valid values are 1 (January) through 12 (December).
day | unsigned integer | The day component of the timestamp value. The day of the month represents local calendar time. Valid values are 1 through 31.
hour | unsigned integer | The hour component of the timestamp value. The hour represents local calendar time. Valid values are 0 through 23.
minute | unsigned integer | The minute component of the timestamp value. The minute represents local calendar time. Valid values are 0 through 59.
second | unsigned integer | The second component of the timestamp value. The second represents local calendar time. Valid values are 0 through 59.
millisecond | double | The milliseconds component of the timestamp value. The millisecond represents local calendar time. You can specify only non-negative values.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_CreateChannelProperty[type]

int DDC_CreateChannelPropertyUInt8 (DDCChannelHandle channel, const char *property, unsigned char value);

int DDC_CreateChannelPropertyInt16 (DDCChannelHandle channel, const char *property, short value);

int DDC_CreateChannelPropertyInt32 (DDCChannelHandle channel, const char *property, long value);

int DDC_CreateChannelPropertyFloat (DDCChannelHandle channel, const char *property, float value);

int DDC_CreateChannelPropertyDouble (DDCChannelHandle channel, const char *property, double value);

int DDC_CreateChannelPropertyString (DDCChannelHandle channel, const char *property, const char *value);

Purpose

Creates a new property for the specified channel.

The DIAdem Connectivity Library provides the following typesafe functions to create a property for a channel. The function you use depends on the data type of the specified channel.

DDC_CreateChannelPropertyUInt8
DDC_CreateChannelPropertyInt16
DDC_CreateChannelPropertyInt32
DDC_CreateChannelPropertyFloat
DDC_CreateChannelPropertyDouble
DDC_CreateChannelPropertyString

If the data type of the new property is DDC_Timestamp, you must call DDC_CreateChannelPropertyTimestampComponents.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The channel handle.
property | const char * | The name of the new channel property.
value | depends on the function | The value of the new channel property.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_CreateFile

int DDC_CreateFile (const char *filePath, const char *fileType, const char *name, const char *description, const char *title, const char *author, DDCFileHandle *file);

Purpose

Creates a file handle for a new DIAdem file. Pass the new file handle to other DIAdem Connectivity Library functions to modify the file contents. Call DDC_SaveFile to save the file to disk.

Call the DDC_CloseFile function to close the file handle when you are finished.

Parameters

Input
Name | Type | Description
filePath | const char * | The path to the file that will be created. If it is not an absolute pathname, then the pathname is relative to the current working directory.
fileType | const char * | The type of file to be created. Pass DDC_FILE_TYPE_TDM to create a .tdm file. Pass DDC_FILE_TYPE_TDMS to create a .tdms file. If the file extension you specify in the filePath parameter is .tdm or .tdms, then you can pass NULL or the empty string to automatically use the file extension to specify the file type. Passing DDC_FILE_TYPE_TDMS will create a .tdms file using the most recent version of the TDM Streaming file format supported by your installation. To specifically create a TDMS 1.0 format file, you must pass DDC_FILE_TYPE_TDMS1_0 for this parameter and you must download and register the TDMS_1_0 DataPlugin. You can find more information about downloading and registering the TDMS_1_0 DataPlugin at ni.com/dataplugins.
name | const char * | The value of the Name property of the file object. This property is stored in the file and can be accessed with the DDC_SetFileProperty and DDC_GetFileProperty functions.
description | const char * | The value of the Description property of the file object. This property is stored in the file and can be accessed with the DDC_SetFileProperty and DDC_GetFileProperty functions.
title | const char * | The value of the Title property of the file object. This property is stored in the file and can be accessed with the DDC_SetFileProperty and DDC_GetFileProperty functions.
author | const char * | The value of the Author property of the file object. This property is stored in the file and can be accessed with the DDC_SetFileProperty and DDC_GetFileProperty functions.
Output
Name | Type | Description
file | DDCFileHandle | The handle for the DIAdem file. Pass this handle to DIAdem Connectivity Library functions that require a file. Call DDC_SaveFile to save the file to disk. Call DDC_CloseFile to close the file handle when you are finished.

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 nilibddc.h.


DDC_CreateFileProperty

int DDC_CreateFileProperty (DDCFileHandle file, const char *property, DDCDataType dataType, void *value);

Purpose

Creates a new property for the specified file.

Note Note If you are using this library from a language other than C or C++, you should consider using the type-safe version of this function.

Parameters

Input
Name | Type | Description
file | DDCFileHandle | The file handle. You obtain this handle from the DDC_OpenFile or DDC_CreateFile function.
property | const char * | The name of the new file property.
dataType DDCDataType The data type of the new file property.

If you choose DDC_Timestamp as the data type of a new file property, you must use the CVIAbsoluteTime type when you set or get the value of that property. You can use this type with DDC_SetFileProperty and DDC_GetFileProperty. Refer to the Absolute Time functions in the Utility Library for more information about this data type.

If you choose DDC_Timestamp as the data type of a new file property, you must call DDC_CreateFilePropertyTimestampComponents instead of this function. You can set and get the value of the property by calling DDC_SetFilePropertyTimestampComponents and DDC_GetFilePropertyTimestampComponents.
value | void * | The value of the new file property.

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 nilibddc.h.


DDC_CreateFilePropertyTimestampComponents

int DDC_CreateFilePropertyTimestampComponents (DDCFileHandle file, const char *property, unsigned int year, unsigned int month, unsigned int day, unsigned int hour, unsigned int minute, unsigned int second, double milliSecond);

Purpose

Creates a new property of data type DDC_Timestamp for the specified file. Specify the timestamp value by passing separate values for each component of the timestamp.

Parameters

Input
Name | Type | Description
file | DDCFileHandle | The file handle. You obtain this handle from the DDC_OpenFile or DDC_CreateFile function.
property | const char * | The name of the new file property.
year | unsigned integer | The year component of the timestamp value. The year represents local calendar time. Values less than 1970 are not supported on Windows 2000. Values less than 1601 are not supported on Windows XP or later.
month | unsigned integer | The month component of the timestamp value. The month represents local calendar time. Valid values are 1 (January) through 12 (December).
day | unsigned integer | The day component of the timestamp value. The day of the month represents local calendar time. Valid values are 1 through 31.
hour | unsigned integer | The hour component of the timestamp value. The hour represents local calendar time. Valid values are 0 through 23.
minute | unsigned integer | The minute component of the timestamp value. The minute represents local calendar time. Valid values are 0 through 59.
second | unsigned integer | The second component of the timestamp value. The second represents local calendar time. Valid values are 0 through 59.
millisecond | double | The milliseconds component of the timestamp value. The millisecond represents local calendar time. You can specify only non-negative values.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_CreateFileProperty[type]

int DDC_CreateFilePropertyUInt8 (DDCFileHandle file, const char *property, unsigned char value);

int DDC_CreateFilePropertyInt16 (DDCFileHandle file, const char *property, short value);

int DDC_CreateFilePropertyInt32 (DDCFileHandle file, const char *property, long value);

int DDC_CreateFilePropertyFloat (DDCFileHandle file, const char *property, float value);

int DDC_CreateFilePropertyDouble (DDCFileHandle file, const char *property, double value);

int DDC_CreateFilePropertyString (DDCFileHandle file, const char *property, const char *value);

Purpose

Creates a new property for the specified file.

The DIAdem Connectivity Library provides the following typesafe functions to create file properties. The function you use depends on the data type of the file property.

DDC_CreateFilePropertyUInt8
DDC_CreateFilePropertyInt16
DDC_CreateFilePropertyInt32
DDC_CreateFilePropertyFloat
DDC_CreateFilePropertyDouble
DDC_CreateFilePropertyString

If the data type of the new property is DDC_Timestamp, you must call DDC_CreateFilePropertyTimestampComponents.

Parameters

Input
Name | Type | Description
file | DDCFileHandle | The file handle. You obtain this handle by calling the DDC_OpenFile or DDC_CreateFile functions.
property | const char * | The name of the new file property.
value | depends on the function | The value of the new file property.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_FilePropertyExists

int DDC_FilePropertyExists (DDCFileHandle file, const char *property, int *exists);

Purpose

Determines whether the specified file property exists.

Parameters

Input
Name | Type | Description
file | DDCFileHandle | The file handle. You obtain this handle from the DDC_OpenFile or DDC_CreateFile function.
property | const char * | The name of the file property.
Output
Name | Type | Description
exists | int | A boolean value indicating whether the file property exists. 0 = Does not exist 1 = Does exist

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 nilibddc.h.


DDC_FreeMemory

void DDC_FreeMemory (void *memoryPointer);

Purpose

Frees memory allocated by this library.

Parameters

Input
Name | Type | Description
memoryPointer | void * | A pointer to memory allocated by this library.

Return Value

None.


DDC_GetChannelGroupProperty

int DDC_GetChannelGroupProperty (DDCChannelGroupHandle channelGroup, const char *property, void *value, size_t valueSizeInBytes);

Purpose

Gets the value of a channel group property.

Note Note If you are using this library from a language other than C or C++, you should consider using the type-safe version of this function.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The channel group handle.
property const char * The name of the channel group property. You can specify a built-in property or a property created by DDC_CreateChannelGroupProperty.

The following built-in properties are available:

Property | Constant | Data Type
Name | DDC_CHANNELGROUP_NAME | String (char *)
Description | DDC_CHANNELGROUP_DESCRIPTION | String (char *)
valueSizeInBytes size_t The size, in bytes, of the memory location specified by the value parameter. This parameter is used only if the specified property is of type string. If the specified property is of another type you should pass 0 for this parameter.

If the value you pass for this parameter is less than the size required to hold the string property, the value of the string property that you get is truncated but still contains the terminating NUL byte.
Output
Name | Type | Description
value void * The pointer that receives the value of the specified channel group property. The type of this pointer must match the data type of the specified property. You can call DDC_GetChannelGroupPropertyType to get the data type of a channel group property.

If the data type of the specified property is string, you must pass a string buffer. This buffer must be large enough to hold the entire string as reported by DDC_GetChannelGroupStringPropertyLength plus the terminating NUL byte. Sample code is shown below:

char *buffer;

size_t length;

DDC_GetChannelGroupStringPropertyLength (group, "MyStringProperty", &length);

buffer = malloc(sizeof(char) * (length+1));

DDC_GetChannelGroupProperty (group, "MyStringProperty", buffer, length+1);

free (buffer); // Free the buffer when you are finished with it.

If the data type of the specified property is DDC_Timestamp, you must pass a pointer to a value of type CVIAbsoluteTime. Refer to the Absolute Time functions in the Utility Library for more information about this type.

If the data type of the specified property is DDC_Timestamp, you must call DDC_GetChannelGroupPropertyTimestampComponents instead of this function.

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 nilibddc.h.


DDC_GetChannelGroups

int DDC_GetChannelGroups (DDCFileHandle file, DDCChannelGroupHandle channelGroupsBuffer[], size_t numberOfChannelGroups);

Purpose

Gets the channel groups in the specified file.

Parameters

Input
Name | Type | Description
file | DDCFileHandle | The file handle. You obtain this handle from the DDC_OpenFile or DDC_CreateFile function.
numberOfChannelGroups | size_t | The number of channel groups to copy into the buffer. The array passed in the channelGroupsBuffer parameter must hold at least as many items as specified in this parameter.
Output
Name | Type | Description
channelGroupsBuffer | DDCChannelGroupHandle [] | The array that will receive the channel groups for the specified file. This array must be large enough to hold at least as many items as you specify in the numberOfChannelGroups parameter.

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 nilibddc.h.


DDC_GetChannelGroupPropertyNameFromIndex

int DDC_GetChannelGroupPropertyNameFromIndex (DDCChannelGroupHandle channelGroup, size_t index, char propertyName[], size_t propertyNameSize);

Purpose

Gets the name of the channel group property with the specified index.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The channel group handle.
index | size_t | The zero-based index of the channel group property name to get.
propertyNameSize | size_t | The size, in bytes, of the memory location specified by the propertyName parameter. You can call DDC_GetChannelGroupPropertyNameLengthFromIndex to determine the necessary buffer size for the name of the channel group property.
Output
propertyName | char [] | The name of the channel group property.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_GetChannelGroupPropertyNameLengthFromIndex

int DDC_GetChannelGroupPropertyNameLengthFromIndex (DDCChannelGroupHandle channelGroup, size_t index, size_t* propertyNameLength);

Purpose

Gets the length of the name of the channel group property with the specified index. The length does not include the terminating NUL byte.

You can call this function to determine the necessary buffer size before getting the name of a channel group property.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The channel group handle.
index | size_t | The zero-based index of the channel group property. The maximum index is one less than the total number of properties on the channel group. You can obtain the total number of properties on the channel group by calling DDC_GetNumChannelGroupProperties.
Output
Name | Type | Description
propertyNameLength | size_t * | The length of the name of the channel group property. The length does not include the terminating NUL byte.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_GetChannelGroupPropertyNames

int DDC_GetChannelGroupPropertyNames (DDCChannelGroupHandle channelGroup, char **propertyNames, size_t numberOfPropertyNames);

Purpose

Gets the names of the properties on the specified channel group.

Note Note If you are using this library from a language other than C or C++, you should consider using the functions that get a channel group property name or name length by index.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The channel group handle.
numberOfPropertyNames | size_t | The number of property names to copy into the buffer. The array passed in the propertyNames parameter must hold at least as many items as specified in this parameter.
Output
Name | Type | Description
propertyNames | char * | The array that will receive the property names of the specified channel group. This array must be large enough to hold at least the number of values specified by the numberOfPropertyNames parameter. You should pass an array of type character pointer (char *). This function will fill the array with string pointers allocated by this function. You must free these strings. Sample code is shown below: char **propertyNames = 0; unsigned int numberOfProperties, i; DDC_GetNumChannelGroupProperties (file, &numberOfProperties); propertyNames = malloc(numberOfProperties * sizeof(char*)); DDC_GetChannelGroupPropertyNames (file, propertyNames, numberOfProperties); for (i = 0; i < numberOfProperties; i++) DDC_FreeMemory (propertyNames[i]); free(propertyNames);

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 nilibddc.h.


DDC_GetChannelGroupPropertyType

int DDC_GetChannelGroupPropertyType (DDCChannelGroupHandle channelGroup, const char *property, DDCDataType *dataType);

Purpose

Gets the data type of the specified property.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The channel group handle.
property | const char * | The name of the channel group property.
Output
Name | Type | Description
dataType | DDCDataType | The data type of the specified property.

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 nilibddc.h.


DDC_GetChannelGroupProperty[type]

int DDC_GetChannelGroupPropertyUInt8 (DDCChannelGroupHandle channelGroup, const char* property, unsigned char *value);

int DDC_GetChannelGroupPropertyInt16 (DDCChannelGroupHandle channelGroup, const char* property, short *value);

int DDC_GetChannelGroupPropertyInt32 (DDCChannelGroupHandle channelGroup, const char* property, long *value);

int DDC_GetChannelGroupPropertyFloat (DDCChannelGroupHandle channelGroup, const char* property, float *value);

int DDC_GetChannelGroupPropertyDouble (DDCChannelGroupHandle channelGroup, const char* property, double *value);

int DDC_GetChannelGroupPropertyString (DDCChannelGroupHandle channelGroup, const char* property, char value[], size_t valueSize);

Purpose

Gets the value of a channel group property.

The DIAdem Connectivity Library provides the following typesafe functions to obtain the value of a channel group property. The function you use depends on the data type of the specified channel group.

DDC_GetChannelGroupPropertyUInt8
DDC_GetChannelGroupPropertyInt16
DDC_GetChannelGroupPropertyInt32
DDC_GetChannelGroupPropertyFloat
DDC_GetChannelGroupPropertyDouble
DDC_GetChannelGroupPropertyString

If the data type of the property is DDC_Timestamp, you must call DDC_GetChannelGroupPropertyTimestampComponents.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The channel group handle.
property const char * The name of the channel group property. You can specify a built-in property or a property created by DDC_CreateChannelGroupProperty.

The following built-in properties are available:

Property | Constant | Data Type
Name | DDC_CHANNELGROUP_NAME | String (char *)
Description | DDC_CHANNELGROUP_DESCRIPTION | String (char *)
valueSize size_t The size, in bytes, of the memory location specified by the value parameter.

If the value you pass for this parameter is less than the size required to hold the string property, the value of the string property that you get is truncated but still contains the terminating NUL byte.

Note Note This parameter is valid only for the DDC_GetChannelPropertyString function.
Output
Name | Type | Description
value depends on the function The pointer that receives the value of the specified channel group property.

When calling DDC_GetChannelGroupPropertyString, you must pass a string buffer. This buffer must be large enough to hold the entire string as reported by DDC_GetChannelGroupStringPropertyLength plus the terminating NUL byte. Sample code is shown below:

char *buffer;

size_t length;

DDC_GetChannelGroupStringPropertyLength (group, "MyStringProperty", &length);

buffer = malloc(sizeof(char) * (length+1));

DDC_GetChannelGroupPropertyString (group, "MyStringProperty", buffer, length+1);

free (buffer); // Free the buffer when you are finished with it.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_GetChannelGroupPropertyTimestampComponents

int DDC_GetChannelGroupPropertyTimestampComponents (DDCChannelGroupHandle channelGroup, const char *property, unsigned int *year, unsigned int *month, unsigned int *day, unsigned int *hour, unsigned int *minute, unsigned int *second, double *milliSecond, unsigned int *weekDay);

Purpose

Gets the value of a property of data type DDC_Timestamp for the specified channel group. Obtain the timestamp value by passing separate values for each component of the timestamp.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The channel group handle.
property | const char * | The name of the channel group property.
Output
Name | Type | Description
year | unsigned integer (passed by reference) | The year component of the timestamp value. The year represents local calendar time. Values less than 1970 are not supported on Windows 2000. Values less than 1601 are not supported on Windows XP or later.
month | unsigned integer (passed by reference) | The month component of the timestamp value. The month represents local calendar time. Valid values are 1 (January) through 12 (December).
day | unsigned integer (passed by reference) | The day component of the timestamp value. The day of the month represents local calendar time. Valid values are 1 through 31.
hour | unsigned integer (passed by reference) | The hour component of the timestamp value. The hour represents local calendar time. Valid values are 0 through 23.
minute | unsigned integer (passed by reference) | The minute component of the timestamp value. The minute represents local calendar time. Valid values are 0 through 59.
second | unsigned integer (passed by reference) | The second component of the timestamp value. The second represents local calendar time. Valid values are 0 through 59.
millisecond | double (passed by reference) | The milliseconds component of the timestamp value. The millisecond represents local calendar time. Only non-negative values are allowed.
weekDay | unsigned integer (passed by reference) | The week day information of the timestamp value. Valid values are 0 (Sunday) to 6 (Saturday).

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_GetChannelGroupStringPropertyLength

int DDC_GetChannelGroupStringPropertyLength (DDCChannelGroupHandle channelGroup, const char *property, unsigned int *length);

Purpose

Gets the length of the current value of a string property. The length does not include the terminating NUL byte.

You can call this function to determine the necessary buffer size before getting the value of a string property.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The channel group handle.
property const char * The name of the channel group property. You can specify a built-in property or a property created by DDC_CreateChannelGroupProperty.

The following built-in properties are available:

Property | Constant | Data Type
Name | DDC_CHANNELGROUP_NAME | String (char *)
Description | DDC_CHANNELGROUP_DESCRIPTION | String (char *)
Output
Name | Type | Description
length | unsigned int | The length of the current value of the string property. The length does not include the terminating NUL byte.

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 nilibddc.h.


DDC_GetChannelProperty

int DDC_GetChannelProperty (DDCChannelHandle channel, const char *property, void *value, size_t valueSizeInBytes);

Purpose

Gets the value of a channel property.

Note Note If you are using this library from a language other than C or C++, you should consider using the type-safe version of this function.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The channel handle.
property const char * The name of the channel property. You can specify a built-in property or a property created by DDC_CreateChannelProperty.

The following built-in properties are available:

Property | Constant | Data Type
Name | DDC_CHANNEL_NAME | String (char *)
Description | DDC_CHANNEL_DESCRIPTION | String (char *)
Unit String | DDC_CHANNEL_UNIT_STRING | String (char *)
Minimum | DDC_CHANNEL_MINIMUM | Double
Maximum | DDC_CHANNEL_MAXIMUM | Double
valueSizeInBytes size_t The size, in bytes, of the memory location specified by the value parameter. This parameter is used only if the specified property is of type string. If the specified property is of another type you should pass 0 for this parameter.

If the value you pass for this parameter is less than the size required to hold the string property, the value of the string property that you get is truncated but still contains the terminating NUL byte.
Output
Name | Type | Description
value void * The pointer that receives the value of the specified channel property. The type of this pointer must match the data type of the specified property. You can call DDC_GetChannelPropertyType to get the data type of a channel property.

If the data type of the specified property is string, you must pass a string buffer. This buffer must be large enough to hold the entire string as reported by DDC_GetChannelStringPropertyLength plus the terminating NUL byte. Sample code is shown below:

char *buffer;

size_t length;

DDC_GetChannelStringPropertyLength (channel, "MyStringProperty", &length);

buffer = malloc(sizeof(char) * (length+1));

DDC_GetChannelProperty (channel, "MyStringProperty", buffer, length+1);

free (buffer); // Free the buffer when you are finished with it.

If the data type of the specified property is DDC_Timestamp, you must pass a pointer to a value of type CVIAbsoluteTime. Refer to the Absolute Time functions in the Utility Library for more information about this type.

If the data type of the specified property is DDC_Timestamp, you must call DDC_GetChannelPropertyTimestampComponents instead of this function.

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 nilibddc.h.


DDC_GetChannelPropertyNameFromIndex

int DDC_GetChannelPropertyNameFromIndex (DDCChannelHandle channel, size_t index, char propertyName[], size_t propertyNameSize);

Purpose

Gets the name of the channel property with the specified index.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The channel handle.
index | size_t | The zero-based index of the channel property name to get.
propertyNameSize | size_t | The size, in bytes, of the memory location specified by the propertyName parameter. You can call DDC_GetChannelPropertyNameLengthFromIndex to determine the necessary buffer size for the name of the channel property.
Output
propertyName | char [] | The name of the channel property.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_GetChannelPropertyNameLengthFromIndex

int DDC_GetChannelPropertyNameLengthFromIndex (DDCChannelHandle channel, size_t index, size_t* propertyNameLength);

Purpose

Gets the length of the name of a channel property with the specified index. The length does not include the terminating NUL byte.

You can call this function to determine the necessary buffer size before getting the name of a channel property.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The channel handle.
index | size_t | The zero-based index of the channel property. The maximum index is one less than the total number of properties on the channel. You can obtain the total number of properties on the channel by calling DDC_GetNumChannelProperties.
Output
Name | Type | Description
propertyNameLength | size_t * | The length of the name of the channel property. The length does not include the terminating NUL byte.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_GetChannelPropertyNames

int DDC_GetChannelPropertyNames (DDCChannelHandle channel, char **propertyNames, size_t numberOfPropertyNames);

Purpose

Gets the names of the properties on the specified channel.

Note Note If you are using this library from a language other than C or C++, you should consider using the functions that get a channel property name or name length by index.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The channel handle.
numberOfPropertyNames | size_t | The number of property names to copy into the buffer. The array passed in the propertyNames parameter must hold at least as many items as specified in this parameter.
Output
Name | Type | Description
propertyNames | char * | The array that will receive the property names of the specified channel. This array must be large enough to hold at least the number of values specified by the numberOfPropertyNames parameter. You should pass an array of type character pointer (char *). This function will fill the array with string pointers allocated by this function. You must free these strings. Sample code is shown below: char **propertyNames = 0; unsigned int numberOfProperties, i; DDC_GetNumChannelProperties (file, &numberOfProperties); propertyNames = malloc(numberOfProperties * sizeof(char*)); DDC_GetChannelPropertyNames (file, propertyNames, numberOfProperties); for (i = 0; i < numberOfProperties; i++) DDC_FreeMemory (propertyNames[i]); free(propertyNames);

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 nilibddc.h.


DDC_GetChannelPropertyTimestampComponents

int DDC_GetChannelPropertyTimestampComponents (DDCChannelHandle channel, const char *property, unsigned int *year, unsigned int *month, unsigned int *day, unsigned int *hour, unsigned int *minute, unsigned int *second, double *milliSecond, unsigned int *weekDay);

Purpose

Gets the value of a property of data type DDC_Timestamp for the specified channel. Obtain the timestamp value by passing separate values for each component of the timestamp.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The channel handle.
property | const char * | The name of the channel property.
Output
Name | Type | Description
year | unsigned integer (passed by reference) | The year component of the timestamp value. The year represents local calendar time. Values less than 1970 are not supported on Windows 2000. Values less than 1601 are not supported on Windows XP or later.
month | unsigned integer (passed by reference) | The month component of the timestamp value. The month represents local calendar time. Valid values are 1 (January) through 12 (December).
day | unsigned integer (passed by reference) | The day component of the timestamp value. The day of the month represents local calendar time. Valid values are 1 through 31.
hour | unsigned integer (passed by reference) | The hour component of the timestamp value. The hour represents local calendar time. Valid values are 0 through 23.
minute | unsigned integer (passed by reference) | The minute component of the timestamp value. The minute represents local calendar time. Valid values are 0 through 59.
second | unsigned integer (passed by reference) | The second component of the timestamp value. The second represents local calendar time. Valid values are 0 through 59.
millisecond | double (passed by reference) | The milliseconds component of the timestamp value. The millisecond represents local calendar time. Only non-negative values are allowed.
weekDay | unsigned integer (passed by reference) | The week day information of the timestamp value. Valid values are 0 (Sunday) to 6 (Saturday).

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_GetChannelPropertyType

int DDC_GetChannelPropertyType (DDCChannelHandle channel, const char *property, DDCDataType *dataType);

Purpose

Gets the data type of the specified property.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The channel handle.
property | const char * | The name of the channel property.
Output
Name | Type | Description
dataType | DDCDataType | The data type of the specified property.

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 nilibddc.h.


DDC_GetChannelProperty[type]

int DDC_GetChannelPropertyUInt8 (DDCChannelHandle channel, const char* property, unsigned char *value);

int DDC_GetChannelPropertyInt16 (DDCChannelHandle channel, const char* property, short *value);

int DDC_GetChannelPropertyInt32 (DDCChannelHandle channel, const char* property, long *value);

int DDC_GetChannelPropertyFloat (DDCChannelHandle channel, const char* property, float *value);

int DDC_GetChannelPropertyDouble (DDCChannelHandle channel, const char* property, double *value);

int DDC_GetChannelPropertyString (DDCChannelHandle channel, const char* property, char value[], size_t valueSize);

Purpose

Gets the value of the specified channel property.

The DIAdem Connectivity Library provides the following typesafe functions to obtain the value of a channel property. The function you use depends on the data type of the specified channel.

DDC_GetChannelPropertyUInt8
DDC_GetChannelPropertyInt16
DDC_GetChannelPropertyInt32
DDC_GetChannelPropertyFloat
DDC_GetChannelPropertyDouble
DDC_GetChannelPropertyString

If the data type of the property is DDC_Timestamp, you must call DDC_GetChannelPropertyTimestampComponents.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The channel handle.
property const char * The name of the channel property. You can specify a built-in property or a property created by DDC_CreateChannelProperty.

The following built-in properties are available:

Property | Constant | Data Type
Name | DDC_CHANNEL_NAME | String (char *)
Description | DDC_CHANNEL_DESCRIPTION | String (char *)
Unit String | DDC_CHANNEL_UNIT_STRING | String (char *)
Minimum | DDC_CHANNEL_MINIMUM | Double
Maximum | DDC_CHANNEL_MAXIMUM | Double
valueSize size_t The size, in bytes, of the memory location specified by the value parameter.

If the value you pass for this parameter is less than the size required to hold the string property, the value of the string property that you get is truncated but still contains the terminating NUL byte.

Note Note This parameter is valid only for the DDC_GetChannelPropertyString function.
Output
Name | Type | Description
value depends on the function The pointer that receives the value of the specified channel property.

When calling DDC_GetChannelPropertyString, you must pass a string buffer. This buffer must be large enough to hold the entire string as reported by DDC_GetChannelStringPropertyLength plus the terminating NUL byte. Sample code is shown below:

char *buffer;

size_t length;

DDC_GetChannelStringPropertyLength (channel, "MyStringProperty", &length);

buffer = malloc(sizeof(char) * (length+1));

DDC_GetChannelPropertyString (channel, "MyStringProperty", buffer, length+1);

free (buffer); // Free the buffer when you are finished with it.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_GetChannels

int DDC_GetChannels (DDCChannelGroupHandle channelGroup, DDCChannelHandle channelsBuffer[], size_t numberOfChannels);

Purpose

Gets the channels in the specified channel group.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The channel group handle.
numberOfChannels | size_t | The number of channels to copy into the buffer. The array passed in the channelsBuffer parameter must hold at least as many items as specified in this parameter.
Output
Name | Type | Description
channelsBuffer | DDCChannelHandle [] | The array that will receive the channels for the specified channel group. This array must be large enough to hold at least as many items as you specify in the numberOfChannels parameter.

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 nilibddc.h.


DDC_GetChannelStringPropertyLength

int DDC_GetChannelStringPropertyLength (DDCChannelHandle channel, const char *property, unsigned int *length);

Purpose

Gets the length of the current value of a string property. The length does not include the terminating NUL byte.

You can call this function to determine the necessary buffer size before getting the value of a string property.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The channel handle.
property const char * The name of the channel property. You can specify a built-in property or a property created by DDC_CreateChannelProperty.

The following built-in properties are available:

Property | Constant | Data Type
Name | DDC_CHANNEL_NAME | String (char *)
Description | DDC_CHANNEL_DESCRIPTION | String (char *)
Unit String | DDC_CHANNEL_UNIT_STRING | String (char *)
Minimum | DDC_CHANNEL_MINIMUM | Double
Maximum | DDC_CHANNEL_MAXIMUM | Double
Output
Name | Type | Description
length | unsigned int | The length of the current value of the string property. The length does not include the terminating NUL byte.

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 nilibddc.h.


DDC_GetDataType

int DDC_GetDataType (DDCChannelHandle channel, DDCDataType *dataType);

Purpose

Gets the data type of the specified channel.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The channel handle.
Output
Name | Type | Description
dataType | DDCDataType | The data type of the specified channel. This is the data type of the data values for this channel.

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 nilibddc.h.


DDC_GetDataValues

int DDC_GetDataValues (DDCChannelHandle channel, size_t indexOfFirstValueToGet, size_t numberOfValuesToGet, void *values);

Purpose

Gets the data values in the specified channel.

Note Note If you are using this library from a language other than C or C++, you should consider using the type-safe version of this function.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The channel handle.
indexOfFirstValueToGet | size_t | The zero-based index of the first data value to get.
numberOfValuesToGet | size_t | The number of data values to get, starting at the specified index.
Output
Name | Type | Description
values void * The array that receives the data values of the specified channel. The type of this array must match the data type of the specified channel. You can call DDC_GetDataType to get the data type of a channel.

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

If the data type of the specified channel is string, you must pass an array of type character pointer (char *). This function fills the array with string pointers allocated by this function. You must free these strings. The following code illustrates one way to obtain data values and free the strings:

char *values[5];

int i;

DDC_GetDataValues (channel, 0, 5, values);

for (i = 0; i < 5; i++)

DDC_FreeMemory (values[i]);

If the data type of the specified channel is DDC_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.

If the data type of the specified channel is DDC_Timestamp, you must call DDC_GetDataValuesTimestampComponents instead of this function.

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 nilibddc.h.


DDC_GetDataValuesTimestampComponents

int DDC_GetDataValuesTimestampComponents (DDCChannelHandle channel, size_t indexOfFirstValueToGet, size_t numValuesToGet, unsigned int year[], unsigned int month[], unsigned int day[], unsigned int hour[], unsigned int minute[], unsigned int second[], double milliSecond[], unsigned int weekDay[]);

Purpose

Gets the data values in the specified channel. Obtain the timestamp values by passing separate arrays for each component of a timestamp. Each complete timestamp value is defined by the corresponding entries in each of the separate arrays.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The handle of the channel that contains the new data values. The data type of the specified channel must be DDC_Timestamp.
indexOfFirstValueToGet | size_t | The zero-based index of the first data value to get.
numValuesToGet | size_t | The number of data values to get starting at the specified index.
Output
Name | Type | Description
year | unsigned integer [] | The array that receives the year component of the timestamp values. Each year value, along with the corresponding values from the other timestamp component arrays, defines a single timestamp value. The year represents local calendar time. Values less than 1970 are not supported on Windows 2000. Values less than 1601 are not supported on Windows XP or later. This array must be large enough to hold at least the number of values specified by the numberOfValuesToGet parameter.
month | unsigned integer [] | The array that receives the month component of the timestamp values. Each month value, along with the corresponding values from the other timestamp component arrays, defines a single timestamp value. The month represents local calendar time. Valid values are 1 (January) through 12 (December). This array must be large enough to hold at least the number of values specified by the numberOfValuesToGet parameter.
day | unsigned integer [] | The array that receives the day component of the timestamp values. Each day value, along with the corresponding values from the other timestamp component arrays, defines a single timestamp value. The day of the month represents local calendar time. Valid values are 1 through 31. This array must be large enough to hold at least the number of values specified by the numberOfValuesToGet parameter.
hour | unsigned integer [] | The array that receives the hour component of the timestamp values. Each hour value, along with the corresponding values from the other timestamp component arrays, defines a single timestamp value. The hour represents local calendar time. Valid values are 0 through 23. This array must be large enough to hold at least the number of values specified by the numberOfValuesToGet parameter.
minute | unsigned integer [] | The array that receives the minute component of the timestamp values. Each minute value, along with the corresponding values from the other timestamp component arrays, defines a single timestamp value. The minute represents local calendar time. Valid values are 0 through 59. This array must be large enough to hold at least the number of values specified by the numberOfValuesToGet parameter.
second | unsigned integer [] | The array that receives the second component of the timestamp values. Each second value, along with the corresponding values from the other timestamp component arrays, defines a single timestamp value. The second represents local calendar time. Valid values are 0 through 59. This array must be large enough to hold at least the number of values specified by the numberOfValuesToGet parameter.
milliSecond | double [] | The array that receives the milliseconds component of the timestamp values. Each millisecond value, along with the corresponding values from the other timestamp component arrays, defines a single timestamp value. The millisecond represents local calendar time. Only non-negative values are allowed. This array must be large enough to hold at least the number of values specified by the numberOfValuesToGet parameter.
weekDay | unsigned integer [] | The array that receives the week day information of the timestamp values. Valid values are 0 (Sunday) to 6 (Saturday). Each weekDay value is associated with the corresponding values from the other timestamp component arrays. This array must be large enough to hold at least the number of values specified by the numberOfValuesToGet parameter.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_GetDataValues[type]

int DDC_GetDataValuesUInt8 (DDCChannelHandle channel, size_t indexOfFirstValueToGet, size_t numValuesToGet, unsigned char values[]);

int DDC_GetDataValuesInt16 (DDCChannelHandle channel, size_t indexOfFirstValueToGet, size_t numValuesToGet, short values[]);

int DDC_GetDataValuesInt32 (DDCChannelHandle channel, size_t indexOfFirstValueToGet, size_t numValuesToGet, long values[]);

int DDC_GetDataValuesFloat (DDCChannelHandle channel, size_t indexOfFirstValueToGet, size_t numValuesToGet, float values[]);

int DDC_GetDataValuesDouble (DDCChannelHandle channel, size_t indexOfFirstValueToGet, size_t numValuesToGet, double values[]);

int DDC_GetDataValuesString (DDCChannelHandle channel, size_t indexOfFirstValueToGet, size_t numValuesToGet, char *values[]);

Purpose

Gets the data values in the specified channel.

The DIAdem Connectivity Library provides the following typesafe functions to obtain data values in a channel. The function you use depends on the data type of the specified channel.

DDC_GetDataValuesUInt8
DDC_GetDataValuesInt16
DDC_GetDataValuesInt32
DDC_GetDataValuesFloat
DDC_GetDataValuesDouble
DDC_GetDataValuesString

If the data type of the specified channel is DDC_Timestamp, you must call DDC_GetDataValuesTimestampComponents.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The channel handle. The data type of the specified channel must match the data type in the function name.
indexOfFirstValueToGet | size_t | The zero-based index of the first data value to get.
numValuesToGet | size_t | The number of data values to get, starting at the specified index.
Output
Name | Type | Description
values | depends on the function | The array that receives the data values of the specified channel. This array must be large enough to hold at least the number of values specified by the numValuesToGet parameter. When calling DDC_GetDataValuesString, you must pass an array of type character pointer (char *). DDC_GetDataValuesString fills the array with string pointers allocated by this function. You must free these strings. The following code illustrates one way to obtain data values and free the strings: char *values[5]; int i; DDC_GetDataValuesString (channel, 0, 5, values); for (i = 0; i < 5; i++) DDC_FreeMemory (values[i]);

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_GetFileProperty

int DDC_GetFileProperty (DDCFileHandle file, const char *property, void *value, size_t valueSizeInBytes);

Purpose

Gets the value of a file property.

Note Note If you are using this library from a language other than C or C++, you should consider using the type-safe version of this function.

Parameters

Input
Name | Type | Description
file | DDCFileHandle | The file handle. You obtain this handle from the DDC_OpenFile or DDC_CreateFile function.
property const char * The name of the file property. You can specify a built-in property or a property created by DDC_CreateFileProperty.

The following built-in properties are available:

Property | Constant | Data Type
Name | DDC_FILE_NAME | String (char *)
Description | DDC_FILE_DESCRIPTION | String (char *)
Title | DDC_FILE_TITLE | String (char *)
Author | DDC_FILE_AUTHOR | String (char *)
Datetime | DDC_FILE_DATETIME | Timestamp
valueSizeInBytes size_t The size, in bytes, of the memory location specified by the value parameter. This parameter is used only if the specified property is of type string. If the specified property is of another type you should pass 0 for this parameter.

If the value you pass for this parameter is less than the size required to hold the string property, the value of the string property that you get is truncated but still contains the terminating NUL byte.
Output
Name | Type | Description
value void * The pointer that receives the value of the specified file property. The type of this pointer must match the data type of the specified property. You can call DDC_GetFilePropertyType to get the data type of a file property.

If the data type of the specified property is string, you must pass a string buffer. This buffer must be large enough to hold the entire string as reported by DDC_GetFileStringPropertyLength plus the terminating NUL byte. Sample code is shown below:

char *buffer;

size_t length;

DDC_GetFileStringPropertyLength (file, "MyStringProperty", &length);

buffer = malloc(sizeof(char) * (length+1));

DDC_GetFileProperty (file, "MyStringProperty", buffer, length+1);

free (buffer); // Free the buffer when you are finished with it.

If the data type of the specified property is DDC_Timestamp, you must pass a pointer to a value of type CVIAbsoluteTime. Refer to the Absolute Time functions in the Utility Library for more information about this type.

If the data type of the specified property is DDC_Timestamp, you must call DDC_GetFilePropertyTimestampComponents instead of this function.

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 nilibddc.h.


DDC_GetFilePropertyNameFromIndex

int DDC_GetFilePropertyNameFromIndex (DDCFileHandle file, size_t index, char propertyName[], size_t propertyNameSize);

Purpose

Gets the name of the file property with the specified index.

Parameters

Input
Name | Type | Description
file | DDCFileHandle | The file handle. You obtain this handle from the DDC_OpenFile or DDC_CreateFile function.
index | size_t | The zero-based index of the file property. The maximum index is one less than the total number of properties on the file. You can obtain the total number of properties on the file by calling DDC_GetNumFileProperties.
propertyNameSize | size_t | The size, in bytes, of the string buffer specified by the propertyName parameter.
Output
Name | Type | Description
propertyName | char [] | The string buffer that receives the name of the file property. This buffer must be large enough to hold the entire string as reported by DDC_GetFileStringPropertyLength plus the terminating NUL byte.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_GetFilePropertyNameLengthFromIndex

int DDC_GetFilePropertyNameLengthFromIndex (DDCFileHandle file, size_t index, size_t* propertyNameLength);

Purpose

Gets the length of the name of a file property with the specified index. The length does not include the terminating NUL byte.

You can call this function to determine the necessary buffer size before getting the name of a file property.

Parameters

Input
Name | Type | Description
file | DDCFileHandle | The file handle. You obtain this handle from the DDC_OpenFile or DDC_CreateFile function.
index | size_t | The zero-based index of the file property. The maximum index is one less than the total number of properties on the file. You can obtain the total number of properties on the file by calling DDC_GetNumFileProperties.
Output
Name | Type | Description
propertyNameLength | size_t * | The length of the name of the file property. The length does not include the terminating NUL byte.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_GetFilePropertyNames

int DDC_GetFilePropertyNames (DDCFileHandle file, char **propertyNames, size_t numberOfPropertyNames);

Purpose

Gets the names of the properties on the specified file.

Note Note If you are using this library from a language other than C or C++, you should consider using the functions that get a file property name or name length by index.

Parameters

Input
Name | Type | Description
file | DDCFileHandle | The file handle. You obtain this handle from the DDC_OpenFile or DDC_CreateFile function.
numberOfPropertyNames | size_t | The number of property names to copy into the buffer. The array passed in the propertyNames parameter must hold at least as many items as specified in this parameter.
Output
Name | Type | Description
propertyNames | char * | The array that will receive the property names of the specified file. This array must be large enough to hold at least the number of values specified by the numberOfPropertyNames parameter. You should pass an array of type character pointer (char *). This function will fill the array with string pointers allocated by this function. You must free these strings. Sample code is shown below: char **propertyNames = 0; unsigned int numberOfProperties, i; DDC_GetNumFileProperties (file, &numberOfProperties); propertyNames = malloc(numberOfProperties * sizeof(char*)); DDC_GetFilePropertyNames (file, propertyNames, numberOfProperties); for (i = 0; i < numberOfProperties; i++) DDC_FreeMemory (propertyNames[i]); free(propertyNames);

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 nilibddc.h.


DDC_GetFilePropertyTimestampComponents

int DDC_GetFilePropertyTimestampComponents (DDCFileHandle file, const char *property, unsigned int *year, unsigned int *month, unsigned int *day, unsigned int *hour, unsigned int *minute, unsigned int *second, double *milliSecond, unsigned int *weekDay);

Purpose

Gets the value of a property of data type DDC_Timestamp for the specified file. Obtain the timestamp value by passing separate values for each component of the timestamp.

Parameters

Input
Name | Type | Description
file | DDCFileHandle | The file handle. You obtain this handle from the DDC_OpenFile or DDC_CreateFile function.
property const char * The name of the file property. You can specify a built-in property or a property created by DDC_CreateFilePropertyTimestampComponents.

The following built-in property is available:

Property | Constant | Data Type
Datetime | DDC_FILE_DATETIME | Timestamp
Output
Name | Type | Description
year unsigned integer (passed by reference) The year component of the timestamp value. The year represents local calendar time.

Values less than 1970 are not supported on Windows 2000. Values less than 1601 are not supported on Windows XP or later.
month unsigned integer (passed by reference) The month component of the timestamp value. The month represents local calendar time.

Valid values are 1 (January) through 12 (December).
day unsigned integer (passed by reference) The day component of the timestamp value. The day of the month represents local calendar time.

Valid values are 1 through 31.
hour unsigned integer (passed by reference) The hour component of the timestamp value. The hour represents local calendar time.

Valid values are 0 through 23.
minute unsigned integer (passed by reference) The minute component of the timestamp value. The minute represents local calendar time.

Valid values are 0 through 59.
second unsigned integer (passed by reference) The second component of the timestamp value. The second represents local calendar time.

Valid values are 0 through 59.
millisecond double (passed by reference) The milliseconds component of the timestamp value. The millisecond represents local calendar time.

Only non-negative values are allowed.
weekDay unsigned integer (passed by reference) The week day information of the timestamp value.

Valid values are 0 (Sunday) to 6 (Saturday).

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_GetFilePropertyType

int DDC_GetFilePropertyType (DDCFileHandle file, const char *property, DDCDataType *dataType);

Purpose

Gets the data type of the specified property.

Parameters

Input
Name | Type | Description
file | DDCFileHandle | The file handle. You obtain this handle from the DDC_OpenFile or DDC_CreateFile function.
property | const char * | The name of the file property.
Output
Name | Type | Description
dataType | DDCDataType | The data type of the specified property.

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 nilibddc.h.


DDC_GetFileProperty[type]

int DDC_GetFilePropertyUInt8 (DDCFileHandle file, const char* property, unsigned char* value);

int DDC_GetFilePropertyInt16 (DDCFileHandle file, const char* property, short* value);

int DDC_GetFilePropertyInt32 (DDCFileHandle file, const char* property, long* value);

int DDC_GetFilePropertyFloat (DDCFileHandle file, const char* property, float* value);

int DDC_GetFilePropertyDouble (DDCFileHandle file, const char* property, double* value);

int DDC_GetFilePropertyString (DDCFileHandle file, const char* property, char value[], size_t valueSize);

Purpose

Gets the value of a file property.

The DIAdem Connectivity Library provides the following typesafe functions to obtain the value of a file property. The function you use depends on the data type of the file property.

DDC_GetFilePropertyUInt8
DDC_GetFilePropertyInt16
DDC_GetFilePropertyInt32
DDC_GetFilePropertyFloat
DDC_GetFilePropertyDouble
DDC_GetFilePropertyString

If the data type of the property is DDC_Timestamp, you must call DDC_GetFilePropertyTimestampComponents.

Parameters

Input
Name | Type | Description
file | DDCFileHandle | The file handle. You obtain this handle from the DDC_OpenFile or DDC_CreateFile function.
property const char * The name of the file property. You can specify a built-in property or a property created by DDC_CreateFileProperty.

The following built-in properties are available:

Property | Constant | Data Type
Name | DDC_FILE_NAME | String (char *)
Description | DDC_FILE_DESCRIPTION | String (char *)
Title | DDC_FILE_TITLE | String (char *)
Author | DDC_FILE_AUTHOR | String (char *)
Datetime | DDC_FILE_DATETIME | Timestamp
valueSize size_t The size, in bytes, of the memory location specified by the value parameter.

If the value you pass for this parameter is less than the size required to hold the string property, the value of the string property that you get is truncated but still contains the terminating NUL byte.

Note Note This parameter is valid only for the DDC_GetFilePropertyString function.
Output
Name | Type | Description
value depends on the function The pointer that receives the value of the specified file property.

When calling DDC_GetFilePropertyString, you must pass a string buffer. This buffer must be large enough to hold the entire string as reported by DDC_GetFileStringPropertyLength plus the terminating NUL byte. Sample code is shown below:

char *buffer;

size_t length;

DDC_GetFileStringPropertyLength (file, "MyStringProperty", &length);

buffer = malloc(sizeof(char) * (length+1));

DDC_GetFilePropertyString (file, "MyStringProperty", buffer, length+1);

free (buffer); // Free the buffer when you are finished with it.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_GetFileStringPropertyLength

int DDC_GetFileStringPropertyLength (DDCFileHandle file, const char *property, unsigned int *length);

Purpose

Gets the length of the current value of a string property. The length does not include the terminating NUL byte.

You can call this function to determine the necessary buffer size before getting the value of a string property.

Parameters

Input
Name | Type | Description
file | DDCFileHandle | The file handle. You obtain this handle from the DDC_OpenFile or DDC_CreateFile function.
property const char * The name of the file property. You can specify a built-in property or a property created by DDC_CreateFileProperty.

The following built-in properties are available:

Property | Constant | Data Type
Name | DDC_FILE_NAME | String (char *)
Description | DDC_FILE_DESCRIPTION | String (char *)
Title | DDC_FILE_TITLE | String (char *)
Author | DDC_FILE_AUTHOR | String (char *)
Output
Name | Type | Description
length | unsigned int | The length of the current value of the string property. The length does not include the terminating NUL byte.

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 nilibddc.h.


DDC_GetLibraryErrorDescription

const char *DDC_GetLibraryErrorDescription (int errorCode);

Purpose

Converts the error code returned by a DIAdem Connectivity Library function into a meaningful error message.

Parameters

Input
Name | Type | Description
errorCode | int | An error code returned by a DIAdem Connectivity Library function.

Return Value

Name | Type | Description
errorDescription | const char * | Explanation of the error code. Do not modify or free this string.


DDC_GetNumChannelGroups

int DDC_GetNumChannelGroups (DDCFileHandle file, unsigned int *numberOfChannelGroups);

Purpose

Gets the number of channel groups in the specified file.

Parameters

Input
Name | Type | Description
file | DDCFileHandle | The file handle. You obtain this handle from the DDC_OpenFile or DDC_CreateFile function.
Output
Name | Type | Description
numberOfChannelGroups | unsigned int | The number of channel groups in the specified file.

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 nilibddc.h.


DDC_GetNumChannels

int DDC_GetNumChannels (DDCChannelGroupHandle channelGroup, unsigned int *numberOfChannels);

Purpose

Gets the number of channels in the specified channel group.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The channel group handle.
Output
Name | Type | Description
numberOfChannels | unsigned int | The number of channels in the specified channel group.

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 nilibddc.h.


DDC_GetNumChannelGroupProperties

int DDC_GetNumChannelGroupProperties (DDCChannelGroupHandle channelGroup, unsigned int *numberOfProperties);

Purpose

Gets the number of properties on the specified channel group.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The channel group handle.
Output
Name | Type | Description
numberOfProperties | unsigned int | The number of properties on the specified channel group.

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 nilibddc.h.


DDC_GetNumChannelProperties

int DDC_GetNumChannelProperties (DDCChannelHandle channel, unsigned int *numberOfProperties);

Purpose

Gets the number of properties on the specified channel.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The channel handle.
Output
Name | Type | Description
numberOfProperties | unsigned int | The number of properties on the specified channel.

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 nilibddc.h.


DDC_GetNumDataValues

int DDC_GetNumDataValues (DDCChannelHandle channel, unsigned __int64 *numberOfValues);

Purpose

Gets the number of data values in the specified channel.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The channel handle.
Output
Name | Type | Description
numberOfValues | unsigned __int64 | The number of data values in the specified channel.

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 nilibddc.h.


DDC_GetNumFileProperties

int DDC_GetNumFileProperties (DDCFileHandle file, unsigned int *numberOfProperties);

Purpose

Gets the number of properties on the specified file.

Parameters

Input
Name | Type | Description
file | DDCFileHandle | The file handle. You obtain this handle from the DDC_OpenFile or DDC_CreateFile function.
Output
Name | Type | Description
numberOfProperties | unsigned int | The number of properties on the specified file.

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 nilibddc.h.


DDC_OpenFile

int DDC_OpenFile (const char *filePath, const char *fileType, DDCFileHandle *file);

Purpose

Opens a file handle for an existing DIAdem file. Pass the file handle to other DIAdem Connectivity Library functions to read or modify the file contents. Call DDC_SaveFile to save file modifications to disk.

Call the DDC_CloseFile function to close the file handle when you are finished.

Note DDC_OpenFile has been superseded by DDC_OpenFileEx. The new function takes an additional parameter for the read-only state of the file handle. Calling DDC_OpenFile is equivalent to passing False for the readOnly parameter with DDC_OpenFileEx.

Parameters

Input
Name | Type | Description
filePath | const char * | The path to the file that will be opened. If you do not specify an absolute pathname, then the pathname is relative to the current working directory.
fileType | const char * | The type of file to be opened. Pass TDM to open a .tdm file. Pass TDMS to open a .tdms file. If the file extension you specify in the filePath parameter is .tdm or .tdms, then you can pass NULL or the empty string to automatically use the file extension to specify the file type.
Output
Name | Type | Description
file | DDCFileHandle | The handle for the DIAdem file. Pass this handle to DIAdem Connectivity Library functions that require a file. Call DDC_SaveFile to save the file to disk. Call DDC_CloseFile to close the file handle when you are finished.

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 nilibddc.h.


DDC_OpenFileEx

int DDC_OpenFileEx (const char *filePath, const char *fileType, int readOnly, DDCFileHandle *file);

Purpose

Opens a file handle for an existing DIAdem file. Pass the file handle to other DIAdem Connectivity Library functions to read or modify the file contents. Call DDC_SaveFile to save file modifications to disk.

Call the DDC_CloseFile function to close the file handle when you are finished.

Parameters

Input
Name | Type | Description
filePath | const char * | The path to the file to open. If you do not pass an absolute pathname, then the pathname is relative to the current working directory.
fileType | const char * | The type of file to be opened. Pass TDM to open a .tdm file. Pass TDMS to open a .tdms file. If the file extension you specify in the filePath parameter is .tdm or .tdms, then you can pass NULL or the empty string to automatically use the file extension to specify the file type.
readOnly | int | The read-only state of the file handle. Pass False to allow read and write access to the file. Pass True to allow only read access. If the current user does not have write privileges for the file or if the file is marked read-only, then you should pass True for this parameter.
Output
Name | Type | Description
file | DDCFileHandle | The handle for the DIAdem file. Pass this handle to DIAdem Connectivity Library functions that require a file. Call DDC_SaveFile to save the file to disk. Call DDC_CloseFile to close the file handle when you are finished.

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 nilibddc.h.


DDC_RemoveChannel

int DDC_RemoveChannel (DDCChannelHandle channel);

Purpose

Removes a channel from a channel group.

This function does not close the channel handle. The handle will be closed automatically when the file handle that contained it is closed. The handle can be closed explicitly by calling DDC_CloseChannel.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The handle of the channel to be removed.

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 nilibddc.h.


DDC_RemoveChannelGroup

int DDC_RemoveChannelGroup (DDCChannelGroupHandle channelGroup);

Purpose

Removes a channel group and the channels it contains from a file.

This function does not close the channel group handle or any channel handles it contains. These handles will be closed automatically when the file handle that contained them is closed. These handle can be closed explicitly by calling DDC_CloseChannelGroup or DDC_CloseChannel.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The handle of the channel group to be removed.

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 nilibddc.h.


DDC_ReplaceDataValues

int DDC_ReplaceDataValues (DDCChannelHandle channel, size_t indexOfFirstValueToReplace, void *values, size_t numberOfValues);

Purpose

Replaces data values for the specified channel. New data values overwrite existing data values starting at the specified index.

Note Note If you are using this library from a language other than C or C++, you should consider using the type-safe version of this function.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The handle of the channel that contains the new data values.
indexOfFirstValueToReplace | size_t | The zero-based index of the first data value in the channel to be replaced. Data values starting at that index will be replaced by the values specified by the values parameter.
values void * An array of data values.

The type of this array must match the data type of the specified channel. You can call DDC_GetDataType to get the data type of a channel.

If the data type of the specified channel is DDC_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.

If the data type of the specified channel is string, you must pass an array of type character pointer (char *). The following code illustrates one way to pass an array of strings:

char *values[] = {"one", "two", "three", "four", "five"};
DDC_ReplaceDataValues (channel, 0, values, 5);

If the data type of the specified channel is DDC_Timestamp, you must call DDC_ReplaceDataValuesTimestampComponents instead of this function.
numberOfValues | size_t | The number of values in the array specified by the values parameter.

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 nilibddc.h.


DDC_ReplaceDataValuesTimestampComponents

int DDC_ReplaceDataValuesTimestampComponents (DDCChannelHandle channel, unsigned int indexOfFirstValueToReplace, unsigned int year[], unsigned int month[], unsigned int day[], unsigned int hour[], unsigned int minute[], unsigned int second[], double milliSecond[], size_t numValues);

Purpose

Replaces data values for the specified channel. New data values overwrite existing data values starting at the specified index.

Specify the timestamp values by passing separate arrays for each component of a timestamp. DDC_ReplaceDataValuesTimestampComponents constructs each complete timestamp value by combining the corresponding entries from each of the separate arrays.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The handle of the channel that contains the new data values. The data type of the specified channel must be DDC_Timestamp.
indexOfFirstValueToReplace | unsigned integer | The zero-based index of the first data value in the channel to be replaced. DDC_ReplaceDataValuesTimestampComponents replaces data values starting at this index with the new values.
year | unsigned integer [] | An array of values containing the year component of the timestamp values. This function combines each year value with the corresponding values from the other timestamp component arrays to construct a single timestamp value. The year represents local calendar time. Values less than 1970 are not supported on Windows 2000. Values less than 1601 are not supported on Windows XP or later.
month | unsigned integer [] | An array of values containing the month component of the timestamp values. This function combines each month value with the corresponding values from the other timestamp component arrays to construct a single timestamp value. The month represents local calendar time. Valid values are 1 (January) through 12 (December).
day | unsigned integer [] | An array of values containing the day component of the timestamp values. This function combines each day value with the corresponding values from the other timestamp component arrays to construct a single timestamp value. The day of the month represents local calendar time. Valid values are 1 through 31.
hour | unsigned integer [] | An array of values containing the hour component of the timestamp values. This function combines each hour value with the corresponding values from the other timestamp component arrays to construct a single timestamp value. The hour represents local calendar time. Valid values are 0 through 23.
minute | unsigned integer [] | An array of values containing the minute component of the timestamp values. This function combines each minute value with the corresponding values from the other timestamp component arrays to construct a single timestamp value. The minute represents local calendar time. Valid values are 0 through 59.
second | unsigned integer [] | An array of values containing the second component of the timestamp values. This function combines each second value with the corresponding values from the other timestamp component arrays to construct a single timestamp value. The second represents local calendar time. Valid values are 0 through 59.
millisecond | double [] | An array of values containing the milliseconds component of the timestamp values. This function combines each millisecond value with the corresponding values from the other timestamp component arrays to construct a single timestamp value. The millisecond represents local calendar time. You can specify only non-negative values.
numberOfValues | size_t | The number of values in each of the timestamp components arrays.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_ReplaceDataValues[type]

int DDC_ReplaceDataValuesUInt8 (DDCChannelHandle channel, size_t indexOfFirstValueToReplace, unsigned char values[], size_t numValues);

int DDC_ReplaceDataValuesInt16 (DDCChannelHandle channel, size_t indexOfFirstValueToReplace, short values[], size_t numValues);

int DDC_ReplaceDataValuesInt32 (DDCChannelHandle channel, size_t indexOfFirstValueToReplace, long values[], size_t numValues);

int DDC_ReplaceDataValuesFloat (DDCChannelHandle channel, size_t indexOfFirstValueToReplace, float values[], size_t numValues);

int DDC_ReplaceDataValuesDouble (DDCChannelHandle channel, size_t indexOfFirstValueToReplace, double values[], size_t numValues);

int DDC_ReplaceDataValuesString (DDCChannelHandle channel, size_t indexOfFirstValueToReplace, const char *values[], size_t numValues);

Purpose

Replaces data values for the specified channel. New data values overwrite existing data values starting at the specified index.

The DIAdem Connectivity Library provides the following typesafe functions to replace data values for a channel. The function you use depends on the data type of the specified channel.

DDC_ReplaceDataValuesUInt8
DDC_ReplaceDataValuesInt16
DDC_ReplaceDataValuesInt32
DDC_ReplaceDataValuesFloat
DDC_ReplaceDataValuesDouble
DDC_ReplaceDataValuesString

If the data type of the specified channel is DDC_Timestamp, you must call DDC_ReplaceDataValuesTimestampComponents.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The handle of the channel that contains the new data values. The data type of the specified channel must match the data type in the function name.
indexOfFirstValueToReplace | size_t | The zero-based index of the first data value in the channel to be replaced. Data values starting at that index will be replaced by the values specified by the values parameter.
values | depends on the function | An array of data values. The type of this array must match the data type of the specified channel. You can call DDC_GetDataType to get the data type of a channel. When calling DDC_ReplaceDataValuesString, you must pass an array of type character pointer (char *). The following code illustrates one way to pass an array of strings: char *values[] = {"one", "two", "three", "four", "five"}; DDC_ReplaceDataValuesString (channel, 0, values, 5);
numValues | size_t | The number of values in the array specified by the values parameter.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_SaveFile

int DDC_SaveFile (DDCFileHandle file);

Purpose

Saves a file to disk. Call this function to save a newly created file to disk or to save changes to an existing file.

This function does not close the file handle. Call DDC_CloseFile to close the file handle.

Parameters

Input
Name | Type | Description
file | DDCFileHandle | The handle of the file to be saved. You obtain this handle from the DDC_OpenFile or DDC_CreateFile function.

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 nilibddc.h.


DDC_SetChannelGroupProperty

int DDC_SetChannelGroupProperty (DDCChannelGroupHandle channelGroup, const char *property, void *value);

Purpose

Sets the value of a channel group property.

Note Note If you are using this library from a language other than C or C++, you should consider using the type-safe version of this function.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The channel group handle.
property const char * The name of the channel group property. You can specify a built-in property or a property created by DDC_CreateChannelGroupProperty.

The following built-in properties are available:

Property | Constant | Data Type
Name | DDC_CHANNELGROUP_NAME | String (char *)
Description | DDC_CHANNELGROUP_DESCRIPTION | String (char *)
value void * The value of the specified channel group property.

If the data type of the specified property is DDC_Timestamp, you must pass a value of type CVIAbsoluteTime. Refer to the Absolute Time functions in the Utility Library for more information about this type.

If the data type of the specified property is DDC_Timestamp, you must call DDC_SetChannelGroupPropertyTimestampComponents instead of this function.

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 nilibddc.h.


DDC_SetChannelGroupPropertyTimestampComponents

int DDC_SetChannelGroupPropertyTimestampComponents (DDCChannelGroupHandle channelGroup, const char *property, unsigned int year, unsigned int month, unsigned int day, unsigned int hour, unsigned int minute, unsigned int second, double milliSecond);

Purpose

Sets a property of data type DDC_Timestamp for the specified channel group. Specify the timestamp value by passing separate values for each component of the timestamp.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The channel group handle.
property | const char * | The name of the channel group property.
year | unsigned integer | The year component of the timestamp value. The year represents local calendar time. Values less than 1970 are not supported on Windows 2000. Values less than 1601 are not supported on Windows XP or later.
month | unsigned integer | The month component of the timestamp value. The month represents local calendar time. Valid values are 1 (January) through 12 (December).
day | unsigned integer | The day component of the timestamp value. The day of the month represents local calendar time. Valid values are 1 through 31.
hour | unsigned integer | The hour component of the timestamp value. The hour represents local calendar time. Valid values are 0 through 23.
minute | unsigned integer | The minute component of the timestamp value. The minute represents local calendar time. Valid values are 0 through 59.
second | unsigned integer | The second component of the timestamp value. The second represents local calendar time. Valid values are 0 through 59.
millisecond | double | The milliseconds component of the timestamp value. The millisecond represents local calendar time. You can specify only non-negative values.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_SetChannelGroupProperty[type]

int DDC_SetChannelGroupPropertyUInt8 (DDCChannelGroupHandle channelGroup, const char* property, unsigned char value);

int DDC_SetChannelGroupPropertyInt16 (DDCChannelGroupHandle channelGroup, const char* property, short value);

int DDC_SetChannelGroupPropertyInt32 (DDCChannelGroupHandle channelGroup, const char* property, long value);

int DDC_SetChannelGroupPropertyFloat (DDCChannelGroupHandle channelGroup, const char* property, float value);

int DDC_SetChannelGroupPropertyDouble (DDCChannelGroupHandle channelGroup, const char* property, double value);

int DDC_SetChannelGroupPropertyString (DDCChannelGroupHandle channelGroup, const char* property, const char *value);

Purpose

Sets the value of a channel group property.

The DIAdem Connectivity Library provides the following typesafe functions to set the value of a channel group property. The function you use depends on the data type of the specified channel.

DDC_SetChannelGroupPropertyUInt8
DDC_SetChannelGroupPropertyInt16
DDC_SetChannelGroupPropertyInt32
DDC_SetChannelGroupPropertyFloat
DDC_SetChannelGroupPropertyDouble
DDC_SetChannelGroupPropertyString

If the data type of the property is DDC_Timestamp, you must call DDC_SetChannelGroupPropertyTimestampComponents.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The channel group handle.
property const char * The name of the channel group property. You can specify a built-in property or a property created by DDC_CreateChannelGroupProperty.

The following built-in properties are available:

Property | Constant | Data Type
Name | DDC_CHANNELGROUP_NAME | String (char *)
Description | DDC_CHANNELGROUP_DESCRIPTION | String (char *)
value | depends on the function | The value of the specified channel group property.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_SetChannelProperty

int DDC_SetChannelProperty (DDCChannelHandle channel, const char *property, void *value);

Purpose

Sets the value of a channel property.

Note Note If you are using this library from a language other than C or C++, you should consider using the type-safe version of this function.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The channel handle.
property const char * The name of the channel property. You can specify a built-in property or a property created by DDC_CreateChannelProperty.

The following built-in properties are available:

Property | Constant | Data Type
Name | DDC_CHANNEL_NAME | String (char *)
Description | DDC_CHANNEL_DESCRIPTION | String (char *)
Unit String | DDC_CHANNEL_UNIT_STRING | String (char *)
Minimum | DDC_CHANNEL_MINIMUM | Double
Maximum | DDC_CHANNEL_MAXIMUM | Double
value void * The value of the specified channel property.

If the data type of the specified property is DDC_Timestamp, you must pass a value of type CVIAbsoluteTime. Refer to the Absolute Time functions in the Utility Library for more information about this type.

If the data type of the specified property is DDC_Timestamp, you must call DDC_SetChannelPropertyTimestampComponents instead of this function.

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 nilibddc.h.


DDC_SetChannelPropertyTimestampComponents

int DDC_SetChannelPropertyTimestampComponents (DDCChannelHandle channel, const char *property, unsigned int year, unsigned int month, unsigned int day, unsigned int hour, unsigned int minute, unsigned int second, double milliSecond);

Purpose

Sets a property of data type DDC_Timestamp for the specified channel. Specify the timestamp value by passing separate values for each component of the timestamp.

Parameters

Input
Name | Type | Description
channelGroup | DDCChannelGroupHandle | The channel handle.
property | const char * | The name of the channel property.
year | unsigned integer | The year component of the timestamp value. The year represents local calendar time. Values less than 1970 are not supported on Windows 2000. Values less than 1601 are not supported on Windows XP or later.
month | unsigned integer | The month component of the timestamp value. The month represents local calendar time. Valid values are 1 (January) through 12 (December).
day | unsigned integer | The day component of the timestamp value. The day of the month represents local calendar time. Valid values are 1 through 31.
hour | unsigned integer | The hour component of the timestamp value. The hour represents local calendar time. Valid values are 0 through 23.
minute | unsigned integer | The minute component of the timestamp value. The minute represents local calendar time. Valid values are 0 through 59.
second | unsigned integer | The second component of the timestamp value. The second represents local calendar time. Valid values are 0 through 59.
millisecond | double | The milliseconds component of the timestamp value. The millisecond represents local calendar time. You can specify only non-negative values.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_SetChannelProperty[type]

int DDC_SetChannelPropertyUInt8 (DDCChannelHandle channel, const char* property, unsigned char value);

int DDC_SetChannelPropertyInt16 (DDCChannelHandle channel, const char* property, short value);

int DDC_SetChannelPropertyInt32 (DDCChannelHandle channel, const char* property, long value);

int DDC_SetChannelPropertyFloat (DDCChannelHandle channel, const char* property, float value);

int DDC_SetChannelPropertyDouble (DDCChannelHandle channel, const char* property, double value);

int DDC_SetChannelPropertyString (DDCChannelHandle channel, const char* property, const char *value);

Purpose

Sets the value of a channel property.

The DIAdem Connectivity Library provides the following typesafe functions to create a property for a channel. The function you use depends on the data type of the specified channel.

DDC_SetChannelPropertyUInt8
DDC_SetChannelPropertyInt16
DDC_SetChannelPropertyInt32
DDC_SetChannelPropertyFloat
DDC_SetChannelPropertyDouble
DDC_SetChannelPropertyString

If the data type of the property is DDC_Timestamp, you must call DDC_SetChannelPropertyTimestampComponents.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The channel handle.
property const char * The name of the channel property. You can specify a built-in property or a property created by DDC_CreateChannelProperty.

The following built-in properties are available:

Property | Constant | Data Type
Name | DDC_CHANNEL_NAME | String (char *)
Description | DDC_CHANNEL_DESCRIPTION | String (char *)
Unit String | DDC_CHANNEL_UNIT_STRING | String (char *)
Minimum | DDC_CHANNEL_MINIMUM | Double
Maximum | DDC_CHANNEL_MAXIMUM | Double
value | depends on the function | The value of the specified channel property.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_SetDataValues

int DDC_SetDataValues (DDCChannelHandle channel, void *values, size_t numberOfValues);

Purpose

Sets the data values for the specified channel. DDC_SetDataValues overwrites any existing data values.

Note Note If you are using this library from a language other than C or C++, you should consider using the type-safe version of this function.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The handle of the channel that contains the new data values.
values void * An array of data values.

The type of this array must match the data type of the specified channel. You can call DDC_GetDataType to get the data type of a channel.

If the data type of the specified channel is DDC_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.

If the data type of the specified channel is string, you must pass an array of type character pointer (char *). The following code illustrates one way to pass an array of strings:

char *values[] = {"one", "two", "three", "four", "five"};
DDC_SetDataValues (channel, values, 5);

If the data type of the specified channel is DDC_Timestamp, you must call DDC_SetDataValuesTimestampComponents instead of this function.
numberOfValues | size_t | The number of values in the array specified by the values parameter.

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 nilibddc.h.


DDC_SetDataValuesTimestampComponents

int DDC_SetDataValuesTimestampComponents (DDCChannelHandle channel, unsigned int year[], unsigned int month[], unsigned int day[], unsigned int hour[], unsigned int minute[], unsigned int second[], double milliSecond[], size_t numValues);

Purpose

Sets the data values for the specified channel. DDC_SetDataValuesTimestampComponents overwrites any existing data values.

Specify the timestamp values by passing separate arrays for each component of a timestamp. DDC_SetDataValuesTimestampComponents constructs each complete timestamp value by combining the corresponding entries from each of the separate arrays.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The handle of the channel that contains the new data values. The data type of the specified channel must be DDC_Timestamp.
year | unsigned integer [] | An array of values containing the year component of the timestamp values. This function combines each year value with the corresponding values from the other timestamp component arrays to construct a single timestamp value. The year represents local calendar time. Values less than 1970 are not supported on Windows 2000. Values less than 1601 are not supported on Windows XP or later.
month | unsigned integer [] | An array of values containing the month component of the timestamp values. This function combines each month value with the corresponding values from the other timestamp component arrays to construct a single timestamp value. The month represents local calendar time. Valid values are 1 (January) through 12 (December).
day | unsigned integer [] | An array of values containing the day component of the timestamp values. This function combines day value with the corresponding values from the other timestamp component arrays to construct a single timestamp value. The day of the month represents local calendar time. Valid values are 1 through 31.
hour | unsigned integer [] | An array of values containing the hour component of the timestamp values. This function combines each hour value with the corresponding values from the other timestamp component arrays to construct a single timestamp value. The hour represents local calendar time. Valid values are 0 through 23.
minute | unsigned integer [] | An array of values containing the minute component of the timestamp values. This function combines each minute value with the corresponding values from the other timestamp component arrays to construct a single timestamp value. The minute represents local calendar time. Valid values are 0 through 59.
second | unsigned integer [] | An array of values containing the second component of the timestamp values. This function combines each second value with the corresponding values from the other timestamp component arrays to construct a single timestamp value. The second represents local calendar time. Valid values are 0 through 59.
millisecond | double [] | An array of values containing the milliseconds component of the timestamp values. This function combines each millisecond value with the corresponding values from the other timestamp component arrays to construct a single timestamp value. The millisecond represents local calendar time. You can specify only non-negative values.
numberOfValues | size_t | The number of values in each of the timestamp components arrays.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_SetDataValues[type]

int DDC_SetDataValuesUInt8 (DDCChannelHandle channel, unsigned char values[], size_t numValues);

int DDC_SetDataValuesInt16 (DDCChannelHandle channel, short values[], size_t numValues);

int DDC_SetDataValuesInt32 (DDCChannelHandle channel, long values[], size_t numValues);

int DDC_SetDataValuesFloat (DDCChannelHandle channel, float values[], size_t numValues);

int DDC_SetDataValuesDouble (DDCChannelHandle channel, double values[], size_t numValues);

int DDC_SetDataValuesString (DDCChannelHandle channel, const char *values[], size_t numValues);

Purpose

Sets the data values for the specified channel. DDC_SetDataValues[type] overwrites any existing data values.

The DIAdem Connectivity Library provides the following typesafe functions to set the data value for a channel. The function you use depends on the data type of the specified channel.

DDC_SetDataValuesUInt8
DDC_SetDataValuesInt16
DDC_SetDataValuesInt32
DDC_SetDataValuesFloat
DDC_SetDataValuesDouble
DDC_SetDataValuesString

If the data type of the specified channel is DDC_Timestamp, you must call DDC_SetDataValuesTimestampComponents.

Parameters

Input
Name | Type | Description
channel | DDCChannelHandle | The handle of the channel that contains the new data values. The data type of the specified channel must match the data type in the function name.
values | depends on the function | An array of data values. When calling DDC_SetDataValuesString, you must pass an array of type character pointer (char *). The following code illustrates one way to pass an array of strings: char *values[] = {"one", "two", "three", "four", "five"}; DDC_SetDataValuesString (channel, values, 5);
numValues | size_t | The number of values in the array specified by the values parameter.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_SetFileProperty

int DDC_SetFileProperty (DDCFileHandle file, const char *property, void *value);

Purpose

Sets the value of a file property.

Note Note If you are using this library from a language other than C or C++, you should consider using the type-safe version of this function.

Parameters

Input
Name | Type | Description
file | DDCFileHandle | The file handle. You obtain this handle from the DDC_OpenFile or DDC_CreateFile function.
property const char * The name of the file property. You can specify a built-in property or a property created by DDC_CreateFileProperty.

The following built-in properties are available:

Property | Constant | Data Type
Name | DDC_FILE_NAME | String (char *)
Description | DDC_FILE_DESCRIPTION | String (char *)
Title | DDC_FILE_TITLE | String (char *)
Author | DDC_FILE_AUTHOR | String (char *)
Datetime | DDC_FILE_DATETIME | Timestamp
value void * The value of the specified file property.

If the data type of the specified property is DDC_Timestamp, you must pass a value of type CVIAbsoluteTime. Refer to the Absolute Time functions in the Utility Library for more information about this type.

If the data type of the specified property is DDC_Timestamp, you must call DDC_SetFilePropertyTimestampComponents instead of this function.

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 nilibddc.h.


DDC_SetFilePropertyTimestampComponents

int DDC_SetFilePropertyTimestampComponents (DDCFileHandle file, const char *property, unsigned int year, unsigned int month, unsigned int day, unsigned int hour, unsigned int minute, unsigned int second, double milliSecond);

Purpose

Sets a property of data type DDC_Timestamp for the specified file. Specify the timestamp value by passing separate values for each component of the timestamp.

Parameters

Input
Name | Type | Description
file | DDCFileHandle | The file handle. You obtain this handle from the DDC_OpenFile or DDC_CreateFile function.
property const char * The name of the file property. You can specify a built-in property or a property created by DDC_CreateFilePropertyTimestampComponents.

The following built-in property is available:

Property | Constant | Data Type
Datetime | DDC_FILE_DATETIME | Timestamp
year unsigned integer The year component of the timestamp value. The year represents local calendar time.

Values less than 1970 are not supported on Windows 2000. Values less than 1601 are not supported on Windows XP or later.
month unsigned integer The month component of the timestamp value. The month represents local calendar time.

Valid values are 1 (January) through 12 (December).
day unsigned integer The day component of the timestamp value. The day of the month represents local calendar time.

Valid values are 1 through 31.
hour unsigned integer The hour component of the timestamp value. The hour represents local calendar time.

Valid values are 0 through 23.
minute unsigned integer The minute component of the timestamp value. The minute represents local calendar time.

Valid values are 0 through 59.
second unsigned integer The second component of the timestamp value. The second represents local calendar time.

Valid values are 0 through 59.
millisecond double The milliseconds component of the timestamp value. The millisecond represents local calendar time.

You can specify only non-negative values.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


DDC_SetFileProperty[type]

int DDC_SetFilePropertyUInt8 (DDCFileHandle file, const char* property, unsigned char value);

int DDC_SetFilePropertyInt16 (DDCFileHandle file, const char* property, short value);

int DDC_SetFilePropertyInt32 (DDCFileHandle file, const char* property, long value);

int DDC_SetFilePropertyFloat (DDCFileHandle file, const char* property, float value);

int DDC_SetFilePropertyDouble (DDCFileHandle file, const char* property, double value);

int DDC_SetFilePropertyString (DDCFileHandle file, const char* property, const char *value);

Purpose

Sets the value of a file property.

The DIAdem Connectivity Library provides the following typesafe functions to set the value of a file property. The function you use depends on the data type of the file property.

DDC_SetFilePropertyUInt8
DDC_SetFilePropertyInt16
DDC_SetFilePropertyInt32
DDC_SetFilePropertyFloat
DDC_SetFilePropertyDouble
DDC_SetFilePropertyString

If the data type of the property is DDC_Timestamp, you must call DDC_SetFilePropertyTimestampComponents.

Parameters

Input
Name | Type | Description
file | DDCFileHandle | The file handle. You obtain this handle from the DDC_OpenFile or DDC_CreateFile function.
property const char * The name of the file property. You can specify a built-in property or a property created by DDC_CreateFileProperty.

The following built-in properties are available:

Property | Constant | Data Type
Name | DDC_FILE_NAME | String (char *)
Description | DDC_FILE_DESCRIPTION | String (char *)
Title | DDC_FILE_TITLE | String (char *)
Author | DDC_FILE_AUTHOR | String (char *)
Datetime | DDC_FILE_DATETIME | Timestamp
value | depends on the function | The value of the specified file property.

Return Value

Name | Type | Description
status | integer | 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 nilibddc.h.


Important Information

Warranty

Copyright

Trademarks

Patents

Warning Regarding Use of NI Products


Warranty

The media on which you receive National Instruments software are warranted not to fail to execute programming instructions, due to defects in materials and workmanship, for a period of 90 days from date of shipment, as evidenced by receipts or other documentation. National Instruments will, at its option, repair or replace software media that do not execute programming instructions if National Instruments receives notice of such defects during the warranty period. National Instruments does not warrant that the operation of the software shall be uninterrupted or error free.

A Return Material Authorization (RMA) number must be obtained from the factory and clearly marked on the outside of the package before any equipment will be accepted for warranty work. National Instruments will pay the shipping costs of returning to the owner parts which are covered by warranty.

National Instruments believes that the information in this document is accurate. The document has been carefully reviewed for technical accuracy. In the event that technical or typographical errors exist, National Instruments reserves the right to make changes to subsequent editions of this document without prior notice to holders of this edition. The reader should consult National Instruments if errors are suspected. In no event shall National Instruments be liable for any damages arising out of or related to this document or the information contained in it.

EXCEPT AS SPECIFIED HEREIN, NATIONAL INSTRUMENTS MAKES NO WARRANTIES, EXPRESS OR IMPLIED, AND SPECIFICALLY DISCLAIMS ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. CUSTOMER'S RIGHT TO RECOVER DAMAGES CAUSED BY FAULT OR NEGLIGENCE ON THE PART OF NATIONAL INSTRUMENTS SHALL BE LIMITED TO THE AMOUNT THERETOFORE PAID BY THE CUSTOMER. NATIONAL INSTRUMENTS WILL NOT BE LIABLE FOR DAMAGES RESULTING FROM LOSS OF DATA, PROFITS, USE OF PRODUCTS, OR INCIDENTAL OR CONSEQUENTIAL DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. This limitation of the liability of National Instruments will apply regardless of the form of action, whether in contract or tort, including negligence. Any action against National Instruments must be brought within one year after the cause of action accrues. National Instruments shall not be liable for any delay in performance due to causes beyond its reasonable control. The warranty provided herein does not cover damages, defects, malfunctions, or service failures caused by owner's failure to follow the National Instruments installation, operation, or maintenance instructions; owner's modification of the product; owner's abuse, misuse, or negligent acts; and power failure or surges, fire, flood, accident, actions of third parties, or other events outside reasonable control.


Copyright

I. Under the copyright laws, this publication may not be reproduced or transmitted in any form, electronic or mechanical, including photocopying, recording, storing in an information retrieval system, or translating, in whole or in part, without the prior written consent of National Instruments Corporation.

National Instruments respects the intellectual property of others, and we ask our users to do the same. NI software is protected by copyright and other intellectual property laws. Where NI software may be used to reproduce software or other materials belonging to others, you may use NI software only to reproduce materials that you may reproduce in accordance with the terms of any applicable license or other legal restriction.

II. Third Party Copyright Notices

A. In regards to components used in USI (Xerces C++, Stingray, ICU, HDF5, b64, and STLport), the following copyright notices apply.

Xerces C++

This product includes software developed by the Apache Software Foundation (http://www.apache.org/) that is subject to the Apache License, Version 2.0, a copy of which may be found at: http://www.apache.org/licenses/LICENSE-2.0. Copyright 1999 The Apache Software Foundation. All rights reserved.

Stingray

This software includes Stingray software developed by Rogue Wave Software division of Quovadx, Inc. Copyright 1995-2006. Quovadx, Inc. All Rights Reserved.

ICU

Copyright (c) 1995-2009 International Business Machines Corporation and others

All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, provided that the above copyright notice(s) and this permission notice appear in all copies of the Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder.

HDF5

Copyright Notice and Statement for NCSA Hierarchical Data Format (HDF) Software Library and Utilities

NCSA HDF5 (Hierarchical Data Format 5) Software Library and Utilities Copyright 1998, 1999, 2000, 2001, 2002, 2003 by the Board of Trustees of the University of Illinois. All rights reserved.

Contributors: National Center for Supercomputing Applications (NCSA) at the University of Illinois at Urbana-Champaign (UIUC), Lawrence Livermore National Laboratory (LLNL), Sandia National Laboratories (SNL), Los Alamos National Laboratory (LANL), Jean-loup Gailly and Mark Adler (gzip library).

Redistribution and use in source and binary forms, with or without modification, are permitted for any purpose (including commercial purposes) provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions, and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the following disclaimer in the documentation and/or materials provided with the distribution.
  3. In addition, redistributions of modified forms of the source or binary code must carry prominent notices stating that the original code was changed and the date of the change.
  4. All publications or advertising materials mentioning features or use of this software are asked, but not required, to acknowledge that it was developed by the National Center for Supercomputing Applications at the University of Illinois at Urbana-Champaign and to credit the contributors.
  5. Neither the name of the University nor the names of the Contributors may be used to endorse or promote products derived from this software without specific prior written permission from the University or the Contributors, as appropriate for the name(s) to be used.
  6. THIS SOFTWARE IS PROVIDED BY THE UNIVERSITY AND THE CONTRIBUTORS "AS IS" WITH NO WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED. In no event shall the University or the Contributors be liable for any damages suffered by the users arising out of the use of this software, even if advised of the possibility of such damage.

Portions of HDF5 were developed with support from the University of California, Lawrence Livermore National Laboratory (UC LLNL). The following statement applies to those portions of the product and must be retained in any redistribution of source code, binaries, documentation, and/or accompanying materials:

This work was partially produced at the University of California, Lawrence Livermore National Laboratory (UC LLNL) under contract no. W-7405-ENG-48 (Contract 48) between the U.S. Department of Energy (DOE) and The Regents of the University of California (University) for the operation of UC LLNL.

DISCLAIMER:

This work was prepared as an account of work sponsored by an agency of the United States Government. Neither the United States Government nor the University of California nor any of their employees, makes any warranty, express or implied, or assumes any liability or usefulness of any information, apparatus, product, or process disclosed, or represents that its use would not infringe privately-owned rights. Reference herein to any specific commercial products, process, or service by trade name, trademark, manufacturer, or otherwise, does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or the University of California. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or the University of California, and shall not be used for advertising or product endorsement purposes.

b64

File: | b64.c
Purpose: | Implementation file for the b64 library
Created: | 18th October 2004
Updated: | 2nd August 2006
Home: | http://synesis.com.au/software/

Copyright (c) 2004-2006, Matthew Wilson and Synesis Software

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • Neither the name(s) of Matthew Wilson and Synesis Software nor the names of any contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

STLport

Copyright 1999-2003 Boris Fomitchev

This material is provided "as is", with absolutely no warranty expressed or implied. Any use is at your own risk.

Permission to use or copy this software for any purpose is hereby granted without fee, provided the above notices are retained on all copies. Permission to modify the code and to distribute modified code is granted, provided the above notices are retained, and a notice that the code was modified is included with the above copyright notice.

The Licensee may distribute binaries compiled with STLport (whether original or modified) without any royalties or restrictions.

The Licensee may distribute original or modified STLport sources, provided that:

  • The conditions indicated in the above permission notice are met;
  • The following copyright notices are retained when present, and conditions provided in accompanying permission notices are met:

    Copyright 1994 Hewlett-Packard Company

    Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Hewlett-Packard Company makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.

    Copyright 1996-1999 Silicon Graphics Computer Systems, Inc.

    Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Silicon Graphics makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.

    Copyright 1997 Moscow Center for SPARC Technology.

    Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Moscow Center for SPARC Technology makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.


Trademarks

National Instruments, NI, ni.com, and LabVIEW are trademarks of National Instruments Corporation. Refer to the Terms of Use section on ni.com/legal for more information about National Instruments trademarks.

Other product and company names mentioned herein are trademarks or trade names of their respective companies.

Members of the National Instruments Alliance Partner Program are business entities independent from National Instruments and have no agency, partnership, or joint-venture relationship with National Instruments.


Patents

For patents covering National Instruments products, refer to the appropriate location: Help»Patents in your software, the patents.txt file on your CD, or ni.com/patents.


WARNING REGARDING USE OF NATIONAL INSTRUMENTS PRODUCTS

(1) NATIONAL INSTRUMENTS PRODUCTS ARE NOT DESIGNED WITH COMPONENTS AND TESTING FOR A LEVEL OF RELIABILITY SUITABLE FOR USE IN OR IN CONNECTION WITH SURGICAL IMPLANTS OR AS CRITICAL COMPONENTS IN ANY LIFE SUPPORT SYSTEMS WHOSE FAILURE TO PERFORM CAN REASONABLY BE EXPECTED TO CAUSE SIGNIFICANT INJURY TO A HUMAN.

(2) IN ANY APPLICATION, INCLUDING THE ABOVE, RELIABILITY OF OPERATION OF THE SOFTWARE PRODUCTS CAN BE IMPAIRED BY ADVERSE FACTORS, INCLUDING BUT NOT LIMITED TO FLUCTUATIONS IN ELECTRICAL POWER SUPPLY, COMPUTER HARDWARE MALFUNCTIONS, COMPUTER OPERATING SYSTEM SOFTWARE FITNESS, FITNESS OF COMPILERS AND DEVELOPMENT SOFTWARE USED TO DEVELOP AN APPLICATION, INSTALLATION ERRORS, SOFTWARE AND HARDWARE COMPATIBILITY PROBLEMS, MALFUNCTIONS OR FAILURES OF ELECTRONIC MONITORING OR CONTROL DEVICES, TRANSIENT FAILURES OF ELECTRONIC SYSTEMS (HARDWARE AND/OR SOFTWARE), UNANTICIPATED USES OR MISUSES, OR ERRORS ON THE PART OF THE USER OR APPLICATIONS DESIGNER (ADVERSE FACTORS SUCH AS THESE ARE HEREAFTER COLLECTIVELY TERMED "SYSTEM FAILURES"). ANY APPLICATION WHERE A SYSTEM FAILURE WOULD CREATE A RISK OF HARM TO PROPERTY OR PERSONS (INCLUDING THE RISK OF BODILY INJURY AND DEATH) SHOULD NOT BE RELIANT SOLELY UPON ONE FORM OF ELECTRONIC SYSTEM DUE TO THE RISK OF SYSTEM FAILURE. TO AVOID DAMAGE, INJURY, OR DEATH, THE USER OR APPLICATION DESIGNER MUST TAKE REASONABLY PRUDENT STEPS TO PROTECT AGAINST SYSTEM FAILURES, INCLUDING BUT NOT LIMITED TO BACK-UP OR SHUT DOWN MECHANISMS. BECAUSE EACH END-USER SYSTEM IS CUSTOMIZED AND DIFFERS FROM NATIONAL INSTRUMENTS' TESTING PLATFORMS AND BECAUSE A USER OR APPLICATION DESIGNER MAY USE NATIONAL INSTRUMENTS PRODUCTS IN COMBINATION WITH OTHER PRODUCTS IN A MANNER NOT EVALUATED OR CONTEMPLATED BY NATIONAL INSTRUMENTS, THE USER OR APPLICATION DESIGNER IS ULTIMATELY RESPONSIBLE FOR VERIFYING AND VALIDATING THE SUITABILITY OF NATIONAL INSTRUMENTS PRODUCTS WHENEVER NATIONAL INSTRUMENTS PRODUCTS ARE INCORPORATED IN A SYSTEM OR APPLICATION, INCLUDING, WITHOUT LIMITATION, THE APPROPRIATE DESIGN, PROCESS AND SAFETY LEVEL OF SUCH SYSTEM OR APPLICATION.


Technical Support and Professional Services

Visit the following sections of the National Instruments Web site at ni.com for technical support and professional services:

  • Support—Online technical support resources at ni.com/support include the following:
    • Self-Help Resources—For answers and solutions, visit the award-winning National Instruments Web site for software drivers and updates, a searchable KnowledgeBase, product manuals, step-by-step troubleshooting wizards, thousands of example programs, tutorials, application notes, instrument drivers, and so on.
    • Free Technical Support—All registered users receive free Basic Service, which includes access to hundreds of Applications Engineers worldwide in the NI Developer Exchange at ni.com/exchange. National Instruments Applications Engineers make sure every question receives an answer.

      For information about other technical support options in your area, visit ni.com/services or contact your local office at ni.com/contact.

  • Training and Certification—Visit ni.com/training for self-paced training, eLearning virtual classrooms, interactive CDs, and Certification program information. You also can register for instructor-led, hands-on courses at locations around the world.
  • System Integration—If you have time constraints, limited in-house technical resources, or other project challenges, National Instruments Alliance Partner members can help. To learn more, call your local NI office or visit ni.com/alliance.

If you searched ni.com and could not find the answers you need, contact your local office or NI corporate headquarters. You also can visit the Worldwide Offices section of ni.com/niglobal to access the branch office Web sites, which provide up-to-date contact information, support phone numbers, email addresses, and current events.


Branch Offices

Office | Telephone Number
Australia | 1800 300 800
Austria | 43 662 457990-0
Belgium | 32 (0) 2 757 0020
Brazil | 55 11 3262 3599
Canada | 800 433 3488
China | 86 21 5050 9800
Czech Republic | 420 224 235 774
Denmark | 45 45 76 26 00
Finland | 358 (0) 9 725 72511
France | 33 (0) 1 57 66 24 24
Germany | 49 89 7413130
India | 91 80 41190000
Israel | 972 0 3 6393737
Italy | 39 02 41309277
Japan | 0120-527196 / 81 3 5472 2970
Korea | 82 02 3451 3400
Lebanon | 961 (0) 1 33 28 28
Malaysia | 1800 887710
Mexico | 01 800 010 0793
Netherlands | 31 (0) 348 433 466
New Zealand | 0800 553 322
Norway | 47 (0) 66 90 76 60
Poland | 48 22 3390150
Portugal | 351 210 311 210
Russia | 7 495 783 6851
Singapore | 1800 226 5886
Slovenia | 386 3 425 42 00
South Africa | 27 0 11 805 8197
Spain | 34 91 640 0085
Sweden | 46 (0) 8 587 895 00
Switzerland | 41 56 2005151
Taiwan | 886 02 2377 2222
Thailand | 662 278 6777
Turkey | 90 212 279 3031
United Kingdom | 44 (0) 1635 523545
United States (Corporate) | 512 683 0100