Free High Performance CORBA Notification Service from AT&T Laboratories

omniORB Home AT&T Research

Back to Documentation Home Page

Running the Example Programs

Overview of Command-Line Arguments

The following arguments are supported by both the 12 CosNotification-style clients and the 4 CosEvent-style ("legacy") clients:

• -d #           Disconnect after # events [default 0 means never disconnect]
• -b #           Batch size (only relevant for batch supplier programs) [must be >= 1; default 5]
• -m #         For push suppliers and pull consumers:
                       # of milliseconds to pause between each push/pull
                          [default 0 means push or pull as fast as possible]
                   For pull suppliers and push consumers:
                       # of milliseconds between each 'ping' request
                          [default 0 means do not use pings]
• -n name   Channel name (use event service to lookup this name)
• -f file        File containing channel IOR (use string_to_object on the IOR)
• -p file       File to store IOR of the proxy used by this client
                      (used by demo_add_filter, demo_offer_change, demo_subscription_chang)
• -v               Verbose output

If both -n and -f are specified, the -n option is tried first. If neither -n or -f is specified, the program first tries the name service using name "EventChannel", then it tries default IOR file /tmp/rdichan.ior.

The following arguments are used to add a filter, and are supported by the 12 CosNotification-style clients:

• -t types     A comma-separated list of types of the form D::T, with no spaces.
• -e expr     A boolean expression written in the default filter constraint language.

If one or both of these arguments is given, a filter is added to the supplier or consumer's proxy object, where the filter has one constraint consisting of a list of types and a constraint expression.  (The filter will match events of the specified types which also match the constraint expression.)  If only -t is given, the expression "true" is used for the constraint expression (true matches all events).  If only -e is given, the event type "*::*" is used for the type list (*::* matches all events).

Example:

      prompt>   struct_push_consumer   -d 10  -t Stock::Ticker,Bond::Ticker  -e "$Value > 10" -v

The boldface command line starts the structured push consumer program, where the program will terminate after 10 events are consumed.  A filter is added that only matches events that have either type Stock::Ticker or type Bond::Ticker where the Value field is greater than 10.  The -v verbose option causes some output to occur for each event that is consumed.  Note that there should be no spaces in the event type list.

Step-by-Step Instructions

This section goes over how to start both the notification daemon, notifd, and the example client programs.  It assumes you are doing an interactive demo, and thus will want to use the -v option for verbose output.  Also, it assumes you will start each program in a separate command window (such as an xterm for Unix systems).   You could also write a script to start several programs in the background (without the -v); this might be useful for making performance measurements.

(1) Start notifd

In one command window, start  notifd like this:

    prompt> notifd  -i  -c <omni_top>/src/services/omniNotify/channel.cfg

where <omni_top> is the top-level directory of your omniORB installation.  The -i option makes the daemon interactive, while the -c option    tells it to configure itself using the configuration file channel.cfg from the omniNotify distribution.

One thing channel.cfg specifies is locations for 2 IORs: notifd should put a factory IOR in /tmp/rdifact.ior and a channel IOR in /tmp/rdichan.ior.  It also specifies that the default channel should register itself with the name service using "EventChannel".   You can change these defaults by editing channel.cfg; if you do so, you may need to start the example programs with extra arguments.  For example, if you change the name of the channel to NotifChannel, you should use   -n NotifChannel   when starting the programs.    Similarly, if you change the IOR file of the default channel, you must use the -f option.

(2) Start one or more consumers

Starting consumers first (before starting any suppliers) makes sense because the consumers will simply block until events start arriving at the channel.

There are 6 new-style consumers:

    any_push_consumer.cc, any_pull_consumer.cc,
    struct_push_consumer.cc, struct_pull_consumer.cc,
    batch_push_consumer.cc, batch_pull_consumer.cc

and 2 CosEvents-style consumers:

    legacy_push_consumer.cc, legacy_pull_consumer.cc

You can start any number of them; 1 is enough for a simple demo.   In addition to the -n and -f options discussed above, you can use the following options.

