This section provides an introduction to in-process adapter API signatures, their purposes, and parameters.
These in-process adapter API signatures are defined in c8adapter_in_process.h.
Each adapter is executed in its own thread. initialize(), execute(), and shutdown() are always called from this thread.For input adapters, the will call the execute() function function as often as possible.
For output adapters, the Sybase CEP Engine will call the execute() function on a periodic basis. Check for message availability; there can be an arbitrary number of messages (0, 1, or more than 1) available for any single call of the execute() function. The output adapter is responsible for processing the messages and should then return control to the .
Parameters:
i_aptr: A pointer to the adapter object.
Returns: A pointer to the schema of this adapter.
The following GetParam() functions interface with the ADL files. Please refer to Adapter Definition Language for detailed descriptions of how to use ADL files. All the GetParam names are displayed in the adapter Properties View in Sybase CEP Studio and are configurable. Parameters can access the original string form as displayed in by calling C8AdapterGetParamString(). If you have additional data types C8AdapterGetParamString() is the appropriate function call. After obtaining the string, you can call one of the data conversion functions supplied by Sybase CEP.
The name string should be identical to the string provided in the ADL file. For instance, if the ADL file contains
<Parameter Name="TitleRow" xsi:type="xsi:boolean">
then the name should be TitleRow. It is important to match the case. Using an unknown name results in the default value being returned.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
name: The name of the adapter property whose value you would like to retrieve.
default: The default value to return if the adapter property is not set in the project or the ADL file.
Returns: The value of the adapter property. If there is no adapter property with that name in the project, returns the default value for the property as specified in the ADL file. If the parameter is not defined in either place, returns the value passed as default.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
name: The name of the adapter property whose value you would like to retrieve.
default: The default value to return if the adapter property is not set in the project or the ADL file.
Returns: The value of the adapter property. If there is no adapter property with that name in the project, returns the default value for the property as specified in the ADL file. If the parameter is not defined in either place, returns the value passed as default.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
name: The name of the adapter property whose value you would like to retrieve.
default: The default value to return if the adapter property is not set in the project or the ADL file.
Returns: The value of the adapter property. If there is no adapter property with that name in the project, returns the default value for the property as specified in the ADL file. If the parameter is not defined in either place, returns the value passed as default.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
name: The name of the adapter property whose value you would like to retrieve.
default: The default value to return if the adapter property is not set in the project or the ADL file.
Returns: The value of the adapter property. If there is no adapter property with that name in the project, returns the default value for the property as specified in the ADL file. If the parameter is not defined in either place, returns the value passed as default.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
name: The name of the adapter property whose value you would like to retrieve.
default: The default value to return if the adapter property is not set in the project or the ADL file.
Returns: The value of the adapter property. If there is no adapter property with that name in the project, returns the default value for the property as specified in the ADL file. If the parameter is not defined in either place, returns the value passed as default.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
name: The name of the adapter property whose value you would like to retrieve.
default: The default value to return if the adapter property is not set in the project or the ADL file.
Returns: The value of the adapter property. If there is no adapter property with that name in the project, returns the default value for the property as specified in the ADL file. If the parameter is not defined in either place, returns the value passed as default.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
name: The name of the adapter property whose value you would like to retrieve.
default: The default value to return if the adapter property is not set in the project or the ADL file.
Returns: A pointer to the value of the specified adapter property. If there is no adapter property with that name in the project, returns the default value for the property as specified in the ADL file. If the parameter is not defined in either place, returns the value passed as default.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
name: The name of the adapter property whose value you would like to retrieve.
default: The default value to return if the adapter property is not set in the project or the ADL file.
Returns: A pointer to the value of the specified adapter property. If there is no adapter property with that name in the project, returns the default value for the property as specified in the ADL file. If the parameter is not defined in either place, returns the value passed as default.
The BLOB values used by this function are raw BLOBs as opposed to hex strings or base64 strings. For an explanation of raw vs. hex string vs. base64 string formats, see Data Types and Subroutines for UDFs and In-process Adapters.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
name: The name of the adapter property whose value you would like to retrieve.
default: The default value to return if the adapter property is not set in the project or the ADL file.
Returns: A pointer to the value of the specified adapter property. If there is no adapter property with that name in the project, returns the default value for the property as specified in the ADL file. If the parameter is not defined in either place, returns the value passed as default.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
Returns: C8_TRUE if the ADL file for this adapter has the SupportsGuranteedDelivery attribute set to "true", otherwise C8_FALSE.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
session_id: The ID of the session being established. The ID must be unique.
timeout: How long to wait for the connection to be made before timing out.
Returns: C8_TRUE on success, C8_FALSE if the timeout is reached or an error occurs.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
Returns: The ID of the last batch processed.
Parameters:
adapter: A pointer to the C8Adapter object that stores information about this instance of the adapter.
i_batch_id: The batch ID.
Returns: Nothing.
When you have finished processing the message, call C8MessageDestroy( to release message resources. The user-written execute() function should continue to process messages as long as C8AdapterReceiveMessage() provides them. When a null is returned from C8AdapterReceiveMessage(), the execute() function return to Sybase CEP Server.
This function works only for output adapters.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
Returns: A pointer to the message received by the adapter. Returns NULL if there are no new messages.
When you finish processing the message, call C8MessageDestroy() to release message resources. The user-written execute() function continues to process messages as long as C8AdapterReceiveMessageWait() (or C8AdapterReceiveMessage()) provides them. When a null is returned from C8AdapterReceiveMessageWait(), the execute() function returns to Sybase CEP Server.
This function works only for output adapters.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
interval: The maximum number of microseconds to wait for a message.
Returns: A pointer to the message received by the adapter. Returns NULL if there are no new messages.
Parameters:
adapter: A pointer to the C8Adapter object that stores information about this instance of the adapter.
i_timeout: How long to wait for the batch of messages before timing out.
Returns: A pointer to the batch of messages. Returns NULL if there are no new messages
Parameters:
adapter_ptr : A pointer to the C8Adapter object that stores information about this instance of the adapter.
msg_ptr: The message to send to the server.
Returns: Nothing.
The C8AdapterSendMessage() call does not send messages instantly. Messages are sent at the end of the execute function or during a C8AdapterSleep() call. To force the adapter to send all messages that have not yet been sent, call this function.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
Returns: Nothing.
Parameters:
adapter: A pointer to the C8Adapter object that stores information about this instance of the adapter.
i_messages: The array of messages to send to the server.
i_num_messages: The number of messages in i_messages.
i_batch_id: The ID of this batch of messages.
i_timeout: How long to wait for the messages to be processed.
Returns: C8_TRUE on success; C8_FALSE if the timeout is reached or an error occurs.
After you send a particular message pointer, you can not "re-use" that message pointer; in other words, you can not put new values into it and send it again. You must use C8MessageDestroy() to dispose of the message pointer and then use C8MessageCreate() to create a new message pointer when you want to send another message.
After you send a msg_ptr, you can not put new values into it and send it again. Use C8MessageDestroy() to dispose of the msg_ptr and then use C8MessageCreate() to create a new msg_ptr when you want to send another message.
Parameters:
adapter: A pointer to the C8Adapter object.
Returns: A copy of the user credentials, or NULL if the credentials aren't set or an error occurs. You must call C8UserCredentialsDestroy to free the memory when you are finished with the credentials.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
Returns: A string that represents the path name of the adapter. This is the CCL or HTTP path name of the instance of the adapter that is running. This is not the pathname of the library file containing the adapter code.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
Returns: The accelerated playback rate. A rate of 1.0 is "normal" (non-accelerated).
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
Returns: C8_TRUE if Persistence is on; C8_FALSE otherwise.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
Returns: C8_TRUE if the server needs the adapter to return control to the server as soon as possible; C8_FALSE otherwise.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
Returns: C8_TRUE if the adapter is connected; C8_FALSE otherwise.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
Returns: Nothing.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
Returns: Nothing.
The header file c8types.h contains definitions that can be convenient for specifying durations; for example, to delay three seconds, use 3*C8PerSecond. Small intervals are probably inappropriate depending on your CPU speed, system clock resolution, and system loading. In general, on many systems, resolutions less than 100 milliseconds are very imprecise. Even for larger values, the actual length of the sleep is not exactly what was specified.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
us_delay: The number of microseconds to delay.
Returns: Nothing.
A value of 0 means that the caller will not sleep at all, but will call the execute() function again as soon as the previous call to execute() has returned.
The header file c8types.h contains definitions that can be convenient for specifying durations; for example, to delay three seconds, use 3*C8PerSecond.
As with any sleep-related function, the duration depends on how heavily loaded the system is and the granularity of the system clock. The actual sleep is only an approximation of the amount you request. The actual length of the sleep is likely to be longer than requested if you request a time smaller than the finest granularity of the system clock, or if the system is heavily loaded. The length of the sleep can be less than the amount of time requested if there is a change in server state (for example, a shutdown) or if the adapter is an output adapter and data is available for that output adapter.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
us_delay: The number of microseconds to delay.
Returns: Nothing.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
Returns: A value indicating how long the server sleeps between calls to the adapter's execute() function.
In the shutdown() function function, the session state should be set to a Null pointer.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
session_state: A pointer to the "state" information that the user would like to be able to see the next time that the adapter's execute() function is called.
Returns: Nothing.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
Returns: A pointer to session state information. The exact structure of this information is defined by the you, so the function returns a pointer to the memory without "interpreting" that memory in any way.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
o_data_size: The number of bytes in the user-defined block of memory that was persisted.
Returns: A pointer to the stored information. The exact structure of this information is defined by the you; so thus the function simply returns a pointer to the memory without "interpreting" that memory in any way. Do not free the pointer returned by this function.
Only one piece of user memory can be made persistent at a time. If you call this function more than once, then only the pointer passed in the most recent call to C8AdapterSetPersistentState() will be returned when you call C8AdapterGetPersistentState(). If you need to expand the amount of memory you want to store persistently, use the C8Realloc() function to get a new (larger) piece of memory and then call C8AdapterSetPersistentState() with the address of that new piece of memory.
The memory you make persistent is normally memory that you yourself have allocated (for example, via C8Malloc()) and therefore you must deallocate via C8Free() when you are done with it, If not done beforehand, deallocate persistent memory when the adapter's shutdown() function is called. If this memory contains any structures that must be cleaned up (for example, pointers to other memory that must be deallocated, or file handles to files that must be closed, then make sure that you clean those up before you deallocate this memory.
Parameters:
adapter_ptr: A pointer to the C8Adapter object that stores information about this instance of the adapter.
data: A pointer to the block of memory containing the bytes to be stored.
data_size: The number of bytes of data stored.
Returns: Nothing.
Below is sample pseudo code showing how C8AdapterSetPersistentState() and related functions are typically used.
initialize() { pMem = C8Malloc(...); ... C8AdapterSetPersistentState(..., pMem, ...); ... } execute() { pMem = C8AdapterGetPersistentState(...); ... }
Remember that if the allocated memory itself contains pointers or handles, those must be cleaned up too.