# EXAMPLES

- Summary
- PingPong
- Tutorial
- HelloWorld
- WaitSet
- Listener
- ContentFilteredTopic
- QueryCondition
- Lifecycle
- Durability
- Ownership
- BuiltInTopics
- NetworkPartitions
- RoundTrip
- Throughput

## Durability

- Running of examples in Standalone Mode

### 1) Description

The durability example illustrates the ability of late joining readers to obtain data that has already been published before these readers were created.

### 2) Design

It consists of 4 units :

- CheckStatus : provides return status checking
- DDSEntityManager : implements a class providing operations to set up DCPS entities (creation, deletion)
- DurabilityDataPublisher application implements the publisher.
- DurabilityDataSubscriber implements the subscriber.

### 3) Scenario

The DurabilityDataPublisher application write 10 samples and wait for user input to terminate the application. Three possibilities are offered (configurable via arguments passed by command line cf.5):

- 3.1 Memory transient & auto_dispose set to true : terminating the DurabilityDataPublsiher will cause its transient data to become disposed and therefore not readable for any subsequent late joining DurabilityDataSubscriber. Therefore the user should not terminate the DurabilityDataPublisher application until the DurabilityDataSubscriber has been started .
- 3.2 Memory transient & auto_dispose set to false : terminating the DurabilityDataPublsiher will NOT cause its transient data to becomes disposed and therefore it will remain available to subsequent late joining DurabilityDataSubscribers as long as the infrastructure is up and running. So the user can terminate the DurabilityDataPublisher before the DurabilityDataSubscriber has been started.
- 3.3 Persistent & auto_dispose set to false : terminating the DurabilityDataPublisher will NOT cause its persistent data to becomes disposed and therefore it will remain available to subsequent late joining DurabilityDataSubscribers even when the infrastructure has been completely shut down in the mean time. It does this by storing the data on disk, and reinserting the data when the infrastructure is restarted.

IMPORTANT : for persistence to work correctly, the configuration file should define a store type and a store location (use the configurator tool to do that).

Run the DurabilityDataSubscriber Application. It will receive the 10 samples written by the DurabilityDataPublisher and display their content.

- For 3.1 case : any number of instances of the DurabilityDataSubscriber will receive the samples as long as the Publisher application is not terminated.
- For 3.2 and 3.3 : any number of instances of the DurabilityDataSubscriber will still receive the samples even when the Publisher application is terminated.
- For 3.3 : any number of instances of the DurabilityDataSubscriber will still receive the samples even when the Publisher application is terminated and the middleware OpenSplice stopped and restarted.

#### Configurable:

- durability_kind : specify the persistence of the publisher
- autodispose_flag : specify whether the publisher will automatically dispose instances each time they are unregistered
- automatic_flag : indicates if the publisher is run in interactive or automatic mode

durability_kind allows one of two values

- transient : keep some samples so that they can be delivered to any potential late joining subscribers
- persistent : data is kept on permanent storage, so that they can outlive a system session

autodispose_flag allows one of two values

- true
- false

automatic_flag allows one of two values

- true
- false

## Running of examples in Standalone Mode

- Running examples in Posix
- Running examples in Visual Studio

### Usage

    DurabilityDataPublisher usage:
              DurabilityDataPublisher [durability_kind] [autodispose_flag] [automatic_flag]

    DurabilityDataSubscriber usage:
              DurabilityDataSubscriber [durability_kind]

### Running the examples in a Posix environment

#### Environment Setup

Let's call OpenSplice_install_dir the OpenSplice installation directory.

The OpenSplice environment variables must be set in order for the examples to build/run correctly. To do this, open a terminal and source the "OpenSplice_install_dir/release.com" script supplied with the distribution.

- C/C++ Examples
- Java examples
- ISO C++ 2 examples

#### C and C++ Executables

Building the examples is described on the Summary page

Two executables and a library are generated in the standalone directory when the example is built:

For C++

- sacpp_durability_pub
- sacpp_durability_sub
- libsacpp_durability_types.so

For C

- sac_durability_pub
- sac_durability_sub
- libsac_durability_types.so

#### Java executables

Building the examples is described on the Summary page

Three jars are generated in the java/standalone or java5 directory when the example is built:

For Java

- saj_durability_pub.jar
- saj_durability_sub.jar
- saj_durability_types.jar

For Java5

- java5_Durability_pub.jar
- java5_Durability_sub.jar

#### ISO C++ 2 Executables

Building the examples is described on the Summary page

Two executables are generated in the isocpp2 directory when the example is built:

- publisher
- subscriber

#### Running the example

Ensure that the environment for OpenSplice is set up correctly as described above for each new terminal used.

It is recommended that you run the subscriber and publisher in separate terminals to avoid mixing the output

Running in single process (heap memory) configuration : the application starts OpenSplice middleware

