Use the ADL to modify how your adapters interact with Sybase CEP Studio.
An in-process adapter may have zero or more adapter properties. These allow one instance of an adapter to have custom values that tell it to behave differently (such as use a different data source) than other instances of the adapter. For example, the ReadFromCSVFile adapter, which is one of the built-in adapters supplied by Sybase CEP, allows you to specify which file to read from. Similarly, if you write your own in-process adapter, you may use parameters to specify the exact data source to read from. If you have not already looked at any built-in in-process adapters, we recommend that you look at one now. Create a stream, attach the ReadFromCSVFile adapter to that stream, and then click on the adapter in the Explorer View of Sybase CEP Studio. The Explorer View of Sybase CEP Studio will display the adapter properties, such as Filename, Loop count, Rate, and so on.
ADL allows you to describe your parameters in such a way that Sybase CEP Studio can display labels and empty fields, and then pass the filled-in values to your in-process adapter. For example, your adapter might use ADL to tell Sybase CEP Studio to display the label "Filename", read the string that a user types into a field next to that label, and then pass your string to you.
As we mentioned in the chapter on creating an in-process adapter, your adapter will consist of two files: one file is the library with your Initialize(), Execute(), and Shutdown() functions, and a second file (the .adl file) contains a description of the adapter's parameters. This chapter describes what that .adl file will contain.
Each ADL File must include:
Name of the Adapter
Direction of Adapter: Input or Output
ScreenName
Vendor
Version
Description
InstanceParameter Definitions
Each InstanceParameter Definition comprises one or more parameter attributes that each contain:
Name
Type
Default Value
Description
A flag to indicate whether the parameter is required or not.
The ADL file must also include Adapter Definition information such as the xmlns field. For details, see the "AdapterDefinition" section in the example below.
Below is an example of an ADL file :
<AdapterDefinition xmlns="http://www.sybase.com/adl/2005/04/" Name="ReadFromXmlFileAdapterType" xmlns:ns1="http://www.sybase.com/cpx/2004/03/" Type="ns1:AdapterType" Direction="Input" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SupportsGuaranteedDelivery="true"> <ScreenName>Read From XML File Adapter</ScreenName> <Vendor>Sybase, Inc.</Vendor> <Version>1.0</Version> <Description>An input adapter that reads tuples from an XML file </Description> <LibraryName>sdk_adapter_lib</LibraryName> <InitializeFunction>my_input_adapter_initialize</InitializeFunction> <ExecuteFunction>my_input_adapter_execute</ExecuteFunction> <ShutdownFunction>my_input_adapter_shutdown</ShutdownFunction> <ReconnectFunction>my_input_adapter_reconnect</ReconnectFunction> <InstanceParameterDefinitions> <Parameter Name="Filename" xsi:type="xsi:string"> <Default/> <Description>The name of the file from which to read tuples. </Description> <Required>1</Required> </Parameter> <Parameter Name="Rate" xsi:type="xsi:integer"> <Default/> <Description>Post tuples at given rate (tuples per second) </Description> <Required>0</Required> </Parameter> </InstanceParameterDefinitions> </AdapterDefinition>
When Sybase CEP releases updated versions of the software, the structure of ADL files may change. If you want to create your own ADL file, and if you want to use an existing ADL file (such as c8_read_from_csv_file.adl) as a baseline, you should use the version that came with your product, which may differ from the version shown above. The ADL files supplied by Sybase CEP can be found in the directory
<install_dir>/Studio/plugins
On Microsoft Windows, this is typically:
C:\Program Files\sybasec8\Studio\plugins
On UNIX-like operating systems, this is typically:
/home/username/sybasec8/studio/plugins
The ADL file begins with a section similar to that shown below:
<AdapterDefinition
xmlns="http://www.sybase.com/adl/2005/07/"
Name="UserDefinedReadFromCsvFileAdapterType"
xmlns:ns1="http://www.sybase.com/cpx/2004/03/"
Type="ns1:AdapterType"
Direction="Input"
SupportsGuaranteedDelivery="true"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
>
<ScreenName>CServer SDK Adapter: Read From CSV File</ScreenName>
<Vendor>Sybase, Inc.</Vendor>
<Version>1.0</Version>
<Description>An input adapter that reads messages from a CSV file
</Description>
<Documentation>An input adapter that reads messages from a file that
contains messages in the Comma Separated Values (CSV)
format, one message per line
</Documentation>
Change the Name attribute to an appropriate value. Do not use spaces or tabs in the name.
The Direction="Input" attribute may require modification to Direction="Output" for an output adapter.
Specify SupportsGuaranteedDelivery="true" if yours is a Guaranteed Delivery adapter. See Implementing Guaranteed Processing for more information.
The ScreenName is the name displayed by Studio in the drop-down selection menu that you see when you attach an adapter. Use a name that users will understand. While multiple in-process adapters are able to display the same screen name, users will be unable to differentiate between identically displayed adapter screen names.
The Description and Documentation attributes provide summary and detailed information relevant to the adapter.
To invoke your C/C++ code, the Sybase CEP Engine needs to know the names of the Initialize(), Execute(), Shutdown(), and possibly Reconnect() functions and the name of the library file that contains those functions. These are provided by:
<LibraryName> sdk_adapter_lib </LibraryName> <InitializeFunction> my_input_adapter_initialize </InitializeFunction> <ExecuteFunction> my_input_adapter_execute </ExecuteFunction> <ShutdownFunction> my_input_adapter_shutdown </ShutdownFunction> <ReconnectFunction>my_input_adapter_reconnect</ReconnectFunction>
The sdk_adapter_lib is the name of the loadable library containing the three entry points. The library name does not contain a trailing ".dll" or ".so". This permits cross-platform loading of libraries that will be handled by the Sybase CEP Engine.
The external name of each of the adapter entry points specifies the name that Sybase CEP Engine will call for initialization, execution, shutdown, and reconnection (for Guaranteed Delivery only) of the adapter. The name must match the name in the C/C++ code that you wrote. The name must also be externalized within the library.
The parameters section is the next section of the ADL file.
Each parameter will be displayed on the adapter's Properties View in Sybase CEP Studio. The exact form of the display depends on each parameter's definition. An example of a parameters section is shown below.
<InstanceParameterDefinitions> <Parameter Name="Filename" xsi:type="xsi:string"> <Default>stock-trades.csv</Default> <Description>The file from which to read rows.</Description> <Required>false</Required> <ScreenName>Filename</ScreenName> <Documentation> The name of the file from which to read rows. </Documentation> <MultiLine>false</MultiLine> </Parameter> <Parameter Name="Port" xsi:type="xsi:integer"> <Default/> <Description>TCP port number of the message source</Description> <Required>true</Required> <ScreenName>Port</ScreenName> <Documentation>TCP port number of the message source</Documentation> <MultiLine>false</MultiLine> <Min>1</Min> <Max>65535</Max> </Parameter>
The Parameter attribute configures an individual parameter. There can be any number of parameters in an ADL file; the exact number depends on your needs. The Default, Description and Required attributes are mandatory for each parameter. The remaining attributes are optional.
The Name attribute is used by the C/C++ code to retrieve the displayed value of the parameter. Each parameter name must be unique within an ADL file.
The xsi:type attribute determines the data type of the parameter. See Printing a Parameter for a table that shows which xsi:type corresponds to each internal Sybase CEP datatype.
The Default attribute determines the default value of the parameter. This value gets displayed in Sybase CEP Studio on the initial display. When the value is modified, Sybase CEP Studio remembers the modified value so it does not have to be reset on subsequent Sybase CEP Studio invocations. The Default must be of the same data type as the xsi:name, otherwise Sybase CEP Studio will issue an error message. Notice that in this example Port does not have a default and the Required attribute is true, meaning you must enter a value.
The Description provides textual information for the "?" popup help message Sybase CEP Studio displays.
The Required attribute specifies whether it is absolutely necessary for you to provide a value for this parameter. If you provide a Default for a Required parameter, and do not modify the parameter, then the default will be used. If you blanks the input field of a Required parameter, Sybase CEP Studio will highlight the input field to indicate that you must input a value. An example of a possibly required parameter is a filename for an output adapter that writes to a file.
The ScreenName value gets displayed to the left of the input field. The ScreenName prompts you for inputting into the field.
The MultiLine attribute causes a larger rectangular display to appear on the adapter's Properties View in Sybase CEP Studio. This would be used for parameters requiring potentially lengthy input strings. An example is a database query that consumes several lines of input.
Numeric datatypes may use the Min and/or Max attributes. It is possible to have a Min without a Max and vice versa; these attributes are independent.