The following functions are called from within a C/C++ application to interface with RT-LAB running on a target processor.

RTActivatePrintBuffer

Group

Orchestra

Description

WARNING: This function is obsolete.

Activates the print buffer used to print data using the OpalPrint() function.

Note: This function MUST be called before calling OpalPrint().

Synopsis

RTAPIReturn_t RTActivatePrintBuffer(void);

Input

None

Output

None

Return Value

See RTAPIReturn_t error code

Example

None

Related Items

RTDeactivatePrintBuffer

Library and Header

	Windows	Redhawk
Static Library	libOpalOrchestra.lib	libOpalOrchestra.a
Dynamic Library	-	-
Header File	RTAPI.h	RTAPI.h

RTConnect

Group

Orchestra

Description

Attaches an External Component to the memory segment corresponding to a domain.

If the connection fails, the calling process goes to sleep and attempts to connect repeatedly until the timeout delay expires.

Synopsis

RTAPIReturn_t RTConnect(const char *domainName, unsigned int timeout);

Input

domainName	The name of the domain to which the connection is requested. This domain must exist in the DDF read by an RT-LAB subsystem.
timeout	The duration after which a failed connection attempt times out, in seconds.

Output

None

Return Value

See RTAPIReturn_t error code

Example

None

Related Items

RTDisconnect

Library and Header

	Windows	Redhawk
Static Library	libOpalOrchestra.lib	libOpalOrchestra.a
Dynamic Library	-	-
Header File	RTAPI.h	RTAPI.h

RTDeactivatePrintBuffer

Group

Orchestra

Description

WARNING: This function is obsolete.

Deactivates the print buffer used to print data using the OpalPrint() function.

Synopsis

RTAPIReturn_t RTDeactivatePrintBuffer(void);

Input

None

Output

None

Return Value

See RTAPIReturn_t error code

Example

None

Related Items

RTActivatePrintBuffer

Library and Header

	Windows	Redhawk
Static Library	libOpalOrchestra.lib	libOpalOrchestra.a
Dynamic Library	-	-
Header File	RTAPI.h	RTAPI.h

RTDisconnect

Group

Orchestra

Description

Detaches the current process from the shared memory segment corresponding to a domain.

Synopsis

RTAPIReturn_t RTDisconnect(void);

Input

None

Output

None

Return Value

See RTAPIReturn_t code

Example

None

Related Items

RTConnect

Library and Header

	Windows	Redhawk
Static Library	libOpalOrchestra.lib	libOpalOrchestra.a
Dynamic Library	-	-
Header File	RTAPI.h	RTAPI.h

RTGetConnectionKey

Group

Orchestra

Description

Gets the current connection key.

Synopsis

RTAPIReturn_t RTGetConnectionKey(unsigned int *key);

Input

None

Output

key: Key to a connection

Return Value

See RTAPIReturn_t error code

Example

None

Related Items

RTNewConnectionKey, RTSetConnectionKey

Library and Header

	Windows	Redhawk
Static Library	libOpalOrchestra.lib	libOpalOrchestra.a
Dynamic Library	-	-
Header File	RTAPI.h	RTAPI.h

RTGetErrorMessage

Group

Orchestra

Description

Retrieves the text description of an RTAPI error.

Synopsis

const char* RTGetErrorMessage(RTAPIReturn_t returnCode);

Input

returnCode: The RTAPIReturn_t error code resturned by a previous RTAPI function call.

Output

None

Return Value

A pointer to a const string that contains the text description of the error.

Example

None

Related Items

RTAPIReturn_t

Library and Header

	Windows	Redhawk
Static Library	libOpalOrchestra.lib	libOpalOrchestra.a
Dynamic Library	-	-
Header File	RTAPI.h	RTAPI.h

RTGetInfoForItem

Group

Orchestra

Description

Retrieves data item information from a locally kept offset table. This item must exist in the DDF read by an RT-LAB subsystem.

Synopsis

RTAPIReturn_t RTGetInfoForItem(const char *itemName,

size_t*pTypeSize, unsigned short *pLength);

Input

itemName: The name of the item for which the info is retrieved.
pTypeSize: Data item type size in bytes.
pLength: Array length of the data item, i.e. the number of times the type is repeated.

Output

None

Return Value

See RTAPIReturn_t error code

Example

None

Related Items

RTGetKeyForItem

Library and Header

	Windows	Redhawk
Static Library	libOpalOrchestra.lib	libOpalOrchestra.a
Dynamic Library	-	-
Header File	RTAPI.h	RTAPI.h

RTGetKeyForItem

Group

Orchestra

Description

