Overview
C API (Component Interface)
struct EngineEvent { Symbol hCaller; UINT32 flags; Symbol type; void* data; }; Symbol brahms_engineEvent(struct EngineEvent* data);

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.

Notes
  • 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.

Fields

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).

Return Values

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 data is NULL.
  • 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 S_ERROR 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 C_OK on successful completion.
  • Many functions will return E_SYSTEMML if the call cannot be completed given the current state of the interface being queried.