This documentation is for an older version of HVR.

Quick Start for HVR - File Replication

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:
Requirements for FTP, SFTP, and SharePoint WebDAV
Requirements for HDFS
Requirements for S3

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, PostgreSQL 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;

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.

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.
Enter the name or IP address of the hub machine in the Node field (e.g. myserver).
Enter the port number (defined in the HVR Remote Listener of the hub machine) in the Port field (e.g. 4343).
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.
Select Oracle in the Class pane.
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).
Click Connect.
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 Configuration, Channel 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.

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.
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.