Retrieves the index of a data item in a locally kept offset table. This item name must exist in the DDF read by an RT-LAB subsystem. The index is used to speed up data access.

Synopsis

RTAPIReturn_t RTGetKeyForItem(const char *itemName,

unsigned short *pKey);

Input

itemName: The name of the item for which the key is retrieved.
pKey: The key corresponding to the data item.

Output

None

Return Value

See RTAPIReturn_t error code

Example

None

Related Items

RTPublishByKey, RTSubscribeByKey

Library and Header

	Windows	Redhawk
Static Library	libOpalOrchestra.lib	libOpalOrchestra.a
Dynamic Library	-	-
Header File	RTAPI.h	RTAPI.h

RTNewConnectionKey

Group

Orchestra

Description

Creates a new connection key. Multiple connection keys are used to handle multiple connections to multiple framework.

This function must be called before any configuration function like RTSetupRefMemRemoteConnection and before RTConnect

Synopsis

RTAPIReturn_t RTNewConnectionKey(unsigned int *key);

Input

None

Output

key: Key to be set to use this connection.

Return Value

See RTAPIReturn_t error code

Example

None

Related Items

RTSetConnectionKey, RTGetConnectionKey

Library and Header

	Windows	Redhawk
Static Library	libOpalOrchestra.lib	libOpalOrchestra.a
Dynamic Library	-	-
Header File	RTAPI.h	RTAPI.h

RTPublish

Group

Orchestra

Description

Writes data to the shared memory segment attached to the current process.

To ensure proper synchronization between a publisher and a subscriber exchanging data through a domain, a call to RTPublish() MUST appear between a call to RTPublishLock() and a call to RTPublishUnlock().

Synopsis

RTAPIReturn_t RTPublish(unsigned int num, ...);

Input

num: The number of data items that are written to the memory segment. At least one (name, value) pair is required.

Output

None

Return Value

See RTAPIReturn_t error code

Example

RTPublish(1, "item01", &value01);
RTPublish(2, "item01", &value01, "item02", &value02);

Related Items

RTSubscribe, RTPublishLock, RTPublishUnlock

Library and Header

	Windows	Redhawk
Static Library	libOpalOrchestra.lib	libOpalOrchestra.a
Dynamic Library	-	-
Header File	RTAPI.h	RTAPI.h

RTPublishByKey

Group

Orchestra

Description

Writes data to the shared memory segment attached to the current process. The key corresponding to the item of interest is obtained by calling RTGetKeyForItem().

Note: To ensure proper synchronization between a publisher and a subscriber exchanging data through a domain, a call to RTPublish() MUST appear between a call to RTPublishLock() and a call to RTPublishUnlock().

Synopsis

RTAPIReturn_t RTPublishByKey(unsigned short key, void *value);

Input

key: Index in the offset table.
value: The value to publish.

Output

None

Return Value

See RTAPIReturn_t error code

Example

None

Related Items

RTGetKeyForItem

Library and Header

	Windows	Redhawk
Static Library	libOpalOrchestra.lib	libOpalOrchestra.a
Dynamic Library	-	-
Header File	RTAPI.h	RTAPI.h

RTPublishLock

Group

Orchestra

Description

Sets a publish (write) lock for synchronous access to a domain.

Synopsis

RTAPIReturn_t RTPublishLock(void);

Input

None

Output

None

Return Value

See RTAPIReturn_t error code

Example

None

Related Items

RTPublishUnlock

Library and Header

	Windows	Redhawk
Static Library	libOpalOrchestra.lib	libOpalOrchestra.a
Dynamic Library	-	-
Header File	RTAPI.h	RTAPI.h

RTPublishUnlock

Group

Orchestra

Description

Releases a publish (write) lock.

Synopsis

RTAPIReturn_t RTPublishUnlock(void);

Input

None

Output

None

Return Value

See RTAPIReturn_t error code

Example

None

Related Items

RTPublishLock

Library and Header

	Windows	Redhawk
Static Library	libOpalOrchestra.lib	libOpalOrchestra.a
Dynamic Library	-	-
Header File	RTAPI.h	RTAPI.h

RTSetConnectionKey

Group

Orchestra

Description

Sets a connection key created by RTNewConnectionKey. Any function called after this function will use this connection key. This function has to be called again to set a new connection.

Synopsis

RTAPIReturn_t RTSetConnectionKey(unsigned int key);

Input

key: Key to a connection

Output

None

Return Value

See RTAPIReturn_t error code

Example

None

Related Items

RTNewConnectionKey, RTGetConnectionKey

Library and Header

	Windows	Redhawk
