Cancels the retrieval in process in a DataWindow.
DataWindow type |
Method applies to |
|---|---|
PowerBuilder |
DataWindow control, DataWindowChild object, DataStore object |
Web ActiveX |
DataWindow control, DataWindowChild object |
integer dwcontrol.DBCancel ( )
number dwcontrol.DBCancel ( )
Argument |
Description |
|---|---|
dwcontrol |
A reference to the DataWindow control, DataStore, or child DataWindows |
Returns 1 if it succeeds and –1 if an error occurs.
If dwcontrol is null, in PowerBuilder and JavaScript the method returns null.
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:
ib_cancel = true
dw_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:
IF ib_cancel = true THEN
RETURN 1
END 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.
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:
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.)
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:
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:
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:
IF ib_cancel = true THEN
RETURN 1
END IF
