pervasive sync

Pervasive DataExchange

User’s GuideGuide to Using Pervasive DataExchange

Pervasive Software Inc.12365 Riata Trace Parkway

Building BAustin, TX 78727 USA

Telephone: 512 231 6000 or 800 287 4383Fax: 512 231 6010

Email: [email protected]: http://www.pervasive.com

d i s c l a i m e r PERVASIVE SOFTWARE INC. LICENSES THE SOFTWARE AND DOCUMENTATION PRODUCT TO YOU OR YOUR COMPANY SOLELY ON AN “AS IS” BASIS AND SOLELY IN ACCORDANCE WITH THE TERMS AND CONDITIONS OF THE ACCOMPANYING LICENSE AGREEMENT. PERVASIVE SOFTWARE INC. MAKES NO OTHER WARRANTIES WHATSOEVER, EITHER EXPRESS OR IMPLIED, REGARDING THE SOFTWARE OR THE CONTENT OF THE DOCUMENTATION; PERVASIVE SOFTWARE INC. HEREBY EXPRESSLY STATES AND YOU OR YOUR COMPANY ACKNOWLEDGES THAT PERVASIVE SOFTWARE INC. DOES NOT MAKE ANY WARRANTIES, INCLUDING, FOR EXAMPLE, WITH RESPECT TO MERCHANTABILITY, TITLE, OR FITNESS FOR ANY PARTICULAR PURPOSE OR ARISING FROM COURSE OF DEALING OR USAGE OF TRADE, AMONG OTHERS.

t r a d e m a r k s Btrieve, Client/Server in a Box, Pervasive, Pervasive Software, Pervasive DataExchange, and the Pervasive Software and the Pervasive DataExchange logos are trademarks or registered trademarks of Pervasive Software Inc.Built on Pervasive Software, Pervasive AuditMaster, “know who’s doing what to your data when, where and how,” MicroKernel Database Engine, MicroKernel Database Architecture, Pervasive.SQL, Solution Network, Ultralight, and ZDBA are trademarks of Pervasive Software Inc.

Microsoft, MS-DOS, Windows, Windows 95, Windows 98, Windows NT, Windows Millennium, Windows 2000, Windows XP, Win32, Win32s, and Visual Basic are registered trademarks of Microsoft Corporation.

NetWare and Novell are registered trademarks of Novell, Inc. NetWare Loadable Module, NLM, Novell DOS, Transaction Tracking System, and TTS are trademarks of Novell, Inc.

The Regex++ library is Copyright (c) 1998-2001 by Dr John Maddock.

This product features PeerDirect™ software. Pervasive Software, Inc. is a licensed user of the trademark "PeerDirect," and that trademark and PeerDirect are owned by PeerDirect Inc. PeerDirect software © 1993-2001 PeerDirect Inc. All Rights Reserved.

All other company and product names are the trademarks or registered trademarks of their respective companies.

© Copyright 2008 Pervasive Software Inc. All rights reserved. Reproduction, photocopying, or transmittal of this publication, or portions of this publication, is prohibited without the express prior written consent of the publisher.

User’s GuideJuly 2008100-004177-005

Contents

ContentsAbout This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Who Should Read This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviManual Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Pervasive DataExchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiReal-Time Backup Edition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiData Synchronization Edition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiDataExchange Tools and Utilities. . . . . . . . . . . . . . . . . . . . . . . . . . . xviiSupplemental Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii

Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix


1 Introducing Pervasive DataExchange . . . . . . . . . . . . . . . . 1-1Understanding Pervasive DataExchange and Its Capabilities

DataExchange Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2DataExchange Editions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

Real-Time Backup Edition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3Data Synchronization Edition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

DataExchange Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4DataExchange Utilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4DataExchange Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

2 Pervasive DataExchange Basics . . . . . . . . . . . . . . . . . . . 2-1An Overview of DataExchange Basics

Starting and Stopping Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2As a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2As a Console Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3From Pervasive Control Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3

Starting and Stopping the DXAgent Service . . . . . . . . . . . . . . . . . . . . . . . . 2-5As a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5From Pervasive Control Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6

ODBC Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7Servers and Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7Data Source Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7

Pervasive PSQL Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9Deploying Demodata Under Pervasive PSQL Security . . . . . . . . . . . . . . . 2-9

3 Using Pervasive DataExchange . . . . . . . . . . . . . . . . . . . . 3-1A Guide to Using DataExchange in Daily Operations

iii

Contents

Activation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2Activation and Data Source Names . . . . . . . . . . . . . . . . . . . . . . . . . 3-2Activating First and Partner Sites . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

Deactivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5Reactivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6

Adding Tables to an Activated Database . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7Before you Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7Determine Event Handler DLL Usage . . . . . . . . . . . . . . . . . . . . . . . . 3-8Deactivate All Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8Verify the Table Exists in the Pervasive Database. . . . . . . . . . . . . . . . . . 3-9Add the New Table to the Replication Template . . . . . . . . . . . . . . . . . . 3-10Stop Replication Service on Partner Sites . . . . . . . . . . . . . . . . . . . . . . 3-11Copy Files (DDFs, D- and PDC Tables) . . . . . . . . . . . . . . . . . . . . . . . 3-11Activate First Site and Synchronize Tables . . . . . . . . . . . . . . . . . . . . . 3-12Start Replication Service on Partner Sites . . . . . . . . . . . . . . . . . . . . . . 3-13Activate Partner Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13Initiate Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14

Removing Tables From an Activated Database . . . . . . . . . . . . . . . . . . . . . . 3-15Before you Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15Deactivate all Sites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15Remove Table From the Replication Template . . . . . . . . . . . . . . . . . . . 3-16Stop Replication Service on Partner Sites . . . . . . . . . . . . . . . . . . . . . . 3-17Copy D*.mkd Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17Start Replication Service on Partner Sites . . . . . . . . . . . . . . . . . . . . . . 3-18Activate all Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18Initiate Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-19

Adding Dynamic Tables to an Activated Database . . . . . . . . . . . . . . . . . . . . 3-20Before you Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-21Include File Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-21Exclude File Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22

Setting up Nondatabase File Replication . . . . . . . . . . . . . . . . . . . . . . . . . . 3-24Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-24Set Log On Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-25Create New Flat File Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-25Execute the SQL Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-26Create the Design Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-27Copy Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-28Activate all Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-28Restart DX Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-29Redesign Dxevent Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-29Create Site Shares . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30Configure Flat File Replication. . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30

Changing a Table Structure in an Activated Database . . . . . . . . . . . . . . . . . . 3-32Before you Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-32Clone PDC Table(s). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-33

iv

Contents

Activate the First Site and Synch Tables . . . . . . . . . . . . . . . . . . . . . . . 3-33Copy Files and Activate the Partner Site . . . . . . . . . . . . . . . . . . . . . . . 3-34Verify the Replication Session. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-34

Real-Time Backup Edition

4 Real-Time Backup Deployment Models . . . . . . . . . . . . . . . 4-1A Look at Alternative Deployment Models for Real-Time Backup

Real-Time Backup Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2Two-Machine Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2Many-to-One Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3

Replication Deployment using the Deployment Tool . . . . . . . . . . . . . . . . . . . 4-5Before You Get Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5

Replication Deployment using DXDeploy . . . . . . . . . . . . . . . . . . . . . . . . . 4-6Replication Deployment Using Designer . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7

Before You Get Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7Create a Template on the First Site Using Designer . . . . . . . . . . . . . . . . . 4-8Copy the Template Files to the Partner Site . . . . . . . . . . . . . . . . . . . . . 4-11Activate the Template on the First Site . . . . . . . . . . . . . . . . . . . . . . . . 4-12Activate the Template on the Partner Site . . . . . . . . . . . . . . . . . . . . . . 4-12Make Sample Database Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13Initiate Replication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14Verify the Changes Were Replicated . . . . . . . . . . . . . . . . . . . . . . . . . 4-17

Many-to-One Deployment using DXDeploy . . . . . . . . . . . . . . . . . . . . . . . . 4-18Before You Get Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19Deploying Using DXDeploy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20

Disaster Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24Failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24No Data Recoverable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-25Data Recoverable But Not Current . . . . . . . . . . . . . . . . . . . . . . . . . . 4-26

Data Synchronization Edition

5 Data Synchronization Deployment Models. . . . . . . . . . . . . . 5-1A Look at Deployment Models Available for Data Synchronization

Data Synchronization Deployment Methods . . . . . . . . . . . . . . . . . . . . . . . 5-2DataExchange Implementation Options . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3

DataExchange Deployment Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3DataExchange DXDeploy Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3DataExchange Designer and Utilities . . . . . . . . . . . . . . . . . . . . . . . . . 5-4Where To Go From Here . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5

Working with the Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6Removing Databases Deployed with DXDeploy. . . . . . . . . . . . . . . . . . . 5-6

v

Contents

Removing Databases Deployed with Designer . . . . . . . . . . . . . . . . . . . 5-8Replication Deployment Using the Deployment Tool . . . . . . . . . . . . . . . . . . 5-11

Before You Get Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-111-Way Deployment Using DXDeploy . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12

Before You Get Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12Create the XML Descriptor File . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13Run DXDeploy on the First Site . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-21Copy the Template to the Partner Site. . . . . . . . . . . . . . . . . . . . . . . . 5-22Run DXDeploy on the Partner Site . . . . . . . . . . . . . . . . . . . . . . . . . 5-23

1-Way Deployment Using Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-24Before You Get Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-24Create a Template on the First Site Using Designer . . . . . . . . . . . . . . . . 5-25Copy First Site Files to the Partner Site . . . . . . . . . . . . . . . . . . . . . . . 5-28Activate the First Site Template . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-28Activate the Partner Site Template. . . . . . . . . . . . . . . . . . . . . . . . . . 5-29Make Sample Database Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-30Initiate Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-31Verify the Changes Were Replicated. . . . . . . . . . . . . . . . . . . . . . . . . 5-33

2-Way Deployment Using DXDeploy . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-34Before You Get Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-34Create the XML Descriptor File . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-35Run DXDeploy on the First Site . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-44Copy the Template to the Partner Site. . . . . . . . . . . . . . . . . . . . . . . . 5-45Run DXDeploy on the Partner Site . . . . . . . . . . . . . . . . . . . . . . . . . 5-46

2-Way Deployment Using Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-47Before You Get Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-47Create the Template Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-48Copy First Site Files to the Partner Site . . . . . . . . . . . . . . . . . . . . . . . 5-51Activate the First Site Template . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-51Activate the Partner Site Template. . . . . . . . . . . . . . . . . . . . . . . . . . 5-52Make Sample Database Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-53Initiate Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-54Verify the Changes Were Replicated. . . . . . . . . . . . . . . . . . . . . . . . . 5-56

6 Example Database Design for Data Synchronization . . . . . . . . 6-1Understanding Database Design Considerations for Data Synchronization

Data Synchronization Design Considerations . . . . . . . . . . . . . . . . . . . . . . . 6-2Application Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2

Basic Data Synchronization Design. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6Database Selection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6Database Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7Replicated Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8

Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10Sample Tracker Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11

vi

Contents

DataExchange Tools and Utilities

7 Using the DataExchange Utilities and Services . . . . . . . . . . . 7-1A Reference for Using the DataExchange Utilities and Services

Utilities and Services Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2Replication Stages and the Utilities Used. . . . . . . . . . . . . . . . . . . . . . . 7-2Accessing the Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3

Command-line Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5dxact. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6dxcleanup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9dxdeact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11dxdeploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-13dxdynpath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-15Types of Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-18dxregevnt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-21dxrepl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-23dxsynctables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-25ffcopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-26

GUI-based Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-31da . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-31prd. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-32replmonitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-32dpwizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-32trwizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-32

Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-34dxagent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-34replserv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-37

8 Using the DataExchange Designer . . . . . . . . . . . . . . . . . . 8-1A Tour of the DataExchange Designer Features and Functionality

DataExchange Designer Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21-Way / 2-Way Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4Design Completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9

DataExchange Designer GUI Visual Reference . . . . . . . . . . . . . . . . . . . . . . . 8-14Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-14Designer Menu and Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-16Database Design pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-22

DataExchange Designer Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-23General Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-23Basic Design Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-23Design Completion Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-24Administrative Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-24

vii

Contents

9 Using DataExchange Manager . . . . . . . . . . . . . . . . . . . . 9-1A Tour of DataExchange Manager Utility

DataExchange Manager Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2Managing Replication Schedules. . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2Managing Site Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3Managing Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-5Managing Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-8

DataExchange Manager GUI Visual Reference . . . . . . . . . . . . . . . . . . . . . . 9-9Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9

DataExchange Manager Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-12General Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-12Schedule Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-18Site Information Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-19User Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-20

10 Using the Replication Progress and Log Viewers . . . . . . . . . . 10-1A Brief Look at the Replication Progress and Log Viewers

Checking the Replication Engine and Service . . . . . . . . . . . . . . . . . . . . . . . 10-2Initiating Replication from the Progress and Log Viewers . . . . . . . . . . . . . . . . 10-4

Initiating a Replication Session. . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-4Reading the Initiate Replication Dialog Box . . . . . . . . . . . . . . . . . . . . 10-6

Recording and Monitoring Replication Activity. . . . . . . . . . . . . . . . . . . . . . 10-7Setting Log Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-7DRE Log File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-8

Supplemental Information

A Basic Troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . A-1How to Identify and Solve Common Problems

Troubleshooting Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2Troubleshooting Strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4

Multiple DataExchange Designers . . . . . . . . . . . . . . . . . . . . . . . . . . A-4Terminal Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4

Uninstalling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5Network Communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6

How to Start PSA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6Documentation for PSA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6

Database Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-7Replication Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-8Log Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9

Log File Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9Log File Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10

viii

Contents

Data Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13List of Sites to Replicate With Seems Inconsistent. . . . . . . . . . . . . . . . . . A-13Replication Fails for a Deactivated Site . . . . . . . . . . . . . . . . . . . . . . . . A-13False Alert Because of Schedule Manipulation. . . . . . . . . . . . . . . . . . . . A-14Correct Alarms but Replication on Wrong Schedule . . . . . . . . . . . . . . . . A-14Dynamically Created Tables Not Being Replicated . . . . . . . . . . . . . . . . . A-14SQL Triggers and Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-15Data Conflicts When Activating Partner Sites . . . . . . . . . . . . . . . . . . . . A-15Index Segments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-16

Data Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-17Conflict Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-17Resolving Primary Key Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . A-20

Notification Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-23Testing the Mail Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-23

How to Get Additional Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-24Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-25

B Supported Data Types . . . . . . . . . . . . . . . . . . . . . . . . . B-1Pervasive DataExchange Data Types

Data Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2Notes on Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-4

DECIMAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-4NUMERIC, BIGINT, UBIGINT and CURRENCY . . . . . . . . . . . . . . . . . B-4CHAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-4VARCHAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-4IDENTITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-4

C Reserved Table Names . . . . . . . . . . . . . . . . . . . . . . . . C-1Pervasive DataExchange Reserved Words and Table Names

Other Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-2

D Advanced Topics. . . . . . . . . . . . . . . . . . . . . . . . . . . . D-1A Look at Advanced Topics for Pervasive DataExchange

Installing DataExchange as Part of Your Application . . . . . . . . . . . . . . . . . . . D-2How To Perform a Silent Install . . . . . . . . . . . . . . . . . . . . . . . . . . . D-2

E Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-1Replication Terminology

Accelerated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-1Activated Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-1Activation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-1Change Capture / Change Apply . . . . . . . . . . . . . . . . . . . . . . . . . . . E-1Control Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-1

ix

Contents

DataExchange Designer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2DataExchange Manager. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2DNA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2First Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2Globally-Unique IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2Hub and Spoke . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2In Place Activation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-3Local Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-3N-Tiered . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-3Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-3ODBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-3Partner Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-3Peer-to-Peer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-3Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-3Refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-4Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-4Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-4Replication Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-4Replication Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-4Replication Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-4Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-4Subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-5Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-5

x

Figures

4-1 Real-Time Backup with Two Machines . . . . . . . . . . . . . . . . . . . . . . . . 4-34-2 Real-Time Backup with Many-to-One Configuration . . . . . . . . . . . . . . . . 4-44-3 DataExchange Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-94-4 DataExchange Designer with All Tables Selected . . . . . . . . . . . . . . . . . . 4-94-5 Replicate Table Command in DataExchange Designer . . . . . . . . . . . . . . . 4-104-6 View of Replicated Tables in DataExchange Designer . . . . . . . . . . . . . . . . 4-104-7 Activated Icon in Pervasive PSQL Explorer . . . . . . . . . . . . . . . . . . . . . 4-134-8 Demodata Tables Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-144-9 Replication - Connected Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-154-10 Replication Progress and Log Viewers . . . . . . . . . . . . . . . . . . . . . . . . 4-154-11 Initiate Replication Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-164-12 Example Replication Progress and Log Viewers . . . . . . . . . . . . . . . . . . . 4-174-13 Multiple Sites Backing Up Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-184-14 Many-to-One Configuration with DataExchange Installed . . . . . . . . . . . . . 4-195-1 SalesDB Database Activated on First Site . . . . . . . . . . . . . . . . . . . . . . . 5-225-2 Data Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-255-3 DataExchange Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-265-4 DataExchange Designer with All Tables Selected . . . . . . . . . . . . . . . . . . 5-265-5 Replicate Table Command in DataExchange Designer . . . . . . . . . . . . . . . 5-265-6 View of Replicated Tables in DataExchange Designer . . . . . . . . . . . . . . . . 5-275-7 Activated Indicator in Pervasive PSQL Explorer . . . . . . . . . . . . . . . . . . . 5-305-8 Starting Statistics View Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-315-9 Replication Progress and Log Viewers . . . . . . . . . . . . . . . . . . . . . . . . 5-315-10 Initiate Replication Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-325-11 Example Replication Process in Statistics View Utility . . . . . . . . . . . . . . . 5-335-12 TrackerDB Activated on First Site . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-455-13 Data Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-485-14 DataExchange Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-495-15 DataExchange Designer with All Tables Selected . . . . . . . . . . . . . . . . . . 5-495-16 Replicate Table Command in DataExchange Designer . . . . . . . . . . . . . . . 5-495-17 View of Replicated Tables in DataExchange Designer . . . . . . . . . . . . . . . . 5-505-18 Activated Indicator in Pervasive PSQL Explorer . . . . . . . . . . . . . . . . . . . 5-535-19 Starting DataExchange Monitoring Tools . . . . . . . . . . . . . . . . . . . . . . 5-545-20 Replication Progress and Log Viewers . . . . . . . . . . . . . . . . . . . . . . . . 5-545-21 Initiate Replication Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-555-22 Example Replication Process in Statistics View Utility . . . . . . . . . . . . . . . 5-566-1 Tracker Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-36-2 Data Synchronization Database Selection Dialog . . . . . . . . . . . . . . . . . . 6-66-3 Data Synchronization Database Selection Dialog. . . . . . . . . . . . . . . . . . . 6-78-1 Data Synchronization Database Selection Dialog. . . . . . . . . . . . . . . . . . . 8-4

xi

Figures

8-2 Real-Time Backup Database Selection Dialog . . . . . . . . . . . . . . . . . . . . 8-58-3 Designer Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-148-4 Designer Menu and Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-168-5 Database Design pane. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-229-1 Site Schedule Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-39-2 Site List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-49-3 Site Information Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-49-4 Location of User List and User Tabbed Dialogs . . . . . . . . . . . . . . . . . . . 9-79-5 User Information Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-79-6 User Membership Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-89-7 Permissions Group List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-89-8 DataExchange Manager Main Window . . . . . . . . . . . . . . . . . . . . . . . . 9-9

xii

Tables

1-1 Overview of Pervasive DataExchange Utilities . . . . . . . . . . . . . . . . . . . . 1-42-1 Actions Required to Deploy Demodata Under Database Security or Mixed Security

2-104-1 Replication System Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-265-1 Data Synchronization Deployment Methods . . . . . . . . . . . . . . . . . . . . 5-25-2 DataExchange Implementation Options . . . . . . . . . . . . . . . . . . . . . . . 5-38-1 DataExchange Designer Logging Level Options . . . . . . . . . . . . . . . . . . . 8-119-1 Permissions Comparison Between Default Groups . . . . . . . . . . . . . . . . . 9-610-1 Replication Logging Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-710-2 Replication Progress and Log Viewers Logging Level Options . . . . . . . . . . . 10-9A-1 Resources that Assist with Problem Determination . . . . . . . . . . . . . . . . . A-2A-2 Pervasive Software Resources and Contact Information . . . . . . . . . . . . . . A-24C-1 Replication System Table Names . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1

xiii

About This Manual

This manual contains information about Pervasive DataExchange. It is intended to help you design, activate, and replicate databases, and to configure and troubleshoot replication.

The manual focuses on DataExchange replication concepts, supported by discussions that include step-by-step instructions for using the features of the product.

xv

About This Manual

Who Should Read This Manual

This manual provides information for users who design databases for replication, implement the design, replicate data, and monitor and maintain replication schedules.

Pervasive Software would appreciate your comments and suggestions about this manual. As a user of our documentation, you are in a unique position to provide ideas that can have a direct impact on future releases of this and other manuals. If you have comments or suggestions for the product documentation, post your request at http://www.pervasive.com/devtalk.

xvi

Manual Organization

Manual Organization

This manual is divided into the following parts.


Chapter 1—“Introducing Pervasive DataExchange”

This chapter provides an introduction to Pervasive DataExchange and an overview of the utilities and DataExchange documentation.

Chapter 2—“Pervasive DataExchange Basics”

This chapter discusses the basic concepts needed in order to work with Pervasive DataExchange.

Chapter 3—“Using Pervasive DataExchange”

This chapter discusses the day-to-day operations you can perform with Pervasive DataExchange.


Chapter 4—“Real-Time Backup Deployment Models”

This chapter offers sample deployment models for using the Pervasive DataExchange Real-Time Backup Edition. It also includes information on recovering your data in the event of a system failure or data loss.


Chapter 5—“Data Synchronization Deployment Models”

This chapter provides sample deployment models for using the Pervasive DataExchange Data Synchronization Edition. Deployments using DXDeploy and the DataExchange Designer are included.

Chapter 6—“Example Database Design for Data Synchronization”

This chapter explains how to design a database for the Data Synchronization Edition using the sample database, Tracker.

DataExchange Tools and Utilities

Chapter 7—“Using the DataExchange Utilities and Services”

This chapter provides a reference for using the Pervasive DataExchange utilities and services.

xvii

About This Manual

Chapter 8—“Using the DataExchange Designer”

This chapter details working with the DataExchange Designer features and functionality.

Chapter 9—“Using DataExchange Manager”

This chapter covers the tasks you can perform in order to administer your replication solutions with the DataExchange Manager.

Chapter 10—“Using the Replication Progress and Log Viewers”

This chapter discusses the tools used for monitoring replication and configuring Pervasive DataExchange replication sessions and properties.

Supplemental Information

Appendix A—“Basic Troubleshooting”

This appendix provides information for troubleshooting and resolving problems.

Appendix B—“Supported Data Types”

This appendix details the data types supported by Pervasive DataExchange and details any known limitations.

Appendix C—“Reserved Table Names”

This appendix details the keywords reserved by DataExchange, system tables created for replication, and the naming convention used to create replication user tables.

Appendix D—“Advanced Topics”

This appendix explains performing a silent installation of DataExchange as an advanced operation.

Appendix E—“Glossary”

This appendix provides a list of terms and definitions for Pervasive DataExchange.

The manual also includes an index.

xviii

Conventions

Conventions

Unless otherwise noted, command syntax, code, and examples use the following conventions:

CASE Commands and reserved words typically appear in uppercase letters. Unless you are working with Unix or the manual states otherwise, you can enter these items using uppercase, lowercase, or both. For example, you can type MYPROG, myprog, or MYprog.

Bold Words appearing in bold include the following: menu names, dialog box names, commands, options, buttons, statements, etc.

Monospaced font

Monospaced font is reserved for words you enter, such as command syntax.

[ ] Square brackets enclose optional information, as in [log_name]. If information is not enclosed in square brackets, it is required.

| A vertical bar indicates a choice of information to enter, as in [file name | @file name].

< > Angle brackets enclose multiple choices for a required item, as in /D=<5|6|7>.

variable Words appearing in italics are variables that you must replace with appropriate values, as in file name.

... An ellipsis following information indicates you can repeat the information more than one time, as in [parameter ...].

::= The symbol ::= means one item is defined in terms of another. For example, a::=b means the item a is defined in terms of b.

xix

About This Manual

xx

PERVASIVE DATAEXCHANGE

c h a p t e r

1
Introducing Pervasive DataExchange
Understanding Pervasive DataExchange and Its Capabilities

This chapter introduces you to Pervasive DataExchange, the DataExchange Editions, and the components included with Pervasive DataExchange. This chapter is divided into the following sections:

“DataExchange Overview” on page 1-2

“DataExchange Editions” on page 1-3

“DataExchange Components” on page 1-4

1-1


DataExchange Overview

Pervasive DataExchange reliably moves data between two or more Pervasive PSQL databases to maintain warm backup systems, drive data into reporting servers, or synchronize multiple remote databases.

The DataExchange technology works by capturing and sharing changes from one Pervasive PSQL database to other databases in a DataExchange replication network. The Pervasive PSQL Engine is augmented with DataExchange, which adds two software components to a Pervasive PSQL database, the Replication Event Handler and the Replication Engine.

The Replication Event Handler (REH) plugs directly into the Pervasive PSQL database engine. Specifically, the REH is a set of DLLs that operate within the database engine, so if the database is running, the replication event handler is running as well. The database engine activates the REH when there is a change event (insert, update, delete). The REH then makes note of the event in one of its private control tables.

The Replication Engine is a separate process that performs the actual replication task. It reads the control tables to determine what records have changed since the last replication session. It then groups these changes into packets and shares them with the other replication engines participating in a DataExchange network. These other engines then apply the updates to their own databases. The replication process occurs either continuously, at scheduled intervals, or on demand. The replication engine does not require constant network connectivity, so DataExchange is suitable for scenarios with intermittent connectivity, like remote users with dialup connections.

Pervasive DataExchange focuses on the two types of data replication:

Providing continuous access to data (Real-Time Backup)

Synchronizing multiple databases (Data Synchronization)

While both capabilities are useful, one typically surfaces as the primary driver for implementing data replication technology in a specific environment.

1-2

DataExchange Editions

DataExchange Editions

Pervasive DataExchange is available in two editions—Real-Time Backup and Data Synchronization.


Pervasive DataExchange Real-Time Backup Edition is optimized for quickly and easily maintaining a backup server. It pairs high performance with minimal installation and maintenance. This edition supports one-way replication between a primary server and a backup server.

Real-Time Backup solutions can be onsite or offsite, depending on your needs. Onsite backups ensure your data is protected from hardware failures. Protecting your data means that data recovery time is reduced and downtime is minimal. Solutions that implement an offsite backup server gain protection to your data against catastrophic loss, such as fire, flood or theft.


Pervasive DataExchange Data Synchronization Edition is optimized for more complex replication scenarios. This edition supports multiple participating databases and data flowing in multiple directions.

The real-time data replication offered in Data Synchronization ensures all users see the same up-to-the-minute information. The ability to configure flexible topologies allows data flows to match the business organization.

1-3


DataExchange Components

Pervasive DataExchange consists of the following primary components:

Replication Engine - used for distributing and applying captured database changes

Replication Event Handler (REH) - used for recording or monitoring database change events

DataExchange Agent - used to provide notification in the event of a replication failure

DataExchange Utilities - used to perform the tasks necessary for replication, such as design and activation

DataExchange Documentation - provides conceptual and instructional information for using Pervasive DataExchange

DataExchange Utilities

Pervasive DataExchange comes with a variety of utilities designed to help you configure and manage the replication process.

For detailed information on the Pervasive DataExchange Utilities, see Chapter 7, “Using the DataExchange Utilities and Services”.

Table 1-1 Overview of Pervasive DataExchange Utilities

Utility Type Utilities Included

GUI-based Utilities Includes the DataExchange Designer, DataExchange Manager, DataExchange Monitoring Tools, Template Remover Wizard, and Deployment Wizard.

Command-line Utilities Includes a suite of utilities for performing all phases of design, activation, replication, and deployment.

Services Monitors data replication, configures replication sessions, and sets logging options. (The set of tools with which you perform these actions are referred to as the DataExchange Monitoring Tools.)

1-4

DataExchange Components

DataExchange Documentation

All Pervasive DataExchange documentation, both printed and online, assumes you are familiar with the basics of using a computer, such as clicking and dragging, opening and saving files. If you need assistance with these tasks, please consult the documentation that came with your computer and/or operating system.

You can order printed copies of the documentation from your sales representative.

Getting Started Guides

Pervasive DataExchange includes a printed manual for installation and setup of your product. The manual included with your software is specific to the replication edition you purchased. Depending on the product you purchased, one of the following titles is included in your product package:

Getting Started with Pervasive DataExchange (Real-Time Backup Edition)

Getting Started with Pervasive DataExchange (Data Synchronization Edition)

Both Getting Started guides explain how to install Pervasive DataExchange and guide you through an example replication using two machines.

User’s Guide

The Pervasive DataExchange User’s Guide includes both conceptual and procedural information related to design, activation, and replication. This manual is intended to help you understand the tools and processes used in the replication process.

Pervasive DataExchange User’s Guide includes information applicable to both the Real-Time Backup Edition and the Data Synchronization Edition. It includes reference-based information and task-based instructions that show step-by-step procedures on using the Pervasive DataExchange products.

1-5


1-6

c h a p t e r

2
Pervasive DataExchange Basics
An Overview of DataExchange Basics

This chapter explains the core concepts and routine tasks of using Pervasive DataExchange. Information on working with the engine, logins and DSNs related to Pervasive DataExchange is included. This chapter is divided into the following sections:

“Starting and Stopping Replication” on page 2-2

“Starting and Stopping the DXAgent Service” on page 2-5

“ODBC Basic Concepts” on page 2-7

“Pervasive PSQL Security” on page 2-9

2-1


Starting and Stopping Replication

Depending on the Pervasive PSQL product, the DataExchange Replication Engine runs as a service or a console application. It can be accessed from Pervasive Control Center (PCC). This section covers starting and stopping the engine in all three cases.

As a Service Pervasive DataExchange (REPLSERV.EXE) runs as a service on the machine where Pervasive PSQL Server is installed. It is a single executable that runs under the Windows Service Control Manager. It is configured by default to run when the system starts under the LocalSystem account, which should be adequate for most systems. You can, however, change the account in the Startup Parameters dialog for the service.

To start the Replication service

1 Open the Windows Control Panel.

2 Click Administrative Tools, then Services.

3 Select the Pervasive PSQL Replication icon.

4 Do one of the following:

Select Action Start.

Open the icon and click Start under Service Status.

Right-click the icon and select Start.

To stop the Replication service



3 Select the Pervasive PSQL Replication icon.


Select Action Stop.

Double-click the icon and click Stop under Service Status.

Right-click the icon and select Stop.

2-2

Starting and Stopping Replication

As a Console Application

Pervasive DataExchange Engine (REPLSERV.EXE) runs as a console application on all platforms if Pervasive PSQL Workgroup engine is installed. The application appears as an icon in the taskbar system tray .

By default, Replication Engine starts when the system starts. You can also start it manually.

To start Replication Engine manually

1 Select DataExchange Replication Engine from the Pervasive group on the Start menu.

To stop Replication Engine while running as a console application

1 Right-click the Pervasive Replication Service icon .

2 Select Stop Engine and Exit.

From Pervasive Control Center

To start the Replication service

1 Start PCC if it is not already running. (Select Control Center & Documentation from the Pervasive group on the Start menu.)

In the Engines branch, the Replication icon shows a red dot to indicate the Replication Engine is stopped.

2 In Pervasive PSQL Explorer, expand the Services branch.

3 Right-click Pervasive Replication and select Start Service.Mapache01

M

2-3


In the Engines branch, the Replication icon shows a green arrow to indicate the Replication Engine is running.

To stop the Replication service


In the Engines branch, the Replication icon shows a green arrow to indicate the Replication Engine is running.


3 Right-click Pervasive Replication and select Stop Service.

In the Engines branch, the Replication icon shows a red dot to indicate the Replication Engine is stopped.

2-4

Starting and Stopping the DXAgent Service

Starting and Stopping the DXAgent Service

Pervasive DataExchange Agent runs as a service. It can be accessed from Pervasive Control Center (PCC). This section covers stopping and starting the agent as a service and from PCC.

As a Service Pervasive DataExchange (DXAGENT.EXE) runs as a service on the machine where Pervasive PSQL Server is installed. It is a single executable that runs under the Windows Service Control Manager. It is configured by default to run when the system starts under the LocalSystem account, which should be adequate for most systems. You can, however, change the account in the Startup Parameters dialog for the service.

To start the DXAgent service



3 Select the Pervasive DataExchange Agent icon.


Select Action Start.

Double-click the icon and click Start under Service Status.

Right-click the icon and select Start.

To stop the DXAgent service



3 Select the Pervasive DataExchange Agent icon.


Select Action Stop.

Double-click the icon and click Stop under Service Status.

Right-click the icon and select Stop.

Note DXAgent.exe is not installed with the Workgroup engine.

2-5


From Pervasive Control Center

To start the DXAgent service



3 Right-click Pervasive DXAgent and select Start Service.

In the Services branch, the service icon shows green to indicate DXAgent is running.

To stop the DXAgent service



3 Right-click Pervasive Replication and select Stop Service.

In the Services branch, the service icon shows red to indicate DXAgent is not running.

2-6

ODBC Basic Concepts

ODBC Basic Concepts

Pervasive PSQL follows the Microsoft standard for ODBC database connections. According to the standard, applications must connect to databases through Data Source Names (DSNs) defined in the operating system.

Every Pervasive PSQL database that you expect to access using ODBC must have a Data Source Name (DSN) available on the same computer as the database engine, and (if applicable) another DSN on the client computer. The only exceptions are Pervasive tools, which can access remote databases without using DSNs on the client computer. A DSN created on the same machine as the database engine is called an Engine DSN. A DSN created on the client machine is called a Client DSN.

Note Pervasive PSQL databases that are accessed only through Btrieve do not need DSNs. However, in this case, the database is not visible in PCC nor can it be manipulated using PCC. Pervasive recommends using Data Dictionary Files (DDFs) and DSNs with all databases, including ones accessed only through Btrieve, to make them easier to manipulate.

Servers and Clients

Every Pervasive PSQL server engine or workgroup engine includes a client installation. So you can use your server machine to connect to other servers as a client.

Pervasive PSQL clients can connect to remote machines where a Pervasive PSQL server engine is installed.

Data Source Names

In a client-server architecture, each data set must have a well-known name. A DSN is a well-known name for a data set. There are generally three ways to create DSNs:

Create an Engine DSN from the server console. Workgroup engines require only Engine DSNs.

Create an Engine DSN remotely from a client machine.

Create a Client DSN on each client machine.

2-7


Components of a Database Name

There are two components of a database name. Pervasive PSQL uses an internal Database Name (DBNAME) to identify the location of the Data Dictionary Files (DDFs) and the data files for each database. An ODBC Data Source Name (DSN) entry refers to one DBNAME.

You may set up more than one DSN that refers to the same DBNAME. If the physical location of the data files on the server is changed, only the DBNAME needs to be updated. All DSNs remain unchanged.

2-8

Pervasive PSQL Security

Pervasive PSQL Security

If you are replicating a database with Pervasive PSQL Security enabled, you will be required to supply a user name and password. The user name defaults to Master, which cannot be changed. You enable security in PCC before designing a template for replication.

Note In order to add Pervasive PSQL security to an already activated database, you must first deactivate the database at all sites before adding security. Once Pervasive PSQL security has been added (via PCC) you will then need to reactivate the database.

Deploying Demodata Under Pervasive PSQL Security

Pervasive PSQL provides security models for Btrieve applications. However, the activated databases created by DXdeploy do not contain security, even if the source database does. You may add security to a replication database if you choose. See “Pervasive PSQL Security” on page 2-9 in Pervasive DataExchange User’s Guide. See also the chapter on Pervasive PSQL Security in the Pervasive PSQL Advanced Operations Guide for details.

Getting Started with Pervasive DataExchange (Real-Time Backup Edition) explains how to deploy the sample database Demodata under the Classic security model. If you are using either the Database security model or the Mixed model and you want to retain security, you must ensure that Demodata can be deployed.

The following table explains the high-level actions required to deploy Demodata. Perform the appropriate actions on both the First Site and the Partner Site before attempting the example deployment. See “Working with the Demodata Sample Database” on page 4-3 in Getting Started with Pervasive DataExchange (Real-Time Backup Edition).

2-9


For information on the types of security available, see the chapter “Pervasive PSQL Security” in the Pervasive PSQL documentation.

Table 2-1 Actions Required to Deploy Demodata Under Database Security or Mixed Security

Replication Site

Database Security Model Mixed Security Model

First Add the Demodata directory (for example, <drive>:\Documents and Settings\All Users\Application Data\Pervasive Software\PSQL\Demodata) to the data file locations for DefaultDB.