Static Library	libOpalOrchestra.lib	libOpalOrchestra.a
Dynamic Library	-	-
Header File	RTAPI.h	RTAPI.h

RTSetupRefMemRemoteConnection

Group

Orchestra

Description

This function is used to set up a remote connection to an RT-LAB framework by means of a reflective memory card.

Synopsis

RTAPIReturn_t RTSetupRefMemRemoteConnection(const char *cardName, unsigned int pciIndex);

Input

cardName: The name of the reflective memory card used to remotely connect to the framework.
pciIndex: The index assigned to the card when the PCI bus is scanned. If there is only one memory card present, this index must be zero.

Output

None

Return Value

See RTAPIReturn_t error code

Example

None

Related Items

RTConnect

Library and Header

	Windows	Redhawk
Static Library	libOpalOrchestra.lib	libOpalOrchestra.a
Dynamic Library	-	-
Header File	RTAPI.h	RTAPI.h

RTSubscribe

Group

Orchestra

Description

Reads from the shared memory segment attached to the current process.

To ensure proper synchronization between a publisher and a subscriber exchanging data through a domain, a call to RTSubscribe() MUST appear between a call to RTSubscribeLock() and a call to RTSubscribeUnlock().

Synopsis

RTAPIReturn_t RTSubscribe(unsigned int num, ...);

Input

num: The number of data items that are read from the memory segment. At least one (name, value) pair is required.

Output

value: Data value of the item read from the domain.

Return Value

See RTAPIReturn_t error code

Example

RTSubscribe(1, "item01", &value01);

RTSubscribe(2, "item01", &value01, "item02", &value02);

Related Items

RTPublish, RTSubscribeLock, RTSubscribeUnlock

Library and Header

	Windows	Redhawk
Static Library	libOpalOrchestra.lib	libOpalOrchestra.a
Dynamic Library	-	-
Header File	RTAPI.h	RTAPI.h

RTSubscribeByKey

Group

Orchestra

Description

Reads from the shared memory segment attached to the current process. The key corresponding to the item of interest is obtained by calling RTGetKeyForItem().

Note: To ensure proper synchronization between a publisher and a subscriber exchanging data through a domain, a call to RTPublish() MUST appear between a call to RTPublishLock() and a call to RTPublishUnlock().

Synopsis

RTAPIReturn_t RTSubscribeByKey(unsigned short key, void *value);

Input

key: Index in the offset table.
value: The subscribed value.

Output

None

Return Value

See RTAPIReturn_t error code

Example

None

Related Items

RTGetKeyForItem

Library and Header

	Windows	Redhawk
Static Library	libOpalOrchestra.lib	libOpalOrchestra.a
Dynamic Library	-	-
Header File	RTAPI.h	RTAPI.h

RTSubscribeLock

Group

Orchestra

Description

Sets a subscribe (read) lock for synchronous access to a domain.

Synopsis

RTAPIReturn_t RTSubscribeLock(void);

Input

None

Output

None

Return Value

See RTAPIReturn_t error code

Example

None

Related Items

RTSubscribeUnlock

Library and Header

	Windows	Redhawk
Static Library	libOpalOrchestra.lib	libOpalOrchestra.a
Dynamic Library	-	-
Header File	RTAPI.h	RTAPI.h

RTSubscribeUnlock

Group

Orchestra

Description

Releases a subscribe (read) lock.

Synopsis

RTAPIReturn_t RTSubscribeUnlock(void);

Input

None

Output

None

Return Value

See RTAPIReturn_t error code

Example

None

Related Items

RTSubscribeLock

Library and Header

	Windows	Redhawk
Static Library	libOpalOrchestra.lib	libOpalOrchestra.a
Dynamic Library	-	-
Header File	RTAPI.h	RTAPI.h

RTAPIReturn_t

Description
Error codes returned by the Orchestra RTAPI - A text version is obtained by calling the
function RTGetErrorMessage().
Usage

