Syntax

When you bind a ProBindingSource to a ProDataSet, you make the hierarchy of tables, starting at one particular parent buffer, available to the bound UI controls. You can bind the ProBindingSource to a ProDataSet using the following syntax:

PUBLIC BindingSource ( INPUT dataset-hdl AS HANDLE
                [ , { INPUT parent-buffer-name AS CHARACTER
                    | INPUT parent-buffer-hdl AS HANDLE }]
                  [ , INPUT include-fields AS CHARACTER, 
                         INPUT except-fields AS CHARACTER ] )

Where dataset-hdl is the ProDataSet handle, parent-buffer-name is the name of a parent buffer object, parent buffer-hdl is the handle of a parent buffer object, include-fields is an optional, comma-separated list of fields from the data object to make available to the UI, and except-fields is a comma-separated list of fields from the data object to exclude from the UI. Note that you must supply the included and excluded field lists together whenever you use them.

Note: If you have to prepare one of the navigation queries, you should use the PRESELECT option, as described in Bind ProBindingSource to queries.

You cannot simultaneously bind the same ProDataSet query to multiple ProBindingSources. A ProDataSet query can only be bound to a single ProBindingSource at any time. If you try to bind a ProDataSet query that is already bound to another ProBindingSource, the ProBindingSource throws an error.

Note: Although you specify the parent buffer or its handle, you are actually binding to the ProDataset's query for that buffer.

The buffer that you choose as the parent buffer controls what tables in the ProDataSet are available through the ProBindingSource. Typically, you choose a top-level buffer for the parent buffer. If you do not specify a parent buffer, the ProBindingSource defaults to using the first top-level buffer listed in the ProDataSet's definition. A ProBindingSource can only make available a single top-level buffer from a ProDataSet.

However, you can choose a buffer that is not a top-level buffer. In that case, the hierarchy of available tables in the ProBindingSource starts with that table and extends to its children. In effect, the ProBindingSource considers its parent buffer as the top-level buffer in the part of the ProDataSet that it makes available. For example, consider a ProDataSet that contains the Customer, Order, and Orderline tables. If you create a ProBindingSource and specify the Order table as the parent buffer, only the Order and Orderline tables are accessible through that ProBindingSource.

Note: When the ProDataSet as a whole is the data object for a ProBindingSource, the ProBindingSource does not show the BEFORE-TABLE for each primary table as an available table. However, you can explicitly specify a BEFORE-TABLE as the parent buffer of another ProBindingSource to make that data available to a bound UI control.

When the specified parent buffer is a top-level buffer in the ProDataSet, the ProBindingSource uses the ProDataSet's top-level navigation query, TOP-NAV-QUERY, and the relationship queries for each of its children to navigate the records in the ProDataSet. When the specified parent buffer is not a top-level buffer, the ProBindingSource uses the parent buffer's relationship query to populate the primary set of records and the relationship queries for any child buffers to populate the subsequent levels.

If you do not use the optional field list parameters, the ProBindingSource makes all fields in the parent buffer and any child buffers available to bound UI controls. When you use the field lists with a ProDataSet-bound ProBindingSource, you must qualify all fields with their buffer. When you specify a group of included fields, you must include at least one field from every buffer that is available through the ProBindingSource. If you do not, an error is raised.

Certain .NET UI controls can display data from both parent and child tables within the same control. For example, the Infragistics.Win.UltraWinGrid.UltraGrid can display the associated rows from a child table under each row from the parent table. For such controls, a single ProBindingSource that makes multiple tables from a ProDataSet available works well.

ProDataSet tables with uncommitted changes might have the ERROR and ERROR-STRING attributes set for one or more rows. The ProBindingSource's Refresh( ) method picks up any modifications to these attributes. The ProBindingSource can make the errors available to a bound UI control. If the UI control is sensitive to these settings on its data source, the UI control adjusts its display to show the errors. For example, a Microsoft System.Windows.Forms.DataGridView displays an error icon on the row header and displays the error string when a mouse hovers over the icon. In the UltraGrid, you need to set the DisplayLayout:Override:SupportDataErrorInfo attribute to see the error icons.