DBNotification
PowerScript 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 |
Arguments
|
Argument |
Description |
|---|---|
|
notification |
A value of the DBNotification enumerated datatype.
DBServerDown! is used for Oracle RAC |
|
command |
A string that informs users which command was being |
|
dbmessage |
A string that describes the reason why the event |
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.