typedef enum{
RTAPI_SUCCESS = 0,
RTAPI_CONNECT_FAILED_TIMEOUT,
RTAPI_CONNECT_FAILED_SHARED_MEMORY_FAILURE,
RTAPI_CONNECT_FAILED_INVALID_DOMAIN_NAME,
RTAPI_CONNECT_FAILED_INVALID_VERSION,
RTAPI_CONNECT_FAILED_ALREADY_CONNECTED,
RTAPI_CONNECT_FAILED_ANOTHER_SYNCHRONOUS_CONNECTION_EXISTS,
RTAPI_CONNECT_FAILED_INVALID_CARD,
RTAPI_CONNECT_FAILED_CARD_NOT_FOUND,
RTAPI_CONNECT_FAILED_CARD_INITIALIZATION_ERROR,
RTAPI_CONNECT_FAILED_CARD_INIT_VISA_SYSTEM_ERROR,
RTAPI_CONNECT_FAILED_CARD_FIND_PCI_RESSOURCE_ERROR,
RTAPI_CONNECT_FAILED_CARD_OPEN_PCI_RESSOURCE_ERROR,
RTAPI_CONNECT_FAILED_CARD_MAPPING_PCI_RESSOURCE_ERROR,
RTAPI_CONNECT_FAILED_CARD_ENABLE_PCI_INTERRUPT_ERROR,
RTAPI_CONNECT_FAILED_MEMORY_ALLOCATION_ERROR,
RTAPI_CONNECT_NO_CONNECTION_AVAILABLE,
RTAPI_DISCONNECT_FAILED_NOT_CONNECTED,
RTAPI_PUBLISH_FAILED_NOT_CONNECTED,
RTAPI_PUBLISH_FAILED_RTLAB_SUBSYSTEM_UNMAPPED,
RTAPI_PUBLISH_FAILED_INVALID_ITEM_LIST,
RTAPI_PUBLISH_FAILED_INVALID_KEY,
RTAPI_PUBLISH_FAILED_NEED_SUBSCRIBE_FIRST,
RTAPI_PUBLISH_FAILED_NO_MULTIPLE_PUBLISHERS_ALLOWED,
RTAPI_SUBSCRIBE_FAILED_NOT_CONNECTED,
RTAPI_SUBSCRIBE_FAILED_RTLAB_SUBSYSTEM_UNMAPPED,
RTAPI_SUBSCRIBE_FAILED_NEED_PUBLISH_FIRST,
RTAPI_SUBSCRIBE_FAILED_INVALID_ITEM_LIST,
RTAPI_SUBSCRIBE_FAILED_INVALID_KEY,
RTAPI_GETKEY_FAILED_INVALID_ITEM_NAME,
RTAPI_GETINFO_FAILED_INVALID_ITEM_NAME,
RTLOCK_FAILED_NOT_CONNECTED,
RTLOCK_FAILED_TIMEOUT,
RTAPI_RFM_WRITE_ERROR,
RTAPI_RFM_READ_ERROR,
RTACTIVATEPRINTBUFFER_FAILED_NOT_CONNECTED,
RTACTIVATEPRINTBUFFER_FAILED_COULD_NOT_ATTACH_TO_BUFFER,
RTDEACTIVATEPRINTBUFFER_FAILED_NOT_CONNECTED,
RTAPI_UNKNOWN_ERROR
} RTAPIReturn_t;

Elements

