DBNotification event
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
|
Event ID |
Objects |
|---|---|
|
pbm_dbnotification |
Transaction |
Parameters
|
Argument |
Description |
|---|---|
|
notification |
A value of the DBNotification enumerated
DBServerDown! is used for Oracle RAC database HA events. DBFailover! |
|
command |
A string that informs users which command |
|
dbmessage |
A string that describes the reason why |
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.