Description
Allows you to perform asynchronous operations on your database in PowerBuilder. If you have coded a RetrieveRow event for a DataWindow object or report, you can cancel the current database retrieval operation or start another (non-database) operation that does not use the same database connection before the current operation completes. You can also switch to another Windows process while the retrieval takes place.
By default, PowerBuilder operates synchronously.
Applies to
ASE, SYC SAP Adaptive Server Enterprise
I10 Informix
IN9 Informix
ODBC (if driver and back-end DBMS support this feature)
O90 Oracle9i
O10 Oracle 10g
ORA Oracle (for 11g and later)
Syntax
Async=value
|
Parameter |
Description |
|---|---|
|
value |
A value specifying synchronous or asynchronous operation. Values are:
|
Default value
Async=0
Usage
Enabling asynchronous operation in PowerBuilder is useful when you are executing a complex SQL statement that takes several minutes to return results. If the Async parameter is set to 1, you can do either of the following while the SQL statement is executing:
-
Work in another window
-
Cancel the statement before it retrieves the first row of data
When to set Async
If you are communicating with the database in code, you can reset the Async value at any time before or after the Transaction object has connected to the database.
How data is retrieved
When you retrieve data in a DataWindow object or report, the following steps occur in order:
-
The database server compiles and executes the SQL statement.
-
PowerBuilder retrieves (fetches) the first row of data.
-
PowerBuilder retrieves each subsequent row of data.
What happens before the first row is retrieved
While the server is compiling and executing the SQL statement and before PowerBuilder retrieves the first row of data, you must have done both of the following to enable asynchronous operation (allowing you to cancel the current operation before it retrieves the first row of data):
-
Coded a RetrieveRow event for the DataWindow object or report (the code can contain only a comment)
-
Set the Async parameter to 1
What happens after the first row is retrieved
After the first row of data is retrieved and between subsequent row fetches, you must have done only the following to enable asynchronous operation:
-
Coded a RetrieveRow event for the DataWindow object or report
After the first row is retrieved, PowerBuilder operates asynchronously without your having to set the Async parameter to 1, so you can cancel the current operation anytime after it retrieves the first row of data. Therefore, the Async parameter has no effect in PowerBuilder after the first row of data is retrieved.
Examples
Example 1
To enable asynchronous operation:
-
Database profile
Select the Asynchronous check box on the Transaction page in the Database Profile Setup dialog box.
-
Application
Type the following in code:
SQLCA.DBParm="Async=1"
Example 2
You can set the Async and DBGetTime parameters in a single statement. DBGetTime specifies the number of seconds you want PowerBuilder to wait for a response from the DBMS when you retrieve rows in a DataWindow object or report. To enable asynchronous operation and set the DBGetTime parameter to 20 seconds:
-
Database profile
Select the Asynchronous check box and type 20 in the Number Of Seconds To Wait box on the Transaction page in the Database Profile Setup dialog box.
-
Application
Type the following in code:
SQLCA.DBParm="Async=1,DBGetTime=20"
See also