• You can give the number of events to consume using the -d option.  The default for -d is zero which means consume events 'forever'.
• You can use the -m option to specify a time interval in milliseconds.
  • For pull consumers, -m is used to specify the number of milliseconds to wait between each pull call that is performed by the consumer.  A value of 0 means pull as fast as possible.
  • For push consumers, -m is used to specify the interval between "pings" of the consumer's proxy. A value of 0 means do not use pings.  (Pings are used to detect that a channel has crashed; if no pings are used, the consumer will not detect a channel crash and will wait indefinetely for the next push call.)

  Zero is the default value for -m.

• The -p option is used to specify a filename for storing the IOR of the proxy that the consumer connects to. This option is used in combination with the demo_subscription_change or demo_add_filter helper clients (see below).
• For new-style consumers, the -t and -e options are available for specifying a filter to be added to the proxy that the consumer connects to. This filter controls which events the consumer will receive (via push or pull). If no filter is specified, the consumer will initially receive all events, and this can then be changed while the consumer is running using either the demo_subscription_change or demo_add_fitler helper clients. The argument to -t is a comma-separated list of event types, and can have no spaces. The argument to -e is a constraint expression written in the default constraint language defined by the CosNotification spec. We give some constraint examples in the "demo_add_filter" section.
• To see some output for each event that is consumed, use the -v option.

Examples:

   prompt> struct_push_consumer  -d 200  -p cproxy.ior   -v

The consumer will consume 200 events then exit. The consumer's proxy's ior is stored in cproxy.ior. All event types are received, even events supplied by suppliers that provide type CORBA::Any events.  (The struct and batch consumers only 'understand' Stock::Ticker events but they will print an acknowledgement when they receive other kinds of events.)

  prompt> struct_push_consumer  -d 200  -p cproxy.ior   -t Stock::Ticker  -v

As above except the consumer will only receive Stock::Ticker events.  If you run the legacy_*_supplier or any_*_supplier clients, no events will be received, as only the struct_*_supplier and batch_*_supplier clients supply Stock::Ticker events.

(3) Start one or more suppliers

There are 6 new-style suppliers:

    any_push_supplier.cc, any_pull_supplier.cc,
    struct_push_supplier.cc, struct_pull_supplier.cc,
    batch_push_supplier.cc, batch_pull_supplier.cc

and 2 CosEvents-style suppliers:

    legacy_push_supplier.cc, legacy_pull_supplier.cc

You can start any number of them; 1 is enough for a simple demo.  In addition to the -n and -f options discussed above, you can use the following.

• The -d option specifies how many events to supply. The default of zero means supply events forever.
• The -m option is used to specify a time interval in milliseconds.
  • For push suppliers, -m is used to specify the number of milliseconds to wait between each push call that is performed by the supplier. A value of 0 means push as fast as possible.
  • For pull suppliers, -m is used to specify the interval between "pings" of the supplier's proxy. A value of 0 means do not use pings.

  Zero is the default value for -m.
  
  ** For interactive demos when you are viewing what is happening using the -v option, it makes sense to use a push supplier and to use a -m value of 1000 (1 second pause between supplying each event).

• The -p option is used to specify a filename for storing the IOR of the proxy that the supplier connects to. This option is used in combination with the demo_offer_change helper client (see below).  (You can only use new-style suppliers with the demo_offer_change helper program.)
• For new-style suppliers, the -t and -e options are available for specifying a filter to be added to the proxy that the supplier connects to. This will be a "supply-side" filter that only acts on the events provided by this particular supplier client, and can be thought of a simple means of discarding supplied events prior to actually having the events processed by the main consumer-side filter matching machinery. (Supply-side filters are rarely used, compared to consume-side filters.) The argument to -t is a comma-separated list of event types, and can have no spaces. The argument to -e is a constraint expression written in the default constraint language defined by the CosNotification spec. We give some constraint examples in the "demo_add_filter" section.
• To see some output for each event that is supplied, use the -v option.

Examples:

  prompt> struct_push_supplier  -d 800  -m 1000  -v

Supplies 800 Stock::Ticker events, with a 2 second pause between each.

  prompt> struct_push_supplier  -d 800  -m 1000  -e '$Value >= 20'  -v

As above, except Stock::Ticker events with Value less than 20 are discarded by the supplier's proxy as soon as they reach the channel.

The "Demo" Helper Programs

(4) Additional "Helper" Client: demo_add_filter

If you used the -p option for one of the consumers that you started, you can use demo_add_filter to filter the events arriving at that consumer. Here we assume that you used -p cproxy.ior ...

