/
/ $Header: has/evm/admin/usrco/README /main/5 2009/06/09 15:41:56 wsun Exp $
/
/ Copyright (c) Oracle Corporation 2002. All Rights Reserved.
/
/   NAME
/     README 
/
/   DESCRIPTION
/     Instruction for creating event user callout programs
/
/   NOTES
/
/

This file should go to $ORA_CRS_HOME/racg.

Oracle Real Application Clusters High Availability Extensions
(RACX) utilizes events for notifications about state changes in
the system that may be of interest to other components in the
system or to the user. Some of the events are informational
that merely informs user something happening in the system.
Some of the events are action driven that require administrator
or other application programs to take appropriate actions to
correct the changes because the state changes in the system
will likely affect other applications. Some examples of such
events include database or instance up/down, service up/down,
node down etc. Oracle RAC supports the infrastructure that user
can define their own event callout programs. These programs
will be invoked by Oracle RAC system when certain events occur.
Oracle RAC passes necessary information as arguments to these
callouts such as the related node name, service name, instance
name, database name etc. The user callout programs will parse
these information and pass them to other user's application or
system administrator. The user callout programs are expected to
understand the communication protocol used by other user
applications.

The user callout programs should be placed in the following
directory: $ORA_CRS_HOME/racg/usrco.  Oracle RAC will only
invoke the callouts placed in this location.  

The user callout programs should understand the following
arguments.

$usrco_prog $event_typ VERSION=1.0 [service=$srvname \
            database=$dbname instance=$instname] \
            host=$hostname status=$status \
            timestamp=$timestamp [card=$cardinality] \
            reason=$reason

$usrco_prog:  user callout program name.
$event_typ:   one of the following: 
              NODE: nodedown event
              SERVICE: entire service is up/down
              SERVICEMEMBER: service provided by a specific instance up/down
              INSTANCE: instance is up/down
              DATABASE: database is up/down
$version:     The version of the event protocol. Currently it's set to "VERSION=1.0"
$hostname:    This is hostname that the event is related to.
$status:      "up", "down" or "nodedown" "restart failed",
              "not_restarting".
$timestamp:   The time when this event happens
$cardinality: Cardinality of service. This indicates the number of service
              numbers that are currently ONLINE for a service. This attribute
              is only for service up event.
$reason:      Reason for the event. Several example of the valid values are 
              USER, FAILURE, FAILOVER.

All the other arguments should be self-explanatory.

Note: The nodedown event is special. It does not need to
      provide DATABASE_NAME SERVICE_NAME and INSTANCE_NAME.
      The nodedown event format is: 

$usrco_prog NODE VERSION=1.0 host=$hostname status=nodedown timestamp=$timestamp 

For more detailed instruction, consult "Real Application Clusters 
Administration and Deployment Guide" book.