DBCancel
method (DataWindows)
Description
Cancels the retrieval in process in a DataWindow.
Applies to
|
DataWindow type |
Method applies to |
|---|---|
|
PowerBuilder |
DataWindow control, DataWindowChild object, DataStore |
Syntax
PowerBuilder
|
1 |
integer dwcontrol.DBCancel ( ) |
|
Argument |
Description |
|---|---|
|
dwcontrol |
A reference to the DataWindow control, DataStore, or |
Return value
Returns 1 if it succeeds and -1 if an error occurs.
If dwcontrol is null, in PowerBuilder and JavaScript the method
returns null.
Usage
To cancel a database retrieval, you need two pieces of code:
-
Code that calls DBCancel. To let the user cancel the retrieval,
you could call DBCancel (or call a user function or member method that
calls it) in code for a button or an item on a menu. This code would
generally set an instance variable or data member to indicate that the
user requested cancellation.In PowerBuilder, this code might be:
12ib_cancel = truedw_1.DBCancel() -
Code for the RetrieveRow event that sets an action/return code
of 1 to stop the retrieval.In PowerBuilder, this code might be:
123IF ib_cancel = true THENRETURN 1END IF
Coding something in the RetrieveRow event’s script (even just a
comment) enables the operating system to process events while the
DataWindow is being populated with rows from the database. If the
RetrieveRow event’s script is empty, menus and command buttons can’t even
be clicked until the retrieval is completely finished. This can be
frustrating if the user inadvertently starts a retrieval that is going to
take a long time.
If the Async DBParm parameter is set to 1 (for asynchronous
operation), a user or a script can cancel a query either before the first
row is returned or during the data retrieval process. If Async is set to 0
(for synchronous operation), the user cannot select the menu or
CommandButton until the first row is retrieved. The asynchronous setting
is useful when a query might take a long time to retrieve its first
row.
For a list of the DBMSs that support the Async DBParm parameter, see
the section called “Async” in Connection Reference.
Examples
In this example, the menu bar for an MDI application has menu items
for starting and canceling a retrieval. When the user cancels the
retrieval, a user function calls DBCancel and sets a boolean instance
variable to Get/SetSeriesStyle and Get/SetDataStyle. The RetrieveStart and
RetrieveRow events check this variable and return the appropriate
value.
In this hypothetical application, the user starts a retrieval by
selecting Retrieve from a menu. The script for the Retrieve menu item
calls a user function for the window:
|
1 |
w_async1.wf_retrieve() |
The wf_retrieve function sets the Async DBParm for asynchronous
processing and starts the retrieval. Because Async is set to 1, the user
can select the Cancel menu item at any time, even before the first row is
retrieved. (In your own application, you would include error handling to
make sure Retrieve returned successfully.)
|
1 2 3 4 |
long rc ib_cancel = false SQLCA.DBParm = 'Async = 1' rc = dw_1.Retrieve() |
The user can stop the retrieval by selecting Cancel from the menu.
The script for the Cancel menu item reads:
|
1 |
w_async1.wf_cancel() |
The user function wf_cancel for the window w_async1 calls DBCancel
and sets a flag indicating that the retrieval is canceled. Other events
for the DataWindow will check this flag and abort the retrieval too. The
variable ib_cancel is an instance variable for the window:
|
1 2 |
ib_cancel = true dw_1.DBCancel() |
Scripts for the RetrieveStart and RetrieveRow events both check the
ib_cancel instance variable and, if it is true, stop the retrieval by
returning a value of 1. In order to cancel the retrieval, some code or
comment in the script for the RetrieveRow event is required:
|
1 2 3 |
IF ib_cancel = true THEN RETURN 1 END IF |
See also