Add the templates directory (for example, <Installation Directory >\Replication\Templates to the data file locations for DefaultDB.

In PCC Configuration for Server Access, set Prompt for Client Credentials to On. You may accomplish the same thing by using the Pervasive PSQL command-line utility pvnetpass. See the Pervasive PSQL Pervasive PSQL User's Guide for details about pvnetpass.

During the example deployment, a login dialog appears from which you must log in to DefaultDB. Specify the user name and password. On the login dialog, select the option Save User Name and Password. This prevents your having to log in for each table replicated.

After the example deployment successfully completes, remove the saved user name and password with the pvnetpass utility. If you retain the saved user name and password, note that any Btrieve application on the secured site has access to all databases associated with DefaultDB.

Add the Demodata directory (for example, <drive>:\Documents and Settings\All Users\Application Data\Pervasive Software\PSQL\Demodata) to the data file locations for DefaultDB.

Add the templates directory (for example, <Installation Directory >\Replication\Templates to the data file locations for DefaultDB.

In PCC, click Users for DefaultDB. Right-click the Public user, then click Properties.

Click the Permissions tab. Grant all permissions for Public, then click OK.

After the example deployment successfully completes, reset the permissions for user Public as suits your business requirements.

Partner Add the Demodata directory (for example, C:\Demodata) to the data file locations for DefaultDB.

Add the Demodata directory (for example, C:\Demodata) to the data file locations for DefaultDB.

2-10

c h a p t e r

3
Using Pervasive DataExchange
A Guide to Using DataExchange in Daily Operations

This chapter provides in-depth information for using DataExchange on a daily basis. It includes discussions about fundamental concepts, as well as procedural information for dealing with some of the common scenarios you may encounter during replication. The topics in this chapter include:

“Activation” on page 3-2

“Deactivation” on page 3-5

“Adding Tables to an Activated Database” on page 3-7

“Removing Tables From an Activated Database” on page 3-15

“Adding Dynamic Tables to an Activated Database” on page 3-20

“Setting up Nondatabase File Replication” on page 3-24

“Changing a Table Structure in an Activated Database” on page 3-32

3-1


Activation

Activation is the process of creating a new database for replication, or enabling an existing one, and establishing the database as belonging to a site within a replication network so that it can replicate.

Note Because activation associates a database with a site, activating a database and activating a site mean the same thing.

Activation can be done by three methods. The Deployment Tool and dxdeploy utility activate automatically as part of deployment. The dxact utility provides a manual method for activation as well as the flexibility to specify options such as preprocessing of starter data. For this discussion, we use the command-line utility dxact to activate the sample database. However, it’s important to first understand some of the concepts of the activation process.

Activation and Data Source Names

When you activate a database, Pervasive DataExchange creates a system data source name (DSN) to point to the activated copy. The DSNs with the prefix xPD are created by the design process. The activation process creates DSNs with names like PDxxxxxxxx.

Another system database is the Database Network Analysis (DNA), which is the replication database called PDDNA. It is created during DataExchange installation. The database appears in Pervasive PSQL Explorer with the DNA icon in its Replication node.

Caution Do not alter or attempt to use the DNA database (PDDNA). Doing so can corrupt the DataExchange installation.

3-2

Activation

Activating First and Partner Sites

The First Site is unique and must be activated before you activate any of the Partner Sites. When activating the First Site, Pervasive DataExchange populates its system tables with information needed to manage the distributed environment. This information is subsequently replicated to all other sites in the network as they are activated.

The First Site is special because it contains information about the replication network and is the only site where DataExchange Designer is installed. Once the First Site is activated, you may activate your Partner Sites in any order.

Tip The Replication Engine must be running to activate a database.

After activation of the First Site is complete, you can activate the databases at the Partner Sites. Activate Partner Sites from each site itself. That is, you execute the Deployment Tool, dxdeploy.exe or dxact.exe on the Partner Site, not on the First Site.

If possible, the machine should have a network connection through which it can communicate with the First Site so that the initial replication session can start immediately. This is not mandatory, however. You can perform the initial replication at a later time if you prefer. A Partner Site cannot replicate with other Partner Sites until it performs an initial replication with the First Site.

Once you’ve successfully performed activation, Pervasive Control Center displays the database as activated, wit the Replication node icon showing an A.

Once the initial replication has succeeded, the newly installed site is fully aware of all administrative data in that workgroup, including all replication schedules.

3-3


For more information

Specific information about using each of the DataExchange deployment utilities mentioned in this chapter is available in Chapter 7, “Using the DataExchange Utilities and Services.” The following table provides specific reference information.

To activate using dxact.exe

1 On the site machine you want to activate, open a command prompt window to start dxact.exe.

2 At the prompt, type a command similar to the following:

dxact demodata /FI

This example activates the demodata database on the First Site using the dxact.exe utility. By default, messages from dxact.exe are written to the dxact.log file, not to the screen. To view the messages on the screen while dxact.exe runs, use the /LOGFILE= option. To do so, you would enter a command similar to the following:

dxact demodata /Logfile= /FI

The /FI option specifies you are activating the First Site, but you should always run dxact.exe from the site you want to activate—remote activations are not available in DataExchange. For the complete list of dxact.exe options available, see “dxact” on page 7-6.

Now that we’ve covered the basics of activation, let’s take a moment to discuss deactivation and reactivation.

Activation Method For more information...

Deployment Wizard (Dpwizard.exe) See “dpwizard” on page 7-32

Dxdeploy.exe See “dxdeploy” on page 7-13

Dxact.exe See “dxact” on page 7-6

3-4

Deactivation

Deactivation

Deactivation is the disabling of an activated database in a replication network. Deactivation uses the dxdeact utility as explained in Chapter 7, “Using the DataExchange Utilities and Services.”

If you deactivate a database on the First Site, Pervasive Control Center displays the First Site database as a design template, since it was used to design the database for the replication network. When the First Site is deactivated, the Replication node icon displays a T.

When a Partner Site is deactivated, in Pervasive Control Center on that site the Replication node icon for the database no longer displays an A for activation.

Other sites do not detect a deactivated site until replication occurs, which fails for the deactivated site. This is normal and generates an error message similar to the following in the DRE.log file:

E 019f 0301-15:46:25 Partner site Partner_Site_2 (site number:

00LFLU) has been removed from the replication network - it

cannot replicate with any other site.

After the failed replication, the error no longer occurs because all sites in the replication network have detected the deactivated site.

3-5


To deactivate using dxdeact.exe

1 On the site machine you want to deactivate, open a command prompt window to start dxdeact.


dxdeact demodata

This example deactivates the demodata database using the dxdeact utility. By default, messages from dxdeact are written to the dxdeact.log file, not to the screen. To view the messages on the screen while dxdeact runs, use the /LOGFILE= option just as you did earlier with dxact.exe. It’s helpful to note that all the DataExchange Utilities provide the /LOGFILE= option to control logging output. For the complete list of dxdeact.exe options available, see “dxdeact” on page 7-11.

Reactivation Reactivation is the reenabling of a deactivated site for replication. A database must be deactivated before it can be reactivated. Reactivation is, in essence, the same as activation in that you use the dxact utility in the same manner as you did when you activated.

If you deactivate a First Site, you must perform a manual replication if you reactivate the First Site. After you reactivate the First Site, you must manually initiate a replication session from each Partner Site to the First Site. The replication sessions ensure that all available sites appear on the Initiate Replication dialog.

Note Manually initiating a replication session is not required if you deactivate/reactivate a Partner Site; it applies only to a First Site.

3-6

Adding Tables to an Activated Database


Once a database has been activated and replication is set up between two or more database servers, you may find that you need to add a table to the replication design. This could be a table that did not previously exist or was not deemed as necessary for replication when you originally designed your replication database.

Before you Begin

You must make certain that the replication schedule associated with the replication design you are changing is currently disabled and that no users are working on the system.

One of the steps you must complete is to deactivate the database, and it is always a good practice to disable any replication schedules before deactivation.

Caution No user should be using the system during the add table process because any modification to the database will not be captured while databases are deactivated.

The following lists the high level steps needed to successfully add a table to an already activated database. Each of these high level steps includes detailed instructions required to complete that phase. The high level steps are as follows:

Determine Event Handler DLL Usage

Deactivate All Sites

Verify the Table Exists in the Pervasive Database

Add the New Table to the Replication Template

Stop Replication Service on Partner Sites

Copy Files (DDFs, D- and PDC Tables)

Activate First Site and Synchronize Tables

Start Replication Service on Partner Sites

Activate Partner Sites

Initiate Replication

3-7


Determine Event Handler DLL Usage

First you need to know if an Event Handler DLL is used in your activated database. Knowing this determines whether you need to use the /DL=<string> option when using dxact.exe.

To determine Event Handler DLL usage

1 Verify if the database has an Event Handler DLL registered by opening a command prompt and typing the following command:

dxregevnt show database_DSN

2 A message displays if your database is using an Event Handler DLL and lists the name of the event handler (dxevent.dll).

If you do not have an Event Handler DLL registered, the following message displays:

No Event Handler is Registered

3 If you have a DLL registered, you must include the /DL=<string> option with the dxact command when you activate or reactivate the database.

Note The /DL=<string> option for dxact.exe enables the activated database to make use of a event handler, or callback, DLL. If you use the /DL=<string> option when activating databases, you must stop and restart the Pervasive PSQL Replication service in order for the callback DLL to be registered and take effect.

The activation examples provided in this chapter assume that you do not require the /DL=<string> option when using dxact.exe.

Deactivate All Sites

Before you change your replication design to include the new table, you must first deactivate all sites.

To deactivate all sites

1 On the First Site open a command prompt.


dxdeact database_DSN

database_DSN represents the DSN of the activated database to which you want to add the table.

3-8


3 Repeat these steps at each Partner Site associated with the replication network until all sites have been deactivated.

Note No additional options are required for dxdeact.exe.

Verify the Table Exists in the Pervasive Database

Before you can add a table to a DataExchange replication database, you must first make sure the table you are adding has been added to the Pervasive PSQL database. The physical file must be present in the data directory of the database. Also, the table must have data dictionary files (DDFs) defined for it. (If you can see the table in the PCC list of tables then it has DDFs defined.)

Tip It is not necessary to have the contents of the new table accurately defined, just make sure the path properly points to the file to replicate.

To verify the table exists in the Pervasive Database

1 At the operating system, ensure that the physical table file is located in the data directory of the database.

For example, suppose that you want to add the table Campus.mkd to the DEMODATA sample database. You would ensure that Campus.mkd resides in the DEMODATA data directory (which, by default, is <drive>:\Documents and Settings\All Users\Application Data\Pervasive Software\PSQL\DEMODATA).

2 Open Pervasive Control Center and expand the database list to display the DSN to which you are adding the table.

3 If the table you want to add is in the list of tables, you are finished with this task. Continue with the next section, “Add the New Table to the Replication Template.”

4 If the table you want to add is not in the list of tables, you need to create a data dictionary file (DDF) for it. Open the database in PCC and execute the following statement to create the DDF for the new table:

CREATE TABLE tablename IN DICTIONARY USING 'data file location' (table element definition(s))

3-9


For example, if you were adding Campus.mkd to the DEMODATA database and the Campus.mkd file is stored in the default data directory, you would a command similar to the following:

CREATE TABLE Campus IN DICTIONARY USING 'Campus.MKD' (COL1 CHAR(20))

Add the New Table to the Replication Template

The original replication template has to be redesigned to include the newly added table.

To add the new table to the replication template

1 On the First Site, start DataExchange Designer (for example, open Pervasive Control Center and click DataExchange Designer).

Designer opens, listing all the templates available to modify.

2 In the list, click the database name that you deactivated in section “Deactivate All Sites,” then click Finish.

Tip If you do not see the deactivated database, check the dxdeact.log to verify that the site was properly deactivated.

This opens Designer, which lists all the tables being replicated in the current design.

Note If you have used Dxdeploy.exe or the Deployment Tool to activate your database, you may have never seen the Designer before. For detailed information on using the DataExchange Designer, see Chapter 8, “Using the DataExchange Designer.”

3 In the Database Design pane, click the Not Replicated tab.

4 Select the table that you want to add.

5 Click Actions Replicate Table from the menu bar, or right-click then click Replicate Table.

3-10


Tip If you are adding multiple tables, select all the tables you want to add.

6 Click the Replicated tab and verify the table was added.

7 Click File Save to save the changes.

8 From the menu bar select Tools Create Replication Template. A dialog displays asking you if you want to Prepare Database data for replication to other sites.

9 Clear the check box and click OK.

You do not want to prepare data for the other sites, which is why you clear the check box.

10 Click OK when the message displays confirming that the replication template has been created.

11 Click File Exit to close the Designer.

12 Exit PCC if it is running.


Because you need to copy files, including ones used for replication, from the First Site to the each Partner Site, you need to stop the replication service on the Partner Sites.

Follow the steps listed in “To stop the Replication service,” on page 2-2 or, if using PCC, in “To stop the Replication service,” on page 2-4.

Copy Files (DDFs, D- and PDC Tables)

To make certain the correct data is available to the replication network, you’ll need to identify the files that you will later need to synchronize.

3-11


To identify files

1 On the First Site, find where the replication-specific files are stored and sort the files by date.

For example, locate the files Dtblchg.mkd and Dcnf.mkd, which are replication-specific files.

Notice, after sorting the files by date, that a number of D*.mkd tables have been updated, and a new PDC table has been created for the new table you just added.

2 Select the following set of files:

The D*.mkd files that have been updated based on your creating DDFs for the new table, or that have been updated since the time you used Designer to add a new table to the replication template.

The PDC for the data table you just added (PDCdatafilename).

The updated DDFs for the replication database (such as FILE.DDF, FIELD.DDF, and INDEX.DDF).

Note Not all D-tables may have been updated. Copy only the D-tables that were updated.

3 Copy the set of files to their corresponding location(s) on a Partner Site. Click “Yes” to replace existing files.

4 Delete all data from the newly added table and from the PDC file for the newly added table. (For example, edit the table with PCC, select all rows then delete them.)

5 After deleting the data from the table and from the PDC file on one Partner Site, copy the set of files mentioned in Step 2 from that Partner Site to the other Partner Sites. Click “Yes” to replace existing files.

Activate First Site and Synchronize Tables

Now that you have copied the new table and the replication-related files to the Partner Sites, you need to active the First Site and synchronize the files.

To activate the first site and synchronize data

1 Activate the First Site using dxact.exe.

3-12


Note You may need to use the /DL<string> option as discussed in “Determine Event Handler DLL Usage” on page 3-8.

The activation command is the following:

DXACT /FI database_DSN

For example, if you wanted to active the DEMODATA sample database, the command is DXACT /FI DEMODATA.

2 Next, you run dxsynctables.exe to populate the PDC table with the initial data from the new user table.

Enter the following command:

DXSYNCTABLES table_name database_DSN

For our example, if you had added a table Campus to the DEMODATA sample database, you would enter the following:

DXSYNCTABLES Campus DEMODATA

If you are adding multiple tables, repeat this command for each new table.


Now that you have copied files from the First Site to the each Partner Site, you can start the replication service on the Partner Sites.

Follow the steps listed in “To start the Replication service,” on page 2-2 or, if using PCC, in “To start the Replication service,” on page 2-3.

Activate Partner Sites

After the First Site is activated and the files synchronized, you can activate the Partner Sites.

1 Activate each Partner Site using dxact.exe and the /PA[RTNERADDRESS]=<string> option, to designate the site with which you will replicate.

Tip The string represents the address of the machine with which you are going to replicate. If your Partner Site replicates with the First Site, you will enter the machine address for the First Site.

For example, if the First Site’s address is SiteA, you would enter a command similar to the following:

3-13


DXACT /pa=SiteA database_DSN



You now need to initiate replication to ensure that the new table is recognized throughout the replication network. Refer to the steps in “To replicate data from First Site to Partner Site” on page 4-14.

After a successful replication to all Partner Sites, you can resume your replication schedules and allow your users to return working on the system.

3-14

Removing Tables From an Activated Database


You may find yourself in a situation where an already activated database contains a table that was originally specified for replication and now needs to be removed from the replication design. This could be because the table is no longer part of the database schema or is no longer required for replication and the users doesn't want the overhead of replicating the table.

Removing tables from an already activated database requires very similar tasks as were required for adding tables to an activated database, with the exception of dropping the table as opposed to adding a new table.

Before you Begin

This section discusses the steps required in order to remove a table to a database that is already activated. The high level steps included in this process are as follows:

Deactivate all Sites

Remove Table From the Replication Template


Copy D*.mkd Tables


Activate all Sites


Make sure that the replication schedules are disabled and that no users are working on the system. The process of removing a table includes deactivating the replication database, and it is always a good practice to disable any replication schedules before deactivation. In addition, no user should be using the system during this process because any modification to the database will not be captured while databases are deactivated.

Deactivate all Sites

Removing a table from an activated database uses the DataExchange Designer to remove the table from the replication design. To do this, you must first deactivate all sites.

Deactivate all sites

1 On the First Site open a command prompt.

3-15



dxdeact database_DSN

database_DSN represents the DSN of the activated database from which you want to remove the table.

Note No additional options are required for dxdeact.exe.

3 Repeat this step at each Partner Site associated with the replication network until all sites have been deactivated.

Remove Table From the Replication Template

Remove table from the replication template

1 On the First Site, open Pervasive Control Center and start the Designer by selecting DataExchange Designer.

Designer opens, listing all the templates available for modification.

2 Select the database that you just deactivated and click Finish.

Tip If you do not see the deactivated database with the T icon in PCC, check the dxdeact.log to verify that the database was properly deactivated.

This opens Designer, which lists all the tables being replicated in the current design.

Note If you have used Dxdeploy.exe or the Deployment Tool to activate your database, you may have never seen the Designer before. For detailed information on using the DataExchange Designer, see Chapter 8, “Using the DataExchange Designer.”

3 In the Database Design pane, click the Replicated tab , then click the table(s) that you want to remove.

4 Click Actions Don’t Replicate Table from the menu bar, or right-click and select Don't Replicate Table. Do this for each table you want to drop, if there is more than one.

3-16


5 Click the Not Replicated tab in the Database Design pane and verify the tables that you just removed are listed here.

6 Click File Save to save the changes.

7 From the menu bar select Tools Create Replication Template. A dialog displays asking you if you want to Prepare Database data for replication to other sites.

8 Clear this check box and click OK.

9 Click OK when the message displays confirming that the replication template has been created.

10 Select File Exit to close the Designer.


Because you need to copy files used for replication from the First Site to the each Partner Site, you need to stop the replication service on the Partner Sites.

Follow the steps listed in “To stop the Replication service,” on page 2-2 or, if using PCC, in “To stop the Replication service,” on page 2-4.

Copy D*.mkd Tables

To identify files

1 On the First Site, find where the replication-specific tables are stored and sort the records by date.

For example, locate the files Dtblchg.mkd and Dcnf.mkd, which are replication-specific files.

Notice, after sorting the files by date, that a number of D*.mkd tables have been updated as a result of redesigning the replication template.

3-17


2 Select the D*.mkd files that have been updated based on your redesigning the replication template.

Note Not all D-tables may have been updated. Copy only the D-tables that were updated.

3 Copy and paste these tables into each of the Partner Sites replication data directories overwriting the files there with these new files.


Now that you have copied files from the First Site to each Partner Site, you can start the replication service on the Partner Sites.

Follow the steps listed in “To start the Replication service,” on page 2-2 or, if using PCC, in “To start the Replication service,” on page 2-3.

Activate all Sites

To activate all sites

1 Activate the First Site using dxact.exe. You must activate the First Site before you activate any Partner Sites. From a command line, you would run the following:

DXACT /FI demodata

2 Activate each of the Partner Sites using dxact.exe and the /PA[RTNERADDRESS]=<string> option to designate the site with which you will replicate.

For example the First Site’s address is SiteA, so you would enter a command similar to the following:

DXACT /pa=SiteA Demodata

You may need to use the /DL=<string> option as discussed in “Determine Event Handler DLL Usage” on page 3-8 at the beginning of this chapter.


3-18



You now need to initiate replication to ensure that the removed table is no longer replicated. Refer to the steps in “To replicate data from First Site to Partner Site” on page 4-14.

After a successful replication to all Partner Sites, you can resume your replication schedules and allow your users to return working on the system.

3-19


Adding Dynamic Tables to an Activated Database

Your database may add new tables dynamically, which is a different scenario than was discussed in the previous section where we added a table to our database as part of an updated design. There are situations where databases are designed to generate tables automatically, and these tables may need to be included in your database replication.

DataExchange provides a way to include these new dynamic tables in—or exclude certain tables from—the set of replicated tables for an activated database. Only table files should be included because only tables may be replicated. Any type of file may be excluded if you want (nontable files are not replicated whether you exclude them or not).

The new tables are identified by a pattern-matching algorithm, which uses glob-style patterns in both regular and dir expressions. You specify which file patterns you want the algorithm to use. The patterns are the only input required from you. DataExchange does the rest automatically. By default, the patterns are blank.

DataExchange first compares file names for the include pattern then compares file names against the exclude pattern. Only files whose names pass both comparisons are included. For example, suppose you specify c:\mydata\*.d?? as an include pattern. If you specify an exclude pattern of c:\mydata\*.ddf, then all files in c:\mydata will be included except for ones with a file extension of “ddf.”

Tip For a detailed discussion about the types of expressions you can use as include and exclude patterns with dxdynpath, see “Types of Expressions” on page 7-18.

The inclusion or exclusion of tables begins when a table is successfully opened with the database open API. DataExchange then determines whether the table is identified as one to be replicated (that is, is the table new to replication). If the table is new and its name matches only with the exclude pattern, DataExchange takes no replication action on the table. DataExchange includes a new table if its name does not match with the exclude pattern but does match with the include pattern. Initially, after a successful open, the table is

3-20


simply identified to DataExchange as being new. Data in the new table is not immediately replicated.

The next replication process (for example, from a scheduled replication) prepares the new table for replication and synchronizes the replication information about it on all sites. The second replication process includes the new table. Note, then, that the actual replication of data to or from a new table requires two replication cycles.

Note Inclusion of dynamically created tables applies only to Real-Time Backup replication. In addition, the dynamically created tables must be on the machine where the database application is running. That is, the tables must be on the machine that serves as the source location from which data is replicated.

Before you Begin

If you’re unfamiliar with expressions or have had little exposure to working with them, we strongly recommend you first review “Types of Expressions” on page 7-18 to gain a basic understanding of how to work with the different types of expressions.

Caution It is critical to note that any file being considered for use with the dxdynpath utility requires system keys.

Include File Patterns

In our example database, demodata, we’ll be automatically generating a set of tables every day that contain the attendance records for each campus. This is important data that must be included in the replication. We’ll add an include pattern using dxdynpath so these tables get replicated as well. The tablename uses a naming convention of attend<campusid>.mkd, where <campusid> is the three letter campus code.

Caution This section only applies if your application dynamically creates new tables for an activated database. This process is only recommended as a solution for tables that are added dynamically.

3-21


To include new tables for replication

1 On the First Site, open a command prompt and type the command:

dxdynpath /t=include /pa="dir attend*.mkd" append demodata

2 Verify that the include pattern is there by typing the following command:

dxdynpath /t=both show demodata

A message should display that lists the name and version of the dynamic table configuration and test utility, and additional information such as the following:

INCLUDE pattern is "dir attend*.mkd"

EXCLUDE pattern is ""

You may want to manually initiate replication after you specify new files to include. This completes the first cycle of replication required to prepare the dynamic tables for replication. The new tables are then ready for the second cycle (for example, a scheduled replication) in which data is replicated.

Exclude File Patterns

Now let’s fine tune our pattern expressions for our example database. We’ve included all of the attend*.mkd files, but there is a cumulative file (attendall.mkd) that gets created too. Since we have all the individual files that are included in the cumulative one, we don’t really need that file replicated. So, we’ll exclude it from our pattern matching.

To exclude files from replication

1 On the First Site, open a command prompt and type the following command:

dxdynpath /t=exclude /pa="dir attendall.mkd" append

demodata

2 Verify that the exclude pattern is there by typing the following command:


A message should display that lists the name and version of the dynamic table configuration and test utility, and additional information such as the following:

3-22


INCLUDE pattern is "dir attend*.mkd"

EXCLUDE pattern is "dir attendall.mkd"

These are simple examples to illustrate how dxdynpath uses pattern matching to determine what files are replicated. For a detailed discussion on using dxdynpath and the different types of expressions you can use, see “dxdynpath” on page 7-15.

3-23


Setting up Nondatabase File Replication

Your Pervasive PSQL database application may require ancillary (nondatabase) files in order to function properly. Typically these files would be missed by replication, since they are outside of the database structure and replication design. In this scenario, it is critical that you associate copying these files with your replication sessions. Doing this ensures that all the data needed by your application is replicated.

DataExchange includes a DLL file (dxevent.dll) which enables you to run independent applications triggered by replication events. This file is referred to as the Event Handler DLL or Callback DLL. The replication events supported in this DLL include the following:

OnReplicationRequest

PreSessionStart

PostSessionStart

OnSessionEnd

Using this event callback mechanism, a flat-file copying tool such as ffcopy.exe, can be used to coordinate the copying of nondatabase files with database replication. This document explains how to register dxevent.dll with DataExchange so that the Flat File Copy Utility (ffcopy.exe) performs flat file replication.

There is more information about this feature on the installation (<Installation Directory >\replication\docs\ffcopy.txt and <Installation Directory >\replication\docs\dxevent.txt).

Before You Begin

You should ensure the following items before beginning this procedure:

You must have administrative rights and DOMAIN administrative rights on the computers to be configured.

Before performing this process, ensure that no replication sessions are running and disable any replication schedules.

High level steps include the following:

Set Log On Properties

Create New Flat File Database

Execute the SQL Queries

3-24


Create the Design Template

Copy Files

Activate all Sites

Restart DX Services

Redesign Dxevent Table

Create Site Shares

Configure Flat File Replication

Set Log On Properties

To set the Log On Properties

1 On the First Site, open the Windows Control Panel and select Services.

2 From the Services dialog, right-click Pervasive PSQL Replication and select Properties.

3 Select the Log On tab from the Properties dialog. Change the log on from a system account to the Domain admin account. This user must have access to the directory on the remote computer so that the files may be replicated.

4 Click Apply, then stop and restart the Pervasive PSQL Replication service.

Create New Flat File Database

Next, you’ll need to create a database to store the replication file information.

To create the new flat file database

1 Create a new directory for the replication file information database.

2 Open Pervasive PSQL Control Center (PCC) and expand the tree to show the machine that you are on.

3 Right-click Databases and select New Database, using FlatFileRepl for the name and the path to the directory you created in step 1.

4 Click Finish.

In the next task, you will run SQL statements to populate the FlatFileRepl database.

3-25


Execute the SQL Queries

To execute the SQL Queries


2 Select File Open and browse to the directory <Installation Directory >\Replication\Docs.

3 Open the file dxEvent.sql.

PCC asks you to select a database.

4 Select FlatFileRepl.

SQL Editor opens the file.

5 Click in the SQL Editor.

The SQL query should look similar to the following:

--This SQL script creates a table for use with dxEvent.dll.--See dxEvent.txt for more information. Some V8 FTF/hotfix --require the following set statement so that true bits are --created for the dxEvent table.

SET TRUEBITCREATE = ON #

create table dxEvent (dxEventType char(30) not null, Command char(128) not null, Wait bit, NeedArgs bit, Ignore bit) #

create index dxEventTypeIdx on dxEvent(dxEventType) #

insert into dxEvent values ('OnReplicationRequest', 'Example: put command and args here', 0, 0, 1) #

insert into dxEvent values ('PreSessionStart', 'Example: put command and args here', 0, 0, 1) #

insert into dxEvent values ('PostSessionStart', 'Example: put command and args here', 0, 0, 1) #

insert into dxEvent values ('OnSessionEnd', 'Example: put

command and args here', 0, 0, 1) #

6 Select SQL Execute All SQL Statements.

7 Click Edit Select All and delete the contents of the Query Pane. Do not save these changes.

8 Click File Open, but this time select the ffcopy.sql file, also located in the <Installation Directory >\Replication\Docs directory.

9 Execute this query in the same way and you should see the query has executed successfully.

3-26


10 Close the SQL Editor.

Create the Design Template

To create the design template

1 In PCC, open DataExchange Designer by selecting DataExchange Designer.

2 Enter FlatFileRepl for the location, select 1-way for the replication method, and click Next.

3 Enter project, network and release names for this replication. For our example, we will use Flatfilerepl for Project, Flatfile for Network, and 1.0 for Release.

4 Click Next, confirm your choices, and click Finish.

5 In the Database Design pane, click the Not Replicated tab.

6 Select both table names, holding down shift while clicking.

7 Click Actions Replicate Table from the menu bar, or right-click and select Replicate Table.

8 You should now see the files are in the Replicated tab. Click File Save or the save icon from the Designer toolbar.

9 From the menu bar, click Tools Create Replication Template. The Create Replication Template - Starter Data dialog displays.

10 Select the Prepare database data for replication to other sites checkbox on this dialog, and click OK. After a few moments, a message displays saying the template was created successfully.

11 Click OK and then close the Designer window.

3-27


Copy Files Now we need to copy the database that we just designed over to the Partner Site.

To copy files

1 Copy the FlatFileRepl directory to the Partner Site.

Tip It is not necessary to put the FlatFileRepl directory in the same place as the First Site, but it may make it easier to find in the future.

2 Once you copy the files to the Partner Site, open PCC on the Partner Site, and expand the tree to show the machine that you are on.

3 Create a database here just like we did on the First Site. (See “Create New Flat File Database,” on page 3-25.)

Activate all Sites

To activate all sites

1 At the First Site, open a command prompt and execute the following command:

Dxact /fi /dl=c:\<Installation Directory

>\bin\dxevent.dll flatfilerepl

Note Your installation directory may be on a different drive as above. Check to make sure that your path to the dxevent.dll is correct. If there are any problems with the activation, check the dxact.log file.

2 Go back to the Partner Site and open a command line. Execute the following command:

Dxact /pa=<name of first site> /su flatfilerepl

3 Back on the First Site open the Statistics and Log View window, and you should see the replication session running between the two sites.

4 After the two databases have finished replicating, you will need to close all the windows associated with PCC and close PCC itself.

3-28


Restart DX Services

To restart DX services

1 Go to Control Panel Administrative Tools Services and select the Pervasive PSQL Replication service; stop and restart this service.

Now when the replication engine starts, the dxevent.dll will be loaded into memory for the FlatFileRepl database.

2 Resume any schedules that were previously turned off when you started this process.

Redesign Dxevent Table

At this point the databases are activated and running. We now need to go into each of the tables that we designed previously and supply the info to replicate the flat files.

To redesign the dxevent table

1 On the First Site, open PCC, expand the tree and select the Tables node in the FlatFileRepl database. The user tables and tables needed for replication display. The replication tables are specifically for replication, so don't open or modify any of them.

2 Double-click the dxevent table to open the table in PCC. The SQL Editor lists four sample entries, as shown in the next illustration.

Note You may need to scroll to the right to see that the Ignore column is set to True so that these do not actually run.

3-29


3 Click the first empty row and type OnSessionEnd in the dxEventType column. Tab to the Command column and type ffcopy.exe followed by a space and then the full path to the Filestocopy.mkd file. For example:

ffcopy.exe c:\temp\flatfilerepl\filestocopy.mkd

The row you enter should look similar to the following in the Data Manager:

4 Tab through the rest of the columns, do not check any of the boxes, and close the Pervasive PSQL Data Manager.

Create Site Shares

To create site shares

1 Locate the directory or directories you want to copy flat files from and share the folder that they are contained in.

2 On the Partner Site locate the directory or directories you want the files copied to and share them as well.

Configure Flat File Replication

To configure flat file replication

1 Back on the First Site in PCC, double-click the FilesToCopy table to open it in the SQL Editor.

2 In the LocalFN column, supply the full path to the files you wish to copy from the First Site. Example:

c:\data\reports\*.doc

Tip To replicate all files in the directory use * not *.* You can use wild cards, or ?, or supply the exact file names. See the ffcopy.txt file located in <Installation Directory >\replication\docs.

3 In the RemoteFN column, supply the full path to the directory where the files are to be copied on the Partner Site. Example:

\\partnerMachine\sharedDirectory\reports\*

4 Tab to the next column, ReserveInt1, and type 0 (zero). Now, enter 0 (zero) again in the next column, ReserveInt2.

3-30


5 In the PartnerSideDelete column, type 1 if you want the Partner Site to delete the file when it is deleted from the First Site, otherwise enter 0 (zero).

6 Enter 0 (zero) in the remaining columns.

You may enter as many directories in the table as needed.

7 In PCC, right-click the Replication - Connected node in Pervasive PSQL Explorer, then click Statistics and Log Views.

The Replication Progress and Log Viewers open.

8 In the toolbar, click the Initiate replication icon .

The Initiate Replication dialog appears.

9 Click Replicate.

The actual data replication session will complete in a few seconds. Recall that we set OnSessionEnd to kick off the flat file replication, so this is when the files actually start replicating.

10 Confirm that the files are reaching their destination. If you encounter problems, see the ffcopy.log file located in <Installation Directory >\replication\logfiles for more information.

3-31


Changing a Table Structure in an Activated Database

You may have a situation where a table that is currently part of a replication design has been changed structurally, or the system keys were updated, and these changes need to get synchronized with the remaining sites. You’ll need to make certain that these changes are properly implemented with your replication design, the changes are synchronized across the replication network, and that you are able to successfully replicate with the changes in place.

Before you Begin

It is strongly recommended that you ensure the following items before beginning this procedure:

Make sure that the replication schedules are currently disabled and that no users are working on the system. This procedure includes deactivating the database, and it is always a good practice to disable any replication schedules before deactivation.

Caution It is important that no user should be using the system while tables are being modified because any changes to the database will not be captured while databases are deactivated.

It is critical that the system keys for records in each of the user tables are accounted for in the user table's corresponding PDC table. This is the mechanism that replication uses to track which records need to be sent to the other sites in the network. If there ever becomes a disconnect between the user and PDC table it can prevent replication from doing its job.

When you add or remove columns from the table at the First Site, make certain you remember to make the same changes to the table on the Partner Site so that the DDFs will reflect the same structure for the tables.

The procedures in this document assume that all sites in the replication network were synchronized prior to new schema changes.

The high level steps needed to complete this procedure are as follows:

Clone PDC Table(s)

Copy Files and Activate the Partner Site

3-32

Changing a Table Structure in an Activated Database

Verify the Replication Session

Clone PDC Table(s)

Although it is not required that a blank copy of the PDC table be used, doing so will:

Reduce the overall size of the PDC table because it will only contain the new records, thus reducing transmission time to the other sites.

Speed up the dxsynctables process because dxsynctables will not have to verify preexisting records in the PDC table.

To clone PDC tables

1 Identify the tables that were modified in the user's data. This is usually on the customer's production site.

2 In the replication data directory, locate the corresponding PDC table for each of the modified tables.

3 Clone the PDC tables and replace the existing ones with the cloned ones.

Tip For information on using the BUTIL utility to clone tables, see the Advanced Operations Guide in the Pervasive PSQL user documentation.

Activate the First Site and Synch Tables

1 Activate the First Site using the dxact.exe command.

DXACT /FI <Database_DSN>

For example, if you wanted to active the DEMODATA sample database, the command is DXACT /FI DEMODATA.

2 For each modified table, run this command from a command prompt:

DXSYNCTABLES <TableName> <DSN>

3-33


Note This process may take some time to run, depending on the number of records contained in the user table. Tests indicate that in cases where there are several million records or more, disabling L2 caching can reduce the population times and speed up this process significantly. Make sure to reenable L2 after the user is finished with all the tables.

Copy Files and Activate the Partner Site

To copy files

1 Copy the newly modified user tables and newly populated PDC table(s) to the appropriate directories at each of the other sites in the replication network. Make certain that you overwrite the already existing tables there.

2 Activate each Partner Site using dxact.exe and the /PA[RTNERADDRESS]=<string> option, to designate the site with which you will replicate.

For example, if the First Site’s address is SiteA, you would enter a command similar to the following:

DXACT /pa=SiteA <Database_DSN>

Verify the Replication Session

To verify the replication session

1 On the each site that should have replicated, browse to the LogFiles directory.

This folder is located at <Installation Directory >\Replication\LogFiles.

2 Open the file dre.log and check for messages indicating success or errors.

3 Reenable replication schedules.

You may now allow your users to return to the system.

3-34

REAL-TIME BACKUP EDITION

c h a p t e r

4
Real-Time Backup Deployment Models
A Look at Alternative Deployment Models for Real-Time Backup

DataExchange provides different deployment methods for Real-Time Backup replication. This chapter discusses the deployment methods available for the most common network configurations and provides you with information in addition to the deployment method between two machines discussed in Getting Started with Pervasive DataExchange Real-Time Backup Edition. This chapter also discusses disaster recovery procedures in the event you need to restore a replicated database. The sections in this chapter include the following:

“Real-Time Backup Configurations” on page 4-2

“Replication Deployment using the Deployment Tool” on page 4-5

“Replication Deployment using DXDeploy” on page 4-6

“Replication Deployment Using Designer” on page 4-7

“Many-to-One Deployment using DXDeploy” on page 4-18

“Disaster Recovery” on page 4-24

4-1


Real-Time Backup Configurations

DataExchange offers three options for Real-Time Backup deployment. An interactive deployment method uses the Deployment Wizard, which automates the entire deployment process and enables creating a replication schedule. Another deployment method uses the DXDeploy utility, which automates several of the processes necessary for replication. The other deployment method uses the Designer and the DataExchange utilities to perform the replication processes. Before you consider what deployment option to use, you should first consider how you will want to configure Real-Time Backup.

Two-Machine Configuration

The most common configuration for Real-Time Backup replicates data between two machines in real-time from a Pervasive PSQL database to a standby server. Upon a system failure, clients can be directed to the up-to-date standby server. Operating at the database level, DataExchange captures database changes on the primary server and applies them to the backup server.

This type of configuration allows DataExchange to avoid errors common to disk-based replication tools, like replicating corrupt data, spreading viruses, or deleting desired user data. With Pervasive DataExchange powering a standby server, data loss, and down time is greatly lessened in the event of system failures, hardware failures, or site disasters.

The following figure illustrates a one-way replication backup network using two machines.

4-2

Real-Time Backup Configurations

Figure 4-1 Real-Time Backup with Two Machines

In this scenario, you have one server, Server A, networked with your backup server. The server runs its own database, dbA. DataExchange then maintains a copy of the database on the standby backup server and replicates with the server at the backup location when changes are applied.

See “Replication Deployment using the Deployment Tool” on page 4-5 for information on starting the DataExchange Deployment Wizard.

Refer to Chapter 4, “Replication Deployment,”in your Getting Started with Pervasive DataExchange Real-Time Backup Edition manual for instructions on implementing Real-Time Backup on a two machine configuration using DXDeploy.

See “Replication Deployment Using Designer” on page 4-7 for instructions on implementing Real-Time Backup on a two machine configuration using Designer and the DataExchange utilities.

Many-to-One Configuration

The other configuration commonly used with Real-Time Backup consists of several database servers at different locations that replicate data to a backup standby server hosting multiple backup databases. This is referred to as a many-to-one configuration. The following provides an illustration of this type of configuration.

4-3


Figure 4-2 Real-Time Backup with Many-to-One Configuration

In this scenario, you have three servers, Server A, Server B, and Server C. Each machine is networked with your backup server. Each server runs its own database, dbA, dbB, and dbC, respectively. DataExchange then maintains individual copies of each database to the standby backup server and replicates with the server at the backup location when changes are applied.

Refer to “Many-to-One Deployment using DXDeploy,” on page 4-18 for instructions on implementing Real-Time Backup on a many-to-one configuration using DXDeploy.

Note Currently DataExchange only supports implementing Real-Time Backup on a many-to-one configuration using DXDeploy.

4-4

Replication Deployment using the Deployment Tool

Replication Deployment using the Deployment Tool

Real-Time Backup deployment can be implemented using the DataExchange Deployment Tool. The Deployment Tool is a step-by-step wizard for deploying replication at First and Partner Sites and includes a means of creating a replication schedule. The Deployment Tool provides automation of the procedures for the DataExchange command-line utility dxdeploy.exe.

Access the Deployment Tool from Pervasive Control Center by selecting DataExchange Deployment Tool or by selecting DataExchange Deployment Tool from the Pervasive group on the Start menu.

Before You Get Started

Before you start the DataExchange Deployment Tool, we recommend that you review the following deployment attributes. It is a good idea to make note of these items for the database you are deploying, as they are needed to complete the Deployment Tool wizard.

Project Name – this corresponds to a specific database. If your goal is to replicate a database named mydatabase, then you may want to call the project mydatabase project or something similar.

Network Name – this refers to the name you have chosen to represent the grouping of replication sites that participate in replication.

Release Name – this is similar to a version number for the design of the replication database.

DSN – this specifies the data source name (DSN) to be associated with the data files deployed for replication. The DSN must be unique on each site.

Directories and file names of data – this specifies the directories and data files to be included in the replication.

For detailed information about these attributes, see “XML Attributes in Deployment Descriptor File” on page 4-15 in Getting Started with Pervasive DataExchange.

4-5


Replication Deployment using DXDeploy

Simple replication deployment between two machines is the standard use case for Real-Time Backup. This scenario involves a primary server and a backup server, as shown in Figure 4-1.

For detailed instructions on deploying a Real-Time Backup solution using DXDeploy, refer to Chapter 4, “Replication Deployment,”in the Getting Started with Pervasive DataExchange Real-Time Backup Edition.

4-6

Replication Deployment Using Designer


Real-Time Backup deployment can be implemented using the Designer and DataExchange utilities instead of the Deployment Wizard or DXDeploy utility. To perform this type of one-way deployment in a two-machine configuration, you will use the following series of tasks:

1 Create a Template on the First Site Using Designer

2 Copy the Template Files to the Partner Site

3 Activate the Template on the First Site

4 Activate the Template on the Partner Site

5 Make Sample Database Changes (optional)

6 Initiate Replication between the First Site and Partner Site

7 Verify the Changes Were Replicated (optional)

This example uses the sample database, Demodata, provided with the Pervasive PSQL installation.


Before performing this task you must install Pervasive DataExchange on a First Site and a Partner Site as explained in Getting Started with Pervasive DataExchange.

We strongly recommend that you shut down all applications using the database you are about to deploy before using this deployment method.

Tip So that you can restore your database to its original state after this deployment exercise, we recommend saving a copy of your database files before proceeding with this example.

Note Currently, you must have an ODBC-compliant DSN and DDFs in order to use the DataExchange Designer for this deployment method.

4-7


Create a Template on the First Site Using Designer

To create a template on the First Site

1 On the First Site machine, start PCC if it is not already running. (Select Control Center & Documentation from the Pervasive group on the Start menu.)

2 In PCC, select DataExchange Designer.

The Designer wizard asks you to specify the data to be replicated.

3 For this example, enter Demodata in the Location field and click Next.

The wizard asks you to identify the replication project, network, and release. These names are of your own choosing to help keep track of what you need to replicate.

4 For this example, enter the following:

Project: DX_Test

Network: Test

Release: 1.0

Project and network names are limited to 20 characters, and the release name must be 8 characters or less.

5 Click Next.

The wizard provides a summary of your input for the replication project.

6 Click Finish.

A message informs you that DataExchange Designer is creating the replication system tables. After the replication system tables are created, DataExchange Designer opens.

DataExchange Designer lists the ten tables in the Demodata sample database on the Not Replicated tab,

4-8


Figure 4-3 DataExchange Designer

7 Select all of the tables by pressing the Shift key and, while holding it down, click the last table in the list.

Figure 4-4 DataExchange Designer with All Tables Selected

8 Right-click the selected tables, then click Replicate Table.

4-9


Figure 4-5 Replicate Table Command in DataExchange Designer

All of the tables move from the Not Replicated tab to the Replicated tab. The view on the right shows the information for the selected table on the Replicated tab.

Figure 4-6 View of Replicated Tables in DataExchange Designer

9 Select File Save to save your work.

10 Select Tools Create Replication Template. A message about starter data appears.

See “Design Completion,” on page 8-7 for more information about starter data.

4-10


11 Leave the selected default option Prepare database data for replication to other sites and click OK.

Messages inform you that DataExchange Designer is preparing the database for activation then preprocessing the existing (starter) data. After the data has been preprocessed, another message informs you that the template has been created.

12 Click OK to complete the template creation process.

13 Select File Exit to close the Designer wizard.

To verify template creation

1 In Pervasive PSQL Explorer, under Engines open the Demodata database branch.

2 Right-click the Replication node and select Refresh.

Notice that a T icon appears next to the node, which indicates that a database template has been created.

Copy the Template Files to the Partner Site

To copy the template files to the Partner Site

You now need to copy all of the template files from the Demodata folder on the First Site to the same folder on the Partner Site.

1 From the First Site, copy the Demodata folder to the same folder on the Partner Site.

4-11


2 Answer Yes to confirm file replacement.

You will now activate replication on each site.

Note When using DataExchange Designer deployment, the template includes the actual database files. If your database contains files in other directories, you must copy them to the same path on the Partner Site as on the First Site.

Activate the Template on the First Site

To activate the database on the First Site

The command-line utility dxact activates the databases.

1 On the First Site, open a command prompt.

2 At the prompt, type the following:

dxact /FIRSTSITE Demodata

Capitalization is for emphasis. The command is case-insensitive.

3 Press Enter.

By default, messages from Dxact are written to dxact.log, not to the screen. This log is located in the <Installation Directory >\Replication\LogFiles folder. If you want to view messages on the screen while Dxact executes, use the /LOGFILE= option (a space character follows the equal sign). For example:

dxact /LOGFILE= /FIRSTSITE Demodata

See “dxact” on page 7-6 in Pervasive DataExchange User’s Guide for more information about the Dxact utility.

The activation process is complete when the command prompt reappears. You now need to activate Demodata on your Partner Site database.

Activate the Template on the Partner Site

To activate the database on the Partner Site

1 At a command prompt on the Partner Site machine, type the following:

dxact /PARTNERNETADDR=address Demodata

where address is the name or IP address of the First Site.

4-12


For example, if the First Site is a machine named TM, the command would be

dxact /PARTNERNETADDR=TM Demodata

The /PARTNERNETADDR option indicates the Partner Site address. Capitalization is for emphasis. The command is case-insensitive.

2 Press Enter.

The activation process is complete when the command prompt reappears. You have now activated both your First Site and Partner Site replication databases.

3 Close the command prompt.

4 On the First Site, open PCC and in Pervasive PSQL Explorer under Engines, open the Demodata database branch.

5 Right-click the Replication node and select Refresh.

Notice that the Replication node beneath Demodata now shows an A icon, indicating that it is activated.

Figure 4-7 Activated Icon in Pervasive PSQL Explorer

Now that the First and Partner Site databases are activated, you are ready to replicate data between them. Before you initiate replication, you may want to perform a sample database change so you can later verify the changes were replicated.

Make Sample Database Changes

To change the database records

You may change records from the First Site. DataExchange replicates the data on your First Site machine to the Partner Site.


2 Open the Tables node for the Demodata database.

4-13


Figure 4-8 Demodata Tables Node

3 Right-click table Billing and select Open, or double-click it.

SQL Editor opens and displays all records in table Billing.

4 Change the Transaction_Number for the first record from “1” to “2”. Change the Amount_Owed and the Amount_Paid for the second record from “1500.00” to “2000.00”.

Optionally—if you’re curious—open the PDCBilling table for Demodata. This is the replication control table for Billing. Modify the SQL statement to read SELECT * FROM "PDCBilling" ORDER BY LastChange DESC. Select SQL Execute in grid or press F9 to execute the statement. Scroll to the right to see the LastChange column. The date and timestamp for the top two records reflect the changes you just made.

5 Close SQL Editor.

This saves the changes to the Billing table.


To replicate data from First Site to Partner Site

You may initiate replication from either site. These steps assume that you are performing the actions from the First Site.

1 In PCC, right-click the Replication - Connected node in Pervasive PSQL Explorer, then click Statistics and Log Views.

4-14


Figure 4-9 Replication - Connected Node


Figure 4-10 Replication Progress and Log Viewers



4-15


Figure 4-11 Initiate Replication Dialog

Note that the source database is Demodata on your First Site and also the database to replicate with on your Partner Site.

3 Click Replicate.

The replication process begins. The Replication Progress Viewer reports the operation.

4-16


Figure 4-12 Example Replication Progress and Log Viewers

4 Notice that the Completed column reports “successful.”

5 Select File Exit to close the viewers.

Your next task is to verify that the data changes were replicated from Demodata on the First Site to Demodata on the Partner Site.

Verify the Changes Were Replicated

To verify that your changes were replicated

1 In PCC on the Partner Site, open the Tables node for the Demodata database, right-click the Billing table, and select Open, or double-click the table.

SQL Editor opens and displays billing data.

2 Note that the changes you made to Demodata on the First Site have been replicated to the Partner Site.

3 Close the SQL Editor.

You have completed this deployment exercise.

4-17


Many-to-One Deployment using DXDeploy

In a many-to-one configuration, multiple sites back up data to a single site. A good choice for a First Site in such a configuration is often the backup location. Consider the following example scenario:

Figure 4-13 Multiple Sites Backing Up Data

Three servers, A, B, and C, each has its own network. Each server runs its own database, dbA, dbB, and dbC, respectively. You want to implement a solution in which a replicated copy of each database is maintained on one backup machine.

Given this scenario, the most reasonable choice for the First Site is the backup location. Why? Part of the reason is that a replication network can have only one First Site. In addition, the backup location meets the following criteria:

Contains network connectivity to the Partner Site(s).

Provides the physical storage for the entire set of data.

Lends itself as the location from which the least amount of file copying is required. Replication design requires that some files are copied to the Partner Site(s).

4-18


The following image shows the same configuration after you install DataExchange. Note that the Partner Sites are the sources of the data and the First Site is the backup location.

Figure 4-14 Many-to-One Configuration with DataExchange Installed

Note In the reverse of a many-to-one configuration, one First Site source replicates to two or more Partner Site backups. This configuration is deployed as a two-way replication.



Tip So that you can restore your databases to their original state after this exercise, we recommend saving a copy of the Demodata database files before proceeding with this example.

4-19


For discussion purposes, this task assumes the following:

You have read the chapter “Replication Deployment” in Getting Started with Pervasive DataExchange Real-Time Backup Edition.

You have three Partner Sites whose names are ServerA, ServerB, and ServerC, as illustrated in Figure 4-13.

Demodata is the application database on all three Partner Sites.

Caution All applications using the database must be shut down before using this deployment method.

Deploying Using DXDeploy

To deploy databases in a many-to-one configuration

1 Ensure that the database you want to enable for replication is not being accessed by your application.

For example, suppose that Demodata is the database used by Myapp.exe. Ensure that Myapp is not accessing Demodata while you perform the steps to deploy Demodata.

2 On the backup (first) site, open the XML descriptor file EXPRESS.XML in a text editor. The file is located in the \<Installation Directory >\Replication\Docs directory.

3 Edit the XML descriptor file, specifying the appropriate information for ServerA and the backup (first) site.

Note that you will edit, and use, a different descriptor file for each Partner Site. Because the backup (first) site is a shared location, some information in the descriptor file must be unique each time that you use the file. The following table explains this.

XML Descriptor File Attribute

Must Be Unique for Each Partner Site

Notes

Project Yes

Network Yes

Release No

4-20


4 Save EXPRESS.XML as ServerA.xml to a location of your choice. This task assumes that you save it to C:\.

5 Copy the Demodata directory from ServerA to the desired backup folder on the backup (first) site.

First ServerName No This is the name of the backup (first) site, which is common to each Partner Site.

First Site DSN Yes The DSN must also be unique for the backup (first) site.

First Site DataDirectory Yes This is the backup location on the backup (first) site specific to each Partner Site

Relative Include Path No You could, for example, include “*.mkd” files from each Partner Site.

Absolute Include Path Yes Absolute paths must not conflict on the backup (first) site. For example, suppose that ServerA, ServerB, and ServerC each use the same absolute data path, C:\mydata\table1.mkd. That path can exist only once on the backup (first) site. This would result in a conflict because the table1.mkd file from the different Partner Sites would get overwritten on the backup (first) site.

Partner ServerName Yes

Partner DSN No Each partner may use the same DSN if you want, provided the DSN is unique on that Partner Site.

Partner DataDirectory No The backup location on the backup (first) site does not have to be the same as the location of the data on the Partner Site.

XML Descriptor File Attribute

Must Be Unique for Each Partner Site

Notes

4-21


The backup location must be unique and must match the location specified for First Site DataDirectory in the XML descriptor file. This task assumes that the backup location is C:\Demodata_Backup_ServerA.

6 On the backup (First) site, open a command prompt and type the following:

DXDeploy /Site=First C:\ServerA.xml

The command is case-insensitive.

7 Press Enter.

DXDeploy provides high-level status messages on the screen as it completes its actions. DXDeploy is complete when the command prompt reappears.

8 After DXDeploy completes, type the following:

DXdeact <First Site DSN>


<First Site DSN> is the DSN you specified in ServerA.xml for the First Site.

9 Press Enter.

10 Copy the contents of the DataExchange directory from C:\Demodata_Backup_ServerA on the backup (first) site to the Demodata directory on ServerA.

Note For a many-to-one configuration, ignore the replication template created on the backup (First) site. Instead, use the files for the activated database, which are located in the DataExchange directory.

11 Copy ServerA.xml from the backup (first) site to ServerA.

12 At a command prompt on the backup (first) site, type the following:

DXact /FIRSTSITE <First Site DSN>


<First Site DSN> is the DSN you specified in ServerA.xml for the First Site.

4-22


13 Press Enter.

14 On ServerA, open a command prompt and type the following:

DXDeploy /Site=Partner C:\ServerA.xml


15 Press Enter.

DXDeploy provides high-level status messages on the screen as it completes its actions. DXDeploy is complete when the command prompt reappears.

16 On ServerA, set up a replication schedule.

See “Managing Replication Schedules” on page 9-2 for how to set up a replication schedule.

17 Bring your application back online.

18 Repeat steps 1 through 17 for each of the other Partner Sites.

Substitute “ServerB” for “ServerA” when repeating the steps for ServerB. Substitute “ServerC” for “ServerA” when repeating the steps for ServerC.

4-23


Disaster Recovery

This section explains how to recover from the failure of one replication site. The information assumes that the disaster occurs to your primary site, requiring that you temporarily switch production to your backup site. After a primary site is again provided, you then need to reestablish the primary site/backup site replication network.

A disaster could, of course, occur to the backup site. The information still applies; just substitute backup for primary. For ease of discussion, and to remain consistent with terminology commonly used to discuss disaster recovery, this section refers to primary site and backup site. Think of them as the First Site and Partner Site, respectively.

The information in this section applies only to a real-time backup situation or to a 1-way situation. See the chapter “Deployment Process” in Getting Started with Pervasive DataExchange Real-Time Backup Edition for an explanation of real-time backup deployment. See “DataExchange Implementation Options” on page 5-3 for an explanation of 1-way deployment.

Failover In the event of a disaster, you must switch your users to access the backup site. Use whatever methods are in place at your company to accomplish switching to a different server. Such methods are many and varied and beyond the scope of this document.

Since the backup site contains current data, your application(s) should continue to function as before.

Once your users are accessing the backup site, reestablish your First Site. Two disaster scenarios exist pertaining to the data on the primary site:

The primary site is catastrophically destroyed and no data can be recovered from it.

The primary is brought back into service and its data is still available, but no longer current.

4-24

Disaster Recovery

No Data Recoverable

Use the following steps to reestablish your primary site.

To set up a new primary site

1 Install the Pervasive PSQL database product on the new machine.

Refer to the Getting Started guides for the product edition.

2 Install Pervasive DataExchange on the new machine.

If the machine was a First Site before, install a First Site setup. If it was a Partner Site, install the Partner Site setup. Refer to the Getting Started guides for the product edition (Real-Time Backup or Data Synchronization).

3 Install your application(s) on the new machine.

This creates a fresh copy of your application database on the new machine.

4 Create the same data source name (DSN) on the primary as used for the replication database on the backup.

5 Take your application(s) offline on the backup site.

You must ensure that the database is not being accessed until you get the primary and backup sites synchronized.

6 Deactivate the replication database on the backup sites.

See “dxdeact” on page 7-11.

7 From the backup machine, copy the following to the same locations on the primary machine:

All user database tables.

All data dictionary (DDF) files.

All replication control tables. Tables with “PDC” as the first three characters added to the name of your data tables.

All replication system tables. See Table 4-1 on page 4-26.

8 Activate the replication database on the primary site.

See “dxact” on page 7-6.

9 Activate the replication database on the backup site.

4-25


See “dxact” on page 7-6. Note that the activation on the backup site performs an initial replication with the primary site. An initial replication is a full replication, in which all data is synchronized between the two machines.

The primary site and backup site now contain the same data.

10 Recreate any replication schedules from the primary site to the backup site.

See “Schedule Tasks” on page 9-18.

11 Switch your users to access the primary site and bring your application(s) back online.

Data Recoverable But Not Current

Use the following steps to reestablish your primary site.

To place an existing primary site back into replication

1 Bring the primary machine back online.

2 Take your application(s) offline.

Table 4-1 Replication System Tables

DACTHIST.MKD DACTSITE.MKD DACTTBL.MKD

DCMD.MKD DCMDSITE.MKD DCNF.MKD

DFKEY.MKD DFRAGF.MKD DFRAGI.MKD

DGRP.MKD DIDB.MKD DIDBDEF.MKD

DKEY.MKD DLANG.MKD DMSG.MKD

DMSGLANG.MKD DPKEY.MKD DPRM.MKD

DPRMGRP.MKD DPRMTYP.MKD DQUEUE.MKD

DSCHED.MKD DSCHEMA.MKD DSET.MKD

DSFSITE.MKD DSITE.MKD DSITEEXT.MKD

DSITELNK.MKD DSITESET.MKD DSORT.MKD

DTBLCHG.MKD DTRN.MKD DUSR.MKD

DUSRGRP.MKD DUSRPRF.MKD DVER.MKD

DWSTS.MKD

4-26

Disaster Recovery

You must ensure that the database is not being accessed until you get the primary and backup sites synchronized.

3 Delete all replication schedules on the primary site.


4 Deactivate the replication database on both the primary and the backup sites.

See “dxdeact” on page 7-11.

5 Activate the replication database on the primary site.

See “dxact” on page 7-6.

6 Activate the replication database on the backup site.

See “dxact” on page 7-6. Note that the activation on the backup site performs an initial replication with the primary site. An initial replication is a full replication, in which all data is synchronized between the two machines.

The primary site and backup site now contain the same data.

7 Recreate any replication schedules from the primary site to the backup site.


8 Bring your application(s) back online.

4-27


4-28

DATA SYNCHRONIZATION EDITION

c h a p t e r

5
Data Synchronization Deployment Models
A Look at Deployment Models Available for Data Synchronization

This chapter explains conceptual information pertaining to the various deployment methods and options available in Data Synchronization. This chapter also provides step-by-step instructions for each available method.

This chapter includes the following sections:

“Data Synchronization Deployment Methods” on page 5-2

“DataExchange Implementation Options” on page 5-3

“Working with the Examples” on page 5-6

“Replication Deployment Using the Deployment Tool” on page 5-11

“1-Way Deployment Using DXDeploy” on page 5-12

“1-Way Deployment Using Designer” on page 5-24

“2-Way Deployment Using DXDeploy” on page 5-34

“2-Way Deployment Using Designer” on page 5-47

5-1


Data Synchronization Deployment Methods

Data Synchronization offers two methods for deploying replication, depending on database properties and business needs. The methods are 1-way and 2-way.

To determine the best deployment method, see the following table. It lists database properties and the best deployment method to meet those needs. So, if your database contains the properties listed in the first column, select the corresponding deployment method in the second column.

Table 5-1 Data Synchronization Deployment Methods

Your Database Properties Deployment Method

If you need one or both of the following:

A data replication solution to ensure that you can restore data from a backup copy. Replication is 1-way from one machine to another or from multiple machines to a single backup machine.

A data portal solution to ensure data backup and be able to run reports on the backup server

1-way

If one or both of the following is true:

You want a data synchronization solution (2-way replication).

You do not require sophisticated conflict handling. That is, record conflicts can be handled at the column level based on the most recent timestamp and other criteria.

2-way

5-2

DataExchange Implementation Options


The deployment methods discussed in the previous section can all be implemented using a combination of the DataExchange Designer and the DataExchange utilities to perform the replication processes. The following table illustrates the implementation options currently available for each deployment method.

DataExchange Deployment Tool

The DataExchange Deployment Tool is a wizard used to implement 1-way and 2-way deployment methods. It walks you through entry of necessary information to deploy a replication database and, if desired, create a replication schedule. The wizard creates a deployment bundle when you deploy at the First Site. This bundle is then used at the Partner Sites to complete the deployment. The wizard automates designing a replication template, activating the database for replication, synchronizing tables, peforming an initial replication, and setting a replication schedule.

See “dpwizard” on page 7-32 for more information on the DataExchange Deployment Tool included in this release.

DataExchange DXDeploy Utility

The DataExchange DXDeploy utility can be used to implement 1-way and 2-way deployment methods. This command-line utility reads information from an XML descriptor file that you create to include specific information about your database and replication environment. You then include this file as an argument when you execute the utility. DXDeploy uses the XML descriptor file to design a replication template, activate the database for replication, synchronize tables, and perform an initial replication.

DataExchange includes two different XML descriptor templates you can use to create your specific XML descriptor file to use with DXDeploy. You must edit the template to include necessary information in order for DXDeploy to successfully replicate your

Table 5-2 DataExchange Implementation Options

Deployment Method

Deployment Tool DXDeploy Utility Designer and Utilities

1-Way

2-Way

5-3


data; you cannot use the template file as-is and successfully replicate your data. See “dxdeploy” on page 7-13 for more information on the XML descriptor templates included in this release and how they are used with DXDeploy.

DataExchange Designer and Utilities

The DataExchange Designer and Utilities option is available for 1-way and 2-way deployment methods. This option uses the DataExchange Designer, DataExchange Activation utility (DXact), and the Statistics and Log Views command to complete the required replication processes.

Designer

The Designer provides a graphical interface for designing your replication template. This interface allows you to easily select tables for replication.

DXact

Activating the design templates at both the First and Partner Sites is handled by DXact. DXact is a command-line utility included with DataExchange.

Statistics and Log Views

An initial manual replication can be performed using the Statistics and Log Views command, which opens the DataExchange Monitoring Tools. The command to start the viewers is available by right-clicking the Replication - Connected node in Pervasive Control Center and selecting Statistics and Log Views. The Initiate Replication dialog box allows you to choose the type of replication to view.

Additional Information Resources

The following table lists additional resources where you can find information about using all of the utilities discussed in this chapter to perform the replication processes.

5-4


Where To Go From Here

By now, you should have a good idea as to the deployment method and implementation option that is right for you. The sections that follow provide step-by-step instructions for each of the deployment methods and implementation options currently available.

The next table lists each deployment method and implementation option described in this chapter and lists where to find specific instructions for implementing each specific scenario.

For More Information About Using... See...

DataExchange Designer to create replication templates

Chapter 8, “Using the DataExchange Designer”

DXact to activate your design templates Chapter 7, “Using the DataExchange Utilities and Services”

DataExchange Monitoring Tools to initiate replication

Chapter 10, “Using the Replication Progress and Log Viewers”

DataExchange Deployment Method and Implementation Option

For step-by-step instructions

1-way using Deployment Wizard See “Replication Deployment Using the Deployment Tool” on page 5-11

1-way using DXDeploy See “1-Way Deployment Using DXDeploy” on page 5-12

1-way using DataExchange Designer See “1-Way Deployment Using Designer” on page 5-24

2-way using Deployment Wizard See “Replication Deployment Using the Deployment Tool” on page 5-11

2-way using DXDeploy See “2-Way Deployment Using DXDeploy” on page 5-34

2-way using DataExchange Designer “2-Way Deployment Using Designer” on page 5-47

5-5


Working with the Examples

This section leads you through a number of useful examples of deployment methods. The steps you need to perform depend on how your database was deployed. The first set of instructions describes steps required for deployments performed using DXDeploy. The second set of instructions describes steps needed for deployments performed using DataExchange Designer.

Tip When working with the examples in this chapter, you should always make a copy of your database before performing the steps, so that you can restore the original database when you are done. In addition, you do not need to retain the example deployed database when you are finished. After each deployment, you will need to perform the steps associated with your deployment method to remove the replication files and templates and restore your database. The following examples explain how to remove an already deployed database from the First Site and the Partner Site.

Removing Databases Deployed with DXDeploy

Use these tasks to remove a database deployed using DXDeploy:

1 Deactivate the Example Database on Both Sites

2 Run Template Remover on the First Site

3 Delete Files on the First Site

4 Delete Database and Files on the Partner Site

5 Restore the Database Copy

Deactivate the Example Database on Both Sites

To deactivate the example database on both sites

1 On the First Site machine, open a command prompt.

2 Type the following:

DXdeact DXDatabase


3 Press Enter.

5-6


When the prompt reappears, the example database on the First Site is deactivated.

4 Repeat these steps at a command prompt on the Partner Site.

Run Template Remover on the First Site

To remove the example database template on the First Site

1 On the First Site, do one of the following:

Select DataExchange Template Remover from the Pervasive group on the Start menu.

In PCC, select DataExchange Template Remover.

The Template Remover wizard displays its welcome dialog.

2 Click Next.

Template Remover asks you to choose a template to remove.

3 In the templates pane, click LOCAL:DXDATABASE.

4 Select Remove DataExchange System Tables and click Yes to confirm that you wish to continue.

5 Select Remove DSN and database name and click Next.

The wizard removes the template and presents a summary.

6 Click Close.

Delete Files on the First Site

To delete example database files on the First Site

1 On the First Site, delete the following:

DataExchange directory under <DataDirectory>

The folder <Installation Directory >\Replication\Templates\Dxdatabase.

5-7


Delete Database and Files on the Partner Site

To delete database files on the Partner Site

1 On the Partner Site, start PCC if it is not already running. (Select Control Center & Documentation from the Pervasive group on the Start menu.)

2 Expand the list of databases under Engines.

3 Right-click <DSN>, then click Delete.

The Delete Database Wizard starts.

4 Verify that <DSN> is the database name selected and that the options Delete database name and Delete system files are selected.

5 Click Next.

6 Click Finish.

7 Click Close.

8 Delete the DataExchange directory under C:\<DataDirectory>.

Restore the Database Copy

To restore the database copy

1 Open the folder to which you saved a copy of your data files before you copied the replication files from the First Site.

2 Move or copy the files back to the folder where your original database was located.

In this example, the location to which files restored is \PVSW\Demodata.

Removing Databases Deployed with Designer

The tasks required to complete the removal of a database deployed using DataExchange Designer include the following:

1 Deactivate the Example Database on Both Sites

2 Run Template Remover on the First Site

3 Delete Database and Files on the Partner Site

4 Restore the Database Copy

5-8


Deactivate the Example Database on Both Sites

To deactivate the example database on both sites

For this example, the value for DSN is Demodata.

1 Run DXdeact DSN at the First Site.

2 Run DXdeact DSN at the Partner Site.

Run Template Remover on the First Site

To run the template remover on the First Site

1 On the First Site, Select DataExchange Template Remover from the Pervasive group on the Start menu.

The Template Remover Wizard displays its welcome dialog.

2 Click Next.

Template Remover asks you to choose a template to remove.

3 In the templates pane, click LOCAL:DSN.

In this example, the value of DSN is Dxdatabase.

4 Select Remove DataExchange System Tables and click Yes in the warning message to confirm that you wish to continue.

5 Select Remove DSN and database name and click Next.

The wizard removes the template and presents a summary.

6 Click Close.

5-9


Delete Database and Files on the Partner Site

To delete database files on the Partner Site

1 On the Partner Site machine, delete the contents of the folder to which you copied the replication replication files from the First Site.

In this example, the location is <drive>:\Documents and Settings\All Users\Application Data\Pervasive Software\PSQL\Demodata.

2 If you need to use the Demodata sample database again, restore it in the next task.

Restore the Database Copy

To restore the database copy

1 Open the temporary folder to which you saved a copy of your data files before you copied the replication files from the First Site.

2 Move or copy the files back to the folder where your original database was located.

In this example, the location to which files are restored is <drive>:\Documents and Settings\All Users\Application Data\Pervasive Software\PSQL\Demodata.

5-10

Replication Deployment Using the Deployment Tool

Replication Deployment Using the Deployment Tool

Data Synchronization deployment can be implemented using the DataExchange Deployment Tool. The Deployment Tool is a step-by-step wizard for deploying replication at First and Partner Sites and includes a means of creating a replication schedule. The Deployment Tool provides automation of the procedures for the DataExchange command-line utility dxdeploy.exe.

Access the Deployment Tool from Pervasive Control Center by selecting DataExchange Deployment Tool.


Before you start the DataExchange Deployment Tool, we recommend that you review the following deployment attributes. It is a good idea to make note of these items for the database you are deploying, as they are needed to complete the Deployment Tool wizard.

Project Name – this corresponds to a specific database. If your goal is to replicate a database named mydatabase, then you may want to call the project mydatabase project or something similar.

Network Name – this refers to the name you have chosen to represent the grouping of replication sites that participate in replication.

Release Name – this is similar to a version number for the design of the replication database.

DSN – this specifies the data source name (DSN) to be associated with the data files deployed for replication. The DSN must be unique on each site.

Directories and file names of data – this specifies the directories and data files to be included in the replication.

For detailed information about these attributes, see “XML Attributes in Deployment Descriptor File” on page 4-15 in Getting Started with Pervasive DataExchange.

5-11


1-Way Deployment Using DXDeploy

This section provides a step-by-step discussion on deploying a replication solution using the DXDeploy utility and the EXPRESS.XML descriptor template to create your XML descriptor file.

You need two machines for the example session. One machine must have DataExchange installed as a First Site. The other machine must have DataExchange installed as a Partner Site.

This section contains the following tasks:

1 Create the XML Descriptor File

2 Run DXDeploy on the First Site

3 Copy the Template to the Partner Site

4 Run DXDeploy on the Partner Site

Note This section covers only deployment and does not discuss setting up a replication schedule.


Before performing this task you must install Pervasive DataExchange on First Site and a Partner Site as explained in Getting Started with Pervasive DataExchange.


In order to complete the changes necessary to the XML descriptor file, we recommend that you make note of the following items:

Name or IP addresses for the two database servers

Root path for the source data

Directories and file names for the source data

Root path for the replicated data

5-12

Caution All applications using the database you are about to deploy must be shut down before using this deployment method.

Create the XML Descriptor File

To create the XML Descriptor file

1 Open the XML descriptor template file EXPRESS.XML in a text editor, such as Notepad, or copy and paste the following EXPRESS.XML text in a new file. The file is located in the \PVSW\Replication\Docs directory.

Tip The XML Descriptor template file used in the following example displays items that you need to change in italics. As each entry is completed in the instructions, they are shown in bold.

Note The  tags indicate comments and are ignored by DXDeploy. The comments included in the template files are intended as informational and may be edited or deleted.

You should see something similar to the following.

<?xml version="1.0" ?><DXDeployment>

<Configuration Project="DXProj" Network="DXNet" Release="1.0" Method="1-way">



<Sites>

<First ServerName="this.hostname" DSN="DXDatabase" DataDirectory="C:\MYDATA">

<!-- In <Files>, enter paths of data files.

5-13

Both Include and Exclude paths have the following properties:

Relative paths are relative to DataDirectory given in <First>.

Paths can specify files (not directories) individually or by wildcard.

Subdirectories in paths are not automatically included.

Subdirectories for include and exclude are supported. For example,

<Include Path="MoreData\dataFile.mkd" /><Exclude Path="OtherData\*" />-->

<Files>

<Include Path="*.mkd" />

<Include Path="*.btr" />

<Include Path="*.dat" />



<Include Path="*.ddf" />

</Files>

</First>

<Partner ServerName="remote.hostname" DSN="DXDatabase" DataDirectory="C:\MYDATA" />

</Sites></Configuration>

</DXDeployment>

Caution You must edit the XML Descriptor file to include the required information in order for DXDeploy to successfully replicate your data.

5-14


2 Save EXPRESS.XML as EXP_1WAY.XML.

Saving the template file with a new name retains the EXPRESS.XML template for you to use again. You may save the file to the location of your choice on your First Site machine. For ease of discussion, this task assumes that you saved it to C:\PVSW\Replication\Docs.

Tip In the event the EXPRESS.XML file is no longer available on your system, copy the text included in this file to recreate a template descriptor file.

Configuration Project

You will first enter the information needed by DXDeploy to configure your replication project. This information includes your replication project name, network and release.

In your newly created EXP_1WAY.XML file, find the following:


1 In the Configuration Project entry, specify as project name for your design. This name is of your own choosing, and we recommend a name that helps you remember which database is involved. The project name is limited to 20 characters.

For example, if you are replicating a database named mydatabase, then you might name the project mydbproject. Using this as our example, change DXProj to mydbproject. The line would now read:

<Configuration Project="mydbproject"

Network="DXNet" Release="1.0" Method="1-way">

2 The next entry is your replication network name. This name represents the group of sites that will participate in your replication. The network name is limited to 20 characters.

For example, if the sites included in your replication network are sites in the sales department, then you could name your network sales dept net. Using this as our example, change DXNet to sales dept net. The line would now read:

5-15


<Configuration Project="mydbproject" Network="sales

dept net" Release="1.0" Method="1-way">

3 Enter a release name for this replication design. The release is similar to a version number for the replication database design. Your first design might be release 1.0. You could then make the next design on this database as 2.0, as so on. The release name is limited to 8 characters.

For our example, we’ll make this release name 1.0, since it’s our first design on this replication database. Using this example, the line would now read:

<Configuration Project="mydbproject" Network="sales dept net" Release="1.0" Method="1-way">

4 Enter a replication method to use for this design. The method you select depends on your database. The only choices that DXDeploy can successfully replicate with are 1-way or 2-way. If you are uncertain of the method you should use, see “Data Synchronization Deployment Methods” on page 5-2 for database properties and corresponding deployment methods.

Because this example illustrates 1-way deployment, you will retain the 1-way entry. Our example would now read:

<Configuration Project="mydbproject" Network="sales dept net" Release="1.0" Method="1-way">

Sites - First ServerName

Next, you will enter the First ServerName information needed by DXDeploy. This information includes the name of your First Site machine, the DSN you wish to associate with your replication design, and the data directory location for the data with which you want to replicate. See “Database Selection” on page 8-4, for conceptual information about the First ServerName and DataDirectory entries.


1 In the First ServerName entry, specify the machine name or IP address of your First Site machine.

For example, if the name of your First Site is SiteA, change this.hostname to SiteA. The line would now read:

5-16


<First ServerName="SiteA" DSN="DXDatabase" DataDirectory="C:\MYDATA">

Note “Localhost” is not permitted as the machine name.

2 In the DSN entry, specify the Data Source Name (DSN) that you want DXDeploy to associate with your replication database.

For example, if the database you are replicating contains all the data for the sales department, you might enter a DSN named SalesDB. Using this example, change DXDatabase to SalesDB. The line would now read:

<First ServerName="SiteA" DSN="SalesDB"

DataDirectory="C:\MYDATA">

3 The DataDirectory entry specifies the directory location on the machine specified as First ServerName where the database resides. In other words, the path to the root directory of the data files on the First Site.

For example, the location of your sales database is on your First Site machine at the C:\CompanyData\SalesData location. Using this as our example, you would change C:\MYDATA to C:\CompanyData\SalesData. The line would now read:

<First ServerName="SiteA" DSN="SalesDB"

DataDirectory="C:\CompanyData\SalesData">

Files

Now you need to specify the tables in your database that you want to include and exclude from your replication design. In simplest terms, you specify the data you want to replicate and the data you don’t want to replicate. See “Replicated Tables” on page 8-7 for conceptual information about selecting tables for replication.

The Include Path entries listed here are not all required; they simply illustrate the file formats accepted by DXDeploy. The template includes the following examples:



5-17




1 First, eliminate any references to file types that are not applicable for your database.

Because the Sales database that we are using was created in Pervasive Control Center using the Create Database wizard, the data files have the .mkd or .ddf file extensions. For this example, delete <Include Path="*.dat" /> and <Include Path="*.btr" /> references. (These entries are shown next with strikethrough applied.)

<Files>





2 By using the wildcard (*) character, the list of files to include contains all of the .mkd and .ddf files in the DataDirectory path.

Because the database has data dictionary files (DDFs), retain the <Include Path="*.ddf" /> line. Typically, you want to replicate your DDFs to maintain a backup version of them. Note that the DSN created by DXDeploy will not use the database DDFs. DXDeploy creates its own DDFs for specific use by replication. The Files section now looks something like this:

<Files>



3 The Include Path statements are relative to the DataDirectory path you specified and not recursive in nature. This means that only the files under C:\CompanyData\SalesData\ are included. Subdirectories are excluded automatically, unless you specifically add them. The comments section of this file provides you with two examples to include and exclude files outside of the DataDirectory location.

<Include Path="MoreData\dataFile.mkd" />

<Exclude Path="OtherData\*" />

5-18


So as an example, to add a subdirectory named SalesReports, change the <Include Path="MoreData\dataFile.mkd" /> to <Include Path="SalesReports\*" /> and add it to the Files section. Now, the Files section should look similar to the following:

<Files>



<Include Path="SalesReports\*" />

4 The Exclude Path statements are relative to the DataDirectory path you specified, just as the Include Path statements. Use the example <Exclude Path="OtherData\*" /> statement to omit files from your replication design.

For example, if you wanted to exclude a file named Q1Rept located in the SalesReports subdirectory you just added, you would change the <Exclude Path="OtherData\*" /> to <Exclude Path="SalesReports\Q1Rept.mkd" />. Now, the files section should look similar to the following:

<Files>




<Include Path="SalesReports\Q1Rept.mkd" />

Another exclude example would be to exclude the leads table from the Sales Database replication design. Because statements are relative to the DataDirectory path you specified, you would add <Exclude Path="leads.mkd" /> to your descriptor file. Now, the files section should look similar to the following:

<Files>





<Include Path="leads.mkd" />

5-19


The next example illustrates how to use an Include Path statement with an absolute path location. Because DataExchange supports the use of absolute paths, we can add a table located outside the DataDirectory location specified. It is important to note that absolute paths, if specified, must all start with the same drive letter, which must be the same drive letter specified by DataDirectory.

For our example, you would add <Include Path="C:\Employee\SalesRep\sample.mkd" /> to your descriptor file. This statement includes a table named sample.mkd located at C:\Employee\SalesRep, which is outside the DataDirectory location specified. Now, the files section should look similar to the following:

<Files>





<Include Path="leads.mkd" />

<Include Path="C:\Employee\SalesRep\sample.mkd" />

Sites - Partner ServerName

Next, you will enter the Partner ServerName information. This information includes the machine name or IP Address of your Partner Site, the DSN you wish to associate with your replication design, and the data directory location for the data which you want to replicate.


1 Specify the machine name or IP address for your Partner Site.

For example, if the machine name of your Partner Site is SiteB, you would change remote.hostname to SiteB. The entry would now look like the following:

<Partner ServerName="SiteB" DSN="DXDatabase" DataDirectory="C:\MYDATA" />

5-20


2 In the DSN entry, specify the Data Source Name (DSN) that you are associating with your replication database.

For this example, change DSN="DXDatabase" to DSN="SalesDB". The line would now read:

<Partner ServerName="SiteB" DSN="SalesDB" DataDirectory="C:\MYDATA" />

3 Specify the absolute path to the root directory of the data files on the Partner Site.

For our example, in the line for Partner Servername, change DataDirectory="C:\MYDATA" to DataDirectory="C:\CompanyData\SalesData".

The line should read something similar to the following:

<Partner ServerName="SiteB" DSN="SalesDB"

DataDirectory="C:CompanyData\SalesData" />

4 Make sure to save your file once all the changes are made.

Run DXDeploy on the First Site

To run DXDeploy on the First Site

1 On the First Site, open a command prompt and type the following:

DXDeploy C:\PVSW\Replication\Docs\EXP_1WAY.XML


2 Press Enter.

As DXDeploy executes, high-level status messages display on the screen as it completes certain actions. For a successful deployment, the following messages appear:

Starting the CreateDSN action

Starting the Design action

Starting the Activate action

Activation done, now synchronizing tables

By default, detailed messages from DXDeploy are written to dxdeploy.log, not to the screen. This log is located in the <Installation Directory >\Replication\LogFiles folder. If you want to view detailed messages on the screen while DXDeploy executes, use the /LOGFILE= option.

5-21


3 For example, you would type the following:

DXDeploy /LOGFILE= C:\PVSW\Replication\Docs\EXP_1WAY.XML

DXDeploy is complete when the command prompt reappears. You may also check the DXDeploy log file to determine when DXDeploy completes. The following message appears at the bottom of the log file: “Successfully completed all deployment actions.”

1 Optionally, start PCC if it is not already running. (Select Control Center & Documentation from the Pervasive group on the Start menu.)

2 In Pervasive PSQL Explorer under Engines, open the SalesDB database branch. Notice that SalesDB is now listed as a database with the A icon shown on its Replication node. This indicates that the database is activated.

Figure 5-1 SalesDB Database Activated on First Site

Copy the Template to the Partner Site

To copy the template to the Partner Site

1 After DXDeploy completes on the First Site, copy the SalesData directory from \PVSW\Replication\Templates\SalesDB to C:\CompanyData on your Partner Site.

Note Note that the example used here contains data files in both relative and absolute locations. When copying your files, you must include absolute paths to data residing outside the DataDirectory location you specified. For information on where to copy your files, see “File Copying” on page 4-18 in Getting Started with Pervasive DataExchange.

5-22


Tip When using DXDeploy deployment, the template consists of a copy of the database files. These files are all located in the directory C:\PVSW\Replication\Templates.

Run DXDeploy on the Partner Site

To run DXDeploy on the Partner Site

1 On the Partner Site, open a command prompt.

2 At the prompt, you would type the following:

DXDeploy C:\CompanyData\SalesData\EXP_1WAY.XML


3 Press Enter.

DXDeploy provides high-level status messages on the screen as it completes certain actions. For a successful deployment, the following messages appear:




By default, detailed messages from DXDeploy are written to dxdeploy.log, not to the screen. DXDeploy is complete when the command prompt reappears. You may also check the DXDeploy log file to determine when DXDeploy completes. The following message appears at the bottom of the log file: “Successfully completed all deployment actions.”

When DXDeploy runs on the Partner Site, it performs an initial replication with the First Site. This replication populates data on the Partner Site so that it is the same as on the First Site.

Note Depending on database size and connection bandwidth, initial replication can take from a few minutes to several hours.

Tip For steps to remove the deployed database you just created, see “Working with the Examples” on page 5-6 and “Removing Databases Deployed with DXDeploy” on page 5-6.

5-23


1-Way Deployment Using Designer

This section describes how to perform an example 1-way Data Synchronization replication between a First Site and a Partner Site. Conducting the example session is optional, but recommended.


The following steps use the sample Tracker database provided with the installation of DataExchange.

The tasks required to complete this type of replication include the following:

1 Create a Template on the First Site Using Designer

2 Copy First Site Files to the Partner Site

3 Activate the First Site Template

4 Activate the Partner Site Template

5 Initiate Replication

6 Verify the Changes Were Replicated






5-24


Create a Template on the First Site Using Designer

To create a template on the First Site




Figure 5-2 Data Location

3 For this example, enter Tracker in the Location field, leave 1-way selected as the default method, and click Next.



Project: DX_1WayTest

Network: Test

Release: 1.0


The names for project, network, and release are of your own choosing and help you identify and keep track of what you need to replicate.

5 Click Next.


6 Click Finish.

5-25



Notice that DataExchange Designer initially lists the tables in the Tracker sample database in the Not Replicated tab.


7 Select all of the tables. Press the Shift key and, while holding it down, click the last table in the list.




5-26




9 Click File Save to save your work.

10 Click Tools Create Replication Template. A message about starter data appears.






5-27


Next, you will copy all of the files from the Demodb folder to your Partner Site.

Copy First Site Files to the Partner Site

To copy the First Site files to the Partner Site

1 From the First Site, copy all of the files from the folder PVSW\Replication\Demodb to the same folder on the Partner Site.


Note When using DataExchange Designer deployment, the template includes the actual database files. If your database contains files in other directories, you must copy them to the same path on the Partner Site as on the First Site.

Activate the First Site Template

To activate the template at the First Site




dxact /FIRSTSITE Tracker


3 Press Enter.

By default, messages from Dxact are written to dxact.log, not to the screen. This log is located in the <Installation Directory >\Replication\LogFiles folder. If you want to view messages on the screen while Dxact executes, use the /LOGFILE= option. For example, at the command prompt you would enter the following:

dxact /FIRSTSITE Tracker /LOGFILE=

See “dxact” on page 7-6 in Pervasive DataExchange User’s Guide for more information about the Dxact utility.

The activation process is complete when the command prompt reappears. You now need to activate Tracker on the Partner Site.

5-28


Activate the Partner Site Template

To activate the template at the Partner Site

1 At a command prompt on the Partner Site machine, type the following:

dxact /PARTNERNETADDR=address Tracker

where address is the name or IP address of the First Site machine.


dxact /PARTNERNETADDR=TM Tracker


2 Press Enter.

The activation process is complete when the command prompt reappears. You have now activated both your First Site and Partner Site databases.



2 In Pervasive PSQL Explorer under Engines, open the Tracker database branch. Notice that Tracker database is now listed as a database with the A icon shown on its Replication node. This indicates that the database is activated.

In PCC on the First Site, the status for Tracker on that machine should also show an A. If you don’t see the A icon, right-click the Replication node and select Refresh. The Partner Site in this example is named DL.

5-29


Figure 5-7 Activated Indicator in Pervasive PSQL Explorer

Now that your First Site and Partner Site databases are activated, you are ready to replicate data between them.



You may change records in your database from either site. DataExchange replicates data and synchronizes each database as changes are made, whether the changes occur at the First Site or the Partner Site. For the sake of this example, the following steps assume that you are performing the actions from the First Site.


2 Click the Tables node for the Tracker database.

3 Right-click table Customer and click Open, or double-click it.

SQL Editor opens and displays all records in table Customer.

4 Position the cursor in the NameStr field for CustomerID 1.

5 Change the NameStr from American Network Group to Worldwide Distributors. You may need to press the Insert key before you can change the string.

6 Close SQL Editor.

This saves the change to the Customer table.

5-30




You may initiate replication from either site. These steps assume that you are performing the actions from the First Site.

1 In PCC, right-click the Replication - Connected node in Pervasive PSQL Explorer and select Statistics and Log Views.

Figure 5-8 Starting Statistics View Utility





5-31



In this example, note that the source database is Tracker (TM) on your First Site and the database to replicate with is Tracker (DL) on your Partner Site.

3 Click Replicate.


5-32


Figure 5-11 Example Replication Process in Statistics View Utility



Your next task is to verify that the data changes were replicated from Tracker (TM) to Tracker (DL).


To verify the changes were replicated

1 In PCC on the Partner Site, open the Tables node for the Tracker database, right-click the Customer table, and select Open, or double-click the table.

SQL Editor opens and displays customer data.

2 Note that the change you made to Tracker has been replicated to the Partner Site.

3 Close SQL Editor.


Tip For steps to remove the deployed database you just created, see “Working with the Examples” on page 5-6 and “Removing Databases Deployed with Designer” on page 5-8.

5-33



This section provides a high level discussion for how to deploy a database for replication using the DXDeploy utility. This section uses the sample database, TRACKER, as a working example. TRACKER is provided with the installation of the Pervasive PSQL Server or Workgroup product.


This section contains the following tasks:

1 Create the XML Descriptor File

2 Run DXDeploy on the First Site

3 Copy the Template to the Partner Site

4 Run DXDeploy on the Partner Site

This section omits setting up a replication schedule. Since the TRACKER deployment is only an example, setting up a regular replication schedule is unnecessary.




In order to complete the changes necessary to the XML descriptor file, we recommend that you make note of the following items:

Name or IP addresses for the two database servers

Root path for the source data

Directories and file names for the source data

Root path for the replicated data

5-34

Caution All applications using the database you are about to deploy must be shut down before using this deployment method.

Create the XML Descriptor File

To create the XML Descriptor file

1 Open the XML descriptor file CUSTOM.XML in a text editor, or copy and paste the following CUSTOM.XML text in a new file. The file is located in the \PVSW\Replication\Docs directory.

Tip The XML Descriptor template file used in the following example displays items that you need to change in italics. As each entry is completed in the instructions, they are shown in bold.

Note The  tags indicate comments and are ignored by DXDeploy. The comments included in the template files are intended as informational and may be edited or deleted.

You should see something similar to the following.

<?xml version="1.0"?><DXDeployment>






<Sites>

5-35

<Files>


<Include Path="MoreData\dataFile.dat" />

<Exclude Path="DontNeed.dat" />

<Include Path="C:\OtherDir\*" />

<Exclude Path="C:\OtherDir\Temp*" />




</Files>

</First>


<!--<Files> is not applicable in <Partner>; files in <First>

are used.

5-36

-->

</Sites></Configuration>



<Actions>

<CreateDSN />

<Design />

<Activate />

</Actions>

</DXDeployment>

Caution You must edit the XML Descriptor file to include the required information in order for DXDeploy to successfully replicate your data.

2 Save CUSTOM.XML as CUST_2WAY.XML.

You may save the file to the location of your choice on your First Site machine. For ease of discussion, this task assumes that you save it to C:\PVSW\Replication\Docs.

Tip In the event the CUSTOM.XML file is no longer available on your system, copy the text included in this file to recreate a template descriptor file.

Configuration Project

You will first enter the information needed by DXDeploy to configure your replication project. This information includes your replication project name, network and release.

5-37


In your newly created CUST_2WAY.XML file, find the following:


1 In the Configuration Project entry, specify as project name for your design. This name is of your own choosing, and we recommend a name that helps you remember which database is involved. The project name is limited to 20 characters.

For example, if you are replicating a database named mydatabase, then you might name the project mydbproject. Using this as our example, change DXProj to mydbproject. The line would now read:

<Configuration Project="mydbproject"

Network="DXNet" Release="1.0" Method="1-way">

2 The next entry is your replication network name. This name represents the group of sites that will participate in your replication. The network name is limited to 20 characters.

For example, if the sites included in your replication network are sites in the administration department, then you could name your network admin dept net. Using this as our example, change DXNet to admin dept net. The line would now read:

<Configuration Project="mydbproject" Network="admin


3 Enter a release name for this replication design. The release is similar to a version number for the replication database design. Your first design might be release 1.0. You could then make the next design on this database as 2.0, as so on. The release name is limited to 8 characters.

For our example, we’ll make this release name 1.0, since it’s our first design on this replication database. Using this example, the line would now read:



5-38


4 Enter a replication method to use for this design. The method you select depends on your database. The only choices that DXDeploy can successfully replicate with are 1-way or 2-way. If you are uncertain of the method you should use, see “Data Synchronization Deployment Methods” on page 5-2 for database properties and corresponding deployment methods.

Because this example illustrates 2-way deployment, change the 1-way entry to 2-way. Our example would now read:



Sites - First ServerName

Next, you will enter the First ServerName information needed by DXDeploy. This information includes the name of your First Site machine, the DSN you wish to associate with your replication design, and the data directory location for the data with which you want to replicate. See “Database Selection” on page 8-4, for conceptual information about the First ServerName and DataDirectory entries.


1 In the First ServerName entry, specify the machine name or IP address of your First Site machine.

For example, if the name of your First Site is SiteA, change this.hostname to SiteA. The line would now read:

<First ServerName="SiteA" DSN="DXDatabase" DataDirectory="C:\MYDATA">

Note “Localhost” is not permitted as the machine name.

2 In the DSN entry, specify the Data Source Name (DSN) that you want DXDeploy to associate with your replication database.

Since our example uses the Tracker database, you might enter a DSN named TrackerDB. Using this example, change DXDatabase to TrackerDB. The line would now read:

5-39


<First ServerName="SiteA" DSN="TrackerDB"

DataDirectory="C:\MYDATA">

3 The DataDirectory entry specifies the directory location on the machine specified as First ServerName where the database resides. In other words, the path to the root directory of the data files on the First Site.

For example, the location of your Tracker database is on your First Site machine at the <Installation Directory >\Replication\Demodb location. Using this as our example, you would change C:\MYDATA to C:\PVSW\Replication\Demodb. The line would now read:

<First ServerName="SiteA" DSN="TrackerDB"

DataDirectory="C:\PVSW\Replication\Demodb">

Files

Now you need to specify the tables in your database that you want to include and exclude from your replication design. In simplest terms, you specify the data you want to replicate and the data you don’t want to replicate. See “Replicated Tables” on page 8-7 for conceptual information about selecting tables for replication.

The Include and Exclude Path entries listed here are not all required; they simply illustrate examples of how Include and Exclude Path statements can be structured. The template includes the following examples:






1 First, include the .mkd files for the database. By using the wildcard (*) character, you can include all of the .mkd files in the DataDirectory path using one statement.

5-40


Because the Tracker database that we are using is a SQL database, the data files have the .mkd file extension. For this example, you will retain the <Include Path="*.mkd" /> statement to include all of your Tracker data files. The Files section now looks something like this:

<Files>






2 Specify the path and file names for any files you want to include or exclude that are located in a subdirectory of the Data Dictionary path you specified.

For example, say you have a subdirectory called C:\PVSW\Replication\Demodb\Misc, which contains misc_file1.dat, misc_file2.dat, and misc_file3.dat. You want to include all of these files except misc_file3.dat. You would change <Include Path="MoreData\dataFile.dat" /> to <Include Path="Misc\*.dat" />. Then you would change <Exclude Path="DontNeed.dat" /> to <Exclude Path="Misc\misc_file3.dat" />. The entry would look something like this:


<Include Path="Misc\*.dat" />

<Include Path="Misc\misc_file3.dat" />

Another example would be to include or exclude data that falls outside of the DataDictionary path you specified, or at an absolute path location. In other words, data you want to replicate that does not reside in C:\PVSW\Replication\Demodb, but instead resides at the C:\Archive location. Because DataExchange supports the use of absolute paths, we can add a table located outside the DataDirectory location specified. It is important to note that absolute paths, if specified, must all start with the same drive letter, which must be the same drive letter specified by DataDirectory.

5-41


For our example, we’ll say that there is one file at this location that you want to exclude from the replication design; this file is C:\Archive\History.dat. You would change <Include Path="C:\OtherDir\*" /> to <Include Path="C:\Archive\*.dat" />. Then you would change <Exclude Path="C:\OtherDir\Temp*" /> to <Exclude Path="C:\Archive\History.dat" />. Now, the files section should look similar to the following:

<Files>




<Include Path="C:\Archive\*.dat" />

<Include Path="C:\Archive\History.dat" />

3 Specify the path to the data dictionary files that you want to replicate.

Because TRACKER has data dictionary files (DDFs), retain the <Include Path="*.ddf" /> line. Typically, you want to replicate your DDFs to maintain a backup version of them. Note that the DSN created by DXDeploy does not use TRACKER’s DDFs. DXDeploy creates its own DDFs for specific use by replication. The completed Files section now looks something like this:

<Files>




<Include Path="C:\Archive\*.dat" />

<Include Path="C:\Archive\History.dat" />


Sites - Partner ServerName

Next, you will enter the Partner ServerName information. This information includes the machine name or IP Address of your Partner Site, the DSN you wish to associate with your replication design, and the data directory location for the data which you want to replicate.

5-42



1 Specify the machine name or IP address for your Partner Site.

For example, if the machine name of your Partner Site is SiteB, you would change remote.hostname to SiteB. The entry would now look like the following:

<Partner ServerName="SiteB" DSN="DXDatabase" DataDirectory="C:\MYDATA" />

2 In the DSN entry, specify the Data Source Name (DSN) that you are associating with your replication database.

For this example, change DSN="DXDatabase" to DSN="TrackerDB". The line would now read:

<Partner ServerName="SiteB" DSN="TrackerDB"

DataDirectory="C:\MYDATA" />

3 Specify the absolute path to the root directory of the data files on the Partner Site.

For our example, in the line for Partner Servername, change DataDirectory="C:\MYDATA" to DataDirectory="C:\PVSW\Replication\Demodb".

The line should read something similar to the following:

<Partner ServerName="SiteB" DSN="TrackerDB" DataDirectory="C:\PVSW\Replication\Demodb" />

Actions

Optionally, you can specify actions for DXDeploy to initiate or omit by removing one or more of the Action statements. It is important to note that you can only remove these statements from the bottom up. In other words, you cannot remove <Design /> without removing <Activate /> or DXDeploy will not run successfully.

<CreateDSN />

<Design />

<Activate />

5-43


Note If you remove all of the Action statements, all actions will be performed.

1 To perform all the actions available, your Actions section should now look something like the following:

<Actions>

<CreateDSN />

<Design />

<Activate />

</Actions>

Or remove the section completely to perform all the Actions.

2 Make certain to save your file once all the changes are made.

Run DXDeploy on the First Site

To run DXDeploy on the First Site



DXDeploy C:\PVSW\Replication\Docs\CUST_2WAY.XML


3 Press Enter.





Activation done, now synchronizing tables

By default, detailed messages from DXDeploy are written to dxdeploy.log, not to the screen. This log is located in the <Installation Directory >\Replication\LogFiles folder. If you want to view detailed messages on the screen while DXDeploy executes, use the /LOGFILE= option. For example, DXDeploy /LOGFILE= CUST_2WAY.XML. (A space character follows the equal sign.)

5-44


DXDeploy is complete when the command prompt reappears. You may also check the DXDeploy log file to determine when DXDeploy completes. The following message appears at the bottom of the log file: “Successfully completed all deployment actions.”

4 Optionally, open Pervasive Control Center (PCC) and in Pervasive PSQL Explorer under Engines, open the TrackerDB branch. Notice that TrackerDB is now listed as a database with the A icon shown on its Replication node. This indicates that the database is activated.

Figure 5-12 TrackerDB Activated on First Site

Copy the Template to the Partner Site

To copy the template to the Partner Site

1 After DXDeploy completes on the First Site, copy the DemoDB directory from C:\PVSW\Replication\Templates\TrackerDB to C:\PVSW\Replication on your Partner Site.

Note that the example used here contains data files in both relative and absolute locations. When copying your files, you must include absolute paths to data residing outside the DataDirectory location you specified. For information on where to copy your files, see “File Copying” on page 4-18 in Getting Started with Pervasive DataExchange.

Note When using DXDeploy deployment, the template consists of a copy of the database files. These files are all located in the <Installation Directory >\Replication\Templates directory.

5-45


Run DXDeploy on the Partner Site

To run DXDeploy on the Partner Site

1 Othe Partner Site, open a command prompt.


DXDeploy C:\PVSW\Replication\DemoDB\CUST_2WAY.XML


3 Press Enter.





By default, detailed messages from DXDeploy are written to dxdeploy.log, not to the screen. DXDeploy is complete when the command prompt reappears. You may also check the DXDeploy log file to determine when DXDeploy completes. The following message appears at the bottom of the log file: “Successfully completed all deployment actions.”

When DXDeploy runs on the Partner Site, it performs an initial replication with the First Site. This replication populates data on the Partner Site so that it is the same as on the First Site.

Note Depending on database size and connection bandwidth, initial replication can take from a few minutes to several hours.

Tip For steps to remove the deployed database you just created, see “Working with the Examples” on page 5-6 and “Removing Databases Deployed with DXDeploy” on page 5-6.

5-46



This section describes how to perform an example 2-way Data Synchronization replication between a First Site and a Partner Site. Conducting the example session is optional, but recommended.


The following steps use the sample database Tracker provided with the installation of DataExchange. The tasks required to complete this type of replication include the following:

1 Create the Template Design

2 Copy First Site Files to the Partner Site

3 Activate the First Site Template

4 Activate the Partner Site Template

5 Initiate Replication

6 Verify the Changes Were Replicated






5-47


Create the Template Design

To create the template design




Figure 5-13 Data Location

3 For this example, enter Tracker in the Location field, select 2-way as the method, and click Next.



Project: DX_2WayTest

Network: Test

Release: 1.0


The names for project, network, and release are of your own choosing and help you identify and keep track of what you need to replicate.

5 Click Next.


6 Click Finish.

5-48



Notice that DataExchange Designer initially lists the tables in the Tracker sample database in the Not Replicated tab.


7 Select all of the tables. Press the Shift key and, while holding it down, click the last table in the list.




5-49




9 Click File Save to retain your work.

10 Click Tools Create Replication Template. A message about starter data appears.






5-50


Next, you will copy all of the files from the Demodb folder to your Partner Site.

Copy First Site Files to the Partner Site

To copy the First Site files to the Partner Site

1 From the First Site, copy all of the files from the folder PVSW\Replication\Demodb to the same folder on your Partner Site.


Note When using DataExchange Designer deployment, the template consists of the actual database files. If your database contains files in other directories, you must copy them to the same path on the Partner Site as on the First Site.

Activate the First Site Template

To activate the template at the First Site




dxact /FIRSTSITE Tracker


3 Press Enter.

By default, messages from Dxact are written to dxact.log, not to the screen. This log is located in the <Installation Directory >\Replication\LogFiles folder. If you want to view messages on the screen while dxact executes, use the /LOGFILE= option. At the command prompt, you would type the following:

dxact /FIRSTSITE Tracker /LOGFILE=

See “dxact” on page 7-6 for more information about the Dxact utility.

The activation process is complete when the command prompt reappears. You now need to activate Tracker on the Partner Site.

5-51


Activate the Partner Site Template

To activate the template at the Partner Site

1 At the command prompt on the Partner Site machine, type the following:

dxact /PARTNERNETADDR=address Tracker

where address is the name or IP address of the First Site machine.


dxact /PARTNERNETADDR=TM Tracker


2 Press Enter.

The activation process is complete when the command prompt reappears. You have now activated both your First Site and Partner Site databases.



2 In the Pervasive PSQL Explorer under Engines, open the Tracker database branch. Notice that Tracker database is now listed as a database with the A icon shown on its Replication node. This indicates that the database is activated.

In PCC on the First Site, the status for Tracker on that machine should also show an A. If you don’t see the A icon, right-click the Replication node and select Refresh. The Partner Site in this example is named DL.

5-52


Figure 5-18 Activated Indicator in Pervasive PSQL Explorer

Now that your First Site and Partner Site databases are activated, you are ready to replicate data between them.



You may change records in your database from either site. DataExchange replicates data and synchronizes each database as changes are made, whether the changes occur at the First Site or the Partner Site. For the sake of this example, the following steps assume that you are performing the actions from the First Site.


2 Click the Tables node for the Tracker database.

3 Right-click table Customer and click Open, or double-click it.

SQL Editor opens and displays all records in table Customer.

4 Position the cursor in the NameStr field for CustomerID 1.

5 Change the NameStr from American Network Group to Worldwide Distributors. You may need to press the Insert key before you can change the string.

6 Close SQL Editor.

This saves the change to the Customer table.

5-53




You may initiate replication from either site.These steps assume that you are performing the actions from the First Site.

1 In PCC, right-click the Replication - Connected node in Pervasive PSQL Explorer and select Statistics and Log Views.

Figure 5-19 Starting DataExchange Monitoring Tools





5-54



In this example, note that the source database is Tracker (TM) on your First Site and the database to replicate with is Tracker (DL) on your Partner Site.

3 Click Replicate.


5-55


Figure 5-22 Example Replication Process in Statistics View Utility



Your next task is to verify that the data changes were replicated from Tracker (TM) to Tracker (DL).


To verify that your changes were replicated

1 In PCC on the Partner Site, open the Tables node for the Tracker database, right-click the Customer table, and select Open, or double-click the table.

SQL Editor opens and displays customer data.

2 Note that the change you made to Tracker has been replicated to the Partner Site.

3 Close SQL Editor.


Note If you make changes from both the Partner and First Sites, each database is replicated to reflect all changes at both sites.

5-56


Tip For steps to remove the deployed database you just created, see “Working with the Examples” on page 5-6 and “Removing Databases Deployed with Designer” on page 5-8.

5-57


5-58

c h a p t e r

6
Example Database Design for Data Synchronization
Understanding Database Design Considerations for Data Synchronization

An effective way in which to understand how to design a database for Data Synchronization is to study an example. Although Pervasive DataExchange offers replication solutions for both backing up and synchronizing your databases, this chapter details an example Data Synchronization design using Tracker, the sample database provided with Pervasive DataExchange. We’ll use this database to illustrate the available functionality in Pervasive DataExchange Data Synchronization Edition.

This chapter discusses the following sections:

“Data Synchronization Design Considerations” on page 6-2

“Basic Data Synchronization Design” on page 6-6

“Security” on page 6-10

“Sample Tracker Database” on page 6-11

1


Data Synchronization Design Considerations

This section discusses database design considerations for creating a new database schema using Data Synchronization. These considerations can also be used for replicating an existing database. The sample database, Tracker, is used for this design.

Note If the Tracker database has been deleted from your computer you can recreate it with the sample Tracker.SQL script. See “Sample Tracker Database” on page 6-11.

Application Overview

A reseller company uses a tracking program, called Tracker, to store customer and product information and to track sales through purchase orders. The business rules are as follows:

The company has a number of geographically distributed sales regions.

Each employee of the company is associated with a specific sales region.

Employees can edit customer entries and assign customers to themselves.

Employees are responsible for creating purchase orders.

A single list of products is shared among all regions.

Based on the above business rules, the following database schema was used.

The Purchase and PurchDet tables help avoid many-to-many relationships. A single purchase can contain many purchase details, which are essentially line items on a single purchase order. That is, a purchase will exist for a given day, and all the items bought on that purchase order are listed in the PurchDet table.

The tables contain the following fields (asterisks denote primary key fields, double asterisks denote foreign key fields). Note that this is the first attempt at the structure, and changes can be made after considering design factors that could be desirable for replication.

2


Figure 6-1 Tracker Schema

Region Table

Employee Table

Customer Table

Field Type Description

RegionID* Long Integer Primary key for region table

NameStr Char[100] Name of the region


EmpID* Long Integer Primary key for employee table

FName Char[30] First name

Initial Char[5] Middle Initial

LName Char[30] Last name

RegionID ** Long Integer Index to the region name


CustID* Long Integer Primary key for customer table

NameStr Char[100] Name of the company

Street Char[100] Street name

3


Purchase Table

Purchase Detail Table

City Char[30] City name

State Char[50] State, province or county name

ZIP Char[10] ZIP or postal code

Phone Char[20] Phone number

CntEmail Char[100] E-mail address of the primary company contact

CntName Char[50] Name of the primary company contact

Comments Char[255] Any comments regarding the company

SlsRepID ** Long Integer Index to the employee who works with the company


PurID* Long Integer Primary key for purchase table

PurDate Date/Time Date and time of purchase order

CustID ** Long Integer Index to the name of the customer who ordered

EmpID ** Long Integer Index to the employee who took the order

DelInst Char[50] Delivery instructions


PurDetID* Long Integer Primary key for purchase detail table

PurchID ** Long Integer Index to the purchase order

ProdID ** Long Integer Index to the product ordered

PurchQty Integer Amount ordered

Cost Char[12] Total cost of the purchase detail


4


Product Table


ProdID* Long Integer Primary key for product table

ProdName Char[50] Name of the product

ProdDesc Char[248] Description of the product

Price Char[12] Price of the product

5


Basic Data Synchronization Design

Pervasive DataExchange Data Synchronization Edition provides you the functionality to easily configure your database designs to mirror the distributed nature of your business. Designing your database for Data Synchronization can be as simple or as complex as your data and business needs demand.

The tasks required to complete a basic Data Synchronization design include the following:

1 Select the database

2 Identify the database

3 Select tables for replication

Database Selection

First you select a database to use for your replication design. You may choose to open an existing database, or you can create a new database for this purpose. The next figure shows the Database Information dialog where the database name is entered and the DataExchange Method is selected, using Data Synchronization.

Figure 6-2 Data Synchronization Database Selection Dialog

DataExchange Method

If you select a new database for replication, you must select the DataExchange Method to use when you enter the database information. In selecting an existing database, the DataExchange Method is already determined by the method previously used for the selected database.

The method you select depends on your database and your business requirements. The choices are 1-way and 2-way.

6


The next figure shows the Database Information dialog where the database name is entered and the DataExchange Method is selected, using Data Synchronization.


Database Connection Information

If applicable, you will need to enter the User Name and Password for your selected database.

Database Identification

When creating a new database for replication, you must designate specific identifiers for the Project, Network, and Release names associated with your replication design.

Project

A project represents a single replicated database. The replication Project Name is of your own choosing and helps you identify and keep track of what you need to replicate. You can use a simple-to-understand name that helps you remember which database is involved.

If your goal is to replicate with a database named mydatabase, then you may want to call the project mydatabase project or something similar that helps you remember which database is involved.

A Project name must be 20 characters or less.

A project can be associated with more than one replication network. That is, you could create a design for mydatabase project, finance department network, 1.0 and mydatabase project, accounting group network, 1.0.

7


Network

A replication network is the grouping of replication sites that will participate in the replication. The name for the replication network is of your own choosing and helps you identify and keep track of what you need to replicate. A name that helps you remember the grouping is very useful. For example, you could name a grouping of sites in the finance department finance network.

The Network name must be 20 characters or less.

Release

The release is like a version number for the design of the replication database. Your first design could be version 1, for instance. If you choose to change the design later, then you would create a version 2 and so forth.

The Release name must be 8 characters or less.

The name for the replication release is of your own choosing and helps you identify and keep track of what you need to replicate.

The Project, Network, and Release names are added to the database network analyst (DNA), which is the system database used by the Replication Engine. The replication utilities use these names from the DNA database to allow or disallow certain actions. For example, databases that differ only by release are allowed to replicate together.

Tip Replication project names and network names must match to allow replication.

Replicated Tables

When you first start the DataExchange Designer, the database tables are listed in the left pane on the Not Replicated tab. Initially, none of the database tables are flagged for replication; all of the tables are marked as Not Replicated.

8


To begin your design, you decide which tables to use for replication and mark these tables accordingly.

Note Selecting tables for replication is a required task for both 1-way and 2-way Data Synchronization designs.

This completes the tasks required for a basic replication design. The next sections discuss Security and the Sample Tracker Database.

9


Security

Pervasive DataExchange automatically encrypts all data transmitted between two sites. The Replication Engine controls the encryption for you.

For information on Pervasive PSQL Security, see What's New in Pervasive PSQL included with your Pervasive PSQL database engine.

10

Sample Tracker Database

Sample Tracker Database

If the Tracker database is not listed in Pervasive PSQL Control Center, you can create it from the file Tracker.sql. Tracker.sql is included in the Pervasive DataExchange installation at <Installation Directory >\Replication\Demodb). This file contains the SQL statements to recreate the Tracker demo database.

To create the Tracker database using Tracker.sql


2 Right-click Databases and select New Database.

The New Database dialog box appears.

3 Fill in the options for the database name and the database directory as listed:

Database Name: Tracker

Location: C:\Program Files\Pervasive Software\PSQL\Replication\DemoDB

You may specify a different directory so long as the folder already exists and does not contain any Pervasive PSQL database files (.ddf or .mkd file extensions).

4 Click Finish.

The empty database is created and ready to run the SQL statements in Tracker.sql.

5 In PCC, select File Open.

An Open dialog box appears.

6 Browse to C:\Program Files\Pervasive Software\PSQL\Replication\DemoDB and open the file tracker.sql.

11


SQL Editor starts.

The system asks you to select a database in which to run the SQL statements.

7 Click OK.

SQL Editor displays the SQL statements in Tracker.sql.

8 Select SQL Execute All SQL Statements.

The statements create the Tracker database tables and populate them with data.

9 After all SQL statements have run, close SQL Editor.

10 Right-click Databases and select Refresh to redisplay the list of databases, including their tables.

12

DATAEXCHANGE TOOLS AND UTILITIES

c h a p t e r

7
Using the DataExchange Utilities and Services
A Reference for Using the DataExchange Utilities and Services

“Utilities and Services Overview” on page 7-2

“Command-line Utilities” on page 7-5

“GUI-based Utilities” on page 7-31

“Services” on page 7-33

7-1


Utilities and Services Overview

Pervasive DataExchange contains a suite of utilities and services for every phase of replication. The Pervasive DataExchange utilities assist you in designing, customizing, and administering your replication requirements. This section covers the following topics:

Replication Stages and the Utilities Used

Accessing the Utilities

Replication Stages and the Utilities Used

The next table lists the Pervasive DataExchange utilities and services and the four primary replication stages in which each is used. Detailed information on the Pervasive DataExchange utilities and services is included in the sections that follow.

Replication Stage

Utility/Service Name File Name For more information...

Activation Activate a Project Release dxact See “dxact” on page 7-6

Activation Deactivate a Project Release

dxdeact See “dxdeact” on page 7-11

Activation Utility to read/write the event handler DLL path to the database.

dxdeploy See “dxdeploy” on page 7-13

Design / Activation

Deployment Utility dxdeploy See “dxdeploy” on page 7-13

Design / Activation

Deployment Wizard dpwizard See “dpwizard” on page 7-32

Design Designer prd See “prd” on page 7-32 and Chapter 8, “Using the DataExchange Designer”

Design Dynamic Table Configuration and Test Utility

(Real-Time Backup Edition only)

dxdynpath See “dxdynpath” on page 7-15

Design Flat File Copy Utility ffcopy See “ffcopy” on page 7-26

7-2

Utilities and Services Overview

Accessing the Utilities

Some of the DataExchange utilities can be accessed from a single control point, Pervasive Control Center (PCC) or the Start menu. Many tools contain only a command-line interface and must be accessed from a command prompt. Services are available from the Windows Control Panel. The following information outlines the various ways to access the Pervasive DataExchange utilities, services and shortcuts.

Accessing the Utilities from a Command Prompt

For most of the replication utilities you’ll need to open a command prompt window to run the executable. You can open a command prompt window from the Windows environment.

Design Template Remover Wizard trwizard See “trwizard” on page 7-32

Replication Pervasive DataExchange Agent

dxagent See “dxagent” on page 7-33

Replication Control Table Cleanup Configuration Utility

dxcleanup See “dxcleanup” on page 7-9

Replication Table Synchronization and Check Utility

dxsynctables See “dxsynctables” on page 7-25

Replication Administrator da See “da” on page 7-31 and Chapter 9, “Using DataExchange Manager”

Replication Statistics and Log View replmonitor See “replmonitor” on page 7-32 and Chapter 10, “Using the Replication Progress and Log Viewers”

Replication Console Replication Initiation Utility

dxrepl See “dxrepl” on page 7-23

All Pervasive PSQL Replication replserv See “replserv” on page 7-36

Replication Stage

Utility/Service Name File Name For more information...

7-3


To open a Command Prompt window in Windows

1 Select Start Programs Accessories Command Prompt.

Note For more information on using the command-line utilities, see “Command-line Utilities” on page 7-5.

Accessing the Utilities from PCC

Expand the tree view in PCC if it is not already expanded. The menus in PCC are context-sensitive; they vary according to which object (node) in the tree is selected.

Note Command-line utilities are not available from PCC.

To access the utilities from PCC

1 Select the Replication node for a specific database

2 Select DataExchange from the menu and select the utility.

Note For more information on using the GUI utilities, see “GUI-based Utilities” on page 7-31.

7-4

Command-line Utilities


This section provides information about the command-line utilities included in Pervasive DataExchange. The following table lists the Pervasive DataExchange command-line utilities, along with a brief description of the utility. The section following this table details each individual utility and includes a list of the options available for each utility.

Utility File Name Utility Name Description

dxact Database Activation Utility Activates an enabled database by registering it with the local runtime environment as belonging to a site on the replication network.

dxcleanup Control Table Cleanup Configuration Utility

Sets/gets control table cleanup schedules for an activated database.

dxdeact Database Deactivation Utility Deactivates a release that was previously activated using dxact.

dxdeploy Deployment Utility Deploys DataExchange on two sites using settings given in the XML deployment descriptor file.

dxdynpath

(Real-Time Backup Edition only)

Dynamic Table Configuration and Test Utility

Supports appending, replacing, showing and testing regular expressions and file patterns for a designed database.

dxrepl Console Replication Initiation Utility

Replicates files from DSN to Partner Site.

dxsynctables Table Synchronization and Check Utility

Finds modified data missed by DataExchange event handler and returns control tables to the consistent state.

ffcopy Flat File Copy Utility Copies non-Btrieve files from First Site to Partner Site.

7-5


dxact Pervasive DataExchange Activate a Project Release

Description

This program activates an enabled database by registering it with the local replication runtime environment.

If the Replication Engine is running and control tables have been populated, the first replication with the initial Partner Site will be performed automatically. Once this first replication has succeeded, the newly activated database will be fully aware of all administrative data in that network, including all replication schedules.

Syntax

DXACT [options] <DSN>

Options

Argument Description

<DSN> Data Source Name for the database to be activated.

Option Description

/DES[CRIPTION]=<string> Description of this replication site, e.g. "My First Site". Database name will be automatically appended to it.

[default=MyFirstSite]

/DL[LPATH]=<string> Full path to the event handler DLL, if specified.

[default=<null>]

/FI[RSTSITE] Use this switch only if this is the First Site at which this release is being activated

/FO[RCEINSTALL] If specified, allows activation of a database that is a copy of an already-activated site

7-6


/LOG={flags} Specify which messages type(s) to log:

I = informational messagesW = warning messagesE = error messages

For example, '/log=e /log=w' or '/log=we' (the default) logs errors and warnings only. Any message type left unspecified is suppressed.

[default=iwe]

/LOGF[ILE]=<string> File name for log messages. Specifying '/LOGFILE=' alone sets logging to the console.

[default=<Installation Directory >\Replication\LogFiles\DXACT.log]

/LOGH[ISTORY]=nnn Number of files to maintain in the log history

[default=5]

/LOGS[IZE]=nnn Maximum size of the log file (0 means 'no limit')

[default=0]

/LOGW[IDTH]=nnn Log messages are wrapped to fit within this line length. (minimum 50)

[default=79]

/NOI[NITIALREPL] If specified, Replication Engine will not perform an initial replication after the release has been activated.

/NOL[OGO] Do not display starting logo.

/ODBCC[ONNSTR]=<string> Additional ODBC connection string parameters in the form:

<name>=<value>[;<name>=<value>...]

[default=<null>]

/ODBCN[AME]=<string> User name for ODBC connection

[default=PDUSER]

/ODBCP[ASSWORD]=<string> Password for ODBC connection

[default=<null>]

Option Description

7-7


Examples

Running the following example from a command prompt on a First Site activates a DSN named Demodata on a First Site machine.

/PA[RTNERNETADDR]=<string> The network address of the Partner Site we should replicate with first. If this switch is not specified, DXact will display a prompt for the user to enter the partner network address

[default=<LocalHost>]

/PN[LICENSE]=<string> Specifies name of PNLicense file to register (specify at network First Site only)

[default=<Installation Directory >\bin\repllicense.pnl]

/PR[EPROCESS] If specified, preprocessing of starter data will be performed. This should be done unless it is known that no database changes occur between design and activation, and that starter data was preprocessed at design time. Otherwise, starter data will not get replicated.

/REC[ONCILEREP] If specified, Replication Engine will perform reconciliation processing during the initial replication after the release has been activated. Should be specified unless data is identical between the site being activated and the First Site. Otherwise, reconciliation will not be performed.

/RED[ESIGN] If specified, the database will still capture events while Redesign occurs.

/SI[TETYPE]=<string> Override new site's default site type. Must be one of: COMPLETE or HIGH

[default=COMPLETE]

/SU[BSCRIBESITES] If specified, this site will be automatically subscribed to all new sites (via the dSite table).

/H[ELP] Displays the command usage help text.

Note: The default installation directory varies depending on the version of your operating system.

Option Description

7-8


DXACT /FIRSTSITE Demodata

The next example, if run from a Partner Site, would activate a DSN named Demodata on a Partner Site machine replicating with a machine named XPServer.

DXACT /PARTNERNETADDR=XPServer Demodata

This example activates the DSN named Demodata on the First Site machine and sets the Dxact logging to the console.

DXACT /FIRSTSITE /LOGFILE= Demodata

This example activates the DSN named Demodata on the Partner Site machine replicating with a machine addressed as Adminserver and sets the Dxact logging to a file named adminlog.txt located at <Installation Directory >\Reports.

DXACT /PARTNERNETADDR=AdminServer /

LOGFILE=C:\<Installation Directory

>\Reports\adminlog.txt Demodata

dxcleanup Pervasive DataExchange Control Table Cleanup Configuration Utility

Description

This program sets or shows the control table cleanup schedules for an activated database.

Syntax

DXCLEANUP [options] <Operation> <DSN>


<Operation> Valid arguments include SET or SHOW

<DSN> Database datasource name

7-9


Options

Option Description

/C[LEANUPPERIOD]=nnn Time (in days) between cleanup cycles

[default=7]

/DXA[DMIN]=<string> DX administrator name

[default=ADMIN]

/DXP[ASSWORD]=<string> DX administrator password

[default=password]




[default=iwe]


[default=<Installation Directory >\Replication\LogFiles\DXCLEANUP.log]


[default=5]


[default=0]


[default=79]

/N[OLOGO] Do not display starting logo.

/ODBCN[AME]=<string> User name for this database (if security enabled)

[default=<null>]

7-10


Example

This example displays the number of days set for the cleanup period and the age (in days) of the oldest allowed record currently in place for the data source name demodata.

dxcleanup show demodata

A message should display that lists the name and version of the control table cleanup configuration utility, and additional information such as the following:

Cleanup Period is 7 day(s)

Oldest Allowed is 90 day(s)

dxdeact Pervasive DataExchange Deactivate a Project Release

Description

This program deactivates a release that was previously activated using DXact and removes the activated database from the list of those available for replication. If you want to delete a replicated database from physical storage, you must deactivate it first.

Syntax

DXDEACT [options] <DSN>

/ODBCP[ASSWORD]=<string> Password for the user specified as ODBCName (if security enabled)

[default=<null>]

/OL[DESTALLOWED]=nnn Age (in days) of oldest allowed record

[default=90]



Option Description


<DSN> Database datasource name

7-11


Options

Option Description

/K[EEPINFO] Keep Activation Information in system database (by default, that info is removed)




[default=iwe]


[default=<Installation Directory >\Replication\LogFiles\DXDEACT.log]


[default=5]


[default=0]


[default=79]



[default=<null>]


[default=<null>]

7-12


Examples

This example deactivates the data source name demodata and retains the activation information in the system database; by default, activation information is removed.

dxdeact /keepinfo demodata

dxdeploy Pervasive DataExchange Deploy DataExchange

Description

This program deploys DataExchange on two sites using settings given in the XML Deployment Descriptor file. This utility streamlines replication processes by combining functionality of DataExchange Designer, Dxact, and Dxsynctables.

Syntax

DXDEPLOY [options] <XML File>

/R[EDESIGN] Use this switch only if planning to redesign this database.


Option Description


<XML file> XML Deployment Descriptor file. XML Descriptor file templates (EXPRESS.XML and CUSTOM.XML) are located in <Installation Directory >\Replication\docs.

7-13


Options

Option Description




[default=iwe]


[default=<Installation Directory >\Replication\LogFiles\DXDEPLOY.log]


[default=5]


[default=0]


[default=79]


/S[ITE]=<string> Choose which site in Sites list to deploy: First | Partner

(This setting is optional and is used for demonstration purposes only.)

[default=<null>]



7-14


XML Descriptor File Templates

DXDeploy is used to implement Real-Time Backup, 1-way, and 2-way Data Synchronization deployment methods. The DXDeploy utility uses an XML descriptor file that you create to include specific information about your database and replication environment. As shown in the syntax example, this file is included as an argument when you execute the utility. DXDeploy uses the XML descriptor file to handle the processes required for replication.

Pervasive DataExchange includes two different XML descriptor templates you can use to create your specific XML descriptor file to use with DXDeploy. You must edit the template to include necessary information in order for DXDeploy to successfully replicate your data.

Caution You cannot use these template files as-is and successfully replicate your data. You must create a template file to include specific information about your replication environment.

EXPRESS.XML

See “1-Way Deployment Using DXDeploy” on page 5-12 for an example deployment using the EXPRESS.XML template file.

CUSTOM.XML

See “2-Way Deployment Using DXDeploy” on page 5-34 for an example deployment using the CUSTOM.XML template file.

dxdynpath Pervasive DataExchange Dynamic Table Configuration and Test Utility (Real-Time Backup Only)

Description

Append, replace or show the existing include and exclude patterns and/or regular expressions for a given designed database. Optionally test existing or hypothetical patterns or regular expressions.

Syntax

DXDYNPATH [options] <Operation> <DSN>

7-15


Options


<Operation> Valid arguments include APPEND, REPLACE, SHOW or TEST.

<DSN> Database datasource name created by DataExchange.

Option Description

/F[ILEPATH]=<string> Absolute file path to test (valid only for <Operation> TEST).

The path used here is the absolute path to the database created by DataExchange.

[default=<null>]




[default=iwe]


[default=<Installation Directory >\Replication\LogFiles\DXDYNPATH.log]


[default=5]


[default=0]

7-16


Remarks

It is critical that to note that any file that is being considered for use with the dxdynpath utility requires system keys.

Before we explain how DataExchange automatically includes or excludes files using pattern matching, let’s first discuss the types of expressions you can use.

Note Dxdynpath should only be used with the Real-Time Backup Edition.


[default=79]



[default=<null>]


[default=<null>]

/P[ATTERN]=<string> Glob-style pattern (e.g. "dir newfile*.mkd") or regular expression.

For <Operation> APPEND or REPLACE, PATTERN is applied to Dynamic Table Configuration. For <Operation> TEST, PATTERN is used to test for a match, otherwise ignored

[default=<null>]

/T[YPE]=<string> INCLUDE, EXCLUDE or BOTH (BOTH is valid only for <Operation> SHOW)

[default=INCLUDE]



Option Description

7-17


Types of Expressions

You may use the following types of pattern-matching expressions with the dxdynpath utility:

Dir expressions

Regular expressions

Dir Expressions

This type of expression is based on the Windows directory (dir) command, and provides an alternative to using regular expressions. Dir expressions have the following characteristics:

Must contain “dir” as the first characters (“dir” is case-insensitive).

May include a relative path to the dictionary files. See “Relative Paths” on page 7-19. Absolute paths are not allowed.

Must include the name(s) of file(s). File names may include the “?” or “*” wildcard. Note that a period (.) designates a period. It is not the same as the “?” wildcard.

May include the slash (/) character, back slash (\) character, or a combination of the two.

May include the parameter “/s” to indicate the processing of files in subdirectories. The “/s” parameter may not be the first characters in the expression. Other than that, the parameter is not positional.

Must include a space character as the separator between the elements of the expression.

May be used in a series, separated by semi-colons (;). A space character may precede or follow the semi-colon if you choose, but is not required.

The following Dir expressions are valid examples:

dir mydbase\*.mkd /s

dir ..\..\acct/acct*.?db

Dir ../payables/custdb/??posted??.pay

dir mydbase\*.mkd /s ; dir ..\..\acct/acct*.?db

Regular Expressions

Regular expressions are a pattern matching technique that let you parse and manipulate text. DataExchange uses the same regular

7-18


expressions as the Windows version of the programming language perl.

Regular expressions have the following characteristics:

May include literal or relative paths. If relative paths are used, see “Relative Paths” on page 7-19.

May include the slash (/) character, back slash (\) character, or a combination of the two as characters in a relative path. When paired with the “..”characters in a relative path, slash and back slash are interpreted as part of a path structure. For example, ..\..\.*bak. If relative paths are used, see “Relative Paths” on page 7-19.

May be used in a series, separated by semi-colons (;). A space character may precede or follow the semi-colon if you choose, but is not required.

May use uppercase characters, lowercase characters, or a combination of the two. (Windows is case-insensitive.)

Must be surrounded by double quotes if the expression contains characters that are meaningful to the command line interpreter. For example, the “|” character is legitimate in a regular expression to indicate “or.” That same character, however, represents a pipe directive to the command line interpreter. Any regular expression that uses the “|” character must be surrounded by double quotes. If you are unsure about a character, surround the regular expression with double quotes.

Must use valid regular expression syntax, with the exceptions noted above in this bulleted list. Consult the regular expression syntax in your perl documentation.

The following regular expressions are valid examples:

“..\..\(mon|tue|wed|thru|fri)\\(([01][0-9]|2[0-3]))\\.*\.mkd” (any mkd file in a relative directory structure of weekday\hour)

.*bak (any backup file in or below the “home” directory)

day\dt\.ddf (dictionary files with a name format of day[0-9]t.ddf, such as day0t.ddf, day4t.ddf, and so forth)

(\w+)\\.*\\\1\\.* (all files in subordinate directories under the “home” directory where a subordinate directory name recurs, for example /data/acct/data/purged)

7-19


Relative Paths

Relative paths are relative to a “home” directory. The home directory is the one that contains data dictionary files (DDFs) recognized by DataExchange. To be recognized by DataExchange, the dictionary files must have been created by one of the DataExchange utilities or by a DataExchange replication process. If you already have dictionary files created by a replication process, the home directory is relative to their location.

Relative paths use “..\” to refer to a directory level. You may also the slash character (/) instead of the back slash (\). Each “..\” means to move up the directory structure relative to the home directory. For example, if your home directory is c:\myapp\mydata\accounts\, then a relative path of “..\” navigates to c:\myapp\mydata. Similarly, a relative path of “..\..\” navigates to c:\myapp.

Verifying Expression Pattern Matching

Regular expressions can be challenging to construct correctly. Because of this, DataExchange provides a command-line utility, Dxdynpath.exe, that helps you to verify the pattern matching of your regular and dir expressions. The utility compares the pattern against the command line arguments and reports if the comparison passes or fails.

Note Dxdynpath bases the pattern matching solely on its command line arguments. It does not check for the existence of files or directories, nor navigate directories. For example, if you are testing an expression against the file name acctdata\Bbzz95.mkd, Dxdynpath does not check if file Bbzz95.mkd exists in directory acctdata.

The following example compares a dir expression against a supposed file located in c:\bklog\hr or in any subdirectories to c:\bklog\hr. (The example would be entered as a single line at the command prompt.)

Dxdynpath /f=c:\mydata\acct\dbQ299x.mkd /p="Dir ..\..\bklog\hr\dbQ2???.mk? /s" test mydbdsn

Dxdynpath reports “matches pattern” because supposed file dbQ299x.mkd matches the pattern and resides in a subdirectory of c:\bklog\hr.

7-20


By default, output from Dxdynpath is written to a log file, not to the screen. If you want output written to the screen, use the /LOGF= option.

Examples

This example displays the include and exclude patterns currently in place for the data source name demodata.


If there are no include or exclude patterns configured, a message similar to the following returns:

INCLUDE pattern is ""

EXCLUDE pattern is ""

Running the following command on the First Site appends attend*.mkd as an include pattern to any include patterns that already exist for demodata.

dxdynpath /t=include /p="dir attend*.mkd" append demodata

Note Commands are case insensitive. You may use uppercase characters, lowercase characters, or a combination of the two.

dxregevnt Pervasive DataExchange Utility to read/write the event handler DLL path to the database

Description

Registers, unregisters or shows the event handler for an activated database.

Syntax

DXREGEVNT [options] <Operation> <DSN>


<Operation> Valid arguments include REGISTER, UNREGISTER or SHOW

<DSN> Datasource name

7-21


Options

Option Description

/DXA[DMIN]=<string> DX administrator name

[default=ADMIN]

/DXP[ASSWORD]=<string> DX administrator password

[default=password]




[default=iwe]


[default=<Installation Directory >\Replication\LogFiles\DXREGEVNT.log]


[default=5]


[default=0]


[default=79]



[default=<null>]

7-22


Examples

Running this example displays if the specified database has an Event Handler DLL registered.

dxregevnt show demodata

If you do not have an Event Handler DLL registered, a message similar to the following displays:

No Event Handler is Registered

The next example registers an Event Handler DLL named dxevent.dll located at c:\<Installation Directory >\bin with demodata.

dxregevnt /p="c:\<Installation Directory >\bin\dxevent.dll" register demodata

If you have an Event Handler DLL registered, a message similar to the following displays:

Event Handler is "c:\<Installation Directory

>\bin\dxevent.dll"

dxrepl Pervasive DataExchange Console Replication Initiation Utility

Description

Replicate files from DSN to Partner Site.

/ODBCP[ASSWORD]=<string> Password for Administrator.

[default=<null>]

/P[ATH]=<string> Absolute path to an event handler (a shared library)

[default=<null>]



Option Description

7-23


Syntax

DXREPL [options] <DSN> [<SiteID>]

Options


<SiteID> The target site for the replication session [default=<null>]

<DSN> The Pervasive Replication datasource name

Option Description



For example, '/log=e /log=w' or '/log=we' logs errors and warnings only. Any message type left unspecified is suppressed. [default=iwe]

/LOGF[ILE]=<string>/ File name for log messages. Specifying '/LOGFILE=' alone sets logging to the console.

[default=<Installation Directory >\Replication\LogFiles\DXREPL.log]

/LOGH[ISTORY]=nnn/ Number of files to maintain in the log history [default=5]

/LOGS[IZE]=nnn Maximum size of the log file (0 means 'no limit') [default=0]

/LOGW[IDTH]=nnn Log messages are wrapped to fit within this line length. (minimum 50) [default=79]


/ODBCN[AME]=<string> User name for this database (if security enabled) [default=<null>]

/ODBCP[ASSWORD]=<string> Password for the user specified as ODBCName (if security enabled) [default=<null>]

7-24


dxsynctables Pervasive DataExchange Table Synchronization and Check Utility

Description

Finds modified data missed by DataExchange event handler and returns control tables to the consistent state.

Syntax

dxsynctables [options] <Table> <DSN>

Options



Option Description


<Table> Name of table to be updated (*=All tables)

<DSN> Datasource name

Option Description

/E[XCLUDE]=<string> Optional comma-separated list of tables to exclude

[default=<null>]

/F[ORCE] Forces update of timestamped columns.



For example, '/log=e /log=w' or '/log=we' (the default) logs errors and warnings only. Any message type left unspecified is suppressed. [default=iwe]

7-25


ffcopy Pervasive DataExchange Flat File Copy Utility

Description

The ffcopy utility copies non-Btrieve files from First Site to Partner Site. This tool can run by hand or as part of the DX session event handling scheme.

See “DxEvent.sql / dxevent.dll” on page 7-28 for more information about event handling.

Syntax

ffcopy.exe [options] <DATAFILE>

/LOGF[ILE]=<string> File name for log messages. Specifying '/LOGFILE=' alone sets logging to the console. [default=<Installation Directory >\Replication\LogFiles\]

/LOGH[ISTORY]=nnn Number of files to maintain in the log history [default=5]



/M[SD] Mark the data with starter data timestamp


/ODBCN[AME]=<string> User name for this database (if security enabled) [default=<null>]

/ODBCP[ASSWORD]=<string> Password for the user specified as ODBCName (if security enabled) [default=<null>]



Option Description

7-26


Options

Setup steps

Run ffcopy.sql file to create the database file that contains the information about the files to be copied. The columns of the table have the following meaning.


<DATAFILE> The MKD file name associated with the table created by the fcopy.sql script

Option Description



For example, '/log=e /log=w' or '/log=we' (the default) logs errors and warnings only. Any message type left unspecified is suppressed. [default=iwe]

/LOGF[ILE]=<string> File name for log messages. Specifying '/LOGFILE=' alone sets logging to the console. [default=<Installation Directory >\Replication\LogFiles\FFCOPY.log]

/LOGH[ISTORY]=nnn Number of files to maintain in the log history [default=5]





LocalFN Local Name and Path of Local file to Replicate

RemoteFN Remote Name and Path of File to Replicate, can be UNC or Drive

7-27


Functionalities

1 Find names may include wildcards (*, ?).

2 A new file that matches a wildcard is detected only on the local site and will be copied to the remote site.

3 If a wildcard matches sub-directories, they will be traversed and new directories will be created on the remote side if they do not exist.

4 Change detection algorithm: A file on NTFS contains 3 dates - creation date, modification date, and accessed date. If a local file is more recent than its remote partner file, the local file is copied to the remote directory. (Note that copying a file does not change its modification date).

5 Check the ffcopy.log file for information and errors.

Note To match all files in a directory, use "*" (for example, c:\files\*), not "*.*".

Logging

ffcopy.exe logs information and error messages to the replication log files directory which is commonly located in

<Installation Directory

>\replication\logfiles\ffcopy.log.

ReserveInt1 Set to 0 initially, used by DLL after that, do not alter manually

ReserveInt2 Set to 0 initially, used by DLL after that, do not alter manually

PartnerSideDelete If '1', file existing only in RemoteFN (not in LocalFN), will be deleted.

CopyInProc Locking byte for other instances of this DLL

ReserveByte Set to 0, reserve by DLL

7-28


DxEvent.sql / dxevent.dll

The dxevent.dll handles replication session event callbacks. The following events are handled:

The dxevent.dll, in conjunction with the dxEvent table in your database will allow the user to spawn 3rd party executables or scripts when the above events occur during a replication session.

Setup steps

Run dxEvent.sql to create the dxEvent table in your database. The dxEvent table columns have the following meaning.

OnReplicationRequest Called whenever a replication session is initiated with the database via user interaction, a scheduled replication, or a DX API call and before a connection has been established with the Partner Site.

PreSessionStart Called once before each session is initiated with the attached database and before any attempt to contact the Partner Site has been made.

PostSessionStart Called after the connection has been made with the Partner Site and before any data has been replicated. This is the first callback method that receives an identifier for the replication session. In addition, it receives the name and network address of the Partner Site.

OnSessionEnd Called after all the data has been replicated and before the network connection is terminated. This is the last session callback method that receives the SessionID. Useful for reporting the results of a replication session including the number of data conflicts resolved.

dxEventType char(30) Contains the event name {OnReplicationRequest, PreSessionStart,PostSessionStart,OnSessionEnd}

Command char(128) Contains the command the user wants to run (ex. 'c:\<Installation Directory >\bin\ffcopy.exe myfiles.mkd')

Wait bit Set this bit if you want the callback DLL to wait for the command to return and check the status code

NeedArgs bit Set this bit if you want the callback DLL to pass in session args such as dsn name, dbname, session id

Ignore bit Set this bit if you want the callback DLL to ignore this command

7-29


Activate (dxact.exe) your database using the /DL option set to dxevent.dll.

Note The replication engine (replserv.exe) must be restarted in order for the dxevent.dll to take effect.

Logging

dxevent.dll logs information and error messages to the replication log files directory which is located in:

<Installation Directory >\replication\logfiles\dxevent.log.

Event Callback API

The event callback API is documented in the Pervasive DataExchange API Reference. Contact Pervasive Software Support for a copy of the DataExchange API Reference.

7-30

GUI-based Utilities

GUI-based Utilities

Pervasive DataExchange includes four graphical user interface (GUI) utilities for completing replication design, administration and monitoring tasks. The following table lists the GUI-based utilities and offers a brief description for each utility.

da Pervasive DataExchange Manager

DataExchange Manager

Description

The DataExchange Manager is used to administer replication networks. DataExchange Manager is a separate application that can be run external to PCC. You can access the Manager by selecting DataExchange Manager from the Pervasive group on the Start menu, or from within PCC by selecting DataExchange Manager.

For more information on using the DataExchange Manager, see Chapter 9, “Using DataExchange Manager.”

Utility File Name

Utility Name Description

da Manager GUI DX Administration utility. Sets up notifications, user access, and replication schedule information.

prd Designer GUI Template Designer utility. Supports creating and updating design templates for replication.

replmonitor Replication Progress and Log Viewers

GUI statistics and logging view utility. Configures replication sessions, monitors data replication, and sets logging options.

dpwizard Deployment Wizard Wizard to deploy replication.

trwizard Template Remover Wizard Wizard to remove a replication template.

7-31


prd DataExchange Designer

Description

The DataExchange Designer is used to design and update a database for replication. You create design templates for replication using this utility. DataExchange Designer is also a separate application that can be run external to PCC. You access the Designer by selecting DataExchange Designer from the Pervasive group on the Start menu or from within PCC by selecting DataExchange Designer.

For more information on using the DataExchange Designer, see Chapter 8, “Using the DataExchange Designer.”

replmonitor Replication Progress and Log Viewers

Description

Pervasive DataExchange allows you to configure replication sessions, initiate replication, monitor it, and log it. The tools with which you perform these actions are the Replication Progress and Log Viewers. Their window is accessed from Pervasive Control Center (PCC).

For more information, see Chapter 10, “Using the Replication Progress and Log Viewers.”

dpwizard Pervasive DataExchange Deployment Tool

Description

Deployment Tool walks you through the steps necessary to deploy replication on First and Partner Sites. The wizard is an automated alternative to the DXDeploy command-line utility and can be invoked by selecting DataExchange DeploymentTool from the Pervasive group on the Start menu, or from within PCC by selecting DataExchange DeploymentTool

trwizard Pervasive DataExchange Template Remover Wizard

Description

Template Remover is a wizard that deletes a replication template. You can no longer use the template to activate sites. You access this

7-32

GUI-based Utilities

wizard by selecting DataExchange Template Remover from the Pervasive group on the Start menu.

7-33


Services

Pervasive DataExchange includes two services that initiate automatically at the time of startup. This section discusses these services and includes specific information on configuring these for your specific business requirements.

dxagent Pervasive DataExchange Agent

Description

Detects critical replication failures and notifies administrators by e-mail.

Failure Notification

DataExchange has the ability to notify you by electronic mail (e-mail) if a scheduled replication fails. The failure can be either of the following types:

A scheduled replication fails to replicate within a specified period.

A replication site cannot be communicated with (perhaps the machine is down, the network has failed, and so forth).

Notification Agent

DataExchange installs a component called the notification agent if the machine contains the Pervasive PSQL Server product. The notification agent, or DXAgent, provides the notification functionality when scheduled replication fails.

The agent is not available if you install DataExchange on a machine with the Pervasive PSQL Workgroup product. If you use a Workgroup engine as a replication site, set up your replication

File Name Utility Name Description

dxagent Pervasive DataExchange Agent

Detects critical replication failures, and notifies administrators by E-mail.

replserv Pervasive PSQL Replication Performs data replication between Pervasive PSQL databases.

7-34

Services

schedule on the site that contains the Server database engine. The agent on the Server machine will detect if replication fails on the site with the Workgroup engine.

The agent initiates an e-mail if a replication failure occurs. The subject line of the e-mail contains the words “DataExchange alert.” The body of the e-mail contains the following primary content:

Identity of computer on which the failure occurred

Name of database

Time since the last successful replication

Communication Protocol

The agent requires the basic Simple Mail Transfer Protocol (SMTP) to communicate with a mail server. Each replication machine with an agent must be configured to access the SMTP server. Correspondingly, the SMTP server must be set up to accept e-mail from each replication site running the agent.

The agent does not deal with authentication or encryption. It does allow a different port other than the standard SMTP port 25. Thus, if a firewall opens a different port, you can specify which one. The port must not require authentication or encryption.

If a replication failure occurs and the SMTP server cannot be reached, a pop-up message appears. The message informs you that e-mail could not be sent and lists the name of the SMTP server that cannot be communicated with. Note that the pop-up message appears even if no one is logged on to the computer. Also, the message continues to display until replication succeeds or the SMTP server becomes available. This is true even if you click OK to dismiss the message.

Agent Configuration

DataExchange contains a configuration file with which you configure the agent.

To configure the notification agent

1 Open the text file DXAgentConfig.XML in a text editor. The file is located in the <Installation Directory >\Replication\Config directory.

<?xml version="1.0"?>

7-35


<dxagentconfig><smtpserver><hostname>SMTP Server To Be Configured</hostname<port>25</port>

</smtpserver><email><from>[email protected]</from><to>E-mail Address To Be Configured</to>

</email></dxagentconfig>

2 Specify the following in the file:

SMTP Server To Be Configured – The name or IP address of the e-mail server.

25 – The port number on the e-mail server used for receiving mail. By default, this is set to port 25.

[email protected] – The e-mail address used by the agent for the sender of the notification. This address is for information only and does not have be an valid address.

E-mail Address To Be Configured – The e-mail address used by the agent for the recipient of the notification. Only one address is allowed, but it may be a group address.

The following example shows a modified DXAgentConfig.XML file.

<?xml version="1.0"?><dxagentconfig> <smtpserver> <hostname>myserver.mylocation.mycompany.com</hostname> <port>25</port> </smtpserver> <email> <from>[email protected]</from> <to>[email protected]</to> </email></dxagentconfig>

3 Save DXAgentConfig.XML after you modify it.

4 If you have not already done so, modify your replication schedule to include notification.

7-36

Services

replserv Pervasive PSQL Replication Service

Description

The executable of the Replication service. The Pervasive DataExchange service performs data replication between Pervasive PSQL databases.

For information on starting and stopping the Replication Service, see “Starting and Stopping Replication,” on page 2-2.

7-37


7-38

c h a p t e r

8
Using the DataExchange Designer
A Tour of the DataExchange Designer Features and Functionality

“DataExchange Designer Concepts” on page 8-2

“DataExchange Designer GUI Visual Reference” on page 8-13

“DataExchange Designer Tasks” on page 8-22

8-1


DataExchange Designer Concepts

Welcome to the DataExchange Designer. The DataExchange Designer allows you to customize a design for replication. This chapter is designed to help you better understand the features available in the DataExchange Designer and how each feature is used to create a customized replication design.

This section contains the following topics:

Overview



1-Way / 2-Way Methods

Database Selection

DataExchange Method



Replicated Tables

Design Completion

Templates

Administration

Database Settings

Preferences

Overview The Designer can be used with both Data Synchronization and Real-Time Backup Editions. An alternate method for Real-Time Backup and Data Synchronization 1-way and 2-way replications is to use the DXDeploy utility.

For information on using DXDeploy, see Chapter 7, “Using the DataExchange Utilities and Services.”


You can use the Designer in the Real-Time Backup Edition, or you can use the DXDeploy utility. This deployment utility is designed to simply and effectively handle the design and activation phases of your replication backup.

8-2


The procedures for using the Designer to create a replication design template for your Real-Time Backup are identical to the procedures for 1-way Data Synchronization. Refer to “1-Way / 2-Way Methods” on page 8-3, and follow the instructions to create a template for Real-Time Backup using the DataExchange Designer.

For information on creating a design for your replication backup, refer to Chapter 4, “Real-Time Backup Deployment Models.”

For more information on using DXDeploy, see Chapter 7, “Using the DataExchange Utilities and Services.”


For the Data Synchronization Edition, the DataExchange Designer requires that you select a DataExchange Method of replication that you want to implement. The method you select depends on your database and your business requirements. The choices are 1-way and 2-way.

1-way

Select the 1-way method if one or more of the following is true:

You want a data replication solution to ensure that you can restore data from a backup copy. This is a 1-way replication from one machine to another or from multiple machines to a single backup machine.

You want a data portal solution to ensure a backup of your data and the ability to run reports on the backup server.

Note The maximum length of a record that can be replicated for the 1-way method is 61,057 bytes.

2-way

Select the 2-way method if one or more of the following is true:

You want a data synchronization solution (2-way replication).

You do not require sophisticated conflict handling. That is, record conflicts can be handled at the column level granularity based on the most recent timestamp and other criteria.

8-3


1-Way / 2-Way Methods

This section explains the concepts of using the DataExchange Designer to create and customize replication designs for both DataExchange Methods. The instructions here provide the foundation for using either the 1-way or 2-way method, in that both methods require you to perform the following:

1 Select the database

2 Identify the database

3 Select tables for replication

Note The DataExchange Designer interface varies, depending on the DataExchange Method you choose to use. Concepts which pertain to specific DataExchange Methods are noted accordingly.

Database Selection

First you select a database to use for your replication design. You may choose to open an existing database, or you can create a new database for this purpose. The next figure shows the Database Information dialog where the database name is entered and the DataExchange Method is selected, using Data Synchronization.


The next figure shows the Database Information dialog where the database name is entered and the DataExchange Method is selected, using Real-Time Backup.

8-4


Figure 8-2 Real-Time Backup Database Selection Dialog

DataExchange Method

If you select a new database for replication, you must select the DataExchange Method to use when you enter the database information. In selecting an existing database, the DataExchange Method is already determined by the method previously used for the selected database.

The method you select depends on your database and your business requirements. The choices are 1-way and 2-way.


If applicable, you will need to enter the User Name and Password for your selected database.

See “Basic Design Tasks” on page 8-22 for more information on selecting databases for replication.


When creating a new database for replication, you must designate specific identifiers for the Project, Network, and Release names associated with your replication design.

Project

A project represents a single replicated database. The replication Project Name is of your own choosing and helps you identify and keep track of what you need to replicate. You can use a simple-to-understand name that helps you remember which database is involved.

8-5


If your goal is to replicate with a database named mydatabase, then you may want to call the project mydatabase project or something similar that helps you remember which database is involved.

A Project name must be 20 characters or less.

A project can be associated with more than one replication network. That is, you could create a design for mydatabase project, finance department network, 1.0 and mydatabase project, accounting group network, 1.0.

Network

A replication network is the grouping of replication sites that will participate in the replication. The name for the replication network is of your own choosing and helps you identify and keep track of what you need to replicate. A name that helps you remember the grouping is very useful. For example, you could name a grouping of sites in the finance department finance network.

The Network name must be 20 characters or less.

Release

The release is like a version number for the design of the replication database. Your first design could be version 1, for instance. If you choose to change the design later, then you would create a version 2 and so forth.

The Release name must be 8 characters or less.

The name for the replication release is of your own choosing and helps you identify and keep track of what you need to replicate.

The Project, Network, and Release names are added to the database network analyst (DNA), which is the system database used by the Replication Engine. The replication utilities use these names from the DNA database to allow or disallow certain actions. For example, databases that differ only by release are allowed to replicate together.

8-6


Tip Replication project names and network names must match to allow replication.

Replicated Tables

When you first start the DataExchange Designer, the database tables are listed in the left pane on the Not Replicated tab. Initially, none of the database tables are flagged for replication; all of the tables are marked as Not Replicated.

To begin your design, you decide which tables to use for replication and mark these tables accordingly.

Note Selecting tables for replication is a required task for both 1-way and 2-way DataExchange Methods.

If you are designing a replication template for Real-Time Backup, 1-way, or 2-way deployments, and you have completed the steps in this section, you may proceed to the section titled “Design Completion” on page 8-7.

See “Basic Design Tasks” on page 8-22 for more information on selecting databases for replication.

Design Completion

After you have completed your design, you save and apply the design to create the replication template. Templates are required for designs in order to establish a structure on which to base data replication.

8-7


Templates

Saving the design writes design information to one of the replication system control tables for the template. The design information for your data has not yet been applied directly to the template itself.

The save action also verifies the design and ensures that you have not specified anything incorrectly. If there are errors, the DataExchange Designer displays a window describing the error and instructing you on how to correct the error. Once the save process completes successfully, a message is presented in the lower left corner of the DataExchange Designer main window.

When you choose to save the design template, the Designer creates a template with initial design information, such as the replication system control tables. This action applies the design of your data to the template. That is, the Designer creates a replication control table for each data table you chose to replicate, and updates the replication system control tables.

A dialog box appears, like the following, on which you can specify the copy of “starter” data. The default is to copy the starter data..

If the database you are designing contains data and you want to replicate that data, then you must copy the data as starter data to the replication template. If you clear this selection, the data will not be replicated.

This option applies only to data existing in the database before configuring the database for replication. All data entered into the

8-8


database after the database is configured for replication gets replicated (provided the data is entered into a table specified for replication).

A message appears informing you that the replication template has been created. The template contains the replication control tables and the data tables.

When you use dxact.exe to activate a site, you can specify whether to copy starter data to the activated site. To copy the data during activation, it must be in the template. Using the /PREPROCESS option with dxact.exe ensures that the data is in the template when you create it with the DataExchange Designer. See “dxact” on page 7-6 for information on using this utility.

See “Design Completion Tasks” on page 8-22 for more information on working with Templates.

Administration Database Settings

You can apply settings for the following areas:

Authentication

Information Files

Authentication

Authentication is not used with Pervasive PSQL databases. Pervasive PSQL databases can replicate with any site regardless of the replication network.

Information Files

Information files contain information about the replication design and are primarily used for troubleshooting. The DataExchange Designer creates two information files when you first save your design (thereafter, a save updates the files). The files are named in the format xPDnnnnnn.OUT and xPDnnnnnn.REF. The default location is the directory where you installed Pervasive PSQL.

Generally, you do not have to use the information files unless requested by a technical support representative.

8-9


Preferences

You can set DataExchange Designer preferences to determine if database selection is automated at startup and how messages and errors are logged.

Wizard

The Startup Wizard can be invoked when you launch the DataExchange Designer, by setting the preferences on the Wizard tab of the Designer. This dialog lets you open a new database or select an existing database to use for your replication design.

Logging

The log file for the DataExchange Designer is PRD.log. This file is located in <Installation Directory >\Replication\LogFiles. You can specify certain options about the information contained in the log, the size and location of the log, and the number of logs that retain historical information.

8-10


The following table describes each available Logging Level option and provides a sample log entry for that option.

Table 8-1 DataExchange Designer Logging Level Options

Option Name Description

Error This setting turns on or off the logging of errors to the PRD.log file.

Select this check box to turn on error logging to the PRD.log file.

Clear this check box to turn off error logging.

Errors are indicated by an E in the first column:

E 01de 1117-11:54:34 Unable to connect to 'acct03db'

Warning This setting turns on or off the logging of warnings to the PRD.log file.

Select this check box to turn on warning logging to the PRD.log file.

Clear this check box to turn off warning logging.

Warnings are indicated by a W in the first column:

W 01de 1117-11:54:34 Connection to acct03db not found.Attempting to create connection.

Information This setting turns on or off the logging of information messages to the PRD.log file.

Select this check box to turn on information logging to the PRD.log file.

Clear this check box to turn off information logging.

Information messages are indicated by an I in the first column:

I 019c 1109-14:06:36 Pervasive PSQL Replication Administrator

8-11


Caution Avoid using the Trace option for long periods (over 30 minutes), particularly if you are performing numerous tasks with the DataExchange Designer. Trace outputs every function call to the log file. Your log file can grow enormously in a very short period. Generally, only use Trace when requested by a technical support representative.

The Verbose Logging option applies only to the Debug Logging Level option. (The Debug option must also be checked.) Verbose Logging outputs the source program file name and the line number within the file. The following example shows that source file dbodbcsend located a driver for Pervasive PSQL (line 425 of the source code).

D 01de 1117-11:54:34 dbodbc 425 Pervasive PSQL driver found:'Pervasive ODBC Client Interface'

Debug This setting turns on or off the logging of debug information to the PRD.log file.

Select this check box to turn on debug information logging to the PRD.log file.

Clear this check box to turn off the logging of debug information.

Debug information is indicated by a D in the first column:

D01de 1117-11:54:26 DRE address for PDDNA is user_main

Tracing This setting turns on or off the logging of trace information to the PRD.log file. The information being traced is every function call.

Select this check box to turn on trace information logging to the PRD.log file.

Clear this check box to turn off the logging of trace information.

Trace information is indicated by a T in the first column:

T 0177 1117-13:19:41 0 << DDBInserter::InsertRecord (0ms)

Table 8-1 DataExchange Designer Logging Level Options


8-12


Log file options you can set include Maximum Log Size, Maximum Logs to Keep, and the Name of Log File.

Maximum Logs to Keep - This value sets the number of history files retained. Each time the Designer is activated, a new PRD.log file is created, renaming the previous PRD.log file to PRD.lo1.

For example, when the Designer is activated, the files PRD.log and PRD.lo1 are created. PRD.log is then empty and starts acquiring data once more. The next time the Designer is activated, PRD.lo1 becomes PRD.lo2, a new PRD.lo1 is created from PRD.log, and PRD.log is again empty and able to acquire data. The Maximum Logs to Keep setting determines the extent of the history retained: lo1, lo2, lo3, and so forth.

Name of Log File - This specifies the location and name of the current log. The Pervasive DataExchange logs are located at <Installation Directory >\Replication\Logfiles. The default log file name for the Designer is PRD.log. You can change the location and the name of log file for the DataExchange Designer if you prefer.

This completes the discussion of DataExchange Designer concepts. The next section discusses the graphical user interface of the DataExchange Designer.

8-13


DataExchange Designer GUI Visual Reference

This section details the objects on the DataExchange Designer graphical user interface (GUI). The areas that are described in this section include:

Main Window

Designer Menu and Toolbar

Database Design pane

Main Window The main window of the DataExchange Designer displays when the application is first started or after you have selected a database for use, depending on the application settings you have made. The following image shows the main window of the DataExchange Designer GUI. The primary objects in this window include:

Title Bar

Menu Bar

Toolbar

Database Design Pane

Status Bar

Figure 8-3 Designer Main Window

8-14


The following table describes the main window GUI objects. Each object is explained in depth in the subsequent sections of this chapter.

GUI Object Description Related Information

Title Bar Shows the name of the utility.

Also contains the following:

Minimize button

Maximize button

Close button

Menu Bar Provides the following menu options:

File

Actions

Tools

View

Help

“Designer Menu and Toolbar” on page 8-15

Toolbar Contains toolbar buttons that allow you to complete a number of tasks quickly and easily.

Contains the following buttons:

New Database

Open Database

Save Database

Verify Design

Create Replication Template

Create a New Release

View Messages

Refresh

Help Topics

“Designer Menu and Toolbar” on page 8-15

8-15


Designer Menu and Toolbar

The following image shows the menu and toolbar in the DataExchange Designer interface.

Figure 8-4 Designer Menu and Toolbar

Database design pane

Displays the tables available for design from the selected database.

Contains the following objects:

Replicated tab

Not Replicated tab

“Database Design pane” on page 8-21

Status Bar Displays helpful information for selected tasks.

Displays the following replication status information:

Database Name

Project Name

Network Name

Release Name


8-16


The following table details each object available from the Designer Menu and Toolbar components.


Menu Bar Shows the following menu options:

File

Actions

Tools

View

Help

Toolbar Provides toolbar buttons that allow you to complete a number of tasks quickly and easily.

Contains the following buttons:

New Database

Open Database

Save Database

Verify Design

Create Replication Template

Create a New Release

View Messages

Refresh

Help Topics

File menu Provides the following menu commands:

New

Open...

Save

Exit

8-17


New (Ctrl+N)

or

(New Database button)

Opens the Database Information dialog with which you can specify a new database to design.

“To create a new database for replication” on page 8-24

Open... (Ctrl+O)

or

(Open Database button)

Displays the Database Select or New dialog with which you can select a replication template database or a new database to open.

“To open an existing database for replication” on page 8-25

Save (Ctrl+S)

or

(Save Database button)

Saves the current state of the design in one of the replication control tables. The Designer adds the replication control tables to an existing database when you open the database. A template already contains the replication control tables. Save Database is not the same as Create Replication Template.

Exit Quits the application and prompts you to save your work.

Actions menu Provides the following commands:

Replicate Table

Don’t Replicate Table

Refresh

Replicate Table Designates a table for replication.

“To designate a table for replication” on page 8-27

Don’t Replicate Table

Designates a table to which you want excluded from replication.

“To designate a table not to be replicated” on page 8-28


8-18


Refresh (F5)

or

(Refresh button)

Displays an updated, or refreshed, view of the current replication design.

Tools menu Provides the following commands:

Verify Design

Create Replication Template...

Create New Release...

Verify Design

or

(Verify Design button)

Checks your replication design for referential integrity. Any design errors are reported in a messages window.

Create Replication Template...

or

(Create Replication Template... button)

Creates a replication template from the current design.

“To create a Replication Template based on a design” on page 8-29

Create New Release...

or

(Create New Release... button)

Creates a new release for the current design.

“To create a new release of a design” on page 8-30


8-19


View menu Provides the following commands:

Database Settings...

Database Information...

Verification Messages...

Preferences...

Switch Views

Database Settings Displays the current settings for the selected database. Database settings include:

Authentication

Information Files

“To access the Database Settings” on page 8-30

“To display Authentication Settings” on page 8-31

“To set the Information Files location” on page 8-32

Database Information

Displays the Database Certification Information for the selected database. Database Certification Information includes:

Name

Type

Location

Project Certificate

Organization Certificate

“To view Database Certification information” on page 8-32

Verification Messages

or

(View Messages button)

Displays all applicable messages related to the verification of the selected database.

“To view generated Verification Messages” on page 8-33


8-20


Preferences Displays the current application settings for DataExchange Designer. Setting options include:

Wizard

Logging

“To set DataExchange Designer preferences” on page 8-33

“To designate settings for the startup wizard” on page 8-33 on page 8-33

“To set the DataExchange Designer logging preferences” on page 8-34

Switch Views (Ctrl+Shift+Tab)

Help menu Provides the following commands:

Help Topics (F1)

About Pervasive DataExchange Designer

Help Topics (F1)

or

(Help Topics button)

Lists the documentation topics for DataExchange Designer.

“To display help” on page 8-23.

About DataExchange Designer

Displays the name and version of DataExchange Designer and the Pervasive DataExchange copyright information.


8-21


Database Design pane

The following image shows the Database Design pane and the objects which are included in this component of the DataExchange Designer GUI.

Figure 8-5 Database Design pane

The following table details the objects included each of the tabbed dialogs in the Database Design pane.


Replicated Tab The Replicated tab shows you a list of all the tables in the selected database that are designated for replication.

This is a list of the tables that you have designated to be replicated. Only the tables in this list will be replicated for the database your are designing.

For information on performing the tasks available from the Replicated tab, see “Basic Design Tasks” on page 8-22

Table Displays the Table name.

Not Replicated Tab

The Not Replicated tab contains a list of the tables that you have designated to not include in replication.

This is a list of the tables that you have designated not to replicate. The tables in this list will not be replicated for the database your are designing.

For information on performing the tasks available from the Not Replicated tab, see “Basic Design Tasks” on page 8-22.

Table Displays the Table name.

8-22

DataExchange Designer Tasks


This section details the tasks that you perform with the DataExchange Designer. The tasks are separated into the following categories:

General Tasks The tasks described in this section apply to general use of the tool and are intended to introduce you to working with DataExchange Designer.

“To start DataExchange Designer as a stand-alone application” on page 8-23

“To start DataExchange Designer from PCC” on page 8-23

“To display help” on page 8-23

Basic Design Tasks

The tasks described in this section apply to all replication designs. Both Real-Time Backup and Data Synchronization Editions require that these tasks be completed. The following lists the tasks included in this category.

“To create a new database for replication” on page 8-24

“To open an existing database for replication” on page 8-25

“To designate a table for replication” on page 8-27

“To designate a table not to be replicated” on page 8-28

Category Description

General Tasks Introduces you to working with the DataExchange Designer.

Basic Design Tasks Apply to creating designs for both Real-Time Backup and Data Synchronization Editions.

Design Completion Tasks Apply to completing and applying replication designs.

Administrative Tasks Apply to setting preferences for replication designs.

8-23


Design Completion Tasks

“To create a Replication Template based on a design” on page 8-29

“To create a new release of a design” on page 8-30

Administrative Tasks

“To access the Database Settings” on page 8-30

“To display Authentication Settings” on page 8-31

“To set the Information Files location” on page 8-32

“To view Database Certification information” on page 8-32

“To view generated Verification Messages” on page 8-33

“To set DataExchange Designer preferences” on page 8-33

“To designate settings for the startup wizard” on page 8-33

“To set the DataExchange Designer logging preferences” on page 8-34

General Tasks

To start DataExchange Designer as a stand-alone application

1 Select DataExchange Designer from the Pervasive group on the Start menu.

To start DataExchange Designer from PCC


2 In PCC expand the database node for the database for which you want to create a design.

3 Select DataExchange Designer.

To display help

1 Click Help, then select the type of help you want:

Help Topics – Lists the documentation topics for DataExchange Designer.

About – Displays the name and version of DataExchange Designer and the Pervasive DataExchange copyright information.

8-24


Tip You may also press F1 to access the list of help topics.

Basic Design Tasks

Note The tasks described in this section apply to all replication designs created with the DataExchange Designer.

To create a new database for replication

1 From the DataExchange Designer menu bar click File New.

The Database Information dialog will prompt you for information about the new database.

2 Type the DBName for the database you want to design.

Tip The database must exist and already have been added to ODBC.

3 Select the DataExchange Method to use. Choices include 1-way or 2-way.

8-25


If you are designing a template for Real-Time Backup replication, you will not have the option to select a DataExchange Method.

4 If the database uses Pervasive PSQL security, enter Master for the the User Name. This is the default user name for databases with Pervasive PSQL security.

Database security can be enabled through Pervasive Control Center (PCC). To verify if security is enabled, right-click a database name in the PCC tree and select Properties. Select the Security tab, which will state if security is enabled.

5 Type the Password for the Master user name.

6 Click Next. The Database Identification dialog will prompt you for information about the replication design.

7 Enter or select from the drop-down list the Project name for your design. Project names must be 20 characters or less.

8 Enter or select from the drop-down list the Network name for your design. The Network name must be 20 characters or less.

9 Enter the Release name for your design. The release is like a version number for the design of the replication database. The Release name must be 8 characters or less.

8-26


Tip The Project names and Network names must match to allow replication.

To open an existing database for replication

1 From the DataExchange Designer menu bar click File Open.

The Database Select or New dialog displays, showing the list of template databases available for design.

2 Select the desired template from the list.

3 Click Finish to open the template.

Note You can select Enable New Database from this screen, and the Database Information dialog discussed in “To create a new database for replication” on page 8-24 displays.

8-27


To designate a table for replication

1 In the Database Design pane, click the Not Replicated tab to display the tables not yet designated for replication.

2 Select the table or tables you want to designate for replication.

Tip To select multiple tables in the list, click the first table in the list. Press the Shift key and, while holding it down, click the additional tables for selection in the list.

3 Click Actions Replicate Table.

Tip You can also designate tables for replication by right-clicking the selected table(s), then click Replicate Table.

The selected tables move from the Not Replicated tab to the Replicated tab.

As you select each table name on the Replicated tab, the view on the right changes to show information for that table. The first tab on the right shows the structure for a particular table.

8-28


To designate a table not to be replicated

1 In the Database Design pane, click the Replicated tab to display the tables designated for replication.

2 Select the table or tables you want to exclude from replication.

Tip To select multiple tables in the list, click the first table in the list. Press the Shift key and, while holding it down, click the additional tables for selection in the list.

3 Click Actions Don’t Replicate Table.

Tip You can also exclude tables from replication by right-clicking the selected table(s), then clicking Don’t Replicate Table.

The selected tables move from the Replicated tab to the Not Replicated tab.

8-29


For more information on Basic Designs, see “1-Way / 2-Way Methods” on page 8-3.

Design Completion Tasks

To create a Replication Template based on a design

1 Click Tools Create Replication Template. A dialog appears on which you specify to copy starter data to other replication sites.

If the database you are designing contains data and you want to replicate that data, then you must copy the data as starter data to the replication template.

8-30


Note When you activate a site you can specify whether to copy the starter data to the activated site. If you want to copy the data during activation, it must already be in the template. The DataExchange Designer and dxact.exe each have options dealing with copying data.


To copy data (the default), click OK.

To not copy data, clear the Copy starter data to other sites option, then click OK.

To create a new release of a design

1 Click Tools Create New Release.

The New Release Name dialog displays.

2 Type a new Release Name, which must be 8 characters or less.

3 Click OK. A message appears informing you that the new release was successfully created.

4 Click OK.

Administrative Tasks

To access the Database Settings

1 Click View Database Settings.

8-31


2 The Database Settings dialog displays.

You can apply settings for the following areas:

Authentication

Information Files

To display Authentication Settings

1 From the Database Settings dialog, select the Authentication tab.

I replicate only with Registered Sites

This option is automatically disabled for you because you are designing with Pervasive PSQL databases. Registered sites do not apply to Pervasive PSQL databases, which can replicate with any site regardless of the replication network being used.

8-32


I replicate with any Site

This option is automatically selected for you because you are designing with Pervasive PSQL databases. Pervasive PSQL databases can replicate with any site regardless of the replication network being used.

To set the Information Files location

1 From the Database Settings dialog, select the Information Files tab.

2 Type the location, or use the browse button, for the location where you want the information files to be created. The default location is the directory where you installed Pervasive PSQL.

3 Click OK.

To view Database Certification information

1 Click View Database Information. The Database Certification displays.

8-33


2 Click OK.

To view generated Verification Messages

1 Click View Verification Messages. A pop-up window appears that contains the messages. The next illustration shows the message window.

To set DataExchange Designer preferences

1 Click View Preferences.

The Settings dialog displays, showing the tabbed areas for which you can designate preferences.

You set preferences on the following Settings tabs:

Wizard

Logging

To designate settings for the startup wizard


2 The Settings dialog displays. Select the Wizard tab.


Select the Show Wizard on Start Up check box to invoke the Startup Wizard when the DataExchange Designer opens.

Clear the Show Wizard on Start Up check box to start the DataExchange Designer without invoking the Startup Wizard automatically.

8-34


Note If you have selected to launch the Designer without invoking the Startup Wizard, you must use either File New to open a new database or File Open to open an existing database.

To set the DataExchange Designer logging preferences


2 The Settings dialog displays. Select the Logging tab.

3 Mark the check box for each of the Logging Levels option for which you want Designer to report.

Error - records Error messages to the log file

Warning - records Warning messages to the log file

Information - records Information messages to the log file

Debug - records debugging information to the log file

Tracing - records trace information to the log file.

For more information on Logging Level options, see “Logging” on page 8-9.

Caution Avoid using the Trace option for long periods (over 30 minutes), particularly if you are performing numerous tasks

8-35


with the DataExchange Designer. Generally, only use Trace when requested by a technical support representative.

4 Select if you want Verbose Logging.

Note This only applies to the Debug Logging Level. Debug must be selected in order to use this option.

5 Enter the Maximum Log Size (in bytes) for the log file.

6 Enter the Maximum Logs to Keep. This is the number of log files you want DataExchange Designer to maintain.

7 Enter the location and name of the log file for DataExchange Designer.

8 Click OK.

8-36

c h a p t e r

9
Using DataExchange Manager
A Tour of DataExchange Manager Utility

The topics in this chapter include:

“DataExchange Manager Concepts” on page 9-2

“DataExchange Manager GUI Visual Reference” on page 9-9

“DataExchange Manager Tasks” on page 9-12

9-1


DataExchange Manager Concepts

DataExchange Manager provides a standard interface to administer your activated databases. You may perform the following functionality with the utility:

Manage replication schedules

Mange information about a site

Manage user information and group memberships

To use DataExchange Manager, you must log on to the utility and connect to a database. By default, the logon user name is “ADMIN” and the password is “password.” Both are case-sensitive.

The log file for DataExchange Manager is DA.log. This log is located in <Installation Directory >\Replication\LogFiles. You may customize certain aspects of the logging as explained in “DataExchange Manager Tasks” on page 9-12.

Managing Replication Schedules

The replication of data to and from sites can be automated by schedules. You may also initiate replication manually. With DataExchange Manager, you may view, change, add, and delete replication schedules.

A schedule becomes effective immediately if you create one for the First Site machine on which you are running the DataExchange Manager. If you create a schedule for a site not local to machine on which the DataExchange Manager is running, the schedule becomes effective after the next successful replication between those sites. For example, suppose you are running the DataExchange Manager on machine A and you create a schedule for machine B. The schedule takes effect the next time site A replicates with site B.

Site Schedule Tab

The site Schedule tab allows you to view, create, delete, or edit replication schedules for a site. You can also schedule periods when replication is not to occur. You access the site Schedule tab by clicking Database Sites.

9-2


Figure 9-1 Site Schedule Tab

A schedule for the First Site applies to all sites that are subscribed to the First Site. You can create as many schedules as you need for each site.

Managing Site Information

DataExchange Manager allows you to manage information about any site in your replication network from a single site (assuming that you have the correct authorization). By default, a user defined in DataExchange Manager as a System Administrator can view all sites. By default, users other than system administrators can view only their own site.

Managing a remote site is done the same way as managing your own site. However, because any changes you make to a remote site are initially stored in your local copy of the replication system database, the changes do not take effect until your site replicates with the managed site. To manage a remote site, your site must subscribe to that remote site.

Site List

The site list contains a list of all the sites to which you have administrative access in the replication network. You display the site list by clicking Database Sites. The first entry in the site list is always All Sites. The other sites are listed below All Sites.

9-3


Figure 9-2 Site List

Site Information Tab

The site Information tab allows you to view or change the information about a site, such as contact information for a person responsible for the site. You access the site Information tab by clicking Database Sites.

Figure 9-3 Site Information Tab

Remove Site from Replication Network

The Information tab contains an option Remove Site from Replication Network. This options acts as a toggle to remove a site from a replication network, or to restore a site that has been previously removed. This option does not delete any database files. The option marks the site as no longer belonging to the replication network.

This option is typically used to exclude a database from replication for a long-term period. See “Using the Replication Progress and Log Viewers” on page 10-1.

9-4


The other sites on your replication network do not know that a site has been removed until you perform a replication. Until you replicate, only the site for which you are logged on to DataExchange Manager knows that a site has been removed. An example helps clarify this.

The DataExchange Manager requires that you connect to a specific database when you log on. Assume that you select MyDataBase when you log on to DataExchange Manager. Once logged on, you remove site Partner_Site_2. At this point, only the replication tables for MyDataBase contain the removal information. The information has not been replicated to the rest of your replication network.

If you were to open the Initiate Replication dialog and select MyDataBase as the source database, Partner_Site_2 would not be included in the list of sites to replicate with. However, if you were to select a different site on the same replication network—for example Partner_Site_1—then Partner_Site_2 would still be listed in the sites to replicate with because you have not yet replicated. After you replicate, then Partner_Site_2 is no longer listed in the sites to replicate with.

Note that the first replication after removing (or restoring) a site from the replication network will fail for that site. The log file for DataExchange Designer, DRE.log, contains an error message similar to the following:

E 019f 0303-15: 6:25 Partner site Partner_Site_2(site number: 00LFLU) has been removed from the replication

network - it cannot replicate with any other site.

After the first replication, this error no longer occurs because all sites on the replication network are aware of the site’s status (removed or restored).

Managing Users

DataExchange Manager is supplied with two groups of users: System Administrators and Everyone. With DataExchange Manager, you may view, change, add, and delete user information and membership groups.

Each group contains certain permissions within DataExchange Manager and within your replication project.

By default, the System Administrator user for DataExchange Manager is named ADMIN. The ADMIN user’s password, by

9-5


default, is “password.” Both are case-sensitive. When you add a user, he or she is automatically added to the Everyone permission group.

The following table compares the default permissions of System Administrators (abbreviated System Admins) and Everyone.

Tabbed Dialogs and User List

Two tabbed dialogs allow you to specify user information and group membership, respectively. You access the tabbed dialogs by clicking Database Users.

A user list appears to the left of the tabbed dialogs and contains a list of the users who can access DataExchange Manager. By default, nonadministrative users have permission to see only themselves in the list.

Table 9-1 Permissions Comparison Between Default Groups

Permissions Within DataExchange Manager and Replication Network

System Admins

Everyone

Can add DataExchange Manager users

Can see all users

Can change information for any group or user

Can view, add, change, or delete replication schedules for any site

Can view, add, change, or delete replication schedules only for their own site

Can change only their own user information

Can change any site’s information

Can change only their own site’s information

9-6


Figure 9-4 Location of User List and User Tabbed Dialogs

By default, new users added to your database project are automatically made members of the Everyone group. To change a user’s membership from the Everyone group, you must change the user’s group membership. See “To change a user’s group membership” on page 9-22.

User Information Tab

This tab allows you to specify information about a user such as name, address, login name, and password.

Figure 9-5 User Information Tab

User Membership Tab

This tab controls a user’s membership in the defined permission groups.

9-7


Figure 9-6 User Membership Tab

Your ability to perform many administrative and data access functions is controlled by the permission group to which you belong.

Managing Permissions

With DataExchange Manager, you may only view the permission groups available with DataExchange Manager. The DataExchange permission groups are System Administrators and Everyone. You access the permissions group list by clicking Database Permission Groups.

Figure 9-7 Permissions Group List

A user’s permissions are determined based on the permission groups to which they belong. As you add new users, you must decide the appropriate permission group to which that user should belong. By default, new users added to your replication project are automatically made members of a permission group Everyone.

9-8

DataExchange Manager GUI Visual Reference


This section details the objects on the DataExchange Manager graphical user interface (GUI).

Main Window The following image shows the main window of the GUI. The table following the image describes the GUI objects.

Figure 9-8 DataExchange Manager Main Window


Title Bar Shows the name of the utility

Actions menu Provides the following commands:

Reconnect

Refresh

Exit

Reconnect command

or

icon

Displays the Logon dialog from which you may disconnect from and reconnect to a database as a different user or connect to a different database.

“To log on to DataExchange Manager” on page 9-13

“To log on as a different user or to connect to a different database” on page 9-13

9-9


Refresh command

or

icon

Applies changes made by another running copy of DataExchange Manager so that the changes are visible to your instance of the utility.

“To refresh DataExchange Manager view” on page 9-16

Exit command Terminates the execution of DataExchange Manager.

Database menu Provides the following commands:

Sites

Users

Permission Groups

Sites command

or

icon

Switches to site view. A list of sites appears in the List pane and tabbed dialogs appear in the Tabbed Dialog pane.

“Managing Replication Schedules” on page 9-2

“Managing Site Information” on page 9-3

“Site Information Tasks” on page 9-19

Users command

or

icon

Switches to user view. A list of users appears in the List Pane and tabbed dialogs appear in the Tabbed Dialog pane.

“User Tasks” on page 9-20

Permission Groups command

or

icon

Switches to permission group view. A list of permission groups appears in the List pane.

“DataExchange Manager GUI Visual Reference” on page 9-9

Options command Displays the dialog on which you specify logging options for DataExchange Manager.

“To set the log options for DataExchange Manager” on page 9-14

Help menu Provides the following commands:

Help Topics

About

Help Topics Lists the documentation topics for DataExchange Manager.



9-10


About Displays the name and version of DataExchange Manager and the Pervasive DataExchange copyright information.


List pane Depending on the selected view, displays a list of the following:

Activated sites within the replication network

DataExchange Manager users

Permission Groups



Tabbed Dialog pane

Depending on the selected view, displays the following:

Tabbed dialogs for working with sites

Tabbed dialogs for working with users



View indicator Specifies the current view:

Sites

Users

Permission



Logged on Database indicator

Identifies the database to which DataExchange Manager is currently connected.



User indicator Identifies the user currently accessing DataExchange Manager.



9-11


DataExchange Manager Tasks

This section explains the tasks that you perform withDataExchange Manager:

“General Tasks” on page 9-12

“Schedule Tasks” on page 9-18



General Tasks General tasks apply to the overall use of the tool:

“To start DataExchange Manager from Pervasive Control Center (PCC)” on page 9-12

“To start DataExchange Manager from a command prompt” on page 9-12



“To change a logon password” on page 9-13

“To set the log options for DataExchange Manager” on page 9-14

“To refresh DataExchange Manager view” on page 9-16


To start DataExchange Manager from Pervasive Control Center (PCC)


2 In Pervasive PSQL Explorer, click Engines.

3 Click DataExchange Manager.

To start DataExchange Manager from a command prompt

1 At the operating system, access a command prompt. (For example, select Start Run, type cmd then click OK.)

2 At the command prompt, type da then press Enter.

9-12


The DataExchange Manager executable is DA.EXE. The executable also supports command-line options. At a command prompt, enter da /H to display the help text and view the available options.

To log on to DataExchange Manager

You must log on to DataExchange Manager before you can use the utility. A logon dialog appears when you start the utility.

1 From the Database selection list, select the activated database to which you want to connect.

2 For Logon Name, type a valid user’s name. The default logon name is ADMIN (all capital letters).

3 For Password, type a valid password. The default password is password (all lowercase).

4 Click OK.

Note DataExchange Manager terminates after three unsuccessful attempts to connect to a database.

To log on as a different user or to connect to a different database

These steps require that you already be logged on to DataExchange Manager.

1 Click Actions Reconnect or click .

Clicking Cancel returns you to DataExchange Manager. However, if an unsuccessful logon attempt has been made, clicking Cancel exits DataExchange Manager.

9-13


To change a logon password

Permission Group Requirement: You must be a member of the System Administrator Permission Group to perform this task.

1 Click Database Users or click .

2 In the user list, click the user whose password you want to change.

3 Click the Information tab.

4 Click Change Password.

5 Type a new password in the New Password and Confirm Password entry fields.

Note The password is stripped of leading and trailing blanks.

6 Click OK to return to the Information tab.

7 Click Apply to save your changes.

To set the log options for DataExchange Manager

1 In the menu bar, click Options.

2 Specify the options you want on the logging options dialog.

The following image shows the Options dialog.

9-14


Option Discussion

Error Turns on or off the logging of errors to the log file. Errors are indicated by an E in the first column:

E 0142 1109-16:33:26 Login unsuccessful, the username/password combination is invalid

Information Turns on or off the logging of information messages to the log file. Information messages are indicated by an I in the first column:

I 019c 1109-14:06:36 Pervasive PSQL Replication Administrator

Tracing Turns on or off the logging of trace information to the log file. The information being traced is every function call. Trace information is indicated by a T in the first column:

T 0172 1109-16:33:26 0 << MessageEvent (0ms)

Caution: Avoid using the Trace option for long periods (over 30 minutes), particularly if you are performing numerous tasks with DataExchange Manager. Trace outputs every function call to the log file. Your log file can grow enormously in a very short period. Generally, use Trace only when requested by a technical support representative.

Warning Turns on or off the logging of warnings to the DA.log file. Warnings are indicated by a W in the first column:

W 0142 1109-14:07:05 Could not find site 000000

Debug Turns on or off the logging of debug information to the log file. Debug information is indicated by a D in the first column:

D 013f 1109-14:06:37 Response received from DRE:

1:SUCCESS:PD2PQQ85001,TrackerPROJ (net) - Tracker

PD2PQQ85002,TrackerPROJ (net) – TrackerPrtnr

PD2PQQ86001,tracker-project

int-tut-network) - IntTut_First_Site


int-tut-network) - IntTut_Partner_Site


