ComponentOne True DataControl 8.0
UserReadData Event

 

UserReadData Event

Occurs when the control requires data in DataMode = 2 - UserEvents.

Syntax

TData_UserReadData (ByVal RowBuf As TrueData60Ctl.RowBuffer, ByVal StartLocation As Variant, ByVal Offset As Long, ApproximatePosition As Long)

Remarks

Arguments: RowBuf is a RowBuffer object used to transfer row data to the control.

StartLocation is a bookmark that, together with Offset, specifies the starting row for data transfer. A StartLocation of Null indicates a request for data from BOF or EOF. For example, if StartLocation is Null and Offset is 2 (or -2), then you should retrieve data starting from the second (or second to last) row.

Offset specifies the relative position (from StartLocation) of the first row of data to be transferred. A positive number indicates a forward relative position; a negative number indicates a backward relative position.

ApproximatePosition is a variable that optionally receives the ordinal position of the first row of data to be transferred. This information is used by the TData control to service client requests for approximate row position information, usually used by bound controls for their scrollbar functionality. If you choose to set the ApproximatePosition, you must also maintain the TData control’s ApproxCount property. If ApproximatePosition = -1 is passed to the event procedure, it means that the programmer can skip setting the ApproximatePosition, which is optional anyway. Even if the programmer supplies a value, TData control will ignore it. Also, the programmer can let TData know that ApproximatePosition is unknown, setting it to -1 in the event procedure.

In user events mode (DataMode set to 2 - User Events), the UserReadData event is fired whenever the TData control requests data from your application. You do not need to write a handler for this event unless you want to create your own data source. See User Events Mode for details.

Before returning from the UserReadData event, you must fill the Bookmark array of RowBuf with unique row identifiers (bookmarks), and the Value array with the actual data. For example, if Offset is 1 (or -1), then you must fill in RowBuf, starting from the row that follows (or precedes) StartLocation.

The RowBuf argument acts like a two-dimensional array of variants corresponding to the fields in the rows being fetched. By populating its Value property with the appropriate data, your event procedure transfers rows from your data source to the TData control.

Use the row buffer's RowCount property to determine how many rows of data TData is requesting. Use its ColumnCount property to determine the number of columns to be populated, if any. If ColumnCount is zero, TData is requesting only bookmarks; if ColumnCount is nonzero, TData is requesting RowCount rows of data and their corresponding bookmarks.

The ColumnIndex property specifies the Fields index (in the collection returned by the Fields property) that corresponds to a row buffer column index; you must fill in the Value property array with field data according to the field index specified by the ColumnIndex property array.

The RowBuf argument is also used to store a set of variant bookmarks that uniquely identify rows in your data source. The format of these bookmarks is determined solely by your application. For example, they may be primary key fields, row numbers, or array indexes, depending upon the nature of your data source.

Your event procedure supplies bookmarks to the TData control by populating the row buffer's Bookmark property for each row returned. Keep in mind that the bookmarks you provide in the UserReadData event may be subsequently passed to the UserWriteData and UserDeleteRow events.

It is not necessary to fill the row buffer completely, and it is in fact acceptable to return no rows at all. The row buffer's RowCount property can be set to indicate that fewer rows were returned than requested. TData interprets this to mean that there are no more rows to retrieve in the indicated direction. Thus, it is only necessary to fill the row buffer completely if there are enough valid rows to be retrieved.

See Also

TData Control

 

 


Copyright (c) GrapeCity, inc. All rights reserved.

Product Support Forum  |  Documentation Feedback