DBCancel

Description

Cancels the retrieval in process in a DataWindow.

Applies to

DataWindow type

Method applies to

PowerBuilder

DataWindow control, DataWindowChild object, DataStore object

Web ActiveX

DataWindow control, DataWindowChild object

Syntax

PowerBuilder

integer dwcontrol.DBCancel ( ) 

Web ActiveX

number dwcontrol.DBCancel ( )

Argument

Description

dwcontrol

A reference to the DataWindow control, DataStore, or child DataWindows

Returns

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:

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

Example 1

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

See also