The Connexis library is tightly integrated with the TargetRTS (a.k.a. the RT Services Library). The Model RealTime installation contains prebuilt versions of the Connexis library for the same platforms as for the TargetRTS. If you need to build and run your distributed application on another platform you need to build both the TargetRTS and the Connexis library for that platform.
Another reason for building the Connexis library, instead of using one of the prebuilt libraries, is if you want to customize its behavior or optimize it. For example:
Changing the compiler flags used for building the library (for example to set some flags that will remove features you don't need)
Implement your own name service to be used instead of the Locator service
Implement a custom transport
Whatever the reason is for building the Connexis library, it's recommended to start with copying the Connexis model library (DCS) so you can modify the model and/or the TCs it contains.
These are the steps to perform when you need to build Connexis for another target platform:
Create Connexis specific header files for the new target configuration
Configure CDR encoding and decoding for the new target configuration
The Connexis library for a target platform depends on the TargetRTS for its target configuration and library settings. The TargetRTS provides several settings that can be configured. The table below lists those settings that are important for Connexis.
| Target Setting | Value | Descriptions |
|---|---|---|
USE_THREADS |
1 | Connexis is only available for multi-threaded applications. |
HAVE_INET |
1 | Connexis requires IP support for the Connexis Datagram Messaging (CDM) and the Connexis Reliable Messaging (CRM) transports. |
OBJECT_ENCODE |
1 | Messages must be encoded before they can be transmitted over the wire. |
OBJECT_DECODE |
1 | A message received over the wire must be decoded into an object. |
Compiler settings that are common to both the TargetRTS, the Connexis library and the application itself should be configured using the LIBSETCCFLAGS macro in $RTS_HOME/libset/<libset>/libset.mk.
Compiler settings that only apply to the TargetRTS should be set in the LIBSETCCEXTRA macro in $RTS_HOME/libset/<libset>/libset.mk.
Compiler settings that only apply to the Connexis library should be configured in the library TC used for building the Connexis model. See Create a CPP Library TC for Connexis.
For more information about how to build the TargetRTS for a new target configuration, refer to the chapter "Porting the TargetRTS" in the document "The RT Services Library - How to manage it using the TargetRTS wizard".
Although most of the configuration of the Connexis library is done within the Connexis model, the Connexis thread configurations are configured in the file $RTS_HOME/target/<target>/RTDcsTarget.h. This file contains specific operating system priority definitions and configuration of the stack size for Connexis threads. The RTDcsTarget.h file also contains the definitions of the maximum and minimum values of the thread priorities for an operating system. Run-time argument processing uses these values to validate the run-time settings or the thread priorities for the Connexis threads. The table below provides a list of constants that must be defined in RTDcsTarget.h.
| Constant | Description |
|---|---|
CNX_PRIORITY_MIN<br>CNX_PRIORITY_MAX |
Defines the minimum and maximum allowable value for a thread priority. The CNX_PRIORITY_MIN and CNX_PRIORITY_MAX are used by Connexis to do bounds checking of thread priorities (e.g., to determine whether the given priority is a legal value). They should be set to the lowest and highest numerical (not logical) thread values as defined by the operating system. For example: For operating system A, the highest thread priority is 10 and the lowest is 0. For operating system B, the highest thread priority is 0 and its lowest thread priority is 10. For both operating systems: #define CNX_PRIORITY_MIN 0<br>#define CNX_PRIORITY_MAX 10 |
CNX_PRIORITY_RAISE |
By default, the priority of the helper threads are higher than the priority of the transporter thread. The CNX_PRIORITY_RAISE constant can be used to increment a thread priority. For OS targets in which the higher priority threads have lower numeric values, the value of CNX_PRIORITY_RAISE must be negative. |
DEFAULT_CNXTTP_PRIORITY |
Sets the default thread priority for the transporter thread. |
DEFAULT_CNXHTP_PRIORITY |
Sets the default thread priority for the helper threads. For optimal system performance, the helper threads should run at a higher priority than the transporter thread. |
DEFAULT_CNXATP_PRIORITY |
Sets the default thread priority for the target agent. The target agent is designed to be minimally intrusive to the application and should be running at a lower priority than the threads of the application. |
CNXTTP_STACK |
Sets the stack size for the transporter thread. |
CNXHTP_STACK |
Sets the stack size for the helper threads. |
CNXATP_STACK |
Sets the stack size for the target agent thread. |
If you take a copy of the Connexis model library (DCS), you can either modify an existing library TC or create a completely new TC for building the library. You can clone an existing TC by means of the context menu command Copy To.
The table below lists the TC properties that typically need to be set in order to build Connexis for a new target configuration:
| TC Property (TargetConfiguration tab) | Description |
|---|---|
| TargetRTS configuration | The <target> and <libset> settings of the TargetRTS configuration that you are building against. Set the property "Target services library" to the folder where you have already built the TargetRTS. |
| Make type | Specify the dialect of the makefiles to be generated. For example, if you are using the GNU make utility in your environment, this property should be set to GNU_make. |
| Make command | Specifies the name of the make utility to be used. |
| Make arguments | You must specify RT_SRC_TGT=<target_base>. Connexis depends on TargetRTS files in the $RTS_HOME/src/target directory. For example, RTtcp.h. The RT_SRC_TGT make variable is used to specify the target base. |
| Compile arguments | If you get compilation errors when building your TC it may be a result of the RTD_CONNEXIS_BUILD constant not being set properly. The definition of this constant should be changed from $(CNX_BUILD_NUM) to a user-defined integer value. This property is used to configure the C++ preprocessor macros that configure certain Connexis capabilities.Viewer tracing is configured on the target using the RTD_TRACE macro:- $(DEFINE_TAG)RTD_TRACE=1 enables tracing- $(DEFINE_TAG)RTD_TRACE=0 disables most traces (except errors and warnings)- $(DEFINE_TAG)RTD_TRACE=2 disables all tracesMetrics collection is configured using the RTD_STATISTICS macro:- $(DEFINE_TAG)RTD_STATISTICS=1 enables metrics collection and reporting- $(DEFINE_TAG)RTD_STATISTICS=0 disables metrics collection and reportingAdditional macros might be required to configure the CDR encode/decode capabilities for the target platform. Additonal macros might be required to configure the CDR encode/decode capabilities for the target platform. These capabilties are described in Configure CDR Encoding and Decoding for a New Target Configuration. |
Connexis by default has plenty of tracing and debugging capabilities included. This is useful during the development of a distributed application, but when you are ready to productify the application you may want to exclude such capabilities to reduce the memory footprint of Connexis. These two compile arguments allow you to accomplish this:
$(DEFINE_TAG)RTD_TRACE=0
$(DEFINE_TAG)RTD_STATISTICS=0
The CDR encode/decode functionality could require platform specific customizations depending on the capabilities of the platform. These customizations are accomplished by defining C++ preprocessor macros in the "Compile arguments" TC property. The following customizations are available:
Overriding the type for use when encoding 64-bit values. The default behavior when the RTDLONGLONGTYPE macro is not defined is to encode/decode 64-bit values using the primitive "long long" type. This customization is required when the compiler does not provide support for "long long" types. Setting
$(DEFINE_TAG)RTD_LONGLONG_TYPE=0 will use the "__int64" type to encode/decode 64-bit values. Setting $(DEFINE_TAG)RTD_LONGLONG_TYPE=1 will cause 64-bit values to be encoded/decoded using the primitive "double" type.
Enabling the inclusion of <sys/types.h>. Some platforms require this inclusion to provide definitions of all the system types. Setting
$(DEFINE_TAG)RTD_INCLUDE_TYPES_IN_RTDPLATFORMCONFIG enables this capability.
Once your library TC is ready, just build it as any other library. Set it as a prerequisite of all TCs that you use for building all executables of your distributed application that run on the specific target. You may have other executables that run on different targets that then would link with another build of the Connexis library.
To do a first basic test of your newly-built Connexis library you can for example use the HelloWorld sample that is included with Model RealTime. See The Connexis HelloWorld sample model.