Provided by: slony1-doc_1.2.22-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, SLONIK SUBSCRIBE SET(7)). WAIT FOR
       EVENT may be used to cause the slonik script to wait  for  confirmation
       of  an  event,  which hopefully means that 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.

       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

       In version 2.0, the default value for WAIT ON was removed,  so  a  node
       must be specified.

ODDITIES

       Not  all  events  return interesting results. For instance, many people
       have  run  afoul  of  problems  with  SLONIK  SUBSCRIBE  SET(7),   when
       subscribing  a  new set. Be aware (and beware!) that a SLONIK 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 SLONIK 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
       SLONIK  SUBSCRIBE  SET(7)  is complete, you may submit a SLONIK SYNC(7)
       event after the subscription, and have the WAIT  request  wait  on  the
       SYNC event, as follows.

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

                                9 December 2010       SLONIK WAIT FOR EVENT(7)