Rx Database Progress

RX Library

Control Name Unit Class
RX Database Progress DBPrgrss TDBProgress

Description: TDBProgress is a wrapper for a Borland Database Engine (BDE) generic progress callback and (in 32-bit version only) trace callback functions. Generic progress callback is issued by BDE to inform applications about the progress made during large batch operations, such as DbiBatchMove. The Generic Progress Report callback allows the client to obtain progress reports during an operation, and to cancel the operation, if desired. This callback is generated when working with Paradox driver and with some other BDE drivers. The query execution generates some text messages and BatchMove execution generates text and percent notifications. You can specify the MessageControl property and Gauge property to display BDE messages and percentage.

For some operations, a percentage completed is passed back to the callback function, for most others a string containing progress information is passed back; for simple database operations no progress information is returned at all. It has been our experience that percentages are mainly passed back in operations where the BDE must physically sort a local database file, such as in indexing DBase files. It is of course possible to interpret the messages passed back and calculate your own percentage completed.

32-bit trace callback is a system-level callback that can be used to retrieve trace information.

Property TraceFlags specifies the database operations to track with the OnTrace event at run time while Trace property is True.


Using class TDBProgress

The TDBProgress component is a non-visual component that holds the latest progress information on the current database operation as returned by the database engine. By updating visual components, such as a gauge or a label, whenever the OnProgress, OnMessageChange and OnPercentChange events is generated, the user is aware of the status of the database action being executed. Such feedback is especially useful when performing database operations that consume a considerable amount of time, such as:

- Index Creation
- Query Execution
- BatchMoves
- etc.

The TDBProgress component enables you to see the actual statement calls made through SQL Links to a remote server or through the ODBC socket to an ODBC data source, like SQL Monitor. You can elect to monitor different types of activity. Choose TraceFlags property value to select different categories of activities to monitor.

Use the TDBProgress component to provide progress feedback on database operations and see the actual statement calls made through SQL Links to a remote server.


Property Active
Declaration: Active: Boolean;

Set the Active property to True to enables the progress callback-events. Depending on the value of the Active the DBProgress will generate the OnProgress, OnMessageChange and OnPercentChange events each time the database passes control back to the TDBProgress component during the current database operation. Setting this property to False disables the generic progress callbacks.


Property Gauge
Declaration: Gauge: TControl;

Gauge is a progress-control associated with the DBProgress to to display BDE percentage. In 16-bit Delphi version you can use TGauge control as progress-indicator. In 32-bit versions you can also use TProgressBar control.


Property MessageControl
Declaration: MessageControl: TControl;

MessageControl is a control associated with the DBProgress to to display BDE messages. You can use any control which displays it's Caption property, i.e. TLabel, TPanel etc.


Property Trace
Declaration: Trace: Boolean;

Set the Trace property to True to enables the trace callback-events. Setting this property to True enables the trace callback and depending on the value of the TraceFlags the DBProgress will generate the OnTrace events. Setting this property to False disables the trace callbacks.


Property WaitCursor
Declaration: WaitCursor: TCursor;

Indicates the mouse cursor changes to during long BDE operations.


Event OnMessageChange
Declaration: OnMessageChange: TOnMessageChange;

The OnPercentChange event occurs every time new text message is returned from the database engine (BDE). This event is only generated when Active is set to True.


Event OnPercentChange
Declaration: OnPercentChange: TOnPercentChange;

The OnPercentChange event occurs every time percent notifications is returned from the database engine (BDE). This event is only generated when Active is set to True.


Event OnProgress
Declaration: OnProgress: TOnProgressEvent;

The OnProgress event occurs every time progress information is returned from the database engine (BDE).

This event is only generated when Active is set to True. To abort the current database operation, set the Abort variable to False. The effect the abort will have depends of the nature of the database operation that is being aborted.


Event OnTrace
Declaration: OnTrace: TOnTraceEvent;

The OnTrace event occurs every time trace information (text string passed as Msg parameter) is returned from the database engine (BDE). This event is only generated when Trace property is set to True and TraceFlags property is not equal to empty set [].


Method ProgressMsgValue
Declaration: function ProgressMsgValue(const Msg: string): Longint;

Returns numeric value contained in BDE callback string specified by Msg parameter. The message string format always is: <Text_string><:><Value>. In the message string, the value and colon fields are optional. When message Msg contains value field, then ProgressMsgValue returns value as result, otherwise this method returns -1. You can use ProgressMsgValue method, for example, in OnMessageChange event handler.


Type TOnMessageChange
Declaration: TOnMessageChange = procedure(Sender: TObject; const Msg: string) of object;

The TOnMessageChange type points to the method that handles the OnMessageChange event of the TDBProgress component. The Msg parameter contains the last progress message passed back from the database engine.


Type TOnPercentChange
Declaration: TOnPercentChange = procedure(Sender: TObject; PercentDone: Integer) of object;

The TOnPercentChange type points to the method that handles the OnPercentChange event of the TDBProgress component. The PercentDone parameter contains the last progress percentage passed back from the database engine.


Type TOnProgressEvent
Declaration: TOnProgressEvent = procedure(Sender: TObject; var Abort: Boolean) of object;

TOnProgressEvent is the type of the OnProgress event of the TDBProgress component.


Type TOnTraceEvent
Declaration: TOnTraceEvent = procedure(Sender: TObject; Flag: TTraceFlag; const Msg: string) of object;

The TOnTraceEvent type points to the method that handles the OnTrace event of the TDBProgress component.


Index Page | About | Download
Creation Date: 4 Feb 1998 | Last Update: 16 Mar 2000