- OpenSplice is deployed in this mode by default.
- The OpenSplice daemon should not be started manually. Instead the OpenSplice middleware and optional services are implicitly started by the single process applications as required
- Open 2 terminals. Set up the environment and go to the example directory as described above

Running in multiple process shared memory configuration

To enable deployment in this mode, an OpenSplice configuration file must be selected that has shared memory support e.g. one of the ospl_shmem xml configuration files found in the OpenSplice_install_dir/etc/config directory.

- Open 2 terminals. In each terminal:
- Setup the environment and go to the example directory as described above
- Set the required configuraton file e.g. OSPL_URI=file://$OSPL_HOME/etc/config/ospl_shmem_ddsi.xml
- Start the OpenSplice daemon. You can do this by typing ospl start

Running the subscriber and publisher

##### Scenario 3.1 :

- Run the Subscriber Application, in a console go to the example directory as described above and start the subscriber
  - sac_durability_sub transient for C
  - sacpp_durability_sub transient for C++
  - java -jar saj_durability_sub.jar transient for Java
  - java -jar sub/java5_Durability_sub.jar transient for Java5
  - subscriber transient for ISO C++ 2
- Run the Publisher Application,in a console go to the example directory as described above and start the publisher
  - sac_durability_pub transient true false for C
  - sacpp_durability_pub transient true false for C++
  - java -jar saj_durability_pub.jar transient true false for Java
  - java -jar pub/java5_Durability_pub.jar transient true false for Java5
  - publisher transient true false for ISO C++ 2
- Check that the Subscriber receives the samples
- Stop the Publisher and the subscriber

##### Scenario 3.2 :

- Run the Subscriber Application, in a console go to the example directory as described above and start the subscriber
  - sac_durability_sub transient for C
  - sacpp_durability_sub transient for C++
  - java -jar saj_durability_sub.jar transient for Java
  - java -jar sub/java5_Durability_sub.jar transient for Java5
  - subscriber transient for ISO C++ 2
- Run the Publisher Application,in a console go to the example directory as described above and start the publisher
  - sac_durability_pub transient false false for C
  - sacpp_durability_pub transient false false for C++
  - java -jar saj_durability_pub.jar transient false false for Java
  - java -jar pub/java5_Durability_pub.jar transient false false for Java5
  - publisher transient false false for ISO C++ 2
- Stop the Publisher Application
- Run another instance of Subscriber Application as described above and check that it receives the samples.
- Stop the subscribers

##### Scenario 3.3 :

