Method 2—Change the Participant QoS to Specify the Monitoring Library Create Function Pointer and Explicitly Load the Monitoring Library

If any of the following are true, you must change the Participant QoS to enable monitoring and explicitly load the correct version of Monitoring Library at compile time:

• Your application is linked to the static version of Connext DDS libraries.
• You are NOT running your application on Linux, Windows, Solaris, AIX or Mac OS platforms.
• You want to explicitly link in the monitoring library (static or dynamic) into your application.

There are two ways to do this:

• Method 2-A: Change the Participant QoS by Specifying the Monitoring Library Create Function Pointer in Source Code: Applies to most users who cannot use Method 1 and do not mind changing/recompiling source code every time you enable/disable monitoring, or whose system does not support setting environment variables programmatically. Participant QoS must be defined in source code with this approach.
• Method 2-B: Change the Participant QoS by Specifying the Monitoring Library Create Function Pointer in an Environment Variable: Applies to users who cannot use Method 1 and want to specify the create function pointer via an environment variable. This approach allows the Participant QoS to be defined in an XML file or in source code.

Method 2-A: Change the Participant QoS by Specifying the Monitoring Library Create Function Pointer in Source Code

1. Modify your Connext DDS application based on the following examples.
Traditional C++ Example:

#include "ndds/ndds_cpp.h"
#include "monitor/monitor_common.h"
extern "C" int publisher_main(int domainId, int sample_count)
{
    ...
    DDSDomainParticipant *participant = NULL;
    DDS_DomainParticipantQos participant_qos;
    char valueBuffer[17];
    /* Get default QoS */
    retcode = 
    DDSTheParticipantFactory->get_default_participant_qos(
        participant_qos);
    if (retcode != DDS_RETCODE_OK) {
        /*Error*/ 
    }
    /* This property indicates that the DomainParticipant 
       has monitoring turned on. The property name MUST be  
       "rti.monitor.library". The value can be anything.*/
    retcode = DDSPropertyQosPolicyHelper::add_property(
	participant_qos.property,
	"rti.monitor.library", "rtimonitoring", DDS_BOOLEAN_FALSE); 
    if (retcode != DDS_RETCODE_OK) {
        /*Error*/ 
    }
    /* The property name "rti.monitor.create_function" 
       indicates the entry point for the monitoring library. 
       The value MUST be the value of the function pointer of 
       RTIDefaultMonitor_create */
    sprintf(valueBuffer, "%p", RTIDefaultMonitor_create);
    retcode = DDSPropertyQosPolicyHelper::add_property(
        participant_qos.property,
        "rti.monitor.create_function_ptr", 
        valueBuffer, DDS_BOOLEAN_FALSE);
    if (retcode!= DDS_RETCODE_OK) { 
        /* Error */
    }
    /* Create DomainParticipant with participant_qos */ 
    participant = DDSTheParticipantFactory->create_participant(
	domainId, participant_qos,NULL /* listener */,
	DDS_STATUS_MASK_NONE); 
    if (participant == NULL) { 
        /* Error */
    }
    ...

Modern C++ Example:

#include "rti/rti.hpp" // include all the modern C++ API
#include "monitor/monitor_common.h" // for RTIDefaultMonitor_create
//...

using rti::core::policy::Property;

// Get the property policy from the default DomainParticipantQos
auto participant_qos = dds::core::QosProvider::Default().participant_qos();
auto property_policy = participant_qos.policy<Property>();

// This property turns monitoring on
property_policy.set(Property::Entry("rti.monitor.library", "rtimonitoring"));

// This property specifies the entry point (function pointer) for the
// monitoring library.
std::ostringstream monitor_function_to_str;
monitor_function_to_str << RTIDefaultMonitor_create;
property_policy.set(Property::Entry(
    "rti.monitor.create_function_ptr", monitor_function_to_str.str()));

C Example:

#include "ndds/ndds_c.h"
#include "monitor/monitor_common.h"
...
extern "C" int publisher_main(int domainId, int sample_count)
{
	DDS_DomainParticipantFactory *factory = NULL;
	struct DDS_DomainParticipantQos participantQos =
    	DDS_DomainParticipantQos_INITIALIZER;
	char valueBuffer[17];
	DDS_DomainParticipant *participant = NULL;
	factory = DDS_DomainParticipantFactory_get_instance();
	if (factory == NULL) {
		/* error */
	}
	if (DDS_DomainParticipantFactory_get_default_participant_qos(
	    factory, &participantQos) != DDS_RETCODE_OK) {
		/* error */
	}
	/* This property indicates that the DomainParticipant has
	    monitoring turned on. The property name MUST be 
	       “rti.monitor.library”. The value can be anything.*/
	if (DDS_PropertyQosPolicyHelper_add_property(
		&participantQos.property, 
		"rti.monitor.library", "rtimonitoring", 
		DDS_BOOLEAN_FALSE) != DDS_RETCODE_OK) {
       		/* error */
	} 
	/* The property name "rti.monitor.create_function_ptr"
           indicates the entry point for the monitoring library.
           The value MUST be the value of the function pointer 
           of RTIDefaultMonitor_create */
	sprintf(valueBuffer, "%p", RTIDefaultMonitor_create);
	if (DDS_PropertyQosPolicyHelper_add_property(
		&participantQos.property, 
		"rti.monitor.create_function_ptr",valueBuffer, 
		DDS_BOOLEAN_FALSE) != DDS_RETCODE_OK) {
		/* error */
	}
	/* create DomainParticipant with participantQos */
	participant= 
		DDS_DomainParticipantFactory_create_participant(
			factory, domainId, &participantQos, 
			NULL /* listener */, 
			DDS_STATUS_MASK_NONE);
	if (participant == NULL) {
		/* error */
	}
	DDS_DomainParticipantQos_finalize(&participantQos);
	...

Note:

• In the above code, you may notice that valueBuffer is initialized to 17 characters. This is because a pointer (RTIDefaultMonitor_create) is at most 8 bytes (on a 64-bit system) and it takes two characters to represent a byte in hex. So the total size must be:

  (2 * 8 characters) + 1 null-termination character = 17 characters.

2. Link the Monitoring Library for your platform into your application at compile time (the Monitoring libraries are listed in the RTI Connext DDS Core Libraries Platform Notes).

The kind of monitoring library that you link into your application at compile time must be consistent with the kind of Connext DDS libraries that you are linking into your application (static/dynamic, release/debug version of the libraries).

On Windows systems:If you are linking a static monitoring library, you will also need to link in Psapi.lib at compile time.

Method 2-B: Change the Participant QoS by Specifying the Monitoring Library Create Function Pointer in an Environment Variable

This is similar to Method 2-A, but if you specify the function pointer value for rti.monitor.create_function_ptr in an environment variable that is set programmatically, you can specify your QoS either in an XML file or in source code. If you specify the QoS in an XML file, you can enable/disable monitoring without recompiling. If you change the QoS in your source code, you may need to recompile every time you enable/disable monitoring.

1. In XML, enable monitoring by setting the rti.monitor.create_function_ptr property to an environment variable. In our example, the variable is named RTIMONITORFUNCPTR.

<participant_qos> 
    <property> 
	<value> 
	    <element> 
		<name>rti.monitor.library</name> 
		<value>rtimonitoring</value> 
	    </element> 
	    <element> 
		<name>rti.monitor.create_function_ptr</name> 
		<value>$(RTIMONITORFUNCPTR)</value> 
	    </element> 
	</value> 
    </property>
</participant_qos>

2. In the DDS application that links in the monitoring library, get the function pointer of RTIDefaultMonitor_create and write it to the same environment variable you named in Step 1 and create a DomainParticipant by using the XML profile specified in Step 1. (Setting of the environment variable must appear in the application before it creates the DomainParticipant using the profile from Step 1.)
Here is an example in C:

#include <stdio.h>
#include <stdlib.h>
#include "monitor/monitor_common.h"
...
char putenvBuffer[34];
int putenvReturn;
putenvBuffer[0] = '\0';
sprintf(putenvBuffer, "RTIMONITORFUNCPTR=%p",	
	 RTIDefaultMonitor_create);
putenvReturn = putenv(putenvBuffer);
if (putenvReturn) {
    printf( 
    "Error: couldn't set env variable for RTIMONITORFUNCPTR. "
    "error code: %d\n",  putenvReturn );
}
...
/* create DomainParticipant using XML profile from Step 1 */
...

Note: In the above code, you may notice that putenvBuffer is initialized to 34 characters. This is because a pointer (RTIDefaultMonitor_create) is at most 8 bytes (on a 64-bit system) and it takes 2 characters to represent a byte in hex. So the total size must be: strlen(RTIMONITORFUNCPTR) + (2 * 8 characters) + 1 null-termination character = 17 + 16 + 1 = 34 characters

3. Link the Monitoring Library for your platform into your application at compile time (the Monitoring libraries are listed in the RTI Connext DDS Core Libraries Platform Notes).

The kind of monitoring library that you link into your application at compile time must be consistent with the kind of Connext DDS libraries that you are linking into your application (static/dynamic, release/debug version of the libraries).

On Windows systems: If you are linking a static monitoring library, you will also need to link in Psapi.lib at compile time.

© 2016 RTI