RTI Persistence Service

Installation Guide

Version 5.0

© 2007-2012 Real-Time Innovations, Inc.

All rights reserved.

Printed in U.S.A. First printing.

August 2012.

Trademarks

Real-Time Innovations, RTI, and Connext are trademarks or registered trademarks of Real-Time Innovations, Inc. All other trademarks used in this document are the property of their respective owners.

Copy and Use Restrictions

No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form (including electronic, mechanical, photocopy, and facsimile) without the prior written permission of Real- Time Innovations, Inc. The software described in this document is furnished under and subject to the RTI software license agreement. The software may be used or copied only under the terms of the license agreement.

Technical Support

Real-Time Innovations, Inc. 232 E. Java Drive Sunnyvale, CA 94089

Phone: (408) 990-7444 Email: support@rti.com Website: https://support.rti.com/

Installation

This document describes how to download and install RTI® Persistence Service and other required components.

1 Optional Database Components

When Persistence Service is used in PERSISTENT mode, you can configure it to store DDS samples into a relational database, such as MySQL.

In principle, you can use any database that provides an ODBC driver, since ODBC is a standard. However, not all ODBC databases support the same feature set. Therefore, there is no guarantee that the persistent durability features will work with an arbitrary ODBC driver.

RTI has tested Persistence Service with MySQL 5.1.44 with MySQL ODBC 5.1.6.

The usage of MySQL requires the separate installation of the MySQL ODBC 5.1.6 (or higher) driver. For non-Windows platforms, the installation of UnixODBC 2.2.12 (or higher) is also required.

❏To use MYSQL, you will need:

