Part IV: Configuring and Running the Synchronization Manager

Introduction

The suite of programs that comprises the MaxDB Synchronization Manager is built on Java and implements the "Java Message Service". In this article, we give an example of configuring this suite of tools and running them for the first time. The intended audience is community members and customers who want to take advantage of MaxDB's replication system.

The two pieces of software that we cover in this article are the Synchronization Manager GUI, a piece of Java software to manage synchronization between databases, and the message server, which acts as the intermediary between databases being synchronized.

Unidirectional synchronization is available for devices that are not well-connected. Platforms that support this form of synchronization include MySQL and MinDB.

Bi-directional synchronization is available for MaxDB to MaxDB connections.

Synchronization Manager Requirements

The Synchronization Manager requires a Java 1.4 runtime environment and the j2ee library in order to function correctly. It is assumed that runtime environment is installed to /opt/j2sdk1.4.2_08/ and that j2ee is installed in /opt/SUNWappserver/

1. Obtain and unpack Eclipse

   The Synchronization Manager depends on Eclipse, the open source Java IDE. You can find out more about Eclipse and related projects at http://eclipse.org/. To make use of the Synchronization Manager and related tools, you will need to obtain and extract the v3.1 linux + gtk+2 package, and swt libraries by following these steps:

   $ cd /tmp
   $ wget http://xrl.us/iba7 # Eclipse v3.0.2, mirror at calvin.edu
   $ unzip eclipse-SDK-3.0.2-linux-gtk.zip
   
   

2. Importing the Java archives and shared libraries

   A number of Java .jar and shared library .so files from Eclipse are needed for the Synchronization Manager product to work correctly. Enter the following from the command-line to place the .jar and .so files in the correct location:

   $ cd /tmp
   $ mkdir eclipse-swt
   $ cd eclipse-swt
   $ unzip ../eclipse/plugins/org.eclipse.swt.gtk.linux.x86_3.1.0.jar
   $ for i in runtime jface swt text osgi
     do
       find /tmp/eclipse-swt -iname "*$i*.so"  \
         -exec cp \{\} /var/opt/sdb/data/app/syncman/extern \;
       find /tmp/eclipse -iname "*$i*.jar"  \
         -exec cp \{\} /var/opt/sdb/data/app/syncman/extern \;
     done

3. Configure the Environment

   Ensure that you source the sapdbenv.sh and sunenv.sh environment scripts in order to be sure that the environment variables are correctly set.

4. Create the example databases

   To create an example databases, run the createexampledatabases script, which was installed along with MaxDB:

   $ /opt/sdb/programs/app/syncman/example/createexampledatabases
   

5. Ensure that your user is in the sdba user group

   Run the adduser program to add your user to the sdba group.

   $ sudo adduser $USER sdba
   

   All commands issued to sudo are run as the super-user. The $USER variable contains the username for the current shell session.

The Message Server

1. Configuring the Message Server

   Before running the Message Server, first run the Message Server configuration script. This script generates the .syncmanacc file, which will be located in the ~/.sdb/syncman/ directory. This file will be used by the message server to determine runtime configuration.

   $ msgserver config

   Issuing the msgserver config command will prompt you for some information about your system's configuration. It is safe to leave all parameters default except for the database name. As you can see in the sample results below, you should use the DBMASTER database, which was created and configured previously by the createexampledatabases script.

   database host [127.0.0.1]: 
   database name [MAXDB1]: DBMASTER
   database user [DBSERVICE]: 
   password of database user [SECRET]: 
   message server admin password [MSGSERVERADMIN]: 
   message server admin port [7220]: 
   JNDI port [7221]: 
   JMS port [7222]: 

2. Running the Message Server

   Now that the configuration file is in place, start the msgserver like so:

   $ msgserver start
   

   At this point, Message Server should be running.

   [starting Mon Aug 15 19:50:35 PDT 2005] Starting server
   ...
   [Mon Aug 15 20:05:14 PDT 2005] =====  S E R V E R   R E A D Y  =====

   At this point, you may configure, start and begin using the Synchronization Manager GUI

Synchronization Manager GUI

The Synchronization Manager GUI is the tool used to create replication schemes and inform the Message Server about new replication endpoints. The GUI is written in Java and makes use of the Eclipse swt library to create a cross-platform interface. The GUI is distributed with MaxDB and installed by default.

Eclipse itself is not required other than SWT and related libraries and classes. After placing the files that are required into /var/opt/sdb/data/app/syncman/extern (instructions above), you may delete the installer as well as the unpacked files in order to save disk space.

1. Configuring the Synchronization Manager GUI

   The configuration file that the syncmangui program uses to access Java install information is called ~/.sdb/syncman.cfg and can be generated using syncmanjconf. If the configuration file does not exist when syncmangui is first run, it will automatically run syncmanjconf to generate it.

   In order to demonstrate its use and be explicit about creating the configuration file, let's run syncmanjconf now.

   $ sudo touch ~/.sdb/syncman.cfg
   $ sudo chown -R $USER ~/.sdb
   $ syncmanjconf
   path to java executable: /opt/j2re1.4.2_05/bin
   path to j2ee.jar file: /opt/SUNWappserver/lib
   $ cat ~/.sdb/syncman.cfg
   J2EEPATH = /opt/SUNWappserver/lib
   JAVAPATH = /opt/j2re1.4.2_05/bin
   

2. Running the Synchronization Manager GUI

Before starting the graphical user interface for Synchronization Manager, Make sure you have X configured to forward the $DISPLAY to your local system. Your $DISPLAY variable is likely to be set differently than the example below. Confirming that the variable has been set is a good way to verify that X is running.

$ echo $DISPLAY
localhost:11.0

If you have the X windowing system installed and your $DISPLAY is set correctly, you can start the Synchronization Manager GUI by running syncmangui like so:

$ syncmangui



3. Connecting to a Database

   In order to connect to the DBMASTER database, click on the Session pull-down menu and choose Connect to Database .... A dialog box will be opened. Provide the host address, database name, username, and password ("SECRET") as show in the screen shot below:

   

   The log window at the bottom of the GUI should display the following text:

   Connecting ...
   Connected to  jdbc:sapdb://127.0.0.1/DBMASTER

4. Connecting to the Message Server

   Having connected to the database, you can now connect to the message server. Click on the Session pull-down menu again and choose Connect to Message Server .... This will open another dialog box. Provide it with the necessary information. Note, the initial administrator password is "MSGSERVERADMIN".

   

   The log window at the bottom of the GUI should display the following text:

   Connected to 127.0.0.1:7220

   You should also see this message on the console from your message server: [Mon Aug 15 20:15:03 PDT 2005] Connected to 127.0.0.1:32848 on port 7220 for service com.sap.sdb.msgServer.service.AdminService

Summary

At this point, you have a working MaxDB Synchronization Manager and are able to create replication tables. You have the tools required to follow SAP's Synchronization Manager documentation and to explore the system on your own.