DBCancel method (DataWindows)
Description
Cancels the retrieval in process in a DataWindow.
Controls
|
DataWindow type |
Method applies to |
|---|---|
|
PowerBuilder |
DataWindow control, DataWindowChild object, DataStore |
|
Web ActiveX |
DataWindow control, DataWindowChild object |
Syntax
[PowerBuilder]
|
1 |
integer <span>dwcontrol</span><span>.DBCancel </span>( ) |
[Web ActiveX]
|
1 |
number <span>dwcontrol</span><span>.DBCancel </span>( ) |
|
Argument |
Description |
|---|---|
|
dwcontrol |
A reference to the DataWindow control, |
Return Values
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:
1ib_cancel = true1dw_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:
1IF ib_cancel = true THEN1RETURN 11END 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 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 |
long rc |
|
1 |
ib_cancel = false |
|
1 |
SQLCA.DBParm = 'Async = 1' |
|
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 |
ib_cancel = true |
|
1 |
dw_1.<span>DBCancel</span>() |
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 |
IF ib_cancel = true THEN |
|
1 |
RETURN 1 |
|
1 |
END IF |