-
Notifications
You must be signed in to change notification settings - Fork 7
Forked from omniEvents-2.6.2 (http://omnievents.cvs.sourceforge.net/viewvc/omnievents/)
License
RedhawkSDR/omniEvents
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
omniEvents ---------- This is a fork of the omniEvents software version 2.6.2 (http://www.omnievents.org/). Information on installing, building and using omniEvents, an implementation of the OMG Event Service Specification v1.1 for omniORB3 and omniORB4. This work is licensed under the Creative Commons Attribution License. To view a copy of this license, visit http://creativecommons.org/licenses/by/2.0/ or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA. We hope you find omniEvents useful. If you have any comments or suggestion for improvements you can email us at: [email protected] [email protected] [email protected] 1. Introduction =============== omniEvents enables CORBA applications to communicate through asynchronous broadcast channels rather than direct method calls. The server runs on Windows, and most Unixes. It is a small, efficient implementation of the Object Management Group's Event Service specification designed to work with omniORB. We provide a number of example programs in C++, Python and Java, to help you get started with writing your own event service clients. If you want to get going quickly, then read the "Quick Install" section for Unix or Windows, and then refer to the Reference section. 1.1 Features ------------ Implements untyped event channels.: "Suppliers" send events to the event channel as a CORBA "`any'" type. The channel then broadcasts the event to all of the "consumers" that have subscribed to the channel. Persistent state.: Channels and connections are continuously saved to disk, so that they can be recreated when the server restarts. Scalable.: Event channels can be federated, which allows multiple servers to share the load of delivering events to many clients across a wide area network. Fault tolerant.: Implements a sub-set of the Fault-Tolerant CORBA specification. Servers may be configured to operate in pairs - if one fails then clients automatically switch over to the alternate. Easy to install.: The server runs as a daemon on Unix or a service on Windows. A SysV style init file can be automatically installed on Unix, to get you up and running with minimum fuss. Events can be filtered by type.: Event channels can be configured to only pass on events of a particular CORBA type. Combined with channel federation, this allows Consumers to choose which type of events to receive. Available as a library.: You can create event channels within your own programs by linking to the shared library (on Unix). 1.2 Further Reading ------------------- Information on the Event Service specification can be obtained from the "CORBA services : Event Service Specification" page at: http://www.omg.org/technology/documents/formal/event_service.htm For an introduction to the various communication models see "OMG Event Object Service", SIGS Vol9, Num 2, February 1997 . You can download from http://www.iona.com/hyplan/vinoski/col9.pdf There is an excellent introduction to the Event Service in Chapter 20 of the book "Advanced CORBA Programming with C++", by Michi Henning & Steve Vinoski. 2. Build and Installation ========================= This section provides a complete guide to building and installing omniEvents. 2.1 Prerequisites ----------------- You need to install omniORB before you can start with omniEvents. The latest version of omniORB4 is strongly recommended. You can download it from here: http://omniorb.sourceforge.net/download.html The Unix install requires GNU Make. If you don't have it already, then you can download it from here: http://ftp.gnu.org/pub/gnu/make/ In order to install omniEvents as a Windows service, you need to be using a modern version of Windows. You need: NT, win2000 or XP. You cannot use: win95, 98 or ME (but you can just run the server manually). 2.2 Quick Install Guide - Unix ------------------------------ omniEvents is distributed as source for Unix platforms. To install you must unpack the omniEvents-XXX-src.tar.gz file, build the code and then install the executables and init scripts into the correct locations on your system. 1) Unpack the .tar.gz file: `gzip -dc omniEvents-XXX-src.tar.gz | tar xvf -'. 2) Go down into the omniEvents diectory: `cd omniEvents-XXX'. 3) Run the `configure' script. For a full list of available parameters, type `./configure --help'. Common parameters are: --prefix=PREFIX install files in PREFIX [/usr/local]. --with-omniorb=PATH set the path to the local omniORB installation [$OMNIORBBASE]. -q, --quiet, --silent do not print "checking..." messages. 4) Compile the executables: `make'. 5) Get superuser privileges: `su root'. 6) Install the executables: `make install'. 7) Install the system init script: `cd etc; make install'. 8) Set up SysV service `omniorb-eventservice'... The procedure for setting up a SysV service differs from platform to platform. You need to create symbolic links from the /etc/rcX.d directories to the /etc/init.d/omniorb-eventservice init script. (The paths to these files may be different on your system.) For example, on a Debian GNU/Linux system, the command `update-rc.d omniorb-eventservice defaults' would set up omniEvents to start at the default runlevels. Example: Typical Unix build session % gzip -dc omniEvents-XXX-src.tar.gz | tar xvf - % cd omniEvents-XXX % ./configure % make % su root # make install # cd etc # make install # 2.3 Quick Install Guide - Windows --------------------------------- omniEvents is distributed precompiled for Windows. To install you must unpack the omniEvents-XXX-win32.zip file, set up your system path and install the service. 1) Unpack the .zip file using (for example) WinZip. We assume that you unpack it into C:\Program Files. If you choose to put it somewhere else, then just adjust the remainder of these instructions accordingly. 2) Add the omniEvents directory to the system environment variable: Path. It's important to NOT use the "local" path. Only the "system" path is available at boot time when services start. Menu: Start -> Control Panel. Icon: System. Tab: Advanced. Click: Environment Variables. Add to System Path: `;C:\Program Files\omniEvents-XXX' 3) Create a data directory: C:\omniEvents. omniEvents will store its persistent state in this directory. 4) Install the service: Open a command window, and type: `omniEvents install -t "C:\omniEvents\trace.out"' 5) The service will start automatically when you next reboot, or you can start it manually now. 2.4 Building from Source on Windows ----------------------------------- It is not usually necessary to compile omniEvents for Windows, since it is available pre-compiled. 1) Firstly make sure you have everything you need: Microsoft Visual C++ compiler. (Tested with version 6.0, service pack 3) The environment variables for command-line compiling must be set up. You can test this by trying to compile hello.cc (in the win32 directory) with the command: > cl -TP -GX -MD hello.cc omniORB4. Get it from http://omniorb.sourceforge.net/download.html You should set up your PATH environment to include: <omniORB Top-Level Directory >\bin\x86_win32 Test this by checking that this command prints out the omniidl help: > omniidl -u A fairly recent version of GNU Make for Windows (3.78.1 or above). Download it from http://unxutils.sourceforge.net/ or Google for "gnu make windows". The make.exe also needs to be in the PATH. For example, you could copy it into your C:\winnt directory. The following command should show version text: > make --help 2) Next make sure that the build files are correctly configured. Don't run the `configure' command on Windows, hand edit the files instead. When you unpack the omniEvents-XXX-src.tar.gz file, the Windows config.mk and src/config.h files should already be in the correct places. If not, then you can copy them from the win32/ directory. Edit config.mk to set the values of these variables: `OMNIORB_BASE' full path to omniORB top-level directory. `OMNIORB_LIBS' libraries provided by omniORB. `OMNIEVENTS_BASE' full path to omniEvents top-level directory. 3) Compile omniEvents. Open a command window, and `cd' to the omniEvents top-level directory. The following command builds omniEvents: > make 2.5 Programs ------------ This section lists the programs that are bundled with the omniEvents distribution. Most importantly, the omniEvents daemon implements the EventChannelFactory and hosts the event channels. The daemon is built in the src/ directory. On Unix the daemon is installed into /usr/local/sbin, by default. Unix win32 Description ---- ----- ----------- omniEvents omniEvents.exe EventChannelFactory server. These tools enable management of event channels from the command line. They are built in the tools/ directory. On Unix, they are installed into /usr/local/bin, by default. Unix win32 Description ---- ----- ----------- eventc eventc.exe Command to create a channel. eventf eventf.exe Command to federate (link) two channels. eventl ---------- Command to list all managed channels events events.exe Command to stream events to or from a file. rmeventc rmeventc.exe Command to remove a channel. rmeventall ----------- Command to remove all managed channels. Finally, four example clients are provided. These enable you to test whether or not your omniEvents daemon is really working. They are built in the examples/ directory. Unix win32 Description ---- ----- ----------- pushsupp pushsupp.exe Push Supplier test client pushcons pushcons.exe Push Consumer test client pullsupp pullsupp.exe Pull Supplier test client pullcons pullcons.exe Pull Consumer test client 2.6 Supported Platforms ----------------------- omniEvents 2.6 has been tested with omniORB 3.0.5 & omniORB 4.0.4 on the following platforms. Platform omniORB3 omniORB4 -------- -------- -------- AIX 5.1 / xlC_r 5.0 no yes HPUX 11.00 / aCC A.03.37 - yes Linux x86, Debian 3.1 / g++ 2.95.4 yes yes Macintosh OS X, 10.3.5 - yes Solaris 9 x86 / gcc-2.95.3 - yes Solaris 8 sparc / CC 5.3 yes yes Tru64 5.1B / cxx 6.5 yes yes Windows 2000 / Visual C++ 6.0 SP3 - yes Earlier versions of omniEvents have been tested on the following platforms. Platform omniORB3 omniORB4 -------- -------- -------- Tru64 4.0F / cxx 6.2 yes yes HPUX 10.20 / aCC (B3910B A.01.21) yes - Windows NT 4.0 / Visual C++ 6.0 SP3 yes - Solaris 2.5 / gcc-2.8.1 yes - x86 Redhat linux 4.2 / gcc-2.7.2 yes - x86 Mandrake 7.2 / gcc-2.95.3 - yes 2.7 Directory Structure ----------------------- The directory structure of the omniEvents distribution looks as follows. auto/ various scripts used by AutoConf doc/ this documentation doc/doxygen/ source code documentation generated by Doxygen. examples/ source files for examples examples/java/ Java version of examples examples/python/ Python version of examples idl/ idl files src/ source files test/ test harness tools/ command line tools for manipulating the Event Service. win32/ build files for Windows 3. How to Set Configuration Options =================================== This section tells you how to set configuration options, not what options are available. For a detailed description of the available configuration options, see the omniEvents reference section. See also the eventc reference section, for a description of how to configure new event channels at run-time. omniEvents' default "out of the box" set-up is fit for most purposes. You only need to modify the configuration if you are interested in advanced features such as fault tolerant failover, or changing the default TCP port. In general, command-line parameters are stored somewhere, and retrieved each time the daemon is started. The method of storing parameters is different on Unix and Windows. In addition, there are a number of defaults that can be set at compile-time. 3.1 Unix SysV-style service. ---------------------------- The SysV `init' program starts the omniEvents daemon from the script /etc/init.d/omniorb-eventservice. You can also use this script to start and stop the service manually: syntax: `/etc/init.d/omniorb-eventservice [start|stop|restart]' The script reads omniEvents' configuration options from the file /etc/default/omniorb-eventservice. Edit this file to change the options. See also: omniEvents reference. 3.2 Windows service. -------------------- The omniEvents Windows service stores options in the Registry key `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\omniEvents'. They are read each time the service starts. Usually the only option you should set is the -t FILENAME option that directs trace output to the named file. You set the service options by listing them after the `install' or `setoptions' commands: syntax: `omniEvents install OPTIONS' syntax: `omniEvents setoptions OPTIONS' You can see the currently stored options with the `getoptions' command: syntax: `omniEvents getoptions' See also: omniEvents-win32 reference. 3.3 Compile-time customisation ------------------------------ Some compile-time parameters may only be adjusted by manually editing the file src/defaults.h: o the default data directory [/var/lib/omniEvents on Unix, C:\omniEvents on Windows.] o the name of the environment variable that sets the data directory [ `OMNIEVENTS_LOGDIR'] o the period between data file checkpoints [`900' seconds] o Default event channel parameters: `PullRetryPeriod_ms' Time between `pull()' calls. [1 second] `MaxQueueLength' Number of events to queue. [1023] `MaxNumProxies' Limit on number of ProxyPullSuppliers. [1024] `CyclePeriod_ns' Time between batch transfer of events. [0.1 second] Please refer to the src/defaults.h file for descriptions of all parameters. 4. Running the examples ======================= The examples programs (`eventc', `pushsupp', `pushcons', `pullsupp', `pullcons') are also available as Python and Java. Look in examples/python/* and examples/java/*. In these examples, we run omniEvents from the command line. A real installation would probably use a system service, as mentioned in the installation section. 4.1 Start the Naming Service (omniNames) ---------------------------------------- You must start the naming service (`omniNames') as the examples make use of the naming service to locate the event channel factory. Please refer to the omniORB documentation for information on how to set up the naming service. 4.2 Start the omniEvents daemon (omniEvents) -------------------------------------------- `omniEvents' implements an Event Channel Factory server which clients can use to create Event Channels. The factory registers itself with the Naming Service to enable clients to locate it. Before you start, you may need to set the environment variable `OMNIORB_CONFIG' to contain the full path name of the file omniORB.cfg. The default is /etc/omniORB.cfg. For example: % OMNIORB_CONFIG=/wib/wob/omniORB.cfg; export OMNIORB_CONFIG Start omniEvents by running the executable. The binary is in PREFIX/sbin (if you used the `configure --prefix' parameter), or in /usr/local/sbin (by default). Once the service is correctly started up, it automatically backgrounds itself (Unix only). Example: Startup from the command-line. % omniEvents -l $HOME % omniEvents supports the following options: cold start syntax: src/omniEvents [-pPORT] [-aENDPOINT] [OPTIONS] warm start syntax: src/omniEvents [OPTIONS] COLD START OPTIONS: -p PORT configure server port [11169] -a ENDPOINT set alternate endPoint for failover OPTIONS: -l PATH full path to data directory* [/var/lib/omniEvents] -P PIDFILE keep track of running instance in PIDFILE. -N ID factory naming service id ["EventChannelFactory"] -f Stay in the foreground. -t FILE Send trace messages to FILE instead of syslog. -v print the IOR of the new EventChannelFactory. -V display version -h display this help text *You can also set the environment variable OMNIEVENTS_LOGDIR to specify the directory where the data files are kept. The options provided allow you to override the default name used to register the Event Channel Factory with the Naming Service. omniEvents supports persistent channels by writing all state changes to a file. This persistency datafile is stored in /var/lib/omniEvents/ by default. Use the -l option or the `OMNIEVENTS_LOGDIR' environment variable to override the default. 4.3 Create an Event Channel (eventc) ------------------------------------ `eventc' resolves the factory name with the Naming Service and then contacts the factory to request an Event Channel. The Event Channel is created within the the omniEvents process. You can by-pass the factory completely and instantiate the event channel directly within your own process by linking your application directly with the omniEvents shared libraries. The src/main.cc file is a good starting point to find out how. eventc then registers the created Event Channel with the Naming Service, and exits. eventc has the following options: syntax: tools/eventc OPTIONS [FACTORY_URI] FACTORY_URI: The factory may be specified as a URI. This may be an IOR, or a corbaloc::: or corbaname::: URI. For example: corbaloc::localhost:11169/omniEvents OPTIONS: DEFAULT: -n channel name ["EventChannel"] -N factory name (if URI is not specified) ["EventChannelFactory"] -c override default CyclePeriod_ns of new channel (nanoseconds) -i set the InsName of new channel, to enable access via corbaloc -p override default MaxNumProxies of new channel -q override default MaxQueueLength of new channel -R override default PullRetryPeriod_ms for new channel (milliseconds) -t set an event type filter, FilterId=<RepositoryId> -v print the IOR of the new EventChannel to standard output. -h display this help text OLD OPTIONS: (only used by omniEvents v2.4 and earlier) -m override default MaxEventsPerConsumer for new channel The options provided allow you to override the default name used to register the Event Channel Factory and the created Event Channel with the Naming Service. eventc starts silently unless it encounters any problems or if you turn tracing on by supplying the omniORB specific option -ORBtraceLevel 20. eventc terminates once the event channel has been created: % eventc % 4.4 Run one or more example suppliers/consumers ----------------------------------------------- There are four example clients: `pushsupp', `pushcons', `pullsupp' and `pullcons'. When run, each supplier and consumer contacts the Naming Service to obtain a reference to the Event Channel created in step 2 above. They then connect themselves to the channel and do their bits. The data sent through the channel is always of type `long' in the examples. As per `eventc', you can override the default name used to register the channel in the naming service. The -d option is used to exercise the disconnect functionality provided by the channel. syntax: examples/pushsupp OPTIONS [CHANNEL_URI] CHANNEL_URI: The event channel may be specified as a URI. This may be an IOR, or a corbaloc::: or corbaname::: URI. OPTIONS: DEFAULT: -d NUM disconnect after sending NUM events [0 - never disconnect] -r connect using a nil reference -s SECS sleep SECS seconds after disconnecting [0] -n NAME channel name (if URI is not specified) ["EventChannel"] -h display this help text syntax: examples/pushcons OPTIONS [CHANNEL_URI] CHANNEL_URI: The event channel may be specified as a URI. This may be an IOR, or a corbaloc::: or corbaname::: URI. OPTIONS: DEFAULT: -d NUM disconnect after receiving NUM events [0 - never disconnect] -s SECS sleep SECS seconds after disconnecting [0] -n NAME channel name (if URI is not specified) ["EventChannel"] -h display this help text syntax: examples/pullsupp OPTIONS [CHANNEL_URI] CHANNEL_URI: The event channel may be specified as a URI. This may be an IOR, or a corbaloc::: or corbaname::: URI. OPTIONS: DEFAULT: -d NUM disconnect after sending NUM events [0 - never disconnect] -s SECS sleep SECS seconds after disconnecting [0] -n NAME channel name (if URI is not specified) ["EventChannel"] -h display this help text syntax: examples/pullcons OPTIONS [CHANNEL_URI] CHANNEL_URI: The event channel may be specified as a URI. This may be an IOR, or a corbaloc::: or corbaname::: URI. OPTIONS: DEFAULT: -t enable try_pull mode -r connect using a nil reference -d NUM disconnect after receiving NUM events [0 - never disconnect] -s SECS sleep SECS seconds after disconnecting [0] -n NAME channel name (if URI is not specified) ["EventChannel"] -h display this help text The -t option in pullcons causes the pull consumer to issue non-blocking `try_pull()' invocations rather than blocking `pull()'s. Example: Here is what to expect during a typical session % examples/pushsupp Looking for EventChannel Obtained SupplierAdmin. Obtained ProxyPushConsumer. Connected Push Supplier. Push Supplier: push() called. Data : 0 Push Supplier: push() called. Data : 1 Push Supplier: push() called. Data : 2 Push Supplier: push() called. Data : 3 Push Supplier: push() called. Data : 4 Push Supplier: push() called. Data : 5 ... % examples/pushcons Obtained ConsumerAdmin. Obtained ProxyPushSupplier. Connected Push Consumer. Push Consumer: push() called. Data : 0 Push Consumer: push() called. Data : 1 Push Consumer: push() called. Data : 2 Push Consumer: push() called. Data : 3 Push Consumer: push() called. Data : 4 Push Consumer: push() called. Data : 5 Push Consumer: push() called. Data : 6 ... Pull consumers cause the event channel to poll every pull supplier connected when they request an event (using `pull()', not `try_pull()') until an event enters the event channel (which could come from a push supplier). In order to prevent the Event Channel from consuming excessive CPU when polling for events the -r option of eventc can be used to specify a pull retry period QOS parameter. This parameter represents a timeout in seconds to wait for before each poll cycle. This parameter defaults to 1 second. 5. Writing an Event Service Client ================================== The examples are a great place to start learning about the event service. Feel free to use them as a starting point for your own clients. The same examples are available as C++, Python and Java. However, this section provides a few more general instructions. 5.1 Connecting -------------- Here's a list of all the ways clients can locate the omniEvents server's EventChannelFactory object: by IOR. (`omniEvents -v'): The -v option prints the EventChannelFactory's IOR. You can then use a straightforward `string_to_object()' method call to turn this into an object reference. by `corbaloc::host:port/omniEvents': The EventChannelFactory is registered in the omniORB INSPOA as `omniEvents' which means that you can use the human readable "corbaloc" string above instead of the IOR. Replace `host' with omniEvents' hostname and `port' with the TCP port: 11169 (or whatever you chose with the -p option). `resolve_initial_references("EventService")': If omniORB.cfg is properly configured, you can use `resolve_initial_references()' to find the event service, just as is usually done for the Naming Service. Just add a line like this: InitRef = EventService=corbaloc::host:port/omniEvents The naming service (`omniEvents -N NAME'): omniEvents always registers the EventChannelFactory as a top-level entry in the naming service. Use the -N option to control the context, id & kind. (`EventChannelFactory' by default). 5.2 Using `any' type -------------------- The "events" pushed and pulled around by the Event Service are simply CORBA `any' values. The `any' type can hold any CORBA type. The examples simply send a `long' value, but a more realistic problem would employ a user-defined struct as the event. For user-defined types you first need to define the type in IDL, then compile the IDL. For omniORB with C++ you would use `omniidl -bcxx -Wba'. The -Wba generates the operators you will need to use your type with `CORBA::Any'. Here's a small example: module MyMessages { struct NVPair { NameType name; ValueType value; }; }; Assuming you compile this IDL correctly, you will have insertion & extraction methods: `operator>>=()' and `operator<<=()'. Here are examples of how to use them: CORBA::Any data; // Insert by value MyMessages::NVPair inputNvPair = ... data <<= inputNvPair; // takes a deep copy. // Insert by pointer MyMessages::NVPair* inputNvPairPtr = ... data <<= inputNvPairPtr; // does NOT copy - assumes ownership //XX delete inputNvPairPtr; <== NO!! . . . // Extract const MyMessages::NVPair* outputNvPairPtr = NULL; if(data >>= outputNvPairPtr) { // Use outputNvPairPtr BUT DON'T DELETE IT!! } else { cerr<<"Wrong type!!"<<endl; } Notice the memory ownership issues. It's best to double check each time you use `<<=' or `>>=' until you're confident you've got it right. 5.3 Disconnecting ----------------- All Supplier and Consumer objects have a `disconnect_*()' method. This means that each connection has two disconnect methods, one at each end. Which method should you call to terminate the connection? The best approach is to call the Proxy's `disconnect_*()', rather than your own. (Either will work, but instructing the Proxy to disconnect is more efficient.) The rule for implementing your own servant's `disconnect_*()' method is quite simple. Each `disconnect_*()' method should call the other `disconnect_*()' method. It is the responsibility of the Event Service end (the Proxy) to ensure that an infinite loop doesn't occur. So clients don't have to worry - they should always just call the Proxy's `disconnect_*()' when their own `disconnect_*()' is called. There is of course NO GUARANTEE that a `disconnect_*()' method will only be called once. You should never assume that your servants' methods will not be called until the object has actually been deactivated in the POA. It is possible to connect to ProxyPushConsumer & ProxyPullSupplier objects without providing an address for callbacks. When you do that, the proxies cannot call your disconnect method. If you choose to connect to these proxies without providing an address for callbacks, then you must clean up your own objects without help from the Event Service. These semantics only apply to Event Service v1.1 implementations such as omniEvents v2.6. Earlier specifications were vague about disconnection semantics, so you must be VERY careful if you want to interoperate with an older Event Service implementation (such as omniEvents v2.4 and earlier). 6. Notes for Windows Users ========================== If you are writing Event Service clients, you can use the omniEventsCl.lib library instead of compiling the Event Service IDL files yourself. BUT I DON'T RECOMMEND IT. There is no debug version of the omniEventsCl.lib library, so developing with it would be awkward. For serious work, you will be far better off compiling the IDL files yourself. If you do use the omniEventsCl.lib library, then make sure that you use the "multithreadded DLL" runtime with exceptions (options: -GX -MD), otherwise it won't work. 7. Reference ============ -------------------------------------------------------------------------------- omniEvents - CORBA Event Service daemon `omniEvents' -p <port> -a <endpoint> -l <directory> -P <pidfile> -N <factory-name> -f -t <file> -vVh -ORB<parameter> <value> DESCRIPTION `omniEvents' is a CORBA Event Service server program. It is designed to be run as a standalone daemon process. The server continuously saves its state to a file. Event channels are re-created from this file each time the server restarts. The options -p and -a affect the identity of the server's event channels, so these options can only be set the first time the server is run. Servers may be configured to operate in pairs - if one fails then clients automatically switch over to the alternate. OPTIONS -p port: Sets the TCP port on which a new server will listen. The default is `11169' This value is stored in the new server's persistent state. There is no need to supply this option when a server is restarted, since the value is read from the file. If the option is supplied then it is simply compared with the stored value - if the two do not match then the program exits with an error. -a endpoint: Sets an alternate endPoint for a new server. All CORBA object references generated by the server include the alternate address. When clients cannot contact the server, they automatically fall back to trying the alternate address. This option is exactly equivalent to the ORB parameter endPointNoListen, except that the value is saved in the server's persistency file, so that it is remembered whenever omniEvents is restarted. The format for a TCP endpoint is `giop:tcp:HOST:PORT', for example: `-a giop:tcp:secondary.host:11169' This value is stored in the server's persistent state. There is no need to supply this option when a server is restarted, since the value is read from the file. If the option is supplied then it is simply compared with the stored value - if the two do not match then the program exits with an error. -l directory: Full path to data directory, where omniEvents stores its persistent state. The default is /var/lib/omniEvents -P pidfile: Keep track of the currently running omniEvents process in `pidfile', which should usually be /var/run/omniEvents.pid. If `pidfile' already exists, then the server refuses to start. The default is to not write a PID file. -N factory-name: Sets the CORBA Name Service name for the EventChannelFactory CORBA object. Each time the server starts, it registers its channel factory object with `factory-name' in the Name Service. Format for name: `[CONTEXT-ID[.CONTEXT-KIND]/]*OBJECT-ID[.OBJECT-KIND]' Examples: `foo', `foo.bar', `foo.bar/baz/qux', `foo/bar/baz.qux'. The default is `EventChannelFactory' -f: Run the server in the foreground (do not daemonize). -t file: Send trace messages to `file' instead of syslog. -v: Output the CORBA IOR of the EventChannelFactory CORBA object when the server starts. This will go either to syslog or to the current trace file. -V: Display version. -h: Display a short summary of command-line options. -ORBparameter value: Standard omniORB options. see omniORB documentation for details. Do NOT use this option to set the `endPoint' or `alternateEndPoint'. This option is commonly used to set the omniORB `traceLevel', in order to get more detailed output. Example: `-ORBtraceLevel 5' EVENT CHANNEL PARAMETERS The omniEvents::EventChannelFactory object implements the standard CosLifeCycle::GenericFactory interface. An EventChannel object is created by a call to the `create_object(key,the_criteria)' operation. The "key" parameter must be set to `"EventChannel"."object interface"'. The "the_criteria" parameter is a sequence of various service parameters. Supported parameters are listed below. CyclePeriod_ns (`long'): Sets the cycle period of the channel (nanoseconds). This is the time that the channel waits before transferring messages from the incoming queue to the outgoing queue. While messages are being transferred, incoming calls are queued. The default is 0.1 seconds. FilterId (`string'): Only types whose `RepositoryId' matches the parameter are permitted to pass through the channel. Other events are silently ignored. InsName (`string'): Sets the name by which the EventChannel is known in omniEvents' INSPOA. You can refer to the channel with a corbaloc string like this: `corbaloc::HOST:11169/NAME' MaxNumProxies (`long'): The maximum number of `ProxyPullSuppliers' per channel. MaxQueueLength (`long'): How many events are buffered by the `ConsumerAdmin' object. The discard policy is FIFO, meaning that the oldest events are discarded first in case of overflow. PullRetryPeriod_ms (`long'): Period (milliseconds) between polls when in Pull Supplier - Push Consumer mode. SIGNALS SIGTERM, SIGINT: Shuts down the server. SIGUSR1: You can change the traceLevel while the application is running. Send the server SIGUSR1 to bump its traceLevel up by 5. The traceLevel is wrapped at 45, so you can always get it back to where it started by repeatedly sending SIGUSR1. Example: `kill -USR1 `cat /var/run/omniEvents.pid`' ENVIRONMENT VARIABLES OMNIEVENTS_LOGDIR: Sets the directory where data files are kept by default. An alternative to the -l option. OMNIORB_CONFIG: The location of the omniORB configuration file. COPYRIGHT Copyright © 2003-2005 Alex Tingle, 1999 Paul Nader. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -------------------------------------------------------------------------------- omniEvents-win32 - CORBA Event Service for Windows Command: `omniEvents' -p <port> -a <endpoint> -l <directory> -N <factory-name> -t <file> -vVh -ORB<parameter> <value> Windows service control: `omniEvents' install <OPTIONS> uninstall setoptions <OPTIONS> getoptions DESCRIPTION `omniEvents' is a CORBA Event Service server program. It is designed to be run as a Windows service. The server continuously saves its state to a file. Event channels are re-created from this file each time the server restarts. The options -p and -a affect the identity of the server's event channels, so these options can only be set the first time the server is run. Servers may be configured to operate in pairs - if one fails then clients automatically switch over to the alternate. SERVICE CONTROL `omniEvents' itself has four service set-up commands. The command name must immediately follow the `omniEvents'. Any normal command-line options which follow the command are stored in the Windows registry. They will be used when the service starts up. `omniEvents install OPTIONS': Install the service with the specified options. The only option that will usually be useful is -t, which instructs omniEvents to send trace logs to a file. Example: `omniEvents install -t "C:\omniEvents\trace.out"' `omniEvents uninstall': Uninstalls the service. `omniEvents setoptions OPTIONS': Changes the service's stored options. `omniEvents getoptions': Outputs the service's stored option to standard output. Once the `omniEvents' is installed, you can control it from the command line, or from scripts with the `Sc.exe' command. `Sc.exe' is distributed with the "Microsoft SDK". `sc start omniEvents': Starts the server. `sc stop omniEvents': Shuts down the server. `sc control omniEvents 128': You can change the traceLevel while the application is running. Send control signal `128' to the server to bump its traceLevel up by 5. The traceLevel is wrapped at 45, so you can always get it back to where it started by repeatedly sending signal `128'. OPTIONS -p port: Sets the TCP port on which a new server will listen. The default is `11169' This value is stored in the new server's persistent state. There is no need to supply this option when a server is restarted, since the value is read from the file. If the option is supplied then it is simply compared with the stored value - if the two do not match then the program exits with an error. -a endpoint: Sets an alternate endPoint for a new server. All CORBA object references generated by the server include the alternate address. When clients cannot contact the server, they automatically fall back to trying the alternate address. This option is exactly equivalent to the ORB parameter endPointNoListen, except that the value is saved in the server's persistency file, so that it is remembered whenever omniEvents is restarted. The format for a TCP endpoint is `giop:tcp:HOST:PORT', for example: `-a giop:tcp:secondary.host:11169' This value is stored in the server's persistent state. There is no need to supply this option when a server is restarted, since the value is read from the file. If the option is supplied then it is simply compared with the stored value - if the two do not match then the program exits with an error. -l directory: Full path to data directory, where omniEvents stores its persistent state. The default is C:\omniEvents -N factory-name: Sets the CORBA Name Service name for the EventChannelFactory CORBA object. Each time the server starts, it registers its channel factory object with `factory-name' in the Name Service. Format for name: `[CONTEXT-ID[.CONTEXT-KIND]/]*OBJECT-ID[.OBJECT-KIND]' Examples: `foo', `foo.bar', `foo.bar/baz/qux', `foo/bar/baz.qux'. The default is `EventChannelFactory' -t file: Send trace messages to `file'. -v: Output the CORBA IOR of the EventChannelFactory CORBA object when the server starts. -V: Display version. -h: Display a short summary of command-line options. -ORBparameter value: Standard omniORB options. see omniORB documentation for details. Do NOT use this option to set the `endPoint' or `alternateEndPoint'. This option is commonly used to set the omniORB `traceLevel', in order to get more detailed output. Example: `-ORBtraceLevel 5' EVENT CHANNEL PARAMETERS The omniEvents::EventChannelFactory object implements the standard CosLifeCycle::GenericFactory interface. An EventChannel object is created by a call to the `create_object(key,the_criteria)' operation. The "key" parameter must be set to `"EventChannel"."object interface"'. The "the_criteria" parameter is a sequence of various service parameters. Supported parameters are listed below. CyclePeriod_ns (`long'): Sets the cycle period of the channel (nanoseconds). This is the time that the channel waits before transferring messages from the incoming queue to the outgoing queue. While messages are being transferred, incoming calls are queued. The default is 0.1 seconds. FilterId (`string'): Only types whose `RepositoryId' matches the parameter are permitted to pass through the channel. Other events are silently ignored. InsName (`string'): Sets the name by which the EventChannel is known in omniEvents' INSPOA. You can refer to the channel with a corbaloc string like this: `corbaloc::HOST:11169/NAME' MaxNumProxies (`long'): The maximum number of `ProxyPullSuppliers' per channel. MaxQueueLength (`long'): How many events are buffered by the `ConsumerAdmin' object. The discard policy is FIFO, meaning that the oldest events are discarded first in case of overflow. PullRetryPeriod_ms (`long'): Period (milliseconds) between polls when in Pull Supplier - Push Consumer mode. ENVIRONMENT VARIABLES OMNIEVENTS_LOGDIR: Sets the directory where data files are kept by default. An alternative to the -l option. OMNIORB_CONFIG: The location of the omniORB configuration file. COPYRIGHT Copyright © 2003-2005 Alex Tingle, 1999 Paul Nader. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -------------------------------------------------------------------------------- eventc - create a CORBA EventChannel and register it in the naming service `eventc' -n <channel-name> -N <factory-name> -c <nanoseconds> -i <id> -p <num> -q <num> -R <milliseconds> -t <repository-id> -vh -ORB<parameter> <value> <factory-uri> DESCRIPTION eventc contacts the omniEvents server to request an Event Channel. The Event Channel is created within the the omniEvents process. eventc then registers the created Event Channel with the Naming Service, and exits. factory-uri: The factory may be specified as a URI. This may be an IOR, or a corbaloc::: or corbaname::: URI. Example: `eventc corbaloc::localhost:11169/omniEvents' If the factory-uri argument is not supplied, then the -N factory-name option is used to look up the server in the CORBA Name Service. OPTIONS -n channel-name: Sets the CORBA Name Service name for the new EventChannel CORBA object. Format for channel-name: `[CONTEXT-ID[.CONTEXT-KIND]/]*OBJECT-ID[.OBJECT-KIND]' Examples: `foo', `foo.bar', `foo.bar/baz/qux', `foo/bar/baz.qux'. The default is `EventChannel' -N factory-name: The CORBA Name Service name for the EventChannelFactory CORBA object. The default value is `EventChannelFactory'. This value is only used when the `factory-uri' argument is not supplied. -c nanoseconds: Sets the `CyclePeriod_ns' parameter of the new event channel. -i id: Set the `InsName' of new event channel, to enable access via corbaloc. -p num: Sets the `MaxNumProxies' parameter of the new event channel. -q num: Sets the `MaxQueueLength' parameter of the new event channel. -R milliseconds: Sets the `PullRetryPeriod_ms' parameter of the new event channel. -t repository-id: Sets the `FilterId' parameter of the new event channel. -v: Output the CORBA IOR of the new EventChannel CORBA object. -h: Display a short summary of command-line options. -ORBparameter value: Standard omniORB options. see omniORB documentation for details. This option is commonly used to set the omniORB `traceLevel', in order to get more detailed output. Example: `-ORBtraceLevel 5' ENVIRONMENT VARIABLES OMNIORB_CONFIG: The location of the omniORB configuration file. COPYRIGHT Copyright © 2003-2005 Alex Tingle, 1999 Paul Nader. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -------------------------------------------------------------------------------- eventf - connect (federate) two CORBA EventChannels `eventf' <from-channel-uri> <to-channel-uri> DESCRIPTION `eventf' establishes a connection between two event channels. The event channels must both already be in existence (perhaps created by the `eventc' command). If both event channels are implemented by omniEvents, then the connection is persistent: it will be recreated if one or both of the channels is shut down and later restarted. The from- and to-channels must be specified as URIs. This may be an IOR, or a corbaloc::: or corbaname::: URI. Example: `eventf corbaname::#from.channel corbaname::#to.channel' ENVIRONMENT VARIABLES OMNIORB_CONFIG: The location of the omniORB configuration file. COPYRIGHT Copyright © 2004,2005 Alex Tingle. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -------------------------------------------------------------------------------- eventl - list all event channels managed by the omniEvents service `eventl' -d DESCRIPTION `eventl' will provide a listing of all known event channels. Without the "-d" option a brief listing is returned as follows: CHANNEL: <channel name> [(unmapped)] If the channel name is followed by the text "(unmapped)", then that channel has no mapping identier can cannot be retrived or delete (rmeventc) using URI methods. Unmapped channels were created without InsName critera. Mapped channels can be dentified using the URI name methods, corbaloc::: or corbaname:::. OPTIONS: -d details the criteria listing when the channels was created. -h: Display a short summary of command-line options. -ORBparameter value: Standard omniORB options. see omniORB documentation for details. This option is commonly used to set the omniORB `traceLevel', in order to get more detailed output. Example: `-ORBtraceLevel 5' ENVIRONMENT VARIABLES OMNIORB_CONFIG: The location of the omniORB configuration file. COPYRIGHT Copyright © 2015 United States Government, as represented by the Secretary of Defense. All rights reserved. Any reproduction of this computer software, or portions thereof, marked with this legend must also reproduce these markings. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -------------------------------------------------------------------------------- events - stream events from or to a CORBA EventChannel `events' -n <channel-name> -s -h -ORB<parameter> <value> <channel-uri> DESCRIPTION `events' streams events from an event channel to standard output, or (-s) from standard input to an event channel. Events are streamed in raw binary form, accompanied by a timestamp. When the stream is played back into a channel, the timestamps are used the replicate the original delays between the messages. The main use for this command it to record sets of events and play them back later for testing. Recording example: `events corbaname::#EventChannel > test.dat' Playback example: `events -s corbaname::#EventChannel < test.dat' OPTIONS -n channel-name: The CORBA Name Service name used to look up the EventChannel CORBA object. Format for channel-name: `[CONTEXT-ID[.CONTEXT-KIND]/]*OBJECT-ID[.OBJECT-KIND]' Examples: `foo', `foo.bar', `foo.bar/baz/qux', `foo/bar/baz.qux'. The default is `EventChannel' -s: Supply mode. Read events from standard input. -h: Display a short summary of command-line options. -ORBparameter value: Standard omniORB options. see omniORB documentation for details. This option is commonly used to set the omniORB `traceLevel', in order to get more detailed output. Example: `-ORBtraceLevel 5' ENVIRONMENT VARIABLES OMNIORB_CONFIG: The location of the omniORB configuration file. COPYRIGHT Copyright © 2004,2005 Alex Tingle. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -------------------------------------------------------------------------------- rmeventc - destroy a CORBA EventChannel `rmeventc' -n <channel-name> -h -ORB<parameter> <value> <channel-uri> DESCRIPTION `rmeventc' connects to an event channel and calls its `destroy()' operation. If the channel is located by the -n option, then the name is unbound (removed) from the Name Service. Example: `rmeventc -nfoo/bar/baz.qux' OPTIONS -n channel-name: The CORBA Name Service name used to look up the EventChannel CORBA object. Format for channel-name: `[CONTEXT-ID[.CONTEXT-KIND]/]*OBJECT-ID[.OBJECT-KIND]' Examples: `foo', `foo.bar', `foo.bar/baz/qux', `foo/bar/baz.qux'. The default is `EventChannel' -h: Display a short summary of command-line options. -ORBparameter value: Standard omniORB options. see omniORB documentation for details. This option is commonly used to set the omniORB `traceLevel', in order to get more detailed output. Example: `-ORBtraceLevel 5' ENVIRONMENT VARIABLES OMNIORB_CONFIG: The location of the omniORB configuration file. COPYRIGHT Copyright © 2003-2005 Alex Tingle. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -------------------------------------------------------------------------------- rmeventc - destroy all managed CORBA EventChannels `rmeventall' -ORB<parameter> [-n] [-h] DESCRIPTION `rmeventall' removes all event channels from the service by calling the `destroy()' operation. If the "-n" option is present, then the correspond channel name will be looked up in the root naming context, and the name is unbound (removed) from the Name Service. Example: `rmeventall -n' OPTIONS -n removed channel names from the NamingService. -h: Display a short summary of command-line options. -ORBparameter value: Standard omniORB options. see omniORB documentation for details. This option is commonly used to set the omniORB `traceLevel', in order to get more detailed output. Example: `-ORBtraceLevel 5' ENVIRONMENT VARIABLES OMNIORB_CONFIG: The location of the omniORB configuration file. COPYRIGHT Copyright © 2015 United States Government, as represented by the Secretary of Defense. All rights reserved. Any reproduction of this computer software, or portions thereof, marked with this legend must also reproduce these markings. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
About
Forked from omniEvents-2.6.2 (http://omnievents.cvs.sourceforge.net/viewvc/omnievents/)
Resources
License
Stars
Watchers
Forks
Packages 0
No packages published