# DSBindCtrl

int DSBindCtrl (int panelHandle, int controlID, char *URL, int accessMode, DSHandle *DSHandle, HRESULT *dataSocketError);

## Purpose

Binds a control to the DataSocket connection specified in the URL parameter. Call DSUnbind to close the connection.

Linux This function is not supported.

Each control can have only one DataSocket connection. Use a URL to specify the location and format of the DataSocket data source. For each DataSocket object that you connect to a DataSocket data source, specify whether the connection is a READ connection or a WRITE connection. If you specify a READ connection, you can use the DataSocket object to get data from the data source. If you specify a WRITE connection, you can use the DataSocket object to send data to the data source.

For some protocols such as dstp, the DataSocket server must be launched on the machine referenced in the URL.

The following control types can be bound using DSBindCtrl:

- Numerics, Strings, Text Boxes
- Tables—If you have not specified a cell range in the UI Editor, the bound range defaults to the full table size. Use DSBindTableCellRange instead of DSBindCtrl to specify a cell range programmatically.
- Graphs — If a graph is bound in READ mode, it automatically creates a plot when it first receives data from DataSocket. That plot will be reused for all data received from DataSocket. Call DSGetBoundPlotID to get the plot ID that is bound. Call DSBindPlot instead of DSBindCtrl to bind to an existing plot instead of having a new one created. If a graph is bound in write mode, all plots to the graph will be written to DataSocket.

## Parameters

Input
Name | Type | Description
panelHandle | integer | Specifier for a particular panel that is currently in memory. You obtain this handle from LoadPanel, NewPanel, or DuplicatePanel.
controlID | integer | The defined constant, located in the .uir header file, that you assigned to the control in the User Interface Editor, or the ID returned by NewCtrl or DuplicateCtrl.
URL | char* | The URL of the data source for the DataSocket object's connection. The URL you pass can resolve to different types of data sources. A URL consists of a scheme and a data source path. The scheme specifies the type of data. The DataSocket library supports the following URL schemes: http—hypertext transfer protocol ftp—file transfer protocol file—local files dstp—DataSocket transfer protocol opc—OPC (OLE for Process control) servers logos—an internal National Instruments technology for transmitting data between the network and your local computer fieldpoint—a protocol that uses the National Instrument logos protocol to send and receive live data to and from a National Instruments Fieldpoint module The data source path specifies the exact location of the data. The format of the data source path depends on the URL scheme. URL examples http://www.natinst.com/cworks/datasocket/chirp.dsd ftp://ftp.natinst.com/support/compworks/datasocket/chirp.wav dstp://localhost/wave dstp://weather.natinst.com/weather/current file://datafiles/newwave.txt opc://machine/National Instruments.OPCDemo/SINE:0.0..8.0:2.0 logos://computer_name/process/data_item_name fieldpoint://computer_name/process/data_item_name
accessMode | integer | The access mode constant for the DataSocket object's connection. The access mode determines whether the DataSocket object can read from the DataSocket data source or write to the DataSocket data source. VAL_DS_READ—Configures the DataSocket connection for automatic reading. The DataSocket object gets data from the DataSocket data source at the time that the connection is established, when the data value changes, and when any of the data attributes change. VAL_DS_WRITE—Configures the DataSocket connection for automatic writing. The DataSocket object transfers data to the DataSocket data source at the time that the connection is established and when the data value changes.
Output
Name | Type | Description
DSHandle | DSHandle (passed by reference) | A handle that you can use to identify the DataSocket object in subsequent function calls. The handle is never 0. The status of the connection between a bound control and its DataSocket data source can be obtained by passing the DSHandle to DS_GetStatus. The DSHandle received from DSBindCtrl should never be passed to DS_DiscardObjHandle. Call DSUnbind to unbind the control.
dataSocketError | HRESULT (passed by reference) | The HRESULT if this function causes a DataSocket error. A value of NULL can be passed in if the HRESULT is not needed. In the event of a DataSocket error, this function returns a value of UIEDataSocketError.

## Return Value

Name | Type | Description
status | integer | Return value indicating whether the function was successful. A negative number indicates that an error occurred.
Code | Error Message String
xx | Success