(int-tut-network) - drelogtest

9-15


To refresh DataExchange Manager view

When you make changes to a database from another running copy of DataExchange Manager, such as adding a user or changing a schedule, the changes may not be immediately visible to your current instance of the Manager.

For example, suppose that you made changes to a specific user in a second instance of the Manager. To see the changes, you would need

Verbose Logging This option applies only to Debug. (The Debug option must also be checked.) Verbose outputs the source program name and the line number within the program. For example, the following example shows that program cmdsend is receiving a response from the replication engine (line 308 of the source code).

D 013f 1109-14:06:37 cmdsend 308 Response received from DRE:

1:SUCCESS:PD2PQQ85001,TrackerPROJ (net) – Tracker

Note: Some of the programs listed in verbose mode may not exist as a separate file on physical storage. Verbose mode shows the programs that are part of a compiled executable or dynamic link library.

Maximum Log Size

This value determines when a new history log file is started (lo1, lo2, and so forth). See Maximum Logs to Keep.

Maximum Logs to Keep

This value sets the number of history log files retained. When a log file reaches its maximum size, the file is reassigned to the next history file name.

For example, when the log (assume it is DA.log) reaches its maximum size, DA.lo1 gets created. DA.log is then empty and starts acquiring data once more. When the maximum size is again reached, DA.lo1 becomes DA.lo2, a new DA.lo1 is created from DA.log, and DA.log is again empty and able to acquire data. The Keep setting determines the extent of the history retained: lo1, lo2, lo3, and so forth.

