Overview

iif and oif, object-oriented bindings to your process's SystemML input and output interfaces which are maintained by the framework.

C++ API (1199)
class SystemMLInterface;

This interface facilitates interaction between the Process and the wider System (other Processes, via Links from their interfaces).

There are two SystemMLInterface interfaces in the Process, one (i)nput (i)nter(f)ace (iif) and one (o)utput (i)nter(f)ace (oif). Each holds one or more "Sets" of "Ports". To begin with, only the Default Set exists on each interface. A Process may create additional Sets in either interface while servicing EVENT_STATE_SET. The Engine may add Ports to Sets in iif by connecting inputs (interleaved with calls to EVENT_INIT_CONNECT). The Process may add Ports to Sets in oif by creating outputs (whilst servicing EVENT_INIT_CONNECT).

Since the actual Data objects on the Ports change in a way that is hidden from the Process as the Engine marshals data, a Process may not usefully hold on to a Handle to an actual Data object retrieved from an interface. Instead, the process can obtain a Handle to a Port (which remains valid for the whole execution), and then resolve that Port Handle into a Data object when it needs access using getData(). Such resolved Data objects are only valid until the Process returns from servicing the event in which they were resolved. Typically, a Process will obtain Port Handles during EVENT_INIT_CONNECT and resolve them to Data Handles during EVENT_RUN_SERVICE. In addition, the Process may resolve Port Handles to Data Handles during EVENT_INIT_CONNECT, in order to validate their structure (input ports) or set their structure (output ports).

Warnings
  • The most common difficulty encountered by BRAHMS users so far is the relationship between empty Ports, full Ports, Due Data, and timing logic. Process developers should make sure they understand what is going on, here. See Servicing, in the Timely Aside section, and then review this reference documentation.

Interface

Set and Port Handles are valid indefinitely; Data Handles are valid only in the context of the event in which they were obtained.

SystemML Interface

Symbol getDefaultSet()
Get a Handle to the Default Set.
Symbol getSet(const char* name)
Get a Handle to the Set with the specified name.

SystemML Set

UINT32 getNumberOfPorts(Symbol hSet)
Return the number of Ports on the specified Set.
const char* getSetName(Symbol hSet)
Return the name of the specified Set.

SystemML Default Set

UINT32 getNumberOfPorts()
Return the number of Ports on the Default Set.

Legacy Extensions

Warnings
  • That concludes the current SystemML interface. It is strongly recommended that you pursue further interaction with Ports through the interfaces provided by individual data classes (see, for example, std/data/numeric). The remainder of this interface is still offered, and may be used by legacy code. It is not exactly deprecated, but the associated interfaces provided by the Standard Library to allow you to interact with the Data objects recovered is deprecated, so it has been rendered superfluous. This part of the interface is only available if COMPONENT_INTERFACE_REVISION is defined to 2451. See Quick Start (1199) for an insight into current best practice.

SystemML Set

Symbol addPort(Symbol hSet, const char* cls, UINT16 release)
Add a Port to the specified Set, loading it with a Data object specified by SystemML Class and Release.
Symbol addPort(Symbol hSet, Symbol copyThis)
Add a Port to the specified Set, loading it with a Data object specified as a duplicate of the passed Data object (particularly useful if your Process wants to create an output with the same structure as one of its inputs).
Symbol getPort(Symbol hSet, std::string name)
Get a Port from the specified Set, by name (raise E_NOT_FOUND if port is not found).
Symbol getPortOrNull(Symbol hSet, std::string name)
Get a Port from the specified Set, by name (return S_NULL if port is not found).
Symbol getPort(Symbol hSet, UINT32 index)
Get a Port from the specified Set, by index (raise E_SML if index is out of range).

SystemML Default Set

Symbol addPort(const char* cls, UINT16 release)
Add a Port to the Default Set, loading it with a Data object specified by SystemML Class and Release.
Symbol addPort(Symbol copyThis)
Add a Port to the Default Set, loading it with a Data object specified as a duplicate of the passed Data object (particularly useful if your Process wants to create an output with the same structure as one of its inputs).
Symbol getPort(std::string name)
Get a Port from the Default Set, by name (raise E_NOT_FOUND if port is not found).
Symbol getPortOrNull(std::string name)
Get a Port from the Default Set, by name (return S_NULL if port is not found).
Symbol getPort(UINT32 index)
Get a Port from the Default Set, by index (raise E_SML if index is out of range).

SystemML Port

const char* getPortName(Symbol hPort)
Return the name of the specified Port.
UINT32 getPortFlags(Symbol hPort)
Return the flags of the specified Port.
void setPortName(Symbol hPort, const char* portName)
Set the name of the specified Port.
void setPortSampleRate(Symbol hPort, SampleRate sampleRate)
Set the Sample Rate of the specified Port.
Symbol getData(Symbol hPort)
Retrieve a Handle to the Data object on the specified Port (raise E_PORT_EMPTY if port is empty).
Symbol getDataOrNull(Symbol hPort)
Retrieve a Handle to the Data object on the specified Port (return S_NULL if port is empty).