Overview
C API (Component Interface)
struct TransportDataPeriodic { struct SampleRate sampleRate; }; struct EventAddPort { UINT32 flags; Symbol hSet; struct ComponentSpec spec; struct HandledEvent* handledEvent; const char* name; UINT32 index; Symbol hPortToCopy; Symbol transportProtocol; void* transportData; };

Add a Port to a Set on the output interface of a Process, either by specifying the component specification (spec) or by passing an existing port from which the Data object is to be copied (hPortToCopy).

Component Release Versioning

Future releases of a given Data class (Component) must continue to offer the previously published interface (i.e. that offered by earlier releases). However, they may extend that interface. When creating the Port, you specify the minimum release which offers sufficient interface for your purposes. There is no harm in specifying the latest interface, since the Data objects created must still offer earlier interfaces, and thus can still be read by older Processes that are connected to your output Ports. In fact, BRAHMS will (under normal conditions) return a Data object that offers the latest interface, even if you ask for an older interface. See notes at ComponentVersion, and compare with the recommendations for use of assertClass.

If you pass a Port to be copied, the Data object on the new Port will support at least the interface supported by the copied object.

Fields

UINT32 flags IN
None defined (must be zero).
Symbol hSet IN
A handle to the Set to which a Port is to be added. Can also be a handle to a Process, in which case the default output set of that Process is targeted.
ComponentSpec spec IN
The SystemML class and release that is required to be supported by the Data that the new Port will output. The actual Data object created may not be exactly that specified, but it will support the requested interface. If hPortToCopy is not S_NULL, spec.cls must be NULL.
HandledEvent* handledEvent IN
If not NULL, the event will be attached to the port.
const char* name IN
If not NULL, the new Port will be named as specified.
UINT32 index IN
If not equal to INDEX_UNSPECIFIED, the new Port will be created at the specified index on the specified set (not currently implemented, so index must be equal to INDEX_UNSPECIFIED).
Symbol hPortToCopy IN
An input port containing a template Data object which will be copied to generate the Data object that the new Port will output. If spec.cls is not NULL, must be S_NULL.
Symbol transportProtocol IN
Currently, must be C_TRANSPORT_PERIODIC.
void* transportData IN
Currently, must point to a TransportDataPeriodic object. If NULL, or if transportData->sampleRate.num is zero, the sample rate is taken from the process.

Return Values

See also SystemML Interface Return Values.

  • A handle to the new Port.
  • E_SML if the specified Set is on the input interface.
  • E_INVALID_ARG if cls and hData are both non-NULL.
  • E_NULL_ARG if cls and hData are both NULL.

Example

Taken from std/data/numeric.

C++ Source Code (against 1199)
void create(Symbol hComponent) { TransportDataPeriodic periodic; periodic.sampleRate = sampleRate; EventAddPort apdata; apdata.flags = 0; apdata.hSet = hSet ? hSet : hComponent; // hComponent means use the default set apdata.spec.cls = "std/2009/data/numeric"; apdata.spec.release = 0; apdata.handledEvent = &hev; apdata.name = m_portName.length() ? m_portName.c_str() : NULL; apdata.index = INDEX_UNDEFINED; apdata.hPortToCopy = S_NULL; apdata.transportProtocol = C_TRANSPORT_PERIODIC; apdata.transportData = (void*) &periodic; EngineEvent event; event.hCaller = hComponent; event.flags = 0; event.type = ENGINE_EVENT_ADD_PORT; event.data = &apdata; hPort = brahms_engineEvent(&event); if (S_ERROR(hPort)) throw hPort; }