C API (Component Interface)
The SystemML Interface offers functionality such that a Process can manipulate its SystemML interfaces (input and output interfaces). The interface is accessed by sending Engine Events.
- User code will NOT generally have to call these events explicitly. Each binding provides wrapper functions for most of these events. See the documentation for your binding for more information.
Symbol hCaller IN
- This should always be set to the handle of the calling component, if possible. Failure to do so will raise an error in most events.
UINT32 flags IN
- None defined (must be zero).
Symbol type IN
- The Engine
Event being called.
- void* data IN/OUT
- The data associated with the event (can be NULL for some events).
Usually, just check the return value using the
S_ERROR macro. If it is an error, you can return it directly to the framework, ignoring its value, and the nature of the error will be reported when execution terminates. If not, you can assume it is a valid return value as specified by the interface function, and continue processing. More information follows, if you are curious.
- Many events in the interface require a pointer to a data structure to be passed in as
data. If this argument is
NULL to one of these events,
E_NULL_ARG is returned. Some events, in addition, will return
E_NULL_ARG when one or more fields of
- Many events require the caller to pass one or more handles to objects in fields of
data (and, at least,
hCaller to specify the calling component). One of the following errors will be raised if one of these handles is no good.
- Any event may return an error code that is not listed in the documentation, so you should test all return codes with the
macro. If you encounter an error, and either you don't recognise it or you don't want to check what it is, you should return the error code directly to the framework as the return code of your
event() function. Internal errors in the framework will, for instance, return unlisted error codes, which you will not be able to identify.
- Any function that does not return data in its return value will return
on successful completion.
- Many functions will return
E_SYSTEMML if the call cannot be completed given the current state of the interface being queried.