--  OVERVIEW
  --
  --  Alerts provide  support for the asynchronous (as opposed to
  --  polling) notification of database events.  By appropriate use of
  --  this package and database triggers, an application can cause itself
  --  to be notified whenever values of interest in the database are
  --  changed.

  --  A waiting application will be blocked in the database and cannot do
  --  any other work.
  --  

Rem     Routines to wait-for, and signal, a named event.  The waiting
Rem     session will block in the database until the event occurs, or until
Rem     a timeout expires.  The implementation avoids polling except when
Rem     running in parallel server mode.

  --  The application can register for multiple events and can then wait for
  --  any of them to occur using the 'waitany' call.
 

      So one could have one program register interest in a number of infrequently 
      updated tables, say, waitany, when an alert fires findd out which table
      has been updated, read it, pass the info on and then 'waitany' again ...



See: /user/oracle/rdbms/admin/dbmsalrt.sql for more details.



Example of the use of alerts:

NOTE: The appropriate trigger has to be in place: someone has to

create trigger bl_alert
after update on m_beamloss
begin
  dbms_alert.signal('bl_alert', 'beam loss table has just been updated');
end;

-------------------------------------------------------------------------



#include <stdio.h>
#include <string.h>
#include <strings.h>


int foo()
{


  exec sql begin declare section;

  varchar almessage[80];
  int alstatus;

  exec sql end declare section;
   
  int i=0;
  
  exec sql declare measure database;
  exec sql include sqlca.h;
  exec sql whenever sqlerror goto oraerr;


  strcpy(almessage.arr," ");
  almessage.len = strlen(almessage.arr);

  /* Register Alert ... */

  exec sql at measure 
    execute
      begin
        dbms_alert.register('bl_alert');
      end;
    end-exec;

  printf("registered\n");


  /* Wait on alert - program will sit here until m_beamloss is updated */

  exec sql at measure 
    execute
      begin
        dbms_alert.waitone('bl_alert',:almessage,:alstatus,300);
      end;
    end-exec;


  if(alstatus)
  { 
    printf("alert returned error\n");
  }
  else
  printf("BINGO\n");

  /* Go off and do whatever */

  /* Remove alert */

  exec sql at measure 
    execute
      begin
        dbms_alert.remove('bl_alert');
      end;
    end-exec;


  return 0;

oraerr:
  oracle_error( __FILE__, &sqlca);

  exec sql at measure 
    execute
      begin
        dbms_alert.remove('bl_alert');
      end;
    end-exec;

  return 1;

}