Name of Log File This specifies the location and name of the current log file. The Pervasive DataExchange logs are located at <Installation Directory >\Replication\Logfiles. You can change the location and the name of log file for DataExchange Manager if you prefer.


Option Discussion

9-16


to switch to the user Information tab in the first Manager and refresh the view.

1 In the menu bar, click Options, or press F5 or click .

To display help

1 Click Help, then the type of help you want:

Help Topics – Lists the documentation topics for DataExchange Manager.

About – Displays the name and version of DataExchange Manager and the Pervasive DataExchange copyright information.

You may also press F1 to access the list of help topics.

9-17


Schedule Tasks Schedule tasks apply to automating replication:

“To create a replication schedule” on page 9-18

“To change a replication schedule” on page 9-19

“To delete a replication schedule” on page 9-19

To create a replication schedule


1 Click Database Sites or click .

2 In the site list, click the site for which you want to set up a replication schedule.

You cannot set up a schedule for All Sites.

3 Click the Schedule tab.

4 Click Add on the tab.

5 Type a name for the new schedule.

6 Specify the days of the week, month, or specific dates for which the replication occurs.

7 Specify the hours, in 24-hour format, for which the replication occurs.

The range is 00:00 to 23:59.

8 Specify the action taken by the schedule:

Option Meaning

