Provided by: slony1-doc_1.2.15-1_all bug

NAME

       WAIT FOR EVENT - Have Slonik script wait for previous event to complete

SYNOPSIS

       WAIT FOR EVENT (options);

DESCRIPTION

       Waits for event Confirmation.

       Slonik remembers the last event generated on every node  during  script
       execution   (events  generated  by  earlier  calls  are  currently  not
       checked). In certain situations it is necessary that  events  generated
       on  one  node (such as CREATE SET) are processed on another node before
       issuing more commands (for instance, SUBSCRIBE SET(7)). WAIT FOR  EVENT
       may  be  used  to  cause the slonik script to wait until the subscriber
       node is ready for the next action.

       WAIT FOR EVENT must be called outside of any  try  block  in  order  to
       work,  since  new  confirm  messages  don’t  become  visible  within  a
       transaction.

       ORIGIN = ival | ALL
              The origin of the event(s) to wait for.

       CONFIRMED = ival | ALL
              The node ID of the receiver that must confirm the event(s).

       WAIT ON = ival
              The ID of the node where the “sl_confirm” [not  available  as  a
              man page] table is to be checked. The default value is 1.

       TIMEOUT = ival
              The  number  of  seconds  to  wait. Default is 600 (10 minutes).
              TIMEOUT = 0 causes the script to wait indefinitely.

EXAMPLE

       WAIT FOR EVENT (
         ORIGIN = ALL,
         CONFIRMED = ALL,
         WAIT ON = 1
       );

LOCKING BEHAVIOUR

       No application-visible locking should take place.

VERSION INFORMATION

       This command was introduced in Slony-I 1.0

ODDITIES

       Not all events return interesting results. For  instance,  many  people
       have  run  afoul  of problems with SUBSCRIBE SET(7), when subscribing a
       new set. Be aware (and beware!) that a SUBSCRIBE  SET(7)  request  will
       return  the  event  confirmation  almost immediately, even though there
       might be several hours of work to do before the subscription is  ready.
       The  trouble  with  SUBSCRIBE  SET(7)  is  that  it is processed as two
       events, one on the origin node, with a  second  event,  to  enable  the
       subscription, on the subscriber.

       In  order  to more reliably monitor from within a slonik(1) script that
       SUBSCRIBE SET(7) is complete, you may submit a SYNC(7) event after  the
       subscription,  and  have  the  WAIT request wait on that SYNC event, as
       follows.

            # Assuming that set 1 has direct subscribers 2 and 3
            SUBSCRIBE SET (ID = 999, PROVIDER = 1, RECEIVER = 2);
            SYNC (ID=1);
            WAIT FOR EVENT (ORIGIN = 1, CONFIRMED = 2, WAIT ON=1);
            SUBSCRIBE SET (ID = 999, PROVIDER = 1, RECEIVER = 3);
            SYNC (ID=1);
            WAIT FOR EVENT (ORIGIN = 1, CONFIRMED = 3, WAIT ON=1);
            MERGE SET ( ID = 1, ADD ID = 999, ORIGIN = 1 );

                               17 November 2008              WAIT FOR EVENT(7)