RTAPI_SUCCESS (0) Function call successful.
RTAPI_CONNECT_FAILED_TIMEOUT (1) The memory segment is not accessible.
RTAPI_CONNECT_FAILED_SHARED_MEMORY_FAILURE (2) Could not attach to the shared memory
segment.
RTAPI_CONNECT_FAILED_INVALID_DOMAIN_NAME (3) Domain name argument is not defined in the
DDF.
RTAPI_CONNECT_FAILED_INVALID_VERSION (4) Invalid version between proxy and external
component.
RTAPI_CONNECT_FAILED_ALREADY_CONNECTED (5) Connection has already been established.
RTAPI_CONNECT_FAILED_ANOTHER_SYNCHRONOUS_CONNECTION_EXISTS (6) Another simulation component has already
established a synchronous connection.
RTAPI_CONNECT_FAILED_INVALID_CARD (7) Invalid or unsupported reflective memory
card name.
RTAPI_CONNECT_FAILED_CARD_NOT_FOUND (8) Reflective memory card could not be
detected.
RTAPI_CONNECT_FAILED_CARD_INITIALIZATION_ERROR (9) Reflective memory card could not be
initialized.
RTAPI_CONNECT_FAILED_CARD_INIT_VISA_SYSTEM_ERROR (10) Failed to open VISA system.
RTAPI_CONNECT_FAILED_CARD_FIND_PCI_RESSOURCE_ERROR (11) Failed to find RFM card in VISA PCI resources.
RTAPI_CONNECT_FAILED_CARD_OPEN_PCI_RESSOURCE_ERROR (12) Error during initialization of PCI RFM card.
RTAPI_CONNECT_FAILED_CARD_MAPPING_PCI_RESSOURCE_ERROR (13) Error during memory mapping of RFM card.
RTAPI_CONNECT_FAILED_CARD_ENABLE_PCI_INTERRUPT_ERROR (14) Failed to enabling interrupts on RFM card.
RTAPI_CONNECT_FAILED_MEMORY_ALLOCATION_ERROR (15) Error to allocate memory while connecting.
RTAPI_CONNECT_NO_CONNECTION_AVAILABLE (16) No more connection to proxy is available (no
more connection key).
RTAPI_DISCONNECT_FAILED_NOT_CONNECTED (17) Connection has not previously been
established.
RTAPI_PUBLISH_FAILED_NOT_CONNECTED (18) Connection has not been previously
established.
RTAPI_PUBLISH_FAILED_RTLAB_SUBSYSTEM_UNMAPPED (19) Connection to the Orchestra framework has
been lost.
RTAPI_PUBLISH_FAILED_INVALID_ITEM_LIST (20) Invalid number of items, or invalid item
name.
RTAPI_PUBLISH_FAILED_INVALID_KEY (21) Invalid item key.
RTAPI_PUBLISH_FAILED_NEED_SUBSCRIBE_FIRST (22) Connected simulation component doesn’t
have states, cannot publish frst.
RTAPI_PUBLISH_FAILED_NO_MULTIPLE_PUBLISHERS_ALLOWED (23) The Quality Of Service attributes for the
current domain indicate that only one
publisher is allower.
RTAPI_SUBSCRIBE_FAILED_NOT_CONNECTED (24) Connection has not been previously
established.
RTAPI_SUBSCRIBE_FAILED_RTLAB_SUBSYSTEM_UNMAPPED (25) Connection to the Orchestra framework has
been lost.
RTAPI_SUBSCRIBE_FAILED_NEED_PUBLISH_FIRST (26) Connected simulation component has states,
therefor it cannot subscribe frst.
RTAPI_SUBSCRIBE_FAILED_INVALID_ITEM_LIST (27) Invalid number of items, or invalid item
name.
RTAPI_SUBSCRIBE_FAILED_INVALID_KEY (28) Invalid item key.
RTAPI_GETKEY_FAILED_INVALID_ITEM_NAME (29) Item lookup failed, invalid item name.
RTAPI_GETINFO_FAILED_INVALID_ITEM_NAME (30) Item data information retrieval failed, invalid
item name.
RTLOCK_FAILED_NOT_CONNECTED (31) Locking/unlocking failed, connection has not
been previously established.
RTLOCK_FAILED_TIMEOUT (32) Timout waiting for the lock.
RTAPI_RFM_WRITE_ERROR (33) Failed to write data in RFM card.
RTAPI_RFM_READ_ERROR (34) Failed to read data in RFM card.
RTACTIVATEPRINTBUFFER_FAILED_NOT_CONNECTED (35) Connection to the Orchestra framework has
not been previously established.
RTACTIVATEPRINTBUFFER_FAILED_COULD_NOT_ATTACH_TO_BUFFER (36) Could not establish a connection with the
OpalPrint buffer.
RTDEACTIVATEPRINTBUFFER_FAILED_NOT_CONNECTED (37) Connection to the Orchestra framework has
not been previously established.
RTAPI_UNKNOWN_ERROR (38) Failed with unknown error.

Examples
None
Related Items
RTGetErrorMessage
Library and Header

	WINDOWS	REDHAWK
Static Library	libOpalOrchestra.lib	libOpalOrchestra.a
Dynamic Library	-	-
Header File	RTAPI.h	RTAPI.h

Enumerations and constants

The enumeration RTAPIReturn_t contains the list of error codes returned by the RT-LAB Orchestra
API.

Space shortcuts

Page tree

RTActivatePrintBuffer

RTConnect

RTDeactivatePrintBuffer

RTDisconnect

RTGetConnectionKey

RTGetErrorMessage

RTGetInfoForItem

RTGetKeyForItem

RTNewConnectionKey

RTPublish

RTPublishByKey

RTPublishLock

RTPublishUnlock

RTSetConnectionKey

RTSetupRefMemRemoteConnection

RTSubscribe

RTSubscribeByKey

RTSubscribeLock

RTSubscribeUnlock

RTAPIReturn_t

Elements

Enumerations and constants

Space shortcuts

Page tree

RT-LAB | ORCHESTRA: Functions Reference

RTActivatePrintBuffer

RTConnect

RTDeactivatePrintBuffer

RTDisconnect

RTGetConnectionKey

RTGetErrorMessage

RTGetInfoForItem

RTGetKeyForItem

RTNewConnectionKey

RTPublish

RTPublishByKey

RTPublishLock

RTPublishUnlock

RTSetConnectionKey

RTSetupRefMemRemoteConnection

RTSubscribe

RTSubscribeByKey

RTSubscribeLock

RTSubscribeUnlock

RTAPIReturn_t

Elements

Enumerations and constants