(If running in Shared Memory deployment we need to stop/start openSplice as we will change the topic durability kind from Transient (in scenario 3.2) to Persistent. Otherwise we won't be able to create the topic)

- Stop OpenSplice if running in Shared Memory deployment
- Start OpenSplice if running in Shared Memory deployment
- Run the Subscriber Application, in a console go to the example directory as described above and start the subscriber
  - sac_durability_sub persistent for C
  - sacpp_durability_sub persistent for C++
  - java -jar saj_durability_sub.jar persistent for Java
  - java -jar sub/java5_Durability_sub.jar persistent for Java5
  - subscriber persistent for ISO C++ 2
- Run the Publisher Application,in a console go to the example directory as described above and start the publisher
  - sac_durability_pub persistent false false for C
  - sacpp_durability_pub persistent false false for C++
  - java -jar saj_durability_pub.jar persistent true false for Java
  - java -jar pub/java5_Durability_pub.jar persistent true false for Java5
  - publisher persistent false false for ISO C++ 2
- Stop the Publisher Application
- Stop OpenSplice if running in Shared Memory deployment
- Start OpenSplice if running in Shared Memory deployment
- Run a new instance of the Subscriber Application as described above and check that it receives the samples.

### Running C/C++/C#/ISO C++ 2/Java examples on Windows

#### Environment Set up

Let's call OpenSplice_install_dir the OpenSplice installation directory.

The OpenSplice environment variables must be set in order for the examples to run correctly. To do this open an OpenSplice Command Prompt which will set up the environment variables for OpenSplice automatically. The OpenSplice Command Prompt can be selected from the start menu. Alternatively, open a windows Command Prompt and execute the "OpenSplice_install_dir\release.bat" batch script supplied with the distribution.

- C/C++/C# Examples
- Java examples
- ISO C++ 2 examples

#### C/C++/C# Executables

Building the examples is described on the Summary page

Two executables are generated in the standalone directory when the example is built:

For C

- sac_durability_sub.exe
- sac_durability_pub.exe

For C++

- sacpp_durability_sub.exe
- sacpp_durability_pub.exe

For C#

- sacs_durability_sub.exe
- sacs_durability_pub.exe

#### Java Executables

Building the examples is described on the Summary page

Three jars are generated in the java\standalone or java5 directory when the example is built:

For Java

- saj_durability_pub.jar
- saj_durability_sub.jar
- saj_durability_types.jar

For Java5

- java5_Durability_pub.jar
- java5_Durability_sub.jar

#### ISO C++ 2 Executables

Building the examples is described on the Summary page

Two executables are generated in the isocpp2 directory when the example is built:

- publisher.exe
- subscriber.exe

#### Running the C/C++/C#/ISO C++ 2/Java Examples

Ensure that the environment for OpenSplice is set up correctly as described above for each new command prompt used.

The following steps describe how to run the examples:

Running in single process (heap memory) configuration : the application starts OpenSplice middleware

- OpenSplice is deployed in this mode by default.
- The OpenSplice daemon should not be started manually. Instead the OpenSplice middleware and optional services are implicitly started by the single process applications as required
- Open 2 OpenSplice Command Prompts and go to the example directory as described above

Running in multiple process shared memory configuration

To enable deployment in this mode, an OpenSplice configuration file must be selected that has shared memory support e.g. one of the ospl_shmem xml configuration files found in the OpenSplice_install_dir\etc\config directory.

- Open 2 OpenSplice Command Prompts. In each window:
- Go to the example directory as described above
- Set the required configuraton file e.g. set OSPL_URI=file://%OSPL_HOME%\etc\config\ospl_shmem_ddsi.xml
- Start the OpenSplice daemon. You can do this by typing ospl start

Running the subscriber and publisher

##### Usage :

- The publisher takes 3 input parameters - durability_kind autodispose_flag automatic_flag, where
  - durability_kind = transient | persistent
  - autodispose_flag = false | true
  - automatic_flag = false | true
    indicates if the publisher is run in interactive or automatic mode
- The subscriber takes 1 parameter - durability_kind, where
  - durability_kind = transient | persistent

##### Scenario 3.1 :

- Run the Subscriber Application, in a console go to the example directory as described above and start the subscriber
  - sac_durability_sub transient for C
  - sacpp_durability_sub transient for C++
  - sacs_durability_sub transient for C#
  - java -jar saj_durability_sub.jar transient for Java
  - java -jar sub/java5_Durability_sub.jar transient for Java5
  - subscriber transient for ISO C++ 2
- Run the Publisher Application,in a console go to the example directory as described above and start the publisher
  - sac_durability_pub transient true false for C
  - sacpp_durability_pub transient true false for C++
  - sacs_durability_pub transient true false for C#
  - java -jar saj_durability_pub.jar transient true false for Java
  - java -jar pub/java5_Durability_pub.jar transient true false for Java5
  - publisher transient true false for ISO C++ 2
- Check that the Subscriber receives the samples
- Stop the Publisher and the subscriber

##### Scenario 3.2 :

- Run the Subscriber Application, in a console go to the example directory as described above and start the subscriber
  - sac_durability_sub transient for C
  - sacpp_durability_sub transient for C++
  - sacs_durability_sub transient for C#
  - java -jar saj_durability_sub.jar transient for Java
  - java -jar sub/java5_Durability_sub.jar transient for Java5
  - subscriber transient for ISO C++ 2
- Run the Publisher Application,in a console go to the example directory as described above and start the publisher
  - sac_durability_pub transient false false for C
  - sacpp_durability_pub transient false false for C++
  - sacs_durability_pub transient false false for C#
  - java -jar saj_durability_pub.jar transient false false for Java
  - java -jar pub/java5_Durability_pub.jar transient false false for Java5
  - publisher transient false false for ISO C++ 2
- Stop the Publisher Application
- Run another instance of Subscriber Application as described above and check that it receives the samples.
- Stop the subscribers

##### Scenario 3.3 :

(If running in Shared Memory deployment we need to stop/start OpenSplice as we will change the topic durability kind from Transient (in scenario 3.2) to Persistent. Otherwise we won't be able to create the topic)

- Stop OpenSplice if running in Shared Memory deployment
- Start OpenSplice if running in Shared Memory deployment
- Run the Subscriber Application, in a console go to the example directory as described above and start the subscriber
  - sac_durability_sub persistent for C
  - sacpp_durability_sub persistent for C++
  - sacs_durability_sub persistent for C#
  - java -jar saj_durability_sub.jar persistent for Java
  - java -jar sub/java5_Durability_sub.jar persistent for Java5
  - subscriber persistent for ISO C++ 2
- Run the Publisher Application,in a console go to the example directory as described above and start the publisher
  - sac_durability_pub persistent false false for C
  - sacpp_durability_pub persistent false false for C++
  - sacs_durability_pub persistent false false for C#
  - java -jar saj_durability_pub.jar persistent true false for Java
  - java -jar pub/java5_Durability_pub.jar persistent true false for Java5
  - publisher persistent false false for ISO C++ 2
- Stop the Publisher Application
- Stop OpenSplice if running in Shared Memory deployment
- Start OpenSplice if running in Shared Memory deployment
- Run a new instance of the Subscriber Application as described above and check that it receives the samples.