•MySQL 5.1.44 or higher (download from http://www.mysql.com)

•MySQL ODBC 5.1.6 driver or higher (download from http://dev.mysql.com/downloads/connector/odbc)

•UnixODBC 2.2.12 or higher (download from http://www.unixodbc.org.)

The Durable Writer History and Durable Reader State features in RTI Connext™ (formerly RTI Data Distribution Service) also use a relational database. Therefore, the installation instructions for MySQL are provided in the RTI Core Libraries and Utilities Getting Started Guide Addendum for Database Setup.

If you need help with the download or installation process, contact support@rti.com.

2 Installation Instructions

Persistence Service is included with RTI Connext Messaging. Use the instructions in this section only if you are installing Persistence Service independently (not part of RTI Connext Messaging).

1

2.1AIX, Linux, and Solaris Systems

You do not need administrator privileges to install Persistence Service.

Install Persistence Service on top of Connext (with the same version number). After installation, the rtipersistenceservice application will be located in the <NDDSHOME>/scripts directory (the same place where you will find rtiddsgen, rtiddsping, etc.).

Follow the instructions below. All directory locations in this document are meant as examples only; adjust them to suit your site.

1.Make sure you have GNU's version of the tar utility, gtar (which handles long file names), and GNU's version of the unzip utility, gunzip.

2.Move the downloaded file to the same directory where you installed Connext 5.0.x. For instance, if you already have /local/rti/ndds.5.0.x, move the downloaded file to /local/rti and change to that directory:

>cd /local/rti

3.Use gunzip to uncompress the file. For example (your filename may be different):

>gunzip RTI_Persistence_Service-5.0.x-sparcSol2.10gcc3.4.2.tar.gz

4.Use gtar to extract the distribution from the uncompressed file. For example:

>gtar xvf RTI_Persistence_Service-5.0.x-sparcSol2.10gcc3.4.2.tar

This will extract files into the existing ndds.5.0.x directory; including placement of the rtipersistenceservice application in /local/rti/ndds.5.0.x/scripts.

5.Include $NDDSHOME/scripts in your PATH if it is not already included:

>setenv PATH $NDDSHOME/scripts:$PATH

6.If you have a licensed version of Persistence Service, please see Installing the License File (Section 2.3).

7.To verify your installation, enter:

>rtipersistenceservice -help

You should see a response similar to:

RTI Persistence Service v5.0.x

 

 

Usage: rtipersistenceservice [options]

 

Options:

 

 

-cfgFile

<file>

Configuration file. This parameter is

 

 

optional since the configuration can

 

 

be loaded from other locations

-cfgName

<name>

Configuration name. This parameter is

 

 

required and it is used to find a

 

 

<persistence_service>

 

 

matching tag in the configuration

 

 

files

-appName

<name>

Application name

 

 

Used to identify this execution for

 

 

remote administration and to name the

 

 

domain participants

 

 

Default: -cfgName

-identifyExecution

 

Appends the host name and process ID

 

 

to the appName to help ensure unique

 

 

names

-domainId

<int>

domain ID for the domain participants

 

 

created by the service

 

 

Default: Use XML value

2

 

 

Installation Instructions

-remoteAdministrationDomainId

<int>

Enables remote administration and sets

 

 

the domain ID for the communication

 

 

Default: Use XML value

-restore

<0|1>

Indicates whether or not Persistence

 

 

Service must restore its state from

 

 

the persistent storage

 

 

Default: Use XML value

-noAutoStart

 

Use this option if you plan to start

 

 

RTI Persistence Service remotely

-infoDir

<dir>

The info directory of the running per-

 

 

sistence

 

 

service. The service writes a ps.pid

 

 

file into this directory when started.

 

 

When the service finalizes the file is

 

 

deleted

 

 

Default: None

-maxObjectsPerThread

<int>

 

 

 

Sets the maximum number of objects

 

 

that can be stored per thread for a

 

 

DomainParticipantFactory

 

 

Default: Connext default

-serviceStackSize

<int>

 

 

 

Service thread stack size

 

 

Default: OS default

-verbosity

[0-6]

RTI Persistence Service verbosity

 

 

* 0 - silent

 

 

* 1 - exceptions (Core Libraries and

 

 

service)

 

 

* 2 - warnings (service)

 

 

* 3 - information (service)

 

 

* 4 - warnings (Core Libraries and

 

 

service)

 

 

* 5 - tracing (service)

 

 

* 6 - tracing (Core Libraries and

 

 

service)

 

 

Default: 1 (exceptions)

-version

 

Prints the RTI Persistence Service

 

 

version

-licenseFile

<file>

License file. This parameter is

 

 

optional

-help

 

Displays this information

2.2Windows Systems

You do not need administrator privileges to install Persistence Service.

Install Persistence Service on top of Connext. After installation, the rtipersistenceservice application will be located in the <NDDSHOME>\scripts directory (the same place where you will find rtiddsgen, rtiddsping, etc.).

Follow the instructions below. All directory locations in this document are meant as examples only; adjust them to suit your site.

1.Right-click the distribution file and extract the contents in the same directory where you installed Connext. For instance, if you already have c:\Program Files\RTI\ndds.5.0.x, then extract to c:\Program Files\RTI.

3

2.Add Persistence Service’s scripts directory to your Path environment variable if it is not already included: %NDDSHOME%\scripts. (If you need help with this process, please see the RTI Core Libraries and Utilities Getting Started Guide.)

3.If you have a licensed version of Persistence Service, please see Installing the License File (Section 2.3).

4.To verify your installation, open a command prompt and enter the following:

>c:\Program Files\RTI\ndds.5.0.x\scripts\rtipersistenceservice -help

You should see a response similar to what is shown in the Linux section above.

2.3Installing the License File

If your Persistence Service distribution requires a license file, you will receive one in an email from RTI.

If you have Connext Messaging and you want to use RTI Launcher1 to start Persistence Service:

By default, RTI Launcher looks for the license file rti_license.dat in the top-level directory where you installed Connext Messaging. If you choose to save the license file elsewhere, you can configure RTI Launcher to look in a different location by using its Configuration tab.

Otherwise:

Save the license file in any location of your choice. When Persistence Service starts, it will look in these locations until it finds a valid license:

1.The file specified with the -licenseFile option when you start Persistence Service from the command-line.

2.The file specified in the environment variable RTI_LICENSE_FILE, which you may set to point to the full path of the license file, including the filename (for example,

C:\RTI\my_rti_license.dat).

3.The file rti_license.dat in the current working directory.

4.The file rti_license.dat in the directory specified by the environment variable NDDSHOME.

If you have any questions about license file installation, please contact support@rti.com.

3 Available Documentation

The following documentation is provided with the Persistence Service distribution. (The paths show where the files are located after Persistence Service has been installed in <NDDSHOME>):

❏Persistence Service Release Notes

(<NDDSHOME>/doc/pdf/RTI_Persistence_Service_ReleaseNotes.pdf)

❏General information on Persistence Service:

Open <NDDSHOME>/ReadMe.html, then select RTI Persistence Service.

❏Example code: <NDDSHOME>/example/<language>/helloWorldPersistence.

1.RTI Launcher is a convenient GUI-based tool that can start and configure all of your Connext Messaging components, including Persistence Service.

4

Available Documentation

Additional documentation is provided with Connext:

❏Configuration, use cases, and execution of Persistence Service:

RTI Core Libraries and Utilities User’s Manual

(<NDDSHOME>/doc/pdf/RTI_CoreLibrariesAndUtilities_UsersManual.pdf)

❏Overview of persistence and durability features:

Open <NDDSHOME>/ReadMe.html, choose your desired API, then select Modules,

Connext API Reference, Durability and Persistence.

5