Schedule every [value] minutes

The frequency, in whole minutes, in which the replication schedule runs. A value of zero indicates continuous replication, which means that another replication session begins as soon as the previous session completes.

Do not replicate Disables the replication schedule.

Notify if no replication after [value] minutes

See “dxagent” on page 7-34 for a discussion of the notification agent and how this option applies to the agent.

The minutes value for the notify option must be either zero, for continuous replication, or greater than the Replicate every value by at least one minute.

9-18


9 Click Apply to save the changes.

10 Click OK to acknowledge that a replication is required for the change(s) to take effect.

To change a replication schedule



2 In the site list, click the site for which you want to set up a replication schedule.

You cannot set up a schedule for All Sites.


4 In the Name list, click the schedule that you want to change.

5 Complete steps 6 through 9 as explained in “To create a replication schedule”.

To delete a replication schedule



2 In the site list, click the site that you want to delete.


4 Click Delete on the tab.

5 Click Yes to confirm the deletion.

Site Information Tasks

Site information tasks apply to contact information about a site or removing a site from a replication network:

“To change site information” on page 9-19

“To remove a site from or restore a site to a replication network” on page 9-20

To change site information


9-19



2 In the site list, click the site that you want to delete.


4 Specify the contact information for the site.

To remove a site from a replication network, or to restore a site that has been previously removed, see the following task.

5 Click Apply to save the changes.

To remove a site from or restore a site to a replication network


2 In the site list, click the desired site.



To remove a site, select Remove Site from Replication Network.

To restore a site already removed, clear Remove Site from Replication Network.

Note The option Remove Site from Replication Network does not require you to apply the action. Selecting or clearing the option is sufficient. For the removal or restoration to take effect, however, you must perform a replication session.

User Tasks User tasks apply to adding or deleting users and membership groups and changing user information:

“To add a new user” on page 9-20

“To change user information” on page 9-21

“To delete a user” on page 9-21

“To change a user’s group membership” on page 9-22

To add a new user


9-20




3 Click Add on the Information tab.

4 Type the desired user information in the entry fields. The First Name, Last Name, Logon Name, and Password are mandatory.

Note that the Logon name is automatically converted to uppercase and stripped of leading and trailing blanks.

5 Click Set Password.

6 For New Password, type the desired password. Retype this same password for Confirm Password.

7 Click OK.

Note that the password is stripped of leading and trailing blanks.


To change user information

Permission Group Requirement: To edit a user’s information (other than your own), you must be a member of the System Administrator Permission Group. All users can change their own information.


2 In the user list, click the desired user.


4 Change the user information as desired.

See “To change a logon password” on page 9-13 if you want to change a password.


To delete a user





9-21


4 Click Delete.

You cannot delete the default administrator user ADMIN.

To change a user’s group membership




3 Click the Membership tab.

4 In the Work Sets pane, click the work set to which the permission group belongs.

Permission groups for a selected work set are sorted into two lists: Not a Member Of and Member Of. The selected user is a member of all those groups in the Member Of list.

5 Click the desired permission group, then use the arrow buttons between the lists to move the group to the Member Of or Not a Member Of lists.

For example, in the following image, if you wanted to add a user to the System Administrators group, click System Administrators in the Not a Member Of list, then click .


9-22

c h a p t e r

10
Using the Replication Progress and Log Viewers
A Brief Look at the Replication Progress and Log Viewers

Pervasive DataExchange allows you to configure replication sessions, initiate replication, monitor it, and log it. The tools with which you perform these actions are the Replication Progress and Log Viewers. Their window is accessed from Pervasive Control Center (PCC).

This chapter covers the following topics:

“Checking the Replication Engine and Service” on page 10-2

“Initiating Replication from the Progress and Log Viewers” on page 10-4

“Recording and Monitoring Replication Activity” on page 10-7

10-1


Checking the Replication Engine and Service

To view engine and service state

1 From Pervasive Control Center (PCC), right-click the Replication - Connected node and select View Engine and Service State.

2 The Engine and Service State dialog box, similar to the following, displays:

The information displayed in this dialog is informational only and cannot be edited.

To view the state of a database

1 In PCC, right-click the Replication node under a specific database and select View Database State.

If the database has been activated, the following dialog appears:

10-2

Checking the Replication Engine and Service

All of the fields on the dialog are ready-only.

The types of states include the following:

DNA. This indicates that the database is the replication system database: Database Network Analysis (DNA). This database has a data source name like PD00000x and is created when you install Pervasive DataExchange.

Caution Do not delete this database. Pervasive DataExchange will not function if you do.

Pure. This indicates that the database does not contain replication control tables. That is, the database has not been activated nor is it a template.

Template. This indicates that the database is a replication template.

2 Click Close when you’re done.

10-3


Initiating Replication from the Progress and Log Viewers

You can manually initiate a replication session. The Initiate Replication dialog box lets you select a database to replicate, the type of replication, and the sites to include. This section covers the following topics:

“Initiating a Replication Session” on page 10-4

“Reading the Initiate Replication Dialog Box” on page 10-6

Initiating a Replication Session

To initiate replication

1 In PCC, right-click the Replication - Connected node in Pervasive PSQL Explorer, then do one of the following:

Select Initiate Replication.

Select Statistics and Log Views to open the Replication Progress and Log Viewers and then in the toolbar, click the Initiate replication icon .


10-4

Initiating Replication from the Progress and Log Viewers

2 Select the Source Database you want from the Source Database drop-down list.

3 Click the type of replication you want. Choose one of the following options:

a. Replicate data between the source database and the selected sites.

This option replicates data between the source database and the selected sites. This is the default and causes the Replication Engine to replicate the data among the machines specified, resolving any data conflicts. Either the default conflict handling is used (most recent change wins) or an event handler callback DLL is used if you specified one at activation time.

b. Delete and replace all data on the selected sites with data from the source database.

This option deletes and replaces all data on the selected sites with data from the source database. This deletes all data on the sites you check mark in the list of sites to replicate with. The data from the source database replaces the data. The source database can be used to delete/replace data on one or more sites. Conflict resolution is not performed.

c. Delete and replace all data on the local site with data from the selected site.

This option deletes and replaces all data on the local site (the source database) with data from the selected site. This deletes all data in the source database and replaces it with the data from the selected site. You can designate only one selected site (a one-to-one situation). Conflict resolution is not performed.

4 Check mark the sites with which you want to replicate with the source database. Clear the check mark for the sites you do not want to participate in the replication.

5 Click Replicate.

Note The list of sites to replicate with may seem inconsistent depending on how you activated your Partner Sites.

10-5


Reading the Initiate Replication Dialog Box

The list of sites to replicate with may seem inconsistent depending on how you activated your Partner Sites.

Here's an example of how the list may appear inconsistent. You create Partner Site PS1 and perform an initial replication with the First Site (the default behavior). You create Partner Site PS2 but do not perform an initial replication with the First Site.

In the Initiate Replication dialog, if you select as the source database the First Site or PS1, neither shows PS2 as a site to replicate with. This may lead you to question, "what became of my second Partner Site? Why isn't PS2 in the list?"

It is not in the list because the information about the replication network, such as the sites on it, is also replicated. If you select PS2 as the source database, the choice First Replication Site shows as a site to replicate with. After you replicate with the First Site, then PS2 appears in the list for the First Site and PS1.

The easiest way to ensure consistency in the list is to perform an initial replication with the First Site when you activate each Partner Site. A Partner Site cannot replicate with other sites until it replicates with the First Site.

10-6

Recording and Monitoring Replication Activity


This section covers the following topics:

“Setting Log Options” on page 10-7

“DRE Log File” on page 10-8

Setting Log Options

To set Log Options

1 In PCC, right-click Replication - Connected and select Statistics and Log Views.

2 Right-click in the Replication Log Viewer and select Log Messages.

A drop-down menu displays log commands and settings.

3 You may select the option shown in the following table for the actions you wish to perform.

Table 10-1 Replication Logging Commands

Command Description

Clear Log Removes all lines from the log display pane. (The log on physical storage is not affected.)

Copy Copies the current highlighted line in the pane. You can then paste the copied line into another application.

Freeze Controls the display of log information while the DRE.log is updated. If selected, no new entries are displayed in the pane. The DRE.log file continues to receive information if loggingis enabled. Toggling the setting redisplays the current log information.

If not selected, new log information appears in the display pane as the DRE.log is updated. This is the default behavior.

10-7


DRE Log File The Replication Engine records its operation in the file DRE.log. You can use this log file to monitor replication activities.

Where appropriate, the messages in the DRE.log include the user-supplied names for the database, replication project, replication network, and replication release. The local database is referred to by its data source name (DSN). Remote sites are referred to by their display name and a site number. Remote sites typically have the same database name as the local site.

Each site in every replication network is numbered, beginning at 1,000,000 for the First Site, and incrementing by one for each site thereafter. These numbers appear as base 36 numbers. The DRE log is the only log that uses the base 36 site numbers.

The type of message in DRE.log is indicated by a letter in the first column of the message, as follows:

D - debug

E - error

I - information

W – warning

The following table describes each available Logging Level option and provides a sample log entry for that option.

Log Messages Toggle the selection for each of the following logging options as needed:

Debug Logging - Writes debug messages to the log file

Error - WrItes error messages to the log file

Information - Writes information messages to the log file

Warning - Writes warning messages to the log file

Verbose Logging - Writes the source program name and the program line number

Group By Displays entries grouped by Type (debug, error, information, and warning) or by None. The default is None, which lists all of the log information with the most recent at the top. Information grouped by Type is initially collapsed into a single node to be expanded for viewing.

Table 10-1 Replication Logging Commands

Command Description

10-8


Table 10-2 Replication Progress and Log Viewers Logging Level Options


Error The option turns on or off the logging of errors to the DRE.log file.

Errors are indicated by an E in the first column:

E 01b7 0219-13:51:34 Partner site AcctSvr1(site number: 00LFLV) has been removed from the replication network - it cannot replicate with any other site.

If checked, the option turns on the logging of errors.

Warning The option turns on or off the logging of warnings to the DRE.log file.

Warnings are indicated by a W in the first column:

W 01a7 0219-09:52:19 CONFLICT: Type V: Starter data in record F1 for table Purchase is different at the two sites - conflict must be resolved manually (key: PDCID(2147483360)). The starter-data (data in the database when the database was first designed and activated) must be identical on each site in the Replication Network. To resolve the conflict manually, insure that this is so.

If checked, the option turns on the logging of warnings.

Information The option turns on or off the logging of information messages to the DRE.log file.

Information messages are indicated by an I in the first column:

I01ae 0216-16:04:10 Attempting replication on Replication Network Finance-Network. Local database is AcctPay. This database is in Project: Finance-Project, Replication Network: Finance-Network, Release: 1.0.

If checked, the option turns on the logging of information messages.

10-9


Tip Typically, use Verbose only for troubleshooting and not as a general setting for DRE.log.

Some of the programs listed in verbose mode may not exist as a separate file on physical storage. Verbose mode shows the programs that are part of a compiled executable or dynamic link library.

For instructions on setting logging options, refer to “Checking the Replication Engine and Service” on page 10-2.

Verbose Logging This option applies only to Debug. (The Debug option must also be checked.) Verbose outputs the source program name and the line number within the program. For example, the following example shows that program drelutil is creating an update list record at line 306 of the source code.

D 0136 1107-16:00:04 drelutil 306 Creating update list record with key 1000001

Debug The option turns on or off the logging of debug information to the DRE.log file.

Debug information is indicated by a D in the first column:

D 0193 0216-16:04:27 Committing transaction

If checked, the option turns on the logging of debug information. Typically, use Debug only for troubleshooting and not as a general setting for the DRE.log.

Table 10-2 Replication Progress and Log Viewers Logging Level Options


10-10

SUPPLEMENTAL INFORMATION

a p p e n d i x

A
Basic Troubleshooting
How to Identify and Solve Common Problems

This chapter provides information for troubleshooting and resolving the most commonly encountered problems. This chapter includes the following sections:

“Troubleshooting Resources” on page A-2

“Troubleshooting Strategies” on page A-3

“Installation” on page A-4

“Uninstalling” on page A-5

“Network Communications” on page A-6

“Database Engine” on page A-7

“Replication Engine” on page A-8

“Log Files” on page A-9

“Data Replication” on page A-13

“Notification Agent” on page A-23

“How to Get Additional Help” on page A-24

A-1


Troubleshooting Resources

The following table describes resources available to help you solve problems.

Table A-1 Resources that Assist with Problem Determination

Feature/Component

Function For More Information

DataExchange log files

Logs information during replication processing.

See “Log Files” on page A-9

DataExchange Table Synchronization and Check utility

Ensures that every record in the data tables has a corresponding record in the replication control tables.

See “dxsynctables” on page 7-25 in Pervasive DataExchange User’s Guide

Pervasive System Analyzer

Tests active engine installations and network communications in DataExchange.

See “Network Communications” on page A-6

Knowledge Base Provides information about many Pervasive software configurations and common environments.

Search the Pervasive Knowledge base at: http://www.pervasive.com/kb

A-2

Troubleshooting Strategies

Troubleshooting Strategies

You must first diagnose a problem before you can fix it. The following checklist contains items to help you diagnose problems with DataExchange.

Did DataExchange install correctly?

Did DataExchange uninstall correctly?

Does the network function correctly?

Is the database engine running?

Is the replication engine running?

Is data being replicated correctly?

Is the notification agent sending e-mail?

Do the log files contain errors?

Are other sources of help available?

The rest of this chapter discusses each checklist item in more depth.

A-3


Installation

This section discusses topics that pertain to installation.

Multiple DataExchange Designers

Unpredictable results can occur if you design replication databases with more than one DataExchange Designer. For this reason, install only one DataExchange Designer per replication network. DataExchange Designer is installed as part of a First Site installation. In other words, install only one First Site per replication network.

Terminal Services

To install DataExchange to a Terminal Server client, you must first modify a registry setting on the Terminal Server client. See “Installing Over Windows Terminal Services” on page 3-2 in Getting Started with Pervasive DataExchange.

A-4

Uninstalling

Uninstalling

If you have activated databases that are located under <Installation Directory >\Replication, first deactivate them then delete the replication template with the Template Remover wizard. If you do not deactivate the database then remove the template, uninstall leaves the database files and the associated replication files. The remaining files do not cause any problems but you may prefer to reclaim physical storage by deleting them. You may delete the files manually if you want. Remember, also, to remove the DSN associated with the database.

See “Working with the Examples” on page 5-6 for a discussion of how to deactivate a database and remove a template.

A-5


Network Communications

Pervasive System Analyzer (PSA) is a diagnostic utility included with the Pervasive PSQL database engines. PSA can be used as a stand-alone diagnostic tool to help you troubleshoot network problems.

Note For DataExchange, use PSA only to troubleshoot network problems. PSA is capable of other functions pertaining only to the Pervasive PSQL database engines. The additional functions in PSA (such as archiving) do not apply to DataExchange.

How to Start PSA

To start PSA

1 Select Pervasive System Analyzer from the Pervasive group on the Start menu.

Note To troubleshoot your network communications for DataExchange, select Test Active Installation on the System Analyzer Options dialog in PSA.

Documentation for PSA

The use of PSA is detailed in the Pervasive PSQL User's Guide. Please see that guide for complete information regarding PSA.

A-6

Database Engine

Database Engine

The Pervasive PSQL database engine must be running to perform replication.

To verify Pervasive PSQL Server engine is running


2 Click Administrative Tools, then open Services.

3 Scroll the list until you reach the following services:

Pervasive PSQL Transactional Engine

Pervasive PSQL Relational Engine

Both of these services must be started for the Pervasive PSQL database engine to function correctly.

The Status column shows whether the service is currently running. The Startup column shows whether the service is set to automatically start on system startup or start manually.

4 If a service is not started, right-click its icon and select Start.

To verify Pervasive PSQL Workgroup engine is running

1 Check for the Workgroup icon in the Windows task bar:

If this icon (engine running) is showing, the engine is running.

The engine is not running if either of the following is true:

The engine-running icon is not showing in the Windows task bar.

The following icon (engine stopped) is showing in Pervasive PSQL Explorer:

You can start the engine by clicking Start Programs Pervasive PSQL Engines Pervasive PSQL Workgroup Engine.

A-7


Replication Engine

The DataExchange replication engine must be running to perform replication.

To verify replication engine is running with Pervasive PSQL Server



3 Scroll the list of services until you reach the service Pervasive PSQL Replication.

This service must be started for the DataExchange replication engine to function correctly.


4 If the service is not started, right-click its icon and select Start.

To verify replication engine is running with Pervasive PSQL Workgroup

1 Check the Workgroup icon in the Windows tasteable

If this icon is showing, the engine is running. The engine is not running if this icon is not showing.

You can start the engine by clicking DataExchange Replication Engine from the Pervasive group on the Start menu.

A-8

Log Files

Log Files

Pervasive DataExchange allows you to enable event logging via log files. You may record the activity of the DataExchange Designer, the DataExchange Monitoring Tools, the DataExchange Manager, and the Replication Engine. Additionally, DataExchange keeps a messages log and an installation log.

All logs are text files and have a file extension of .log for the most current one saved. The files produce any mix of data: Information, Warning, Error, and Debugging. You can choose verbose (as opposed to terse) messages. Verbose messages contain the name of the program and a line number within the program to help you debug situations. Verbose applies only to the Debug logging level.

You can change the default location of the logs, which is <Installation Directory >\Replication\LogFiles. If you want, you can also change the default log size and the default number of files kept (a history). You can view the LogFiles folder by selecting DataExchange LogFiles from the Pervasive group on the Start menu.

Log File Size If you set the maximum log size to zero, or no limit, the log will increase in size to whatever capacity the physical storage allows. We recommend that you do not set a maximum log size of zero except for troubleshooting. Even then, avoid using the no limit setting for an extended period (typically, more than four hours). The DRE log, for example, can grow rapidly depending on the type of logging being performed (such as Debug logging), the frequency of replication, and the number of sites replicating.

In the case of the DRE.log, when the log file reaches its maximum size, the file is reassigned to the next history file name. For example, when the Dre.log reaches its maximum size, it gets renamed to Dre.lo1 and a new Dre.log gets created. Dre.log is then empty and starts acquiring data once more. When the maximum size is again reached, Dre.lo1 gets renamed to Dre.lo2, Dre.log gets renamed to Dre.lo1, and a new Dre.log is again empty and able to acquire data. The Maximum Logs to Keep setting determines the extent of the history retained: lo1, lo2, lo3, and so forth.

Other DataExchange components automatically start a new log file when the utility or service executes. In this situation, each time the

A-9


utility is activated the associated XXX.log file is copied to a new XXX.lo1 file. The utility then begins logging in the now empty XXX.log file. Again, the Maximum Logs to Keep setting determines the extent of the history retained: lo1, lo2, lo3, and so forth.

The DataExchange Designer, DataExchange Manager, and the DataExchange Monitoring Tools have a Logging dialog that allows you to change the logging settings.

Log File Descriptions

The following table describes the content of the various log files.

Log File (.log) Description

da The log updated by DataExchange Manager when you modify schedules, user access, and so forth.

dnewsite The replication installation log. This log is created when you install Pervasive DataExchange and contains information about setting up the replication DNA database.

dre This log contains detailed information on the status of the replications, and is the most active log file. The Replication Engine updates this log as replication occurs.

The default maximum size of this log is 2 MB. You may want to limit this log to a maximum 5 MB. Some text editors cannot open files larger than 10 MB.

When the Replication Engine reassigns the DRE log to the next history version (DRE.log to DRE.lo1, for instance), some log messages may be lost. The loss is typically minimal and may not even occur, depending on the replication activity when the history version is assigned.

dregdtk This log is created if you install a First Site (which includes the DataExchange Designer). The log contains information about registering the licenses.

dxact The log updated by the activation utility when you activate a site.

dxdeact The log updated by the deactivation utility when you deactivate a site.

dxevent The log updated by the dxevent.dll, which handles replication session event callbacks.

dxsynctables The log updated by the dxsynctables utility, which is used to synchronize data files and the replication data control files.

A-10

Log Files

To access logging options in DataExchange Manager

1 In PCC, click the name of a database.

2 Click Tools Manager.

3 Log on to Manager.

4 Click Options.

To access logging options

1 In PCC, right-click Replication under the name of a database.

ffcopy The log updated by the ffcopy.exe utility, which copies non-Btrieve files from a First Site to a Partner Site.

mer This log is written to if errors occur while DataExchange routes calls to the MKDE. This log is usually empty. If you suspect that data is not getting replicated correctly, check this log.

msg This log lists messages about the replication sessions, the sites that replicated and if the replication was successful. The Replication Engine writes to this log. The dre log is more detailed.

prd The log that DataExchange Designer updates when you design a replication template.

reh This log contains information only if the Replication event handlers encounter problems updating control tables. If you suspect that data is not getting replicated correctly, check this log.

replinst The log that Pervasive DataExchange creates to record information related only to installation. This log file is especially useful if installation fails.

Note that if installation fails, the file is located in the Windows directory for Windows 9x and in the WINNT directory under Windows 2000.

sess#### These logs contain information about particular replication sessions. The #### represents a four-digit number.

The logs are created if you set up a replication schedule and then replicate. The logs are deleted if you stop the replication engine, and are also deleted at regular intervals. The deletion interval is set by a registry setting.

Log File (.log) Description

A-11


2 Select Statistics and Log Views.

3 Right-click in the Replication Log Viewer and select Log Messages.

To change the deletion interval for session logs

Caution Incorrectly editing your computer’s registry can damage the registry. The damage can cause undesirable results, such as your computer not being able to boot. If you do not feel comfortable editing the registry, obtain the services of a qualified technician. Pervasive Software accepts no responsibility for a damaged registry.

We suggest that you create a backup of your registry before editing the registry. Refer to the online help for your operating system. Look for index entries such as “registry, backing up,” or “emergency repair disk.”

1 Select Start Run, type regedt32 in the Open field of the Run dialog box, and click OK.

Registry Editor opens.

2 Find the following registry key:

HKEY_LOCAL_MACHINE\Software\Pervasive Software\Pervasive Replication\SessionExpiry

3 Double-click REG_DWORD for the key.

The Edit DWORD Value dialog opens.

4 In the Value Data field, change the value to the desired minutes (5 is the default).

5 Click OK.

6 Exit Registry Editor.

A-12

Data Replication

Data Replication

This section discusses topics that pertain to replicating data.

List of Sites to Replicate With Seems Inconsistent

The Initiate Replication dialog allows you to start a replication. (Right-click Replication - Connected in the PCC tree, then click Tasks Initiate Replication to display the dialog.) On this dialog, you select a source database and the sites to replicate with. The list of sites to replicate with may seem inconsistent depending on how you activated your Partner Sites.

Here’s an example of how the list may appear inconsistent. You create Partner Site PS1 and perform an initial replication with the First Site (the default behavior). You create Partner Site PS2 but do not perform an initial replication with the First Site.

In the Initiate Replication dialog, if you select as the source database the First Site or PS1, neither shows PS2 as a site to replicate with. This may lead you to question, “what became of my second Partner Site? Why isn’t PS2 in the list?”

It is not in the list because the information about the replication network, such as the sites on it, is also replicated. If you select PS2 as the source database, the choice First Replication Site shows as a site to replicate with. After you replicate with the First Site, then PS2 appears in the list for the First Site and PS1.

The easiest way to ensure consistency in the list is to perform an initial replication with the First Site when you activate each Partner Site. A Partner Site cannot replicate with other sites until it replicates with the First Site.

Replication Fails for a Deactivated Site

The other sites on your replication network do not know that a site has been deactivated until you perform a replication. Therefore, the first replication after deactivating a site from the replication network will fail for that site. This is the normal behavior.

The DRE.log file contains an error message similar to the following:

E 019f 0301-15:46:25 Partner site Partner_Site_2 (site number: 00LFLU) has been removed from the replication network - it cannot replicate with any other site.

A-13


After the first replication, this error no longer occurs because all sites on the replication network are aware of the site’s status (deactivated).

Note If you deactivate a First Site, you must perform a manual replication if you reactivate the First Site. After you reactivate the First Site, you must manually initiate a replication session from each Partner Site to the First Site. The replication sessions ensure that all available sites appear on the Initiate Replication dialog.

This action is not required if you deactivate/reactivate a Partner Site. It applies only to a First Site.

False Alert Because of Schedule Manipulation

If you delete, disable, or modify a schedule, the other replication sites are not aware of this because replication does not take place. The notification agent on the other sites continues to contact the scheduling site. If the scheduling site is down or unreachable, the agent sends a failure alert. The alert is false because the schedule no longer applies.

To prevent such false alerts, manually initiate replication after you delete, disable, or modify a schedule. The replication ensures that the schedule changes get replicated. Alternatively, if your entire replication network no longer needs replication, deactivate all replication sites on the network.

Correct Alarms but Replication on Wrong Schedule

This situation occurs if you change a schedule remotely. For example, you start DataExchange Manager on site B and use it to change the schedule on site A. The replication engine on site A will not use the new settings until you restart the engine. The notification agent, however, uses the new schedule without having to be restarted. The agent properly notifies of replication being off schedule.

To prevent this situation, do not update schedules remotely.

Dynamically Created Tables Not Being Replicated

If your dynamically created tables are not being replicated, verify that the file matching patterns in the dCNF table are correct. DataExchange provides a utility, Dxdynpath, to help you verify file matching patterns. See “dxdynpath” on page 7-15 in Pervasive DataExchange User’s Guide.

A-14

Data Replication

Note that relative paths are relative to a home directory that contains data dictionary files (DDFs) recognized by DataExchange.

Note Dxdynpath should only be used with the Real-Time Backup Edition.

SQL Triggers and Replication

SQL triggers are a type of stored procedure that are automatically executed when data in a table is modified with an INSERT, UPDATE, or DELETE. (Stored procedures are SQL statements that are predefined and saved in the database dictionary.)

Replication updates the base table before updating the dependent tables. This sequence maintains the correct foreign key relationships. In the case of the sample database Tracker, for example, the Region table is updated before the Employee table.

For illustration, suppose you have a database with a base table A and a dependent table B (table B has a foreign key relationship to table A). You create a trigger that updates base table A when a new record is inserted into table B.

Partner site 1 inserts a new record into table B, causing the trigger to execute. Table A is updated on Partner Site 1. Then you replicate Partner Site 1 with your other sites.

On the other sites, replication updates table A, then inserts a new record into table B, causing the trigger in table B to execute and again attempt to update table A. This may not be the desired behavior because the Replication Engine has already updated the record in table A with changes made on Partner Site 1.

Definite rules concerning triggers and replication cannot be given. In general, carefully consider each trigger that is part of a replicated database. Make certain that the trigger’s functionality and the behavior of replication are compatible to ensure the outcome you desire.

Data Conflicts When Activating Partner Sites

The template data prepared for replication during design is marked differently (with timestamps and other internal methods) than the data prepared during activation. The Replication Engine resolves the differences during replication. In a few cases, data conflicts may result between how you activate your First Site versus how you activate your Partner Sites.

A-15


Index Segments

For data files with 4096 byte page size, you are limited to 119 index segments per file. Because each indexed nullable column with true NULL support requires an index consisting of 2 segments, you cannot have more than 59 indexed nullable columns in a table (or indexed nullable true NULL fields in a Btrieve file). This limit is smaller for smaller page sizes.

Any file created with Pervasive PSQL, with file create mode set to 7.x, and TRUENULLCREATE set to the default value of On, has true null support. Files created using an earlier file format, or with Pervasive PSQL 7, or with TRUENULLCREATE set to Off, do not have true null support and do not have this limitation.

Refer to the Pervasive PSQL book SQL Engine Reference for more information about TRUENULLCREATE.

A-16

Data Conflicts

Data Conflicts

Central to any replication solution is its ability to detect and resolve conflicts when they occur. The best method of handling conflicts is a preventative one: avoid conflicts by design. In addition to this, Pervasive DataExchange includes a default last-in-wins policy. By maintaining time stamps in control tables and synchronizing clocks on replication sites, an accurate account of when records where inserted, updated, and deleted is kept. The Replication Engine is responsible for enforcing the conflict policy (and logging conflicts) as they occur.

In addition, Pervasive DataExchange provides an interface with which you can define your own conflict resolution. You can design the appropriate conflict resolution for any set of business rules and provide the resolution through an event handler DLL. The DLL overrides or extends the functionality of the Replication Engine.

For information about creating an event handler DLL, contact Pervasive Software. We will supply you the Event Callback API documentation.

Conflict Types Data conflicts are divided into types by Pervasive DataExchange. Each conflict is recorded in the log dre.log. You can read the log entries and determine what, if any, action needs to be taken. Messages similar to the following appear in the log. It contains the type of conflict, the key of the record involved, and how the conflict was resolved.

When a conflict occurs and a record must be overwritten, the newest record is always used. To alter this behavior, you can register your customized Event Handler DLL with the Replication Engine.

W 0130 0321-17:44:04 CONFLICT: Type I: Record 2 for table Customer has been altered at both sites (key: 123).W 0130 0321-17:44:04 Type I conflict resolved: Record 2 will be updated at partner (Table Customer, key: 123).

The log file of the Site where the record was not updated will contain a message saying that the record at the partner Site was updated (as above). At the Site where a record was overwritten messages similar to the following indicate the data value that was updated as well as

A-17


the new value (in this case the last name Yin was replaced by the last name Yan:

I 0130 0321-17:44:04 Local field Customer.LastName replaced by remote valueI 0130 0321-17:44:04 Before: YinI 0130 0321-17:44:04 After: Yan

Type I Conflict

A Type I conflict occurs when a record has been updated at both Sites since the last replication session. When this occurs the newer record is replicated and a log message similar to the following is generated:

W 0130 0321-17:44:04 Type I conflict resolved: Record 2 will be updated at partner (Table Customer, key: 123).

Variations of this conflict type include the following possible scenarios and associated log messages:

local site has more recent record and initiator is local site

W 01f8 08-17 19:09:41 CONFLICT: Type I: a record in table Employee has been altered at both sites GIDSysKey: 632940095990000027 GIDSiteID: 0 Unless overridden by an event handler, the DRE will choose the most recent (partner) record.

local site has more recent record and initiator is partner site

W 055c 08-17 19:00:51 CONFLICT: Type I: a record in table Employee has been altered at both sites GIDSysKey: 632940095990000028 GIDSiteID: 0 Unless overridden by an event handler, the DRE will choose the most recent (local) record.

partner site has more recent record and initiator is local site

W 0518 08-17 19:14:25 CONFLICT: Type I: a record in table Employee has been altered at both sites GIDSysKey: 632940095990000029 GIDSiteID: 0 Unless overridden by an event handler, the DRE will choose the most recent (local) record.

partner site has more recent record and initiator is partner site

W 0954 08-17 19:05:23 CONFLICT: Type I: a record in table Employee has been altered at both sites GIDSysKey: 632940095990000030 GIDSiteID: 0 Unless overridden by an event handler, the DRE will choose the most recent (partner) record.

A-18

Data Conflicts

Type V Conflict

Type V conflicts occur when there is an error with the starter data at each Site (the data that already exists in the database when your database application is activated).

If starter data exists at one Site and not at the other, the starter data is replicated to the other site. If the existing starter data is different, however, a type V conflict is logged and replication stops:

W 0130 0321-17:44:04 CONFLICT: Type V: Starter data in record 2 for table Customer is different at the two sites - the conflict must be resolved manually.

Type VI and VIa Conflicts

Conflicts between a record inserted or updated at one site and deleted at another site are treated as a Type VI conflict. During conflict processing, if all records are updated at one site (or the record was inserted) and the record is deleted at the other site, a type VIa conflict is logged and the most recent operation wins. If any records are not updated, then the delete operation must always win. This type VI conflict needs to be resolved in this way because there is insufficient information available to reinsert the entire record at the site where the record was deleted. The following describes the possible scenarios and the associated log messages:

record updated or inserted locally and deleted on the partner site

W 0130 0321-17:44:04 CONFLICT: Type VI: A locally-updated record in table Customer has been deleted at the partner site (key: 123)Creation date: 2000/05/10 12:26:45Deletion date: 2000/05/11 11:18:23The record will be deleted locally.W 0130 0321-17:44:04 CONFLICT: Type VIa: A newly-inserted record in tableCustomer has been deleted at the partner site (key: 123)Creation date: 2000/05/10 12:26:45Deletion date: 2000/05/11 11:18:23The record will be transmitted.

record updated or inserted at the partner site and deleted locally

W 0a78 08-17 13:05:13 CONFLICT: Type VI: A record in table t1 has been deleted at the partner site and updated locally. GIDSysKey: 632939880130000000 GIDSiteID: 0 The record will be deleted locally.

A-19


Successful Conflict Resolution

Note that if conflicts were successfully resolved during a replication cycle, a message similar to the following appears in the replication log file:

0082 0818-10:47:36 Replication of Tracker with 000030 ended successfully with 2 conflicts resolved.

Resolving Primary Key Conflicts

The best way to avoid primary key conflicts is to design your source database with unique primary keys. If you are using an existing database for replication that does not have unique primary keys, you can designate primary keys with the Pervasive PSQL Control Center.

A primary key conflict occurs when two rows have been inserted into two different activated databases that have the same primary key. Because each row could potentially have relevant data, the replication engine stops the replication and will not modify these rows.

You will see the following errors the DRE.log file on the system that detects the primary key conflict. For this example, the primary key conflict has been detected on the Region table of the sample database Tracker.

E 01cb 1108-11:42:21 sqlhelp 852 ODBC Error -1: (S1000) ‘[Pervasive][ODBC Client Interface][LNA][Pervasive][ODBC Engine Interface][Data Record Manager] The record has a key field containing a duplicate value(Btrieve Error 5)’ <-4994>E 01cb 1108-11:42:21 dbutil 629 ODBC statement failed: -1 from function ExecuteE 01cb 1108-11:42:21 dbutil 636 ODBC statement: INSERT INTO "Region" ("RegionID","NameStr") VALUES (?,?)E 01cb 1108-11:42:21 dsectbl 927 Unable to insert new record into table Region having key: 8E 01cb 1108-11:42:21 dresyncs5368 FSM:{22: An ODBC error occurred}: Unable to store next PD2PQQ88002.Region record from partner’s data list (key:PDCID(1000010))

All other systems that attempt to replicate with this system will fail with the Error:

A-20

Data Conflicts

E 01e8 1108-11:36:40 dresyncs1542 Error received from partner replication engine: ‘Update of Region failed’Replication stopped.

Remedying a primary key conflict requires manual intervention. You must update the primary key of one of these conflicting rows to a new, unique value. Following that, you must start a replication session.

For instance, from the example above, the conflict occurred with primary key 8. So, on one of the databases involved you would update the primary key to 9, a unique key value for the table. Then you would replicate the two systems together.

Note that during this replication, the replication control tables are cleaned up to correct the primary key conflict, and the following message is written to the DRE.log file as a warning message. The purpose of this message is to let you know that the primary key conflict was successfully resolved.

W 01b7 1107-17:12:56 dsectbl 893 A primary key conflict has been rectified on a replication control table. Table: PDCRegion, Column: CRegionID with key value of: 8

So, what transpired in terms of data in the database? Here is the contents of the Region table throughout the process.

First, a row with the same key is inserted onto each site.

We replicate and we get the primary key conflict, replication is stopped, no tables are updated.

Site 1 Site 2

RegionID NameStr RegionID NameStr

8 Site1Data 8 Site2Data

Site 1 Site 2



A-21


Update one of the sites to a new unique value.

Replicate the new change.

Now both sites are replicated to a consistent copy and no data has been lost.

Site 1 Site 2



Site 1 Site 2




A-22

Notification Agent

Notification Agent

If the notification agent is not sending e-mail, check the following:

The agent is running as a service

The agent is correctly configured (see “dxagent” on page 7-34 in Pervasive DataExchange User’s Guide)

The SMTP port through which the agent communicates does not require authentication or encryption

Each replication machine with an agent has access to the SMTP server

The SMTP server is set up to accept e-mail from each replication site running the agent

To verify notification agent is running



3 Scroll the list of services until you reach the service Pervasive DataExchange Agent.

This service must be started for the notification agent to function correctly.


4 If the service is not started, right-click its icon and select Start.

Testing the Mail Server

The SMTP mail server must also be functioning correctly. If required, verify that the SMTP mail server is sending and receiving e-mail correctly. Reference the documentation supplied for your SMTP server software or check for testing procedures on vendor Web sites.

A-23


How to Get Additional HelpPervasive Software strives to ensure that your product installation is easy and successful. If you encounter problems during or after the installation that are not covered in the user documentation, please contact Pervasive Software and we will address your problem promptly.

The following table lists a variety of resources to help you get answers to your questions, troubleshoot problems, and interact with the Pervasive team as well as with other customers.

Table A-2 Pervasive Software Resources and Contact Information

Resource Description Contact Information

Pervasive Software Web site The Pervasive Software Web site is a great source for everything Pervasive PSQL.

http://www.pervasive.com

Pervasive Resource Center The Resource Center provides a quick and easy way to access Pervasive resources, such as:

Free Trials - Data Sheets - White Papers - Success Stories - Tech Papers - Demos - Webinars - Audio - Training - Subscription Center - Developer Center - Community Forums

http://www.pervasive.com/resources/

FTP Site The Pervasive FTP site contains downloadable updates and patches to our product offerings, as well as additional debugging tools, documentation, third-party tools, and beta releases.

ftp://ftp.pervasive.com/support/

Newsgroup The Pervasive PSQL newsgroup is managed by the end-user community, posting and answering questions as they wish.

news://comp.databases.btrieve.

Technical Support The Support site contains product support assistance, support offerings, as well as online forms to submit service tickets, feedback and product defects.

http://www.pervasive.com/support/

A-24

How to Get Additional Help

Technical Support

If you still have questions or problems relating to your Pervasive DataExchange installation, you can obtain help from the Pervasive Customer Support department.

Your purchase of Pervasive products entitles you to 30 days of free technical support for installation and configuration problems.

Pervasive PSQL Knowledge Base The Pervasive PSQL Knowledge Base is a searchable database of information on installation, configuration, component management, product defect status, and answers to the frequently asked questions (FAQs).

http://www.pervasive.com/support/

Pervasive Library View the current documentation and technical papers online and access Pervasive discussion forums.

http://www.pervasive.com/library

Online Documentation Download the latest versions of Pervasive PSQL product manuals.

http://www.pervasive.com/support/technical/online_manuals.asp

The complete suite of online documentation is installed automatically on Windows, unless you specifically excluded it, during installation.

Access installed documentation from the Pervasive program on the Start menu or from the installation CD-ROM.

Printed Documentation Printed versions of each manual are available for purchase separately, or you may purchase the entire documentation set.

http://www.pervasive.com/ecommerce/Scripts/default.asp

Send e-mail to:[email protected]

Or telephone:1 800 287 4383.

Telephone Contacts Pervasive Software has offices worldwide to help solve your product support issues.

http://www.pervasive.com/company/contact

E-Mail Contacts Pervasive Software welcomes your comments, suggestions and requests for assistance via e-mail.

Table A-2 Pervasive Software Resources and Contact Information

Resource Description Contact Information

A-25


A-26

a p p e n d i x

B
Supported Data Types
Pervasive DataExchange Data Types

This appendix contains the following topics:

“Data Types” on page B-2

“Notes on Data Types” on page B-4

B-1


Data Types

The following table lists the Pervasive PSQL data types supported by Pervasive DataExchange.

Pervasive PSQL Data Type

Pervasive DataExchange Implementation

Can be Used as Primary Key for Replication

Bit bool no

Tinyint byte yes

Utinyint byte yes

Decimal numeric yes

Numeric1 numeric no

Bigint1 numeric no

Ubigint1 numeric no

Currency1 numeric no

Longvarbinary blob no

Binary blob no

Longvarchar blob no

Char2 string yes

Varchar3 string yes

Integer long yes

Uinteger long yes

Identity4 long yes

Smallint short yes

Usmallint short yes

Smallidentity short yes

Float double yes

Real double yes

Double double yes

B-2

Data Types

Note :1Partially supported data type in Pervasive PSQL. Refer to the appendix on Pervasive PSQL supported data types in the SQL Engine Reference. 2Limited to 255 characters.3Limited to 254 characters.4Although Identity is supported in Pervasive DataExchange for replication primary keys, using it for any part of a unique index is strongly discouraged.

Date timestamp yes

Time timestamp yes

Timestamp timestamp yes

Pervasive PSQL Data Type

Pervasive DataExchange Implementation

Can be Used as Primary Key for Replication

B-3


Notes on Data Types

This section outlines special information regarding the use of data types in Pervasive DataExchange.

DECIMAL DECIMAL is implemented in Pervasive DataExchange as a NUMERIC and can be use as a primary key for replication.

NUMERIC, BIGINT, UBIGINT and CURRENCY

The other data types that are implemented as NUMERICS cannot be used as primary keys for replication. These include NUMERIC, BIGINT, UBIGINT, and CURRENCY.

CHAR The CHAR data type is limited to 255 characters.

VARCHAR The VARCHAR data type is limited to 254 characters.

IDENTITY Although you may use IDENTITY data types for primary keys in DataExchange, we strongly recommend that you not use this data type as part of a unique index.

B-4

a p p e n d i x

C
Reserved Table Names
Pervasive DataExchange Reserved Words and Table Names

DataExchange reserved words are keywords with special meanings when processed by the Replication Engine. These words cannot be used as database or table names in your applications. The following is a list of the Replication system table names used by DataExchange.

In addition to the system table names listed here, DataExchange creates a unique replication table for each user table in your database that you have marked for replication. Replication user tables created by DataExchange are named by preceding the original table name

Table C-1 Replication System Table Names

ActivateInfo dActHist dActSite

dActTbl dCmd dCmdSite

dCnf dFKey dFragF

dFragI dGrp dIDB

dIDBDef dKey dLang

dMsg dMsgLang dPKey

dPrm dPrmGrp dPrmTyp

dQueue dSched dSchema

dSet dSFSite dSite

dSiteExt dSiteLnk dSiteSet

dSort dTblChg dTrn

dUsr dUsrGrp dUsrPrf

dVer dWSTS

C-1

Reserved Table Names

with PDC. For example, a table named Billing.MKD has a companion replication table named PDCBilling.MKD. DataExchange uses the PDCtablename convention to keep track of the replication database tables during replication.

In the event of tables with the same name in different folders, DataExchange creates a unique file name, similar to the naming convention used for log files. For example, two tables named Billing.MKD located in different directories would result in a table named PDCBilling.MKD and PDCBilling0.MKD.

Pervasive DataExchange requires that the replication tables created from selected user tables have unique names and be preceded by PDC. Pervasive PSQL limits table names to 20 characters. Replication table names created by DataExchange meet all of these requirements.

Note A database deployed for replication is allowed to include table names that start with PDC. However, if you add those tables to a replication template, DataExchange asks you to confirm that they are not files internal to the replication system.

Other Limitations

Pervasive DataExchange conforms to almost all of the same limitations and conditions implied in Pervasive PSQL. The following lists any known Pervasive DataExchange limitations that differ from those listed for the Pervasive PSQL ODBC Engine Interface.

For the complete list of Pervasive PSQL ODBC Engine Interface limitations, see the ODBC Engine in the SQL Engine Reference.

Pervasive PSQL Feature Pervasive DataExchange Limit or Condition

Database tables 4,800 (per replication network)

C-2

a p p e n d i x

D
Advanced Topics
A Look at Advanced Topics for Pervasive DataExchange

This appendix discusses advanced topics dealing with installation of Pervasive DataExchange. The following section is included:

“Installing DataExchange as Part of Your Application” on page D-2

D-1

Advanced Topics

Installing DataExchange as Part of Your Application

The DataExchange Getting Started guides explain how to install DataExchange interactively from a CD. You can also install DataExchange as part of your own application installation process. The DataExchange installation can be noninteractive, in which no input is required from the user. This is referred to as a silent installation.

See also Installation Toolkit Handbook under the “Embedding Pervasive PSQL” topic at http://www.pervasive.com/library/index.asp?_shownode=EMB.

How To Perform a Silent Install

The following steps explain how to perform a silent installation for a First Site and a Partner Site.

Note Ensure that all Pervasive PSQL utilities, such as PCC, and all applications that use Pervasive PSQL are closed before performing a silent install.

To install DataExchange silently

1 Copy all files from the Pervasive DataExchange CD to a temporary directory on a hard disk.

Use a machine that does not have DataExchange already installed.

2 Execute the DataExchange setup.exe program on the hard disk and include the -r argument.

For example, you would type setup -r. This creates an InstallShield record of the installation.

Continue the installation as explained in “Installing Pervasive DataExchange” on page 3-6 of the Getting Started with Pervasive DataExchange. Select First Site as the type of installation.

3 Copy the setup.iss file from the Windows directory (identified by the %windir% system variable) to the directory containing the DataExchange setup.exe file.

Setup.iss is an InstallShield script file that was created by the setup -r process from the previous step.

D-2

Installing DataExchange as Part of Your Application

4 Open setup.iss in an editor.

Notice that szType is set to Complete (szType=Complete). “Complete” indicates a First Site installation.

5 Modify the SiteName and HostAddr to the name or IP address of the machine that you want to be the First Site.

For example, if the machine name is DXSRVR, the entries would read SiteName=DXSRVR and HostAddr=DXSRVR.

6 For szEdit1, specify a DataExchange server activation license.

For example, if your license is AAAA1234BBBB5678CCCC9999, the entry reads szEdit1=AAAA1234BBBB5678CCCC9999.

7 Save setup.iss with a name that identifies it as pertaining to a First Site (such as first.iss).

You have created an ISS file for the First Site. You now need to create an ISS file for the Partner Site by modifying the First Site ISS file.

8 Save first.iss with a name that identifies it as pertaining to a Partner Site (such as partner.iss).

9 Change szType to Typical (szType=Typical).

“Typical” indicates a Partner Site installation.

10 Modify the Site Name and HostAddr to the name or IP address of the machine that you want to be the Partner Site.

For example, if the machine name is DXPRTNR, the entries would read SiteName=DXPRTNR and HostAddr=DXPRTNR.

11 In the [DlgOrder] section, perform the following actions:

a. Change count=9 to count=8.

b. Delete the line Dlg4=AskYesNo-0.

c. Renumber the subsequent dialog lines sequentially:

Dlg4=SdSelectFolder-0

Dlg5=Site Information-0

Dlg6=SdStartCopy-0

Dlg7=SdFinish-0

12 Delete the section [AskYesNo-0] and all of its subordinate lines, such as Result=1.

D-3

Advanced Topics

13 Delete setup.iss.

14 Add the contents of the temporary directory, with both of the newly created ISS files, to your installation media.

15 Use the following commands to silently install DataExchange from your media.

For a First Site: setup -sms /f1 first.iss /s (or whatever you named the ISS file in step 7)

For a Partner Site: setup -sms /f1 partner.iss /s (or whatever you named the ISS file in step 8)

D-4

a p p e n d i x

E
Glossary
Replication Terminology

Accelerated In Btrieve 7.x, a file open mode that provides improved response time over Normal mode when updating data files. However, Accelerated mode disables the MicroKernel’s logging capability. Therefore, the MicroKernel cannot guarantee transaction durability or atomicity on files opened in Accelerated mode.

If you are using Btrieve 6.x, Accelerated mode is equivalent to Normal mode, except that opening a data file in Accelerated mode cancels the effect of flagging a file as transactional.

Activated Database

A database on a specific site that is capable of replicating data to or from another site's database, provided the other site is a member of the same replication network. Activated databases contain a copy of the replication template with information about the sites that constitute the replication network.

Activation The process of creating a new database for replication—or enabling an existing one—and establishing the database as belonging to a site.

Change Capture / Change Apply

The change capture/change apply mechanism is a major subsystem of any replication implementation and is used to track and propagate modifications to replicated databases. Change capture occurs concurrent with database application execution, whereas change apply occurs during database synchronization. The Pervasive DataExchange change capture mechanism is not log-based. It is based on control tables that store only the most recent changes. It reflects the current state of the database and not the history of prior states as in log-based mechanisms.

Control Table Each replicated table in the database has a control table associated with it. Control tables store a record for each record in its

E-1

corresponding user table, and contain associated information such as the creation date of the record, last change date for the record, and so forth. By creating a control table for each replicated table, Pervasive PSQL ensures that you do not have to make any changes to your existing tables to enable replication.

DataExchange Designer

A graphical user interface tool for enabling your database for replication. DataExchange Designer allows you to enable all of Pervasive DataExchange's features.

DataExchange Manager

A graphical user interface for managing tasks, users, and sites in a replication network. DataExchange Manager can:

Manage replication schedules

Manage site information

Manage local or remote sites

DNA Database Network Analysis, the replication system database.

Encryption Encryption is the process of disguising a message to hide its contents. An encrypted message is referred to as ciphertext; the original, or decrypted message is referred to as plaintext.

First Site Every replication network must have a First Site, which is the first site to be activated for replication. The First Site contains information about the whole replication network, such as, sites available for replication, etc. It also contains a copy of the whole database. Any other site in the replication network is a Partner Site.

Globally-Unique IDs

A record ID that is guaranteed to be unique throughout your entire network, even if some sites create many new records in the same table between replications.

Hub and Spoke A network configuration that consists of a centralized server that maintains a complete copy of the database (the hub) and several connected servers or workstations with subsets of the replication data (spokes). The replication process typically consists of all spokes replicating with the hub at a predetermined time. Then, upon this successful initial replication, the updates are distributed to all spokes via a second replication cycle from the hub to each spoke site.

E-2

In Place Activation

Activation of an existing database by either using a replication template or by using a design exported from a template.

Local Table A nonreplicated table. Each site can have different local tables.

N-Tiered A network configuration that is similar to hub and spoke, but with additional levels (or tiers) in the network. An n-tiered configuration can be thought of as a hub and spoke network, where the spoke sites are also hub sites for the next tier in the configuration hierarchy. Thus, a centralized server can replicate with three second tier server sites, each of which, in turn, communicates with several desktop and notebook machines.

N-tiered configurations allow some scalability that is not available in hub and spoke networks. Configuring these network topologies and balancing the load as the network grows requires some planning.

Network A network is a collection of sites that can replicate among themselves. You can create separate environments, called networks, in which to run different versions of your database. For example, Version 1.0 could be running on a Production network, while Version 2.0 could be running on a Test network with its own separate and distinct data.

ODBC Open Data Base Connectivity, a standard programming interface used to connect to a variety of data sources. Pervasive DataExchange connects to all of its supported databases using ODBC.

Partner Site Any site that is not the First Site in a replication network.

Peer-to-Peer A replication network configuration in which every node, regardless of its size, amount of data, or location, behaves as a true peer to other sites in the network. Each node with a Replication Engine can schedule and manage replication and provides it share of the replication processing burden. Peer-to-peer is the default replication network configuration.

Project A project represents a single replicated database. Each time you enable a different database, you must specify a new project. A project can contain a number of networks and releases.

E-3

Refresh A term used for a mode of synchronization that involves unidirectional flow of data, as opposed to the default bidirectional flow of data commonly referred to as replication. A refresh is used to manually override the conflict resolution rules by specifying a prevailing site. For example, a “refresh local” operation overwrites all local data with data from a specified site.

Release A release represents a change in your database's schema. Therefore, each time you modify your database schema you must create a new release. A replication project can contain several networks and releases.

Replication The default database synchronization mode that involves bidirectional flow of data between two or more sites based on conflict resolution rules.

Replication Engine

The component that manages the replication process. All replication is performed in the background and can be fully automated according to schedules that you define.

Pervasive Control Center contains the user interfaces to the Replication Engine from which you can:

Remotely manage replication sites

View current state of replication nodes

Query history of replication activity

Provide multiple views of replication statistics and information

Filter replication messages/logs

Replication Network

A collection of sites that can replicate among themselves. A replication network can contain several releases.

Replication Template

A copy of a database that includes the user’s database tables, replication control tables, system tables, and optionally, the user data.

Site A replication-enabled database that can replicate and synchronize database information with other sites across TCP/IP networks over an ODBC interface. Each local replication-enabled database is one site regardless of the number of users accessing it or the amount of data stored in it. A site can be:

E-4

one computer with its own local database

a local database shared by a local network

a large client/server database used by hundreds or thousands of users

Subscription A site’s authorization to replicate with other sites on the replication network.

Template See Replication Template.

E-5

Index

Numerics1-way method

concepts 8-4

overview 5-2

selecting 8-3

2-machine configuration

for Real-Time Backup 4-2

2-way method

concepts 8-4

overview 5-2

selecting 8-3

AAccelerated

defined E-1

Accessing DataExchange Utilities

from a command prompt 7-3

from Pervasive Control Center 7-4

Activate a Project Release utility

See Dxact.exe

Activated Database

defined E-1

Activating

project release 7-6

template on first site 4-12, 5-28, 5-51

template on partner site 4-12, 5-29, 5-52

Activation 3-2

DSN created 3-2

First and Partner Sites 3-3

more information 3-4

Adding new dynamic tables to an activated database

3-20

Administrative tasks

in DataExchange Designer 8-31

Advanced Topics

Silent Install D-1

Assigning

permissions 9-9

Attributes

of XML Descriptor file 4-20

Authentication

database setting 8-9

Automating Replication

with schedules 9-2

BBasic concepts

of Pervasive DataExchange 2-1

Basic designs

concepts 8-4

tasks to create 8-25

Bigint

data type B-4

CChange Apply

defined E-1

Change Capture

defined E-1

Char

data type B-4

Clear Log

log file actions 10-7

Client DSN 2-7

defined 2-7

Command prompt

accessing utilities from 7-3

opening in Windows 7-4


Dxact.exe 7-6

Dxcleanup.exe 7-9

Dxdeact.exe 7-11

DXDeploy.exe 7-13

Dxdynpath.exe 7-15

Dxregevnt.exe 7-21

Dxsynctables.exe 7-25

Ffcopy.exe 7-26

Components

in DataExchange 1-4

Concepts

basic designs 8-4

Data Synchronization Edition 8-3

Index 1

database connection information 8-5

database identification 6-7, 8-5

network 8-6

project 8-5

release 8-6

database selection 8-4

DataExchange methods 8-5

1-way 8-4

2-way 8-4

design completion 8-8

initiate replication 10-4

network 6-8

Real-Time Backup Edition 8-2

release 6-8

replicated tables 8-7

Configuration

for DataExchange Notification Agent 7-35

for dynamic tables 7-15


using many-to-one 4-3

using multiple machines 4-3

using one-to-many 4-19

using two machines 4-2

Console Application

Replication Engine 2-3

Control Table

cleanup (Dxcleanup.exe) 7-9

configuration (Dxcleanup.exe) 7-9

defined E-1

Control Table Cleanup Configuration utility

See Dxcleanup.exe

Copy

log file actions 10-7

Copying

files 7-26

flat files 7-26

Creating

design templates 8-30

new release of a design 8-31

new replication database 8-25

sample Tracker database

from SQL 6-11

Currency

data type B-4

Current Log

size A-9


setting in DataExchange Manager 9-14

setting in Designer 8-35

Custom.XML Descriptor file 5-35

DDa.exe 7-31

See also DataExchange Manager

Da.log A-10

Data conflicts

with partner site activation A-15

Data dictionary files for DataExchange 7-20

Data recoverable but not current

in disaster recovery 4-26

Data Source Names

assigned during activation 3-2

Data Source Names (DSNs) 2-7

Data Synchronization

basic design considerations 6-6

database design overview 6-2

DataExchange methods

1-way 8-3

2-way 8-3

concepts 8-3

deployment models 5-1

additional information resources 5-4

using DataExchange Designer and Utilities 5-

4

using Dxact.exe 5-4

using DXDeploy.exe 5-3

working with the examples 5-6

deployment using Deployment Wizard 5-11

design considerations 6-2

example database design 6-1

security 6-10

Tracker sample database 6-11

understanding database designs 6-1

Data Types B-2

bigint B-4

char B-4

currency B-4

decimal B-4

notes about B-4

numeric B-4

supported B-2

ubigint B-4

2 Index

varchar B-4

Data unrecoverable

in disaster recovery 4-25

Database

activation utility 7-6

connection information

concepts 8-5

creating new replication 8-25

deactivation utility 7-11

selection

concepts 8-4

settings in DataExchange Designer 8-31

Authentication 8-9

Information Files 8-9

Database Certification Information

viewing 8-33

Database Design

considerations for Data Synchronization 6-6

for Data Synchronization 6-1

Database Engine

checking status A-7


concepts 6-7, 8-5

network 6-8, 8-6

project 6-7, 8-5

release 6-8, 8-6

Database Network Analysis (DNA) 3-2

Database network analyst

See DNA

Database state

DNA 10-3

Pure 10-3

Template 10-3

viewing 10-2

Databases

named 2-7

Tracker

creating from SQL 6-11

DataExchange

(PDC) user table names C-1

Agent 7-34

See also DXAgent.exe

data dictionary files 7-20

notification agent 7-34

communication protocol 7-35

configuration 7-35

replicating dynamically created tables 3-20

relative paths 7-20

types of expressions 7-18

verifying expression pattern matching 7-20

reserved words C-1

system table names C-1

table name limitations C-2

using 3-1

DataExchange components

DataExchange Agent 1-4

Documentation 1-4

overview 1-4

Replication Engine 1-2, 1-4

Replication Event Handler (REH) 1-2, 1-4

Utilities 1-4

DataExchange Designer 7-32

administrative tasks 8-31

database settings 8-31

defined E-2

deploying Real-Time Backup 4-7

GUI icons 8-14

logging 8-10

main window visual reference 8-14

menu and toolbar 8-16

overview 8-2

removing databases after deployment 5-8

replicated tables 6-9

concepts 8-7

See also Prd.exe

setting preferences 8-10, 8-34

logging 8-10

wizard 8-10

tasks

access the Database Settings 8-31

create a new database for replication 8-25

create a new release of a design 8-31

create a replication template based on a design

8-30

designate settings for the startup wizard 8-34

designate tables for replication 8-28

designate tables not to be replicated 8-29

display Authentication Settings 8-32

display help 8-24

open an existing database for replication 8-27

set logging preferences 8-35

set preferences 8-34

Index 3

set the Information Files location 8-33

start Designer as a stand-alone application 8-

24

start Designer from PCC 8-24

view Database Certification information 8-33

view generated Verification Messages 8-34

templates 8-8

troubleshooting multiple installations A-4

using for Data Synchronization deployments 5-4

DataExchange Documentation 1-5

DataExchange Editions 1-3

Data Synchronization 1-3, 8-3

Real-Time Backup 1-3, 8-2

DataExchange Manager 7-31

defined E-2

GUI icons 9-9

log 9-14

logon

name 9-13

password 9-13

main window visual reference 9-9

managing

user permissions 9-9

users 9-5

permissions 9-9

replication schedules 9-2

schedules 9-2

See also Da.exe

site information 9-3

site information tab 9-4

site list 9-3

site schedule tab 9-2

tasks 9-12

add new user 9-20

change logon password 9-14

change replication schedule 9-19

change site information 9-19

change user information 9-21

change user’s group membership 9-22

connect as different user 9-13

connect to different database 9-13

create replication schedule 9-18

delete a user 9-21

delete replication schedule 9-19

display help 9-17

logging on 9-13

refresh view 9-16

remove a site from replication network 9-20

restore a site to replication network 9-20

set logging options 9-14

start from command prompt 9-12

start from PCC 9-12

user information tab 9-7

user membership tab 9-7

DataExchange methods

1-way 8-3

2-way 8-3

concepts 8-5

DataExchange Monitoring Tools 7-32

See also Pvreplcm.exe

tasks

view engine and service state 10-2

view the state of a database 10-2

DataExchange Template Remover Wizard

See also Trwizard.exe

DataExchange Utilities

accessing 7-3

overview 1-4, 7-2

when used 7-2

DBNAMES (Named Databases) 2-7

Deactivate a Project Release utility

See Dxdeact.exe

Deactivating

project release 7-11

Debug information

logging in DataExchange Designer 8-10, 8-12, 8-

35

logging in DataExchange Manager 9-15

logging in DataExchange Monitoring Tools 10-

10

Decimal

data type B-4

implemented as numeric B-4

Deploy DataExchange utility

See DXDeploy.exe

Deploying

replication 7-13

Deployment

using Deployment Wizard

for Data Synchronization 5-11


using Designer

4 Index


using DXDeploy.exe

for many-to-one Real-Time Backup 4-18


Deployment Models

for Data Synchronization Edition 5-1

1-way using Designer 5-24

1-way using DXDeploy.exe 5-12

2-way using Designer 5-47

2-way using DXDeploy.exe 5-34

using Deployment Wizard 5-11

for Real-Time Backup Edition 4-1

using DataExchange Designer 4-7

using Deployment Wizard 4-5

using DXDeploy.exe 4-6, 4-18, 4-20

Deployment Wizard 3-4

deploying Data Synchronization 5-11

deploying Real-Time Backup 4-5

Descriptor File

attributes 4-20

Custom.XML 5-35

Express.XML 4-20, 5-13

Design

DSN created 3-2

Designer

See DataExchange Designer

Designs

basic

concepts 8-4

tasks to create 8-25

completing

concepts 8-8

for Data Synchronization databases 6-1

tasks to complete 8-30

Disaster Recovery

data recoverable but not current 4-26

failover 4-24


no data recoverable 4-25

setting primary site back into replication 4-26

setting up a new primary site 4-25

DNA database 3-2

database identification 8-6

defined E-2

state 10-3

Dnewsite.log A-10

Documentation

for DataExchange 1-5

for Pervasive System Analyzer A-6

Getting Started Guides 1-5

User’s Guide 1-5

Dre.log A-10

Dregdtk.log A-10

DSN 3-2

client

defined 2-7

engine

defined 2-7

DSNs

created during activation 3-2

created during design 3-2

DX Designer


DX Manager

See DataExchange Manager

DX Monitoring Tools

See DataExchange Monitoring Tools

Dxact.exe 3-4, 7-6

See also Utilities

using for Data Synchronization deployments 5-4

Dxact.log A-10

DXAgent.exe 7-34

not installed on Workgroup engine 2-5

See also Services

starting the service 2-5

stopping the service 2-5

DXAgentConfig XML file 7-35

Dxcleanup.exe 7-9

See also Utilities

Dxdeact.exe 7-11

See also Utilities

Dxdeact.log A-10

DXDeploy.exe 5-3, 7-13

removing databases after deployment 5-6

See also Utilities

using in many-to-one configuration 4-20

using with Data Synchronization deployments 5-

3

using with Real-Time Backup 4-6, 4-18

Dxdeploy.exe 3-4

Dxdynpath utility 7-20

Dxdynpath.exe 7-15

Index 5

See also Utilities

Dxevent.log A-10

Dxregevnt.exe 7-21

See also Utilities


See also Utilities

Dxsynctables.log A-10

Dynamic Table Configuration and Test utility

See Dxdynpath.exe

Dynamic Tables

configuration and test utility 7-15

Dynamically created tables

replicating 3-20

EE-mail

response to replication failure 7-34

Email

See E-mail

Encryption

defined E-2

Engine

checking status A-8

DSN 2-7

defined 2-7

replication (Replserv.exe) 2-2, 2-3

Event Handler

component of DataExchange 1-4

registering 7-21

Express.XML Descriptor file 4-20, 5-13

FFailover

disaster recovery 4-24

Failure notification 7-34

Ffcopy.exe 7-26

See also Utilities

Ffcopy.log A-10

Files

copying utility 7-26

First Site

activating template on 4-12, 5-28, 5-51

activation 3-3

copying files from 5-28, 5-51

creating template on 4-8, 5-25, 5-48

defined E-2

running DXDeploy.exe on 5-21, 5-44

specifying in XML Descriptor file 5-16, 5-39

Flat File Copy utility

See Ffcopy.exe

GGeneral tasks


in DataExchange Manager 9-12

Getting Started Guides 1-5

Globally-Unique IDs

defined E-2

Glossary of terms E-1

Group By

log view option 10-8

GUI-based Utilities

Da.exe 7-31

Prd.exe 7-32

ReplMonitor.exe 7-32

Trwizard.exe 7-32

HHome directory for DataExchange DDFs 7-20

How to find

information 1-5

Hub and Spoke

defined E-2

IIn Place Activation

defined E-3

Index segments

troubleshooting A-16

Information

about Data Synchronization deployments 5-4

how to find 1-5

Information Files

database setting 8-9


concepts 10-4

Installation troubleshooting A-4

Installing DataExchange

as part of your application D-2

silently D-2

troubleshooting A-4

6 Index

LLimitations

of DataExchange C-2

Local Table

defined E-3

Log File actions

clear log 10-7

copy 10-7

Log files

Da A-10

Dnewsite A-10

Dre A-10

Dregdtk A-10

Dxact A-10

Dxdeact A-10

Dxevent A-10

Dxsynctables A-10

Ffcopy A-10

Mer A-10

Msg A-10

Prd A-10

Reh A-10

session A-10

setting


setting in DataExchange Designer 8-10

setting size A-9

used for troubleshooting A-9

Log options

setting 10-7

Log View options

group by 10-8

Logging

on to DataExchange Manager 9-13

Logging Level Options 10-9

Debug 10-10

Error 10-9

Information 10-9

Verbose Logging 10-10

Warning 10-9

Logging options

in DataExchange Designer 8-10, 8-12, 8-35


Maximum Log Size 8-13

Maximum logs to keep 8-13

Name of Log File 8-13

Trace 8-12

Logon name for DataExchange Manager 9-13

Logon password for DataExchange Manager 9-13

MManaging

replication schedules 9-2


users for DataExchange Manager 9-5

Many-to-One Configuration

for Real-Time-Backup 4-3

Many-to-One Deployment

for Real-Time Backup

using DXDeploy.exe 4-18

Maximum Log Size

logging option 8-13

Maximum Logs to Keep

logging option 8-13

Menu and toolbar

for DataExchange Designer 8-16

Mer.log A-10

Messages, Verification

viewing 8-34

Monitoring Tools

See DataExchange Monitoring Tools

Msg.log A-10

NName of Log File

logging option 8-13

Named databases 2-7

Network

concepts 6-8, 8-6

defined E-3, E-4

Network communications

testing A-6

troubleshooting A-6

Not Replicated Tables 8-29

Notification agent

troubleshooting A-23

Notification of replication failures 7-34

N-Tiered

defined E-3

Numeric

data type B-4

data type used for primary key B-4

Index 7

OODBC

defined E-3

One-to-many

configuration 4-19

Operations

using DataExchange 3-1

Options

logging level 10-9

Debug 10-10

Error 10-9

Information 10-9

Verbose logging 10-10

Warning 10-9

Overview

of 1-way method 5-2

of 2-way method 5-2

of DataExchange Designer 8-2

of DataExchange Utilities 1-4, 7-2

of Pervasive DataExchange 1-2, 2-1

of Tracker example database design 6-2

of Utilities and Services 7-2

PPartner Site

activating template on 4-12, 5-29, 5-52

copying files to 4-11, 5-28, 5-51

copying template to 5-22, 5-45

data conflicts when activating A-15

defined E-3

running DXDeploy.exe on 5-23, 5-46

specifying in XML Descriptor file 5-20, 5-42

Partner Sites

activation 3-3

Password to log on to DataExchange Manager 9-14

Pattern matching

verifying 7-20

Peer-to-Peer

defined E-3

Performing actions

on the log file

clear log 10-7

copy 10-7

Permissions

assigning


managing 9-9


overview 1-2

overview of basic concepts 2-1

Pervasive PSQL

client, defined 2-7

server, defined 2-7

Pervasive PSQL Engine

checking status A-7

checking status of Server A-7

checking status of Workgroup A-7

Pervasive PSQL Replication Service 7-37

See also Replserv.exe

Pervasive PSQL utilities

See Utilities

Pervasive System Analyzer

documentation A-6

starting A-6

using for troubleshooting A-6

Prd.exe 7-32

See also DataExchange Designer

Prd.log 8-10, A-10

Preferences

setting in Designer 8-10

Primary Keys

resolving conflicts A-20

Primary Site

putting back into replication after disaster

recovery 4-26

setting up after disaster recovery 4-25

Project

activation 7-6

concepts 6-7, 8-5

deactivation 7-11

defined E-3

deployment 7-13

Pure database

state 10-3

Pvreplcm.exe

See also DataExchange Monitoring Tools

RReal-Time Backup

concepts 8-2

configuration 4-2

deployment models 4-1

8 Index

deployment using DataExchange Designer 4-7

deployment using Deployment Wizard 4-5

deployment using DXDeploy.exe 4-6

disaster recovery 4-24

no data recoverable 4-25

disaster recovery failover 4-24

many-to-one configuration 4-3

many-to-one deployment

using DXDeploy.exe 4-18, 4-20

multiple machine configuration 4-3

recovering from data loss 4-24

two-machine configuration 4-2

Refresh

defined E-4

option in Designer 8-19

view in DataExchange Manager 9-16

Register Event Handler utility

See Dxregevnt.exe

Registering

event handler 7-21

REH

See also Dxregevnt.exe

Reh.log A-10

Relative path for DataExchange DDFs 7-20

Release 8-6

concepts 6-8

defined E-4

Release name 8-6

Removing

a site from replication network 9-4

databases deployed with Designer 5-8

databases deployed with DXDeploy.exe 5-6

Replace Data on Local Site with Data from Selected

Site 10-5

Replicate Data Between Source and Selected Sites 10-

5

Replicated Tables

concepts 8-7

Replication

automating with schedules 9-2

defined E-4

deployment utility 7-13

initiating 10-4

removing a site from network 9-4

restoring a site to network 9-4

Replication Designer


Replication Engine

checking status A-8

defined E-4

Replserv.exe 2-2, 2-3

starting and stopping as a console application 2-3

starting manually 2-3

starting the service 2-2

stopping the service 2-2

Replication Progress and Log Viewers 7-32

Replication schedules

automating 9-2

Replication System Table Names

limitations C-2

Replication Templates

See Templates

Replication terminology

defined E-1

Replication Tools

See Utilities


Replserv.exe 2-2, 2-3, 7-37

Replserv.exeSee also Services

Reserved words C-1

Resources

for troubleshooting A-2

Restoring

a site to replication network 9-4

SSample Tracker Database 6-11

creating with SQL Editor 6-11

Saving

design templates 8-8

Schedule tasks


Schedules

managing for replication 9-2

Schedules, using to automate replication 9-2

Scheduling replication 9-2

Security

in Data Synchronization 6-10

Services

DXAgent.exe 2-5, 7-34

overview 7-2

Pervasive DataExchange 7-2

Index 9

Replication Engine 2-2

Replserv.exe 7-37

See also Notification agent

Services, terminal

installation issues A-4

Session log files A-10

Setting

Designer preferences 8-10, 8-34

Designer settings 8-31

logging options



startup wizard settings 8-34

Settings

Authentication 8-32

Information Files location 8-33

Show Wizard on Startup 8-34

Silent Install D-2

Simple mail transfer protocol

See DataExchange notification agent

Site

defined E-4

information 9-3

setting primary back into replication 4-26

setting up new primary 4-25

Site information tasks


Site List


SMTP

See DataExchange notification agent

SQL Editor

used to create Tracker sample database 6-11

Starter data 8-8

Starting

DXAgent service 2-5

Replication Engine

as a console application 2-3

as a service 2-2

manually 2-3

Statistics and Log Views command 5-4

Stopping

DXAgent service 2-5

Replication Engine

as a console application 2-3

as a service 2-2

Subscriptions

defined E-5

Synchronization

of tables 7-25

System database

DNA 3-2

System Failure

recovering from in Real-Time Backup 4-24

TTabbed work areas

in DataExchange Designer

Logging 8-35

Not Replicated tab 8-22

Replicated tab 8-22

Wizard 8-34

in DataExchange Manager

Site Information 9-4

Site Schedule 9-2

User Information 9-7

User Membership 9-7

Table designs

completing 8-8

Table Names

limitations C-2

Table Synchronization and Check utility

See dxsynctables.exe

Tables

checking utility 7-25

designate for replication 8-28

Not Replicated 8-29

Replicated 8-28

synchronization utility 7-25

Tasks


administrative 8-31

basic designs 8-25

design completion 8-30

general 8-24


general 9-12

schedule 9-18


user 9-20

Technical Support A-25

Template database

10 Index

state 10-3

Template Descriptor Files

Custom.XML 5-35


Template Remover Wizard 7-32

Templates

concepts 8-8

creating for replication 8-30

defined E-4

Terminal Services

troubleshooting installation of A-4

Terminology

used in DataExchange E-1

Testing

dymanic tables 7-15

network connectivity A-6

Tools

See Utilities

Trace

logging option 8-12

Tracker sample database

creating from SQL 6-11

Tracker.SQL

using to create sample database 6-11

Troubleshooting

data conflicts when activating partner sites A-15

index segments A-16

installation issues A-4

installation of multiple DataExchange Designers

A-4

installation of terminal services A-4

network connectivity A-6

primary key conflicts A-20

resources A-2

strategies A-3

uninstalling issues A-5

using log files A-9

using Pervasive System Analyzer A-6

verifying database engine is running A-7

verifying Pervasive PSQL Server engine is running

A-7

verifying Pervasive PSQL Workgroup engine is

running A-7

verifying replication engine is running A-8

Trwizard.exe 7-32

See also DataExchange Template Remover

Wizard

Two-machine configuration


UUbigint

data type B-4

Understanding

Data Synchronization database designs 6-1

Uninstalling

DataExchange A-5

User tasks


User’s Guide 1-5

Users

assigning permissions 9-9

for DataExchange Manager 9-5

information tab in DataExchange Manager 9-7

membership tab in DataExchange Manager 9-7

Utilities

accessing from a command prompt 7-3

accessing from Pervasive Control Center 7-4

command-line

Dxact.exe 7-6

Dxcleanup.exe 7-9

Dxdeact.exe 7-11

DXDeploy.exe 7-13

Dxdynpath.exe 7-15

Dxregevnt.exe 7-21


Ffcopy.exe 7-26

DataExchange 1-4

GUI-based

Da.exe 7-31

Prd.exe 7-32


Trwizard.exe 7-32

overview 7-2

Pervasive DataExchange 7-2

replication stages used in 7-2

used in Data Synchronization deployments 5-4

Designer 5-4

Dxact.exe 5-4

Utility

to verify pattern matching 7-20

Index 11

VVarchar

data type B-4

Verbose Logging

option in DataExchange Designer 8-12

option in DataExchange Manager 9-16

option in DataExchange Monitoring Tools 10-10

option used in troubleshooting A-9

Verification Messages

viewing 8-34

Verifying

regular expression patterns 7-20

status of database engine A-7

status of replication engine A-8

Viewing

Database Certification Information 8-33

Verification Messages 8-34

WWords

reserved C-1

Workgroup Engine

DXAgent.exe not installed 2-5


in Data Synchronization 5-6

XXML Configuration File

DXAgentConfig.XML 7-35

XML Descriptor File

attributes 4-20

Custom.XML 5-35


specifying First Site 5-16, 5-39

specifying Partner Site 5-20, 5-42

12 Index