Configuring the Sybase CEP Engine General Purpose Plugin

A description of how to customize the appropriate section of the c8-server.conf file to configure the general purpose plugin.

Sybase CEP Engine includes a general purpose plugin, which invokes any executable program you specify in response to an event.

If necessary, you may configure multiple instances of the general purpose plugin to execute different programs in response to different events. You may specify as many event/program pairs as you wish for each Sybase CEP Server. To spawn a single event to more than one program, or to spawn one program from more than one event, a separate instance of the general purpose plugin should be configured for each invocation of each program in response to each desired event.

If you are configuring multiple instances of the plugin, follow the steps described here for each instance you are defining:

Create a subsection for the plugin configuration in the "SybaseC8/Server/Manager/Plugins" section of the c8-server.conf file.

This section already contains a "SampleCommandLinePlugin" subsection that looks like this:

<!--
	<section name="SampleCommandLinePlugin">
	<preference name="LibraryName" value="c8_server_plugins_lib"/>
	<preference name="InitializeFunction"
  value="c8_command_line_plugin_initialize"/>
	<preference name="ExecuteFunction"
  value="c8_command_line_plugin_execute"/>
	<preference name="ShutdownFunction"
  value="c8_command_line_plugin_shutdown"/>
	<preference name="MessageGroup" value="SampleMessageGroup"/>
	<preference name="MessageName" value="SampleMessageName"/>
	<preference name="CommandName" value="/usr/bin/some_command"/>
	<preference name="CommandArgument1" value="-a={MessageGroup}"/>
	<preference name="CommandArgument2" value="-b={MessageName}"/>
	<preference name="CommandArgument3" value="-c={ObjectID}"/>
	<preference name="CommandArgument4" value="-d={Value}"/>
	<preference name="MaxRunningProcesses" value="10"/>
	<preference name="CommandTimeoutSeconds" value="5"/>
	</section>
	-->

You can either remove the markings from this section and customize it, as described in this section, or make a copy of the section below the original and customize that copy.

Rename the "SampleCommandLinePlugin" section.
It is best to give the section a meaningful name. Use any name that is unique within the configuration file. For example:
```
<section name="testplugin1">
```

Make sure that the "LibraryName" , "InitializeFunction" ,"ExecuteFunction", and "ShutdownFunction" preferences are set as shown here:

<preference name="LibraryName"
	value="c8_server_plugins_lib"/>
	<preference name="InitializeFunction"
	value="c8_command_line_plugin_initialize"/>
	<preference name="ExecuteFunction"
	value="c8_command_line_plugin_execute"/>
	<preference name="ShutdownFunction"
	value="c8_command_line_plugin_shutdown"/>

Set the "MessageGroup" preference to the Sybase CEP Server event group that includes the event that you want to invoke the plugin.

For a list of available Sybase CEP Server event groups and the events included in each group, see "Sybase CEP Server Events".
Set the "MessageName" preference to the name of the event that you want to invoke the plugin.
Set the "CommandName" preference to the full path and name of the executable program you want the plugin to execute.

Note:
On Microsoft Windows, you can specify only the name of the program, without the path, if the path to the program appears in the %PATH% environment variable.
If you want the command specified in the "CommandName" preference to execute with command line arguments, specify the arguments with the "CommandArgument#" preferences, where # is a number from 1 to 1024.
1. The "SampleCommandLinePlugin" includes the first four "CommandArgument#" preferences with sample values.
  
  Replace these with the actual arguments you want to pass to your program. You may also add additional "CommandArgument#" preferences as necessary or delete extra preferences, as needed.
  
  Use the "CommandArgument1" preference to specify the first argument you want to pass to the command, then specify any subsequent arguments in numeric order: using preferences "CommandArgument2", "CommandArgument3" and so on. Sybase CEP Server ignores any arguments that are specified out of order.
2. Use a separate "CommandArgument#" preference for every command line argument.
  For example, configure a shell command such as this:
```
command
 -a -b -c -d "
-quoted value
"
```
  like this:
```
...
		<preference name="CommandArgument1" value="-a"/>
		<preference name="CommandArgument2" value="-b"/>
		<preference name="CommandArgument3" value="-c"/>
		<preference name="CommandArgument3" value="-d"/>
		<preference name="CommandArgument4" value="-quoted value"/>
		...
```
  The quotation marks in this example are optional. Sybase CEP Engine automatically adds quotation marks around values that require them, so you do not have to explicitly indicate quotation marks in the argument configuration.
3. The value of any command argument preference may contain the following pre-defined special names.
  Sybase CEP Engine replaces these names with the corresponding values for every invocation:
```
{SourceTimestamp}
```
  is replaced by the time at which the event took place.
```
{MessageGroup}
```
  is replaced by the message group of the event.
```
{MessageName}
```
  is replaced by the message name of the event, as it occurs within its message group.
```
{ObjectID}
```
  is replaced by the URI of the object to which event applies.
```
{Value}
```
  is replaced by the value associated with the event.
4. Since the curly bracket characters ({ }) have special meanings, as shown in the previous bullet item, preface any other occurrences of curly brackets with the \ escape character.
  For example:
```
...
		<preference name="CommandArgument1" value="\{a\}"/>
		...
```
Set the desired value for the "MaxRunningProcesses" preference, or leave the value at its sample setting of ten (10).

This preference works in conjunction with the "CommandTimeoutSeconds" preference, and allows you to set the maximum number of event-handling programs spawned by the current instance of the plugin that may execute at the same time.

If a new event arrives when the maximum number of programs are running, Sybase CEP Server attempts to terminate any running event-handling processes that have either finished execution, or have reached the maximum time limit specified by the "CommandTimeoutSeconds" preference. If none of the running processes can be terminated, the new process does not launch.

If you delete this preference, the number of maximum running process defaults to 32.
Set the "CommandTimeoutSeconds" preference, or leave it at its sample setting of 5.
This works in conjunction with "MaxRunningProcesses" and takes effect only when the indicated maximum number of processes are running. Once the number of running processes reaches the maximum indicated by "MaxRunningProcesses", Sybase CEP Engine terminates all processes launched previously by the current instance of the plugin that have been running longer than the number of seconds indicated by "CommandTimeoutSeconds".

If you delete this preference entirely, "CommandTimeoutSeconds" defaults to 60. A value of 0 indicates that processes should never be timed out.
Note: Keep in mind these considerations when you are setting the timeout preferences intervals for events.
- Most event-handling programs take less than one second to process events that regularly occur once per second: for example notifications about CPU consumption.
- Events that occur infrequently, such as Container failure, usually do not occur in groups of more than one, so, in most cases, the maximum running processes and timeout interval is irrelevant. However, Sybase suggests that you consider the maximum number of such events that could occur within a specified time, and set the preferences accordingly.