DS_SetAttrValue

Download PDF

Updated2023-02-21
3 minute(s) read

HRESULT DS_SetAttrValue (DSHandle DSHandle, const char *attributeName, unsigned int type, const void *value, unsigned int dimension1, unsigned int dimension2);

Purpose

Sets the data value of the attribute you specify.

The DataSocket object must be configured for writing. If you call this function for a DataSocket object that was opened for reading, it returns DISP_E_EXCEPTION (0x80020009).

This function is a convenience function that performs, in a single operation, the same task as calling DS_GetAttrHandle to obtain a handle to an attribute and then calling DS_SetDataValue to set the data value of the attribute.

When you call this function, the DataSocket object might not immediately send the new value to the DataSocket data source to which the DataSocket object is connected. If the DataSocket object is configured for WriteAutoUpdate mode, the DataSocket object sends the new value to the DataSocket data source before this function returns. If the DataSocket object is configured for Write mode, the DataSocket object sends its data value to the DataSocket data source when you call DS_Update.

Parameters

Input

Name Type Description

DSHandle DSHandle Pass the handle you obtained from DS_Open, DS_GetAttrHandle, or DS_CreateAttrHandle to identify the DataSocket object.

attributeName const char * A string to specify the name of the attribute. If the attribute does not already exist, this function creates it.

type

unsigned int

A constant to indicate the type of data you are setting.

The attribute data value can be one of the valid types or an array of one of the valid types other than CAVT_VARIANT. The following table lists the valid type constants and their corresponding C/Windows types:

Constant	C/Windows type
CAVT_DOUBLE	double
CAVT_FLOAT	float
CAVT_LONG	long
CAVT_SHORT	short
CAVT_UCHAR	unsigned char
CAVT_CSTRING	char *
CAVT_BOOL	short
CAVT_VARIANT	VARIANT

To specify an array type, combine the CAVT_ARRAY flag with one of the preceding data types using the bitwise operator (|). For example, to indicate an array of long values, pass CAVT_LONG | CAVT_ARRAY.

Press <Ctrl-T> to change this parameter's ring control to a manual input box.

value

const void *

The address of a variable that contains the data value if the constant you pass in the type parameter does not indicate an array or a string, that is, the constant is a scalar.

If the constant you pass in the type parameter indicates a string or an array, pass a buffer containing the data.

If the constant you pass in the type parameter is CAVT_CSTRING | CAVT_ARRAY, pass an array of elements of type char *.

Example

Example of scalar of type double
double value = 5.5;
DS_SetAttrValue (dsHandle, "Attribute1", CAVT_DOUBLE, &value, 0, 0);

Example of string
char *value = "String Value";
DS_SetAttrValue (dsHandle, "Attribute1", CAVT_CSTRING, value, 0, 0);

Example of 1D array of doubles
double value[] = {4.0, 5.0, 5.5};
DS_SetAttrValue (dsHandle, "Attribute1", CAVT_DOUBLE | CAVT_ARRAY, value, sizeof (value) / sizeof (value[0]), 0);

Example of 1D array of strings
char *value[] = {"String Value 1", "String Value 2"};
DS_SetAttrValue (dsHandle, "Attribute1", CAVT_CSTRING | CAVT_ARRAY, value, sizeof (value) / sizeof (value[0]), 0);

dimension1 unsigned int The number of elements in the array if the value you pass in the value parameter is a 1D array.

The number of elements in the first dimension of the array if the value you pass in the value parameter is a 2D array.

If the value you pass in the value parameter is not an array, pass 0 for this parameter.

dimension2 unsigned int The number of elements in the second dimension of the array if the value you pass in the value parameter is a 2D array.

If the value you pass in the value parameter is not an array or is a 1D array, you must pass 0 for this parameter.

Return Value

Name	Type	Description
status	HRESULT	The value that indicates whether an error occurred. A negative error code indicates function failure. Error codes are defined in CVIversion\toolslib\datasock\dataskt.h and <Program Files>\National Instruments\Shared\MSDTRedistributables\SDKHeaderFiles\8.1\winerror.h. Other error codes in winerror.h are generated by ActiveX Servers and are passed on to you by the DataSocket Library.

Additional Information

Library: DataSocket Library

Include file: datasock\dataskt.h

LabWindows/CVI compatibility: LabWindows/CVI 5.5 and later

LabWindows/CVI