Description
Triggered by a PowerBuilder script or DataWindow database operation command if a PowerBuilder database driver receives a notification from the database server. This event is supported only with the Oracle 10g (O10) native database interface.
Event ID
Arguments
|
Argument |
Description |
|---|---|
|
notification |
A value of the DBNotification enumerated datatype. The database interface determines the type of the notification received from the server, triggers the DBNotification event, and passes the notification type in this argument. Values are:
DBServerDown! is used for Oracle RAC database HA events. DBFailover! and DBDataTruncate! can be used with other databases for failover and data truncation warnings. |
|
command |
A string that informs users which command was being executed when the notification occurred. |
|
dbmessage |
A string that describes the reason why the event occurred. |
Return Values
Long.
Return code choices (specify in a RETURN statement):
-
0 -- Continue to process the database command. If the event does not exist or does not have a script, the return value is 0 by default.
-
Any other value -- Ignored if the notification argument is DBFailover!. If the value of the notification argument is DBServerDown! or DBDataTruncate!, the current command returns with an error. SQLCA.SQLCode is set to -1 and SQLCA.SQLDBCode is set to the return value.
Usage
Oracle Real Application Clusters (RAC) is a cluster database that uses a shared cache architecture. In Oracle 10g Release 2, a High Availability (HA) client connected to an RAC database can register a callback to indicate that it wants the server to notify it in case of a database failure event that affects a connection made by the client. The DBNotification event is triggered when the client is notified that such an event has occurred.
The default transaction object, SQLCA, does not support this event. To use the event, create a new standard class user object that inherits from the Transaction object and add code to the DBNotification event script. You can then use this Transaction object in your application, or substitute it for SQLCA on the Variable Types tab page in the Application Properties dialog box.
To be notified when the server shuts down, your application must be connected to an Oracle 10g RAC database using the O10 database interface and the HANotification database parameter must be set to 1. When the server shuts down, the O10 driver is notified. The DBNotification event is triggered if the application continues to attempt to access the server. The value of the notification argument is set to DBServerDown!, the command string is set to the syntax of the current command, and the dbmessage string is populated with information about the shutdown.
If your application does not execute any SQL statements on the current connection after the server shuts down, the DBNotification event is not triggered until Disconnect is called.
You can code the return value of the DBNotification event to specify whether the application should continue to execute the current command:
-
If the event returns 0, the current command continues executing until failover occurs and completes successfully (if failover is supported), then the application continues. If failover is not supported, the application will receive an error for the current command.
-
If the event returns any other value, the current command execution is stopped immediately and the Transaction object property SQLCode is set to -1, SQLDBCode is set to the return value, SQLErrText is set to the value of the dbmessage string, and failover does not happen. After the event, only Disconnect can be called on the current transaction.
Inside the DBNotification event script, the current connection of the Transaction object is protected and database operations with the connection are not allowed. All database commands will return as failed. However, the application can still access the database with another Transaction object.
If the SvrFailover database parameter is set to Yes, the DBNotification event is triggered with the notification argument set to DBFailover!
The event can be triggered several times during the failover, as when the failover begins and ends. You do not need to be connected to an Oracle RAC database or to set the HANotification database parameter to be notified when a failover occurs.
