Quick Start for HVR - File Replication

Last updated on May 13, 2020

Contents

This quick start guide helps you to get started with HVR for replicating files between directories.

To proceed with this replication you must have basic understanding about HVR's architecture and terminologies like Hub, Location, Channel, Location Groups, Actions etc.

The example here demonstrates how to replicate files from one directory (source location) to another two directories (target location).

In real-life scenarios, the source location(s) and the target location(s) reside on different machines (some of these directories would be reached via FTP, SFTP or SharePoint/WebDAV) and the HVR hub can reside on source or target or a separate machine. However, in this example, for simplicity we have the source, target, and HVR hub on the same machine i.e., HVR will replicate between three directories all created on the hub machine; files are captured from subdirectory /tmp/f1 and copied to /tmp/f2 and /tmp/f3. The channel is a 'blob' file channel, which means it has no table information and simply treats each file as a sequence of bytes without understanding their file format. If the HVR hub is installed on a Unix/Linux machine, to manage HVR hub and the replication activities from a remote location (for example a PC), you need to install HVR GUI on your PC.

Before proceeding with this example ensure that the requirements for using HVR with File location are met.

For information about access privileges and advanced configuration changes required for performing file replication, see:


Create File Locations

Create three directories to test replication:

 $ mkdir /tmp/f1
 $ mkdir /tmp/f2
 $ mkdir /tmp/f3

Install HVR

First read section Architecture Overview which explains the HVR's terminology and architecture. In particular this explains the importance of a hub database.

Then install the HVR software on the hub machine by following the installation steps in section Installing HVR on Windows or Installing HVR on Unix or Linux. If the hub machine is a Unix machine then HVR can either be installed on a Windows PC (so the HVR GUI can run on the PC and connect to the Unix hub machine) or the HVR GUI can be run on the Unix hub machine and connect back to an X server running on a PC.

Create the Hub Database

Create the hub database, in which the HVR GUI will store the channel definition. This can be an Ingres database, Oracle schema, SQL Server, DB2 (LUW), DB2 for I, Postgres or Teradata database. The steps to create an Oracle hub database schema are as follows:
$ sqlplus system/manager
 SQL> create user hvrhub identified by hvr
  2  default tablespace users
  3  temporary tablespace temp
  4  quota unlimited on users;
  
 SQL> grant create session to hvrhub;
 SQL> grant create table to hvrhub;
 SQL> grant create sequence to hvrhub;
 SQL> grant create procedure to hvrhub; 
 SQL> grant create trigger to hvrhub;
 SQL> grant create view to hvrhub;
 SQL> grant execute any procedure to hvrhub;
  
$ sqlplus
 Enter user-name: / as sysdba
 SQL> grant execute on dbms_alert to hvrhub;
 SQL> exit;

See also:

 Create the Hub Database in Ingres

Create the hub database, in which the HVR GUI will store the channel definition.

 $ createdb hvrhub

 Create the Hub Database in SQL Server

This section describes how to create a hub database. The hub database is a repository database that HVR uses to control its replication activities. It contains HVR catalog tables that hold all specifications of replication such as the names of the replicated databases, the replication direction and the list of tables to be replicated. For more information about HVR hub server and database, see section Hub Server in System Requirements.

HVR supports the creation of a hub database on certain databases (location classes) only. For the list of supported location classes, see section Hub Database in Capabilities.

For this demonstration, the hub database (e.g. hvrhub) is created in SQL Server.

Create the hub database using the SQL Server Management Studio. Alternatively, use the following SQL statement:

create database hvrhub

Connect to Hub Database

This section describes how to connect HVR GUI to the hub database.

When you launch HVR GUI for the first time, the Register Hub dialog is displayed automatically. The Register Hub dialog can also be accessed from menu File by selecting Register Hub. Skip steps 1 to 4 if you want to run HVR GUI directly on the hub machine.

  1. Click Connect to HVR on remote machine.

    To connect HVR GUI on a PC to a remote HVR hub machine, the HVR Remote Listener must be configured and running on the HVR hub machine.

  2. Enter the name or IP address of the hub machine in the Node field (e.g. myserver).
  3. Enter the port number (defined in the HVR Remote Listener of the hub machine) in the Port field (e.g. 4343).
  4. Enter the Login (e.g. myserveradmin) and Password for the hub machine. By default, this is the operating system login credentials of the hub machine.
  5. Select Oracle in the Class pane.
  6. Specify Database Connection details.
    1. Enter the directory path in ORACLE_HOME. You can also click the browse button to select the directory path.
    2. Enter the Oracle System ID in ORACLE_SID or TNS credentials.
    3. Enter the user name of the hub database in User (e.g. hvrhub).
    4. Enter the password for the hub database in Password (e.g. hvr).
  7. Click Connect.


  8. Click Yes in the prompt dialog asking to create catalog tables in the hub database.

    HVR displays this prompt when connecting to a hub database for the first time.

    On connecting successfully to the hub database, the navigation tree pane displays the hub machine and the hub database. Location ConfigurationChannel Definitions, and Scheduler are displayed under the hub database.

See also:

 Connect to Hub Database (Ingres)

This section describes how to connect HVR GUI to the hub database.
  1. First, register the hub database: right-click on hub machines▶ Register hub.
  2. Enter connection details.

In this example the hub is a machine called guam, where an INET daemon is listening on port 4343. See section Installing HVR on Unix or Linux for how to configure this.