NOTE: this discussion assumes you are using struct_*_supplier or batch_*_supplier for your supplier. I.e., it assumes you are using clients that supply Stock::Ticker and Bond::Ticker events. These suppliers announce events for 5 stocks (A, B, C, D, E) and 5 bonds (F, G, H, I, J) with a Name field and a Value field. You must use -v option with the consumer to observe the impact of adding or changing a filter. (We suggest using the struct_push_consumer client and using struct_push_supplier with -m 1000 so that the consumer will not be flooded with event output.)

You start the program with the same -p option you used with the consumer, e.g.,

  prompt> demo_add_filter  -p cproxy.ior

The client will prompt you to enter a constraint expression. After typing an expression and hitting return, the client will replace any existing filters with a new filter that contains the constraint you specified.

Here are some example filters:

  false

  true

  $Name < 'D'

  $Name == 'F' and $Value >= 20 and $Value <= 30

The constraint expression `false' trivially evaluates to false, so the consumer will stop receiving events. Similarly, `true' will cause it to receive all events supplied to the channel.

The expression

    $Name < 'D'

will match events for stocks A, B, and C, as these are the only names "less than" D.

The expression

    $Name == 'F' and $Value >= 20 and $Value <= 30

will only match Stock::Bond events for bond F that have a Value that is between 20 and 30 inclusive.

You can exit the demo_add_filter program by entering

  exit

as the constraint.

(Note that demo_add_filter causes subscription_change messages to be sent out: each constraint expression that is entered causes a filter removal followed by a filter addition, which means there are typically 2 subscription_change messages generated, one with a list of event types to remove, one with a list of event types to add. Since it uses *::* for the event type, this is always the type that is removed/added.)

(5) Additional "Helper" Client: demo_subscription_change

If you start a consumer with the -p option then you can use demo_subscription_change to cause subscription_change messages to be sent to this consumer's proxy. Here we assume that you used -p cproxy.ior ...

NOTE: For a consumer that has no attached filters, subscription_change messages serve to control the event types that it receives. However, if filters have been added to the proxy then subscription_change messages will have NO EFFECT. This is the specified semantics from the spec -- the idea being that once you start giving explicit filters you should no longer be using subscription_change directly (but rather modifying, adding, or removing filters) to change the event type subscriptions.

You start the program with the same -p option you used with the consumer, e.g.,

    prompt> demo_subscription_change  -p cproxy.ior

After this you are prompted first for a list of types to be removed, then for a list of types to be added. You must enter comma-separated lists with no spaces between the types or in the type names; hit return after each list. (Hit return immediately for an empty list.)

A subscription_change message is sent to the proxy, and then you are prompted for another pair of lists. You can enter exit instead of a type list to quit the program.

As with demo_add_filter, we suggest using the struct_push_consumer client and using struct_push_supplier with -m 1000 so that the consumer will not be flooded with event output. In this case, try the following sequence:

(At the start the consumer should be receiving both Stock::Ticker and Bond::Ticker event types.  Your input to the demo_subscription_change program is shown in bodl.)

  Enter list of removals (or empty for none):
  *::*<return>

  Enter list of additions (or empty for none):
  Stock::Ticker

(At this point only Stock::Ticker events should be received.)


  Enter list of removals (or empty for none):
  Stock::Ticker

  Enter list of additions (or empty for none):
  Bond::Ticker

(At this point only Bond::Ticker events should be received.)

(6) Additional "Helper" Client: demo_offer_change

** NOTE: There is no real reason to use demo_offer_change, since the example consumers do not change their behavior because on what event types have been offered. This helper program is really just a convenient way to test whether the offer_change mechanism implemented by the notification channel is working.

If you start a supplier with the -p option then you can use demo_offer_change to cause offer_change messages to be sent to this supplier's proxy. Here we assume that you used -p sproxy.ior ...

You start the program with the same -p option you used with the consumer, e.g.,

    prompt> demo_offer_change  -p sproxy.ior

After this you are prompted first for a list of types to be removed, then for a list of types to be added. You must enter comma-separated lists with no spaces between the types or in the type names; hit return after each list. (Hit return immediately for an empty list.)

An offer_change message is sent to the proxy, and then you are prompted for another pair of lists. You can enter exit instead of a type list to quit the program.

Back to Documentation Home Page