DS_GetDataValue

Download PDF

Updated2023-02-21
5 minute(s) read

HRESULT DS_GetDataValue (DSHandle DSHandle, unsigned int type, void *value, unsigned int size, unsigned int *dimension1, unsigned int *dimension2);

Purpose

Obtains the data value of the DataSocket object you specify. The DataSocket object must be configured for reading.

The data value of a DataSocket object might not be the same as the current data value of the DataSocket data source to which the DataSocket object is connected. The DataSocket object obtains the DataSocket data source's data value at the time that the connection is made and again at a later time, depending on how the DataSocket object is configured. If the DataSocket object is configured for ReadAutoUpdate mode, the DataSocket object obtains the DataSocket data source's data value each time it changes. If the DataSocket object is configured for Read mode, the DataSocket object obtains the DataSocket data source's data value each time you call DS_Update.

Note If the execution model of your DataSocket object is the 'Event Model', it is highly recommended that you call this function in your DataSocket callback function in response to DS_EVENT_DATAUPDATED events. Otherwise, you will only get the latest data and may lose intermediate data.

Note If the execution model of your DataSocket object is the 'Polling Model', this function removes the oldest item from the polling queue, and gets its value. If the polling queue is empty, this function gets the value of the last item received, and returns a S_FALSE status. The function DS_GetDataUpdated indicates if there is new data in the polling queue.

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.

type

unsigned int

The type of the DataSocket object's data value.

The DataSocket object's 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 OR 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.

size unsigned int The size, in bytes, of the buffer you pass in the value parameter if the constant you pass in the type parameter indicates an array or a string.

If the constant you pass in the type parameter indicates a scalar, this parameter is meaningless.

Output

Name Type Description

value

void *

The address of a variable to hold 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.

Some servers support non-Automation data types, such as unsigned short and unsigned long. In this case, if you pass CAVT_VARIANT for the type parameter and the address of an empty VARIANT variable in the value parameter, this function returns the data in the variant.

If the type you pass is a string or an array, you must allocate and pass a buffer that is large enough to hold all of the data. This function copies the data into the buffer that you pass.

If the type you pass is an array of strings, you must allocate an array of pointers (of type char *) that is large enough to hold all of the strings in the array. This function allocates memory for each string and stores pointers to that memory in the array that you pass. You must call DS_FreeMemory to free each of these strings.

Example

Example of scalar of type double
double value;
DS_GetDataValue (dsHandle, CAVT_DOUBLE, &value, 0, 0, 0);

Example of string
unsigned int size;
char *value;
DS_GetDataType (dsHandle, NULL, &size, NULL);
value = malloc (size+1);
DS_GetDataValue (dsHandle, CAVT_CSTRING, value, size+1, 0, 0);
// Free the memoryfree (value);

Example of 1D array of doubles
unsigned int size;
double *value;
DS_GetDataType (dsHandle, NULL, &size, NULL);value = malloc (size * sizeof (double));
DS_GetDataValue (dsHandle, CAVT_DOUBLE | CAVT_ARRAY, value, size * sizeof(double), 0, 0);
// Free the memoryfree (value);

Example of a 1D array of strings
unsigned int size, n;
char **value;
DS_GetDataType (dsHandle, NULL, &size, NULL);
value = malloc (size * sizeof (char *));
DS_GetDataValue (dsHandle, CAVT_CSTRING | CAVT_ARRAY, value, size * sizeof(char *), 0, 0);
// Free the strings
for (n = 0; n < size; n++)
DS_FreeMemory (value[n]);
// Free the array
free (value);

Example of 2D array of doubles
unsigned int size1, size2;
double *value;
DS_GetDataType (dsHandle, NULL, &size1, &size2);
value = malloc (size1 * size2 * sizeof (double));
DS_GetDataValue (dsHandle, CAVT_DOUBLE | CAVT_ARRAY, value, size1 * size2 * sizeof (double), 0, 0);
// Free the memory
free (value);

dimension1 unsigned int Returns the length of the string if the constant you pass in the type parameter is CAVT_CSTRING. The length does not include the terminating NUL byte.

Returns the number of elements in the array if the constant you pass in the type parameter indicates a 1D array of any type.

Returns the size of the first dimension of the array if the constant you pass in the type parameter indicates a 2D array of any type.

If the constant you pass in the type parameter indicates neither a string nor an array, the value returned is not defined.

Pass NULL if you do not want this value.

dimension2 unsigned int The size of the second dimension of the array if the constant you pass in the type parameter indicates a 2D array of any type.

If the constant you pass in the type parameter does not indicate a 2D array, the value returned is not defined.

Pass NULL if you do not want this value.

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