For a new hub database a dialog will prompt Do you wish to create the catalogs?; answer Yes.

 Connect to Hub Database in SQL Server

This section describes how to connect HVR GUI to the hub database.

When HVR GUI is launched for the first time, the Register Hub dialog is displayed automatically. The Register Hub dialog can also be accessed from the main menu File ▶ Register Hub.

Skip steps 1 to 4, if HVR GUI is executed directly on the hub machine or if HVR hub is connected to a remote SQL Server database without using the SQL Server protocol. For more information about connecting HVR hub with remote SQL Server database, see section Connecting HVR Hub to a Remote SQL Server Database in Requirements for SQL Server.

  1. Click Connect to HVR on remote machine.

    To connect HVR GUI on a PC to a remote HVR hub machine, the HVR Remote Listener must be configured and running on the HVR hub machine.

  2. Enter the name or IP-address of the hub machine in the Node field (e.g. myserver).
  3. Enter the port number (defined in the HVR Remote Listener of the hub machine) in the Port field (e.g. 4343).
  4. Enter the Login (e.g. myserveradmin) and Password for the hub machine. By default, this is the operating system login credentials of the hub machine.
  5. Select SQL Server in the Class pane.
  6. Specify Database Connection details. For more information about the Database Connection fields, see section Location Connection.
    1. Enter the HVR hub database name in the Database field. For example, hvrhub.
    2. Enter the SQL Server user name in the User field. This username is used to connect HVR to the SQL Server database. For example, hvr.
    3. Enter the password for the SQL Server user in the Password field.
  7. Click Connect.

  8. Click OK in the prompt dialog asking to create catalog tables in the hub database. HVR displays this prompt when connecting to a hub database for the first time.

Upon successful connection to the hub database, the navigation tree pane displays the hub machine and the hub database. Location ConfigurationChannel Definitions, and Scheduler are displayed under the hub database.

Create Channel and Location groups

Next create three file locations (one for each replicated directory) using right-click on Location Configuration ▶ New Location.

In this example there is no need to check Connect to HVR on remote machine because /tmp/f1 is on the same machine as the hub.

Ignore the Group Membership tab for now.

Make locations for /tmp/f2 and /tmp/f3 as well.

Now define a channel using Channel Definitions ▶ New Channel.

The channel needs two location groups. Under the new channel: right–click on Location Groups ▶ New Group. Enter a group name (for instance CENTRAL).

Add location f1 as a member of this group by checking the box for f1.

Then create a second location group, called DECENTRAL that has members f2 and f3.

This is a 'blob' file channel so it has no table layout information.

Define Actions

The new channel needs two actions to indicate the direction of replication.
  1. Right-click on group CENTRAL ▶ New Action ▶ Capture. If parameter /DeleteAfterCapture is checked, then HVR will remove files from the source directory after they are captured. Otherwise, the contents of the directory (and its subdirectories) will be copied and changes will be detected by monitoring the files' timestamps.
  2. Right-click on Group DECENTRAL ▶ New Action ▶ Integrate.

Note that the Actions pane only displays actions related the objects selected in the left hand pane. So click on channel hvr_demo31 to see both actions.

Enable Replication with HVR Initialize

Now that the channel definition is complete, create the runtime replication system.

Right-click on channel hvr_demo31 ▶ HVR Initialize. Choose Create or Replace Objects and click HVR Initialize.

From the moment that HVR Initialize is done, all changes in directory /tmp/f1 will be captured by HVR.

HVR Initialize also creates three replication jobs, which can be seen under the Scheduling node in the HVR GUI.

Start Scheduling of Replication Jobs

Start the Scheduler on the hub machine by clicking in the HVR GUI on the Scheduler node of the hub database.

Next, instruct the HVR Scheduler to trigger the replication jobs.

The replication jobs inside the Scheduler each execute a script under $HVR_CONFIG/job/hvrhub/hvr_demo31 that has the same name as the job. So job hvr_demo31–cap–f1 detects changes in directory /tmp/f1 and stores these as transactions files on the hub machine. The other two jobs (hvr_demo31–integ–f2 and hvr_demo31–integ–f3) pick up these transaction files, and copy new or modified files to the two target directories.

Test Replication

To test replication, copy any file into directory /tmp/f1:
 $ echo hello > /tmp/f1/world

In the HVR log file you can see the output of the jobs by clicking on View Log. This log file can be found in $HVR_CONFIG/log/hubdb/hvr_demo01–cap–db1.

The job output looks like this:

 hvr_demo31-integ-f3: Waiting...
 hvr_demo31-cap-f1: Capture cycle 1 for 2 files (37 bytes).
 hvr_demo31-cap-f1: Routed 150 bytes (compression=19.8%) from 'f1' into 2 locations.
 hvr_demo31-integ-f2: Integrate cycle 2 for 1 transaction file (150 bytes).
 hvr_demo31-cap-f1: Waiting...
 hvr_demo31-integ-f2: Moved 2 files to 'C:\tmp\f2'.
 hvr_demo31-integ-f2: Waiting...
 hvr_demo31-integ-f3: Integrate cycle 2 for 1 transaction file (150 bytes).
 hvr_demo31-integ-f3: Moved 2 files to 'C:\tmp\f3'.
 hvr_demo31-integ-f3: Waiting...

This indicates that the new file has been replicated to directories /tmp/f2 and /tmp/f3. Look in these directories to confirm this.