replication server - concordia...

Replication ServerAdministration Guide

Replication ServerVersion 12.0

ii

Document ID: 32511-01-1200-01

Last revised: January 2000

Copyright © 1989-1999 by Sybase, Inc. All rights reserved.

This publication pertains to Sybase database management software and to any subsequent release until otherwise indicated in new editions or technical notes. Information in this document is subject to change without notice. The software described herein is furnished under a license agreement, and it may be used or copied only in accordance with the terms of that agreement.

To order additional documents, U.S. and Canadian customers should call Customer Fulfillment at (800) 685-8225, fax (617) 229-9845.

Customers in other countries with a U.S. license agreement may contact Customer Fulfillment via the above fax number. All other international customers should contact their Sybase subsidiary or local distributor. Upgrades are provided only at regularly scheduled software release dates. No part of this publication may be reproduced, transmitted, or translated in any form or by any means, electronic, mechanical, manual, optical, or otherwise, without the prior written permission of Sybase, Inc.

Sybase, the Sybase logo, ADA Workbench, Adaptable Windowing Environment, Adaptive Component Architecture, Adaptive Server, Adaptive Server Anywhere, Adaptive Server Enterprise, Adaptive Server Enterprise Monitor, Adaptive Server Enterprise Replication, Adaptive Server Everywhere, Adaptive Server IQ, Adaptive Warehouse, AnswerBase, Anywhere Studio, Application Manager, AppModeler, APT Workbench, APT-Build, APT-Edit, APT-Execute, APT-FORMS, APT-Translator, APT-Library, Backup Server, ClearConnect, Client-Library, Client Services, Data Pipeline, Data Workbench, DataArchitect, Database Analyzer, DataExpress, DataServer, DataWindow, DB-Library, dbQueue, Developers Workbench, Direct Connect Anywhere, DirectConnect, Distribution Director, E-Anywhere, E-Whatever, Embedded SQL, EMS, Enterprise Application Server, Enterprise Application Studio, Enterprise Client/Server, Enterprise Connect, Enterprise Data Studio, Enterprise Manager, Enterprise SQL Server Manager, Enterprise Work Architecture, Enterprise Work Designer, Enterprise Work Modeler, EWA, Gateway Manager, ImpactNow, InfoMaker, Information Anywhere, Information Everywhere, InformationConnect, InternetBuilder, iScript, Jaguar CTS, jConnect for JDBC, KnowledgeBase, MainframeConnect, Maintenance Express, MAP, MDI Access Server, MDI Database Gateway, media.splash, MetaWorks, MySupport, Net-Gateway, Net-Library, NetImpact, ObjectConnect, ObjectCycle, OmniConnect, OmniSQL Access Module, OmniSQL Toolkit, Open Client, Open ClientConnect, Open Client/Server, Open Client/Server Interfaces, Open Gateway, Open Server, Open ServerConnect, Open Solutions, Optima++, PB-Gen, PC APT Execute, PC DB-Net, PC Net Library, Power++, power.stop, PowerAMC, PowerBuilder, PowerBuilder Foundation Class Library, PowerDesigner, PowerDimensions, PowerDynamo, PowerJ, PowerScript, PowerSite, PowerSocket, Powersoft, PowerStage, PowerStudio, PowerTips, Powersoft Portfolio, Powersoft Professional, PowerWare Desktop, PowerWare Enterprise, ProcessAnalyst, Report Workbench, Report-Execute, Replication Agent, Replication Driver, Replication Server, Replication Server Manager, Replication Toolkit, Resource Manager, RW-DisplayLib, RW-Library, S Designor, S-Designor, SDF, Secure SQL Server, Secure SQL Toolset, Security Guardian, SKILS, smart.partners, smart.parts, smart.script, SQL Advantage, SQL Anywhere, SQL Anywhere Studio, SQL Code Checker, SQL Debug, SQL Edit, SQL Edit/TPU, SQL Everywhere, SQL Modeler, SQL Remote, SQL Server, SQL Server Manager, SQL SMART, SQL Toolset, SQL Server/CFT, SQL Server/DBM, SQL Server SNMP SubAgent, SQL Station, SQLJ, STEP, SupportNow, Sybase Central, Sybase Client/Server Interfaces, Sybase Financial Server, Sybase Gateways, Sybase MPP, Sybase SQL Desktop, Sybase SQL Lifecycle, Sybase SQL Workgroup, Sybase User Workbench, SybaseWare, Syber Financial, SyberAssist, SyBooks, System 10, System 11, System XI (logo), SystemTools, Tabular Data Stream, Transact-SQL, Translation Toolkit, UNIBOM, Unilib, Uninull, Unisep, Unistring, URK Runtime Kit for UniCode, Viewer, Visual Components, VisualSpeller, VisualWriter, VQL, WarehouseArchitect, Warehouse Control Center, Warehouse Studio, Warehouse WORKS, Watcom, Watcom SQL, Watcom SQL Server, Web Deployment Kit, Web.PB, Web.SQL, WebSights, WebViewer, WorkGroup SQL Server, XA-Library, XA-Server and XP Server are trademarks of Sybase, Inc. 9/99

Unicode and the Unicode Logo are registered trademarks of Unicode, Inc.

All other company and product names used herein may be trademarks or registered trademarks of their respective companies.

Use, duplication, or disclosure by the government is subject to the restrictions set forth in subparagraph (c)(1)(ii) of DFARS 52.227-7013 for the DOD and as set forth in FAR 52.227-19(a)-(d) for civilian agencies.

Sybase, Inc., 6475 Christie Avenue, Emeryville, CA 94608.

Contents

iii

About This Book ........................................................................................................................ xvii

CHAPTER 1 Introduction ..................................................................................... 1About Replication Server ................................................................. 1

Asynchronous Transaction Replication ..................................... 2Advantages of Replicating Local Data ...................................... 2

Replication Server and Distributed Database Systems.................... 3Replication Server’s Basic Primary Copy Model ....................... 5Other Distributed Data Models .................................................. 9Replication Server and Heterogeneous Data Servers ............ 16

Warm Standby Applications ........................................................... 18Mixed-Version Replication Systems............................................... 18

Restrictions in Mixed-Version Systems ................................... 19Mixed Versions of Adaptive Server ......................................... 19

Replication System Security........................................................... 20Replication Server Security Features...................................... 20Network-Based Security Features........................................... 21

Replication Server Roles and Responsibilities............................... 22Replication System Administrator ........................................... 22Database Administrator ........................................................... 22Replication Server Tasks and Responsibilities ....................... 22

CHAPTER 2 Replication Server Technical Overview ...................................... 25Replication System Components ................................................... 25

Replication Server ................................................................... 27Adaptive Server or Other Data Server .................................... 28Client Applications................................................................... 31Sybase Central ........................................................................ 32

Specifying Data for Replication ...................................................... 33Replication Definitions and Subscriptions for Tables .............. 33Replication Definitions for Stored Procedures......................... 34Publications ............................................................................. 35Overview of Replicating Tables............................................... 36

Contents

iv

Commands for Managing Replicated Data ............................. 37Establishing Replication Server Connections ................................ 38

Interfaces File.......................................................................... 38Making Replication Server Connections ................................. 39

Specifying Database Operations.................................................... 41Function Strings ...................................................................... 42Function-String Classes .......................................................... 42

Transaction Handling with Replication Server ............................... 43Stable Queues......................................................................... 44Distributed Concurrency Control ............................................. 47Transaction Processing by the Replication Agent................... 48

CHAPTER 3 Managing Replication Server with Sybase Central .................... 51Replication System Management with Sybase Central ................. 52

Replication Server Manager.................................................... 52Using Online Help .......................................................................... 54

Topic Help ............................................................................... 54Context-Sensitive Help............................................................ 56Tooltips.................................................................................... 56

Starting and Stopping Sybase Central ........................................... 56Starting Sybase Central .......................................................... 57Stopping Sybase Central......................................................... 57

Using Windows and Dialog Boxes ................................................. 57Navigating the Sybase Central Main Window ......................... 57

Using Menus and Toolbars ............................................................ 62Standard Menus ...................................................................... 62Shortcut (Pop-Up) Menus........................................................ 63Toolbar and Status Bar ........................................................... 63Refreshing Window and Dialog Box Displays ......................... 65

Performing Common Tasks ........................................................... 65Create an Object ..................................................................... 65View an Object’s Properties .................................................... 66Delete an Object...................................................................... 69

Managing Replication Server ......................................................... 70Connecting to RSM Server

and Defining an RSM Server Domain .............................. 71Replication Server Views ........................................................ 75

CHAPTER 4 Managing a Replication System................................................... 81Setting Up a Replication System.................................................... 81Performing Replication Server Tasks............................................. 84

Using rs_init............................................................................. 84Managing Replication Server with Sybase Central ................. 85

Contents

v

Using isql................................................................................. 85Starting Replication Server ............................................................ 87

Replication Server Executable Program ................................. 88Replication Server Configuration File...................................... 89

Shutting Down Replication Server ................................................. 89Adding a Replication Server........................................................... 89Adding a Replication System Domain............................................ 90

Guidelines for Adding Replication System Domains ............... 91Setting Replication Server Configuration Parameters.................... 92

About Configuration Parameters ............................................. 92Changing Replication Server Parameters ............................... 95

Managing RepAgent ...................................................................... 96Setting Up RepAgent............................................................... 97Configuring RepAgent ............................................................. 99Starting RepAgent ................................................................. 101Stopping RepAgent ............................................................... 102Disabling RepAgent............................................................... 102Checking Log Files for Information and Error Messages ...... 103Configuring RepAgent for Network Security.......................... 103Reviewing Status and Configuration Information .................. 104Managing Log Transfer Activity............................................. 106

Managing the RSSD .................................................................... 107Enabling Failover Support for an RSSD Connection............. 108

Quiescing Replication Server....................................................... 109Quiescing a Replication System............................................ 109

Removing a Replication Server.................................................... 110Removing an Active Replication Server ................................ 110Removing an Inactive Replication Server ............................. 113

CHAPTER 5 Managing Routes ........................................................................ 117Overview ...................................................................................... 117Before You Begin ......................................................................... 118

Routing Preparations............................................................. 119Routing Schemes......................................................................... 119

Direct Routes......................................................................... 120Indirect Routes ...................................................................... 120Unsupported Routing Schemes ............................................ 123

Creating Routes ........................................................................... 124Using the create route Command ......................................... 125Configuring a Replication Server to Manage Primary Tables 128

Suspending and Resuming Routes.............................................. 129Using the suspend route Command...................................... 130Using the resume route Command ....................................... 130

Changing Routes ......................................................................... 130

Contents

vi

Changing Route Topology..................................................... 131Changing the Password for the RSI User for a Direct Route 134Changing Parameters Affecting Direct Routes...................... 134Routing Modification Example............................................... 136

Dropping Routes .......................................................................... 138Using the drop route Command ............................................ 139Using the sysadmin purge_route_at_replicate Command .... 139

Upgrading Routes ........................................................................ 140Monitoring Routes ........................................................................ 141

Displaying RSI Thread Status Using admin who................... 141Using the rs_helproute Stored Procedure ............................. 141

CHAPTER 6 Managing Database Connections .............................................. 143Preparing Databases for Replication ........................................... 143

Steps in Preparing Databases for Replication....................... 144Upgrading an Existing Adaptive Server Database ................ 145

Managing Maintenance User Login Names ................................. 145Finding the Current Maintenance User ................................. 146Granting Permissions in the Database.................................. 146

Creating Database Connections .................................................. 147Information for Adding a Database Connection .................... 148Using the create connection Command ................................ 149

Altering Database Connections.................................................... 150Suspending Database Connections ...................................... 151Setting and Changing Parameters

Affecting Physical Connections ...................................... 152Resuming Database Connections......................................... 160Changing Replicate Databases to Primary Databases ......... 161Changing Primary Databases to Replicate Databases ......... 163

Dropping Database Connections ................................................. 164Dropping a Database from the ID Server .............................. 165

Monitoring Database Connections ............................................... 165Viewing Current Database Connections ............................... 165Listing Databases Managed by a Replication Server............ 166Displaying DSI Thread Status ............................................... 166

CHAPTER 7 Managing Replication Server Security ...................................... 167Overview ...................................................................................... 167Managing Replication Server System Security ............................ 168

RSSD Login Names and Passwords..................................... 168Replication Server Login Name

and Password for the RepAgent..................................... 169ID Server Login Name and Password ................................... 170

Contents

vii

Replication Server Login Name and Password for Replication Servers ........................... 171

Maintenance User Adaptive Server Login Name and Password................................................................. 171

Sybase Central Dependencies.............................................. 171Replication Server Object Creation Dependencies ............... 172

Managing Replication Server User Security ................................ 173Managing Replication Server Login Names and Passwords 173Enabling and Disabling Password Encryption....................... 175Managing Replication Server Permissions............................ 176Examining Users, Passwords, and Permissions ................... 182

Managing Network-Based Security.............................................. 183How Security Services Work ................................................. 184Requirements and Restrictions ............................................. 186Setting Up Network-Based Security ...................................... 186Modifying Configuration Parameters

and Environment Variables ............................................ 187Configuring objectid.dat......................................................... 188Configuring the Interfaces File .............................................. 189Setting Environment Variables (Kerberos) ............................ 189Establishing the Principal User.............................................. 190Identifying Principal Users to Replication Server .................. 191

Activating Network-Based Security .............................................. 191Starting Server and Clients .......................................................... 192Configuring Security Services for Replication Server .................. 193

Identifying Replication Server Pathways ............................... 193Configuration Parameters ..................................................... 195Planning for Compatible Settings .......................................... 196Configuring Default Values.................................................... 197Configuring Security for the Connection to the RSSD........... 199Configuring Security for Database Connections ................... 199Configuring Security for Routes ............................................ 201Configuring Security to the ID Server.................................... 203Configuring Security for the RepAgent Pathway ................... 204Logging In to Replication Server ........................................... 205Borrowing Security Settings to Secure Other Pathways ....... 207

Managing Network Security ......................................................... 208Using set proxy to Switch Logins .......................................... 208Disabling Network-Based Security ........................................ 208Changing the Security Mechanism........................................ 209Resetting Per-Target Values to Default Values..................... 209Viewing Information About Security Services........................ 210 Mapping a Security System Login

to a Replication Server Login ......................................... 211

Contents

viii

Using More Than One Security Mechanism.......................... 211

CHAPTER 8 Managing Replicated Tables ...................................................... 213Planning a Replication System .................................................... 214

Design Considerations .......................................................... 214Restrictions on Data Replication ........................................... 215Preparing a Replication System ............................................ 215

Summarizing the Process ............................................................ 216Replication Procedure ........................................................... 216Commands for Managing Table Replication Definitions ....... 220

Creating Replication Definitions ................................................... 221Replication Definition Settings............................................... 222Using the create replication definition Command.................. 223Creating Multiple Replication Definitions Per Table .............. 234Replication Definitions and Function Strings......................... 236Replication Definition Restrictions

in Mixed-Version Systems .............................................. 237Marking Tables for Replication..................................................... 238

Using the sp_setreptable System Procedure ........................ 239Replicating Java Columns............................................................ 241

Restrictions............................................................................ 241Upgrade Considerations........................................................ 241Java Datatypes in Replication Server ................................... 242Creating Replication Definitions for Java Columns ............... 242Function Strings for Java Columns ....................................... 243

Replicating text, image, and rawobject Columns ......................... 246Creating a text, image, or rawobject Replication Definition... 247Marking Tables with text, image, or rawobject Columns ....... 248Changing Column Status for text, image,

or rawobject Columns..................................................... 249Altering Replication Status for text, image,

and rawobject Columns .................................................. 250Resolving Inconsistencies in Replication Status ................... 251Subscription Issues for replicate_if_changed Status............. 254Function Strings for Replicating text and image Data ........... 254

Working with Special Datatypes................................................... 254Using the rs_address Datatype ............................................. 255Replicating IDENTITY Columns ............................................ 255

Modifying Replication Definitions ................................................. 256Maintaining Table Schema.................................................... 257Viewing Existing Replication Definitions................................ 261Altering Replication Definitions.............................................. 261Dropping Replication Definitions ........................................... 267

Modifying Replicated Data ........................................................... 267

Contents

ix

Adding a New Table .............................................................. 268Renaming Replicated Tables ................................................ 268Dropping a Replicated Table................................................. 268Adding Columns in Source and Destination Tables .............. 269Deleting Columns in a Source or Destination Table.............. 269Changing Searchable Columns............................................. 270Changing Column Datatypes

in a Source or Destination Table .................................... 270Using Publications........................................................................ 271

Using Publications To Replicate Data in Sybase Central...... 272Using Publications to Replicate Data at the Command Line. 273

Translating Datatypes Using HDS ............................................... 281Overview ............................................................................... 282Getting Started ...................................................................... 283Creating Class-Level Translations ........................................ 284Creating Column-Level Translations ..................................... 287Using Class-Level and Column-Level Translations Together 292Verifying Translations............................................................ 292

CHAPTER 9 Managing Replicated Functions................................................ 293Prerequisites and Restrictions ..................................................... 294

Replicated Function Prerequisites......................................... 294Replicated Function Restrictions........................................... 295Commands for Managing Function Replication Definitions... 296

Using Replicated Functions ......................................................... 297Applied Functions.................................................................. 298Request Functions ................................................................ 298

Implementing an Applied Function............................................... 299Implementing a Request Function ............................................... 302Marking Stored Procedures for Replication ................................. 305Subscribing to Replicated Functions............................................ 305Modifying or Dropping Replicated Functions ............................... 306

Before Modifying a Function Replication Definition............... 306Modifying a Function Replication Definition .......................... 306Dropping a Function Replication Definition ........................... 307Creating or Modifying a Function String

for a Replicated Function................................................ 307Using Publications for Stored Procedures ................................... 308

CHAPTER 10 Managing Subscriptions ............................................................ 309Overview ...................................................................................... 309Subscription Materialization Methods .......................................... 310

Atomic Materialization ........................................................... 311

Contents

x

Nonatomic Materialization ..................................................... 313No Materialization.................................................................. 314Bulk Materialization ............................................................... 315

Dematerialization Processing....................................................... 321Dematerializing and Purging Rows ....................................... 322Dematerialization Without Purging Rows .............................. 323

Monitoring Materialization and Dematerialization ........................ 323Before You Create Subscriptions................................................. 324Using Subscription Commands.................................................... 326

Using the where Clause ........................................................ 328Enabling Replication of truncate table................................... 329Using the create subscription Command .............................. 330Using the define subscription Command............................... 333Using the activate subscription Command ............................ 333Using the validate subscription Command ............................ 334Using the check subscription Command ............................... 335Using the drop subscription Command ................................. 336

Subscription Example .................................................................. 338Description of Replication System......................................... 338Procedures for Replicating Tables ........................................ 339

Materializing text, image, and rawobject Data ............................. 342Nonatomic Materialization ..................................................... 342Row Migration ....................................................................... 342

Subscriptions for Columns with Heterogeneous Datatypes ......... 343Bitmap Subscriptions ................................................................... 344Obtaining Subscription Information .............................................. 346

Displaying Subscription Information ...................................... 347Verifying Subscription Consistency ....................................... 347

Using Publication Subscriptions................................................... 350Commands for Creating

and Managing Publication Subscriptions........................ 351Creating Publication Subscriptions........................................ 352Dropping Subscriptions for Publications and Articles............ 356Viewing Publication Subscription Information ....................... 358

CHAPTER 11 Verifying and Monitoring Replication Server............................ 361Checking Replication System Log Files for Errors....................... 362Verifying a Replication System .................................................... 362Monitoring Replication Server ...................................................... 364

Verifying Server Status.......................................................... 365Displaying Replication System Thread Status ...................... 366

Setting and Using Threshold Levels ............................................ 368Monitoring Partition Percentages .......................................... 368

Contents

xi

CHAPTER 12 Customizing Database Operations............................................ 371Overview ...................................................................................... 371Working with Functions, Function Strings, and Classes .............. 372

Functions............................................................................... 373Summary of System Functions ............................................. 375Function Strings .................................................................... 378System Functions with Multiple Function Strings .................. 380

Function-String Classes ............................................................... 380System-Provided Classes ..................................................... 381Function-String Inheritance ................................................... 382Restrictions in Mixed-Version Systems ................................. 384

Managing Function-String Classes .............................................. 385Creating a Function-String Class .......................................... 386Assigning a Function-String Class to a Database ................. 390Dropping a Function-String Class ......................................... 391

Managing Function Strings .......................................................... 391Function Strings and Function-String Classes ...................... 392Function-String Input and Output Templates ........................ 392Using Output Templates........................................................ 393Using Input Templates .......................................................... 395Using Function-String Variables............................................ 397Creating Function Strings...................................................... 398Altering Function Strings ....................................................... 400Dropping Function Strings..................................................... 402Restoring Default Function Strings........................................ 403Creating Empty Function Strings with the Output Template . 404Remapping Table

and Column Names with Function Strings ..................... 405Defining Multiple Commands in a Function String ................ 405Using Declare Statements in Language Output Templates .. 406

Displaying Function-Related Information ..................................... 407Obtaining Information Using the admin Command ............... 407Obtaining Information Using Stored Procedures................... 408

Using the Default System Variable .............................................. 408Extending Default Function Strings ....................................... 409Using Replicate Minimal Columns......................................... 410

Using Function Strings with text, image, and rawobject Datatypes 410Using output writetext for rs_writetext Function Strings ........ 411Using output none for rs_writetext Function Strings.............. 411

CHAPTER 13 Managing Warm Standby Applications..................................... 415Overview ...................................................................................... 415

How a Warm Standby Works ................................................ 415Database Connections in a Warm Standby Application........ 416

Contents

xii

Primary and Replicate Databases and Warm Standby Applications .................................... 417

Warm Standby Requirements and Restrictions .................... 418Function Strings for Maintaining Standby Databases ........... 419

What Information Is Replicated? .................................................. 420Comparing Replication Methods ........................................... 421Using sp_reptostandby to Enable Replication....................... 422Using sp_setreptable to Enable Replication.......................... 424Using sp_setrepproc to Copy User Stored Procedures ........ 425Replicating Tables

with the Same Name but Different Owners .................... 425Replicating text, image, and rawobject Data ......................... 426Changing Replication for the Current isql Session................ 427

Setting Up Warm Standby Databases ......................................... 428Before You Begin .................................................................. 428Task One: Creating the Logical Connection.......................... 429Task Two: Adding the Active Database ................................ 431Task Three: Enabling Replication for Objects in the Active

Database ........................................................................ 431Task Four: Adding the Standby Database ............................ 433

Switching the Active and Standby Databases.............................. 440Determining If a Switch Is Necessary.................................... 440Before Switching Active and Standby Databases ................. 440Internal Switching Steps........................................................ 442After Switching Active and Standby Databases .................... 442Making the Switch ................................................................. 443

Monitoring a Warm Standby Application ...................................... 448Replication Server Log File ................................................... 448Commands for Monitoring Warm Standby Applications........ 449

Setting Up Clients to Work with the Active Data Server............... 450Two Interfaces Files .............................................................. 451Symbolic Data Server Name for Client Applications ............. 451Map Client Data Server to Currently Active Data Server ...... 452

Altering Warm Standby Database Connections........................... 452Altering Logical Connections................................................. 452Altering Physical Connections............................................... 454Dropping Logical Database Connections .............................. 456

Warm Standby Applications Using Replication ............................ 457Warm Standby Application for a Primary Database .............. 457Warm Standby Application for a Replicate Database ........... 459

Using Replication Definitions and Subscriptions.......................... 464Creating Replication Definitions

for Warm Standby Databases ........................................ 464Using Subscriptions with Warm Standby Application............ 469

Contents

xiii

Missing Columns When You Create the Standby Database. 474Loss Detection and Recovery ...................................................... 474

CHAPTER 14 Performance Tuning ................................................................... 477Replication Server Internal Processing ........................................ 477

Threads, Modules, and Daemons ......................................... 477Processing in the Primary Replication Server ....................... 478Processing in the Replicate Replication Server .................... 483

Default Configuration Parameters Affecting Performance ........... 484Using Parallel DSI Threads.......................................................... 486

Parallel DSI Parameters........................................................ 487Components of Parallel DSI .................................................. 488Processing Transactions with Parallel DSI Threads ............. 489Transaction Serialization Methods ........................................ 490Detecting Conflicting Updates with the rs_threads Table...... 491Configuring Parallel DSI for Optimal Performance................ 494Parallel DSI and the

rs_origin_commit_time System Variable ........................ 496

CHAPTER 15 Handling Errors and Exceptions ............................................... 499General Error Handling ................................................................ 499Error Log Files.............................................................................. 500

Replication Server Error Log ................................................. 500RepAgent Error Log Messages ............................................. 503

Data Server Error Handling.......................................................... 504Creating an Error Class......................................................... 505Initializing a New Error Class ................................................ 505Dropping an Error Class........................................................ 506Changing the Primary Replication Server for an Error Class 506Displaying Error Class Information........................................ 507Assigning Actions to Data Server Errors ............................... 508Displaying Assigned Actions for Error Numbers ................... 509

Exceptions Handling .................................................................... 509Handling Failed Transactions................................................ 510Accessing the Exceptions Log .............................................. 511Deleting Transactions from the Exceptions Log.................... 514

DSI Duplicate Detection ............................................................... 514Duplicate Detection for System Transactions .............................. 515

CHAPTER 16 Replication System Recovery.................................................... 517How to Use Recovery Procedures ............................................... 517Configuring the Replication System to Support Sybase Failover. 518

Contents

xiv

Overview ............................................................................... 518Enabling Failover Support in Replication Server................... 519

Configuring the Replication System to Prevent Data Loss .......... 523Save Interval for Recovery .................................................... 523Backing Up the RSSDs ......................................................... 526Creating Coordinated Dumps................................................ 526

Recovering from Partition Loss or Failure.................................... 527Procedure for Recovering from Partition Loss or Failure ...... 528Message Recovery from Off-line Database Logs.................. 530Message Recovery from the Online Database Log............... 532

Recovering from Truncated Primary Database Logs ................... 532Truncated Message Recovery from the Database Log......... 533

Recovering from Primary Database Failures ............................... 536Loading from Coordinated Dumps ........................................ 536Loading a Primary Database from Dumps ............................ 537

Recovering from RSSD Failure.................................................... 540Recovering an RSSD from Dumps........................................ 541Basic RSSD Recovery Procedure......................................... 541Subscription Comparison Procedure..................................... 544Subscription Re-Creation Procedure..................................... 551Deintegration/Reintegration Procedure ................................. 554

Recovery Support Tasks.............................................................. 555Rebuilding Stable Queues..................................................... 555

APPENDIX A Asynchronous Stored Procedures ............................................ 567Overview ...................................................................................... 567

Logging Replicated Stored Procedures................................. 567Logging Replicated Stored Restrictions ................................ 568Mixed-Mode Transactions ..................................................... 568

Applied Stored Procedures .......................................................... 568Request Stored Procedures......................................................... 569Asynchronous Stored Procedure Prerequisites ........................... 570Steps for Implementing an Applied Stored Procedure ................. 571

Warning Conditions ............................................................... 574Steps for Implementing a Request Stored Procedure.................. 575Specifying Stored Procedures and Tables for Replication........... 577Managing User-Defined Functions............................................... 578

Creating a User-Defined Function......................................... 579Adding Parameters to a User-Defined Function.................... 580Dropping a User-Defined Function........................................ 580Mapping to a Different Stored Procedure Name ................... 581Specifying a Non-Unique Name

for a User-Defined Function ........................................... 583

xv

APPENDIX B LTM for SQL Server..................................................................... 585Overview....................................................................................... 585Data Flow for Replication Systems with LTMs ............................. 586

LTM Processing..................................................................... 587LTM Processing Data Flow.................................................... 587

SQL Server LTM Executable Program......................................... 590Shutting Down an LTM .......................................................... 591Checking Log Files for Errors ................................................ 591

Configuring and Maintaining the LTM........................................... 592Adding a Replication Server .................................................. 592Preparing Databases for Replication ..................................... 593Interfaces File ........................................................................ 594LTM Configuration File .......................................................... 594Replication Server Login Name and Password for the LTM.. 595LTM Login Name and Password ........................................... 596SQL Server Login Name and Password................................ 596Enabling and Disabling Password Encryption ....................... 596

Suspending and Resuming Log Transfer ..................................... 597Suspending LTMs.................................................................. 597Resuming LTMs..................................................................... 598

Modifying Replication Systems with LTMs ................................... 598Configuring Replication Servers to Manage Primary Tables . 599Changing Replicate Databases to Primary Databases.......... 599Changing Primary Databases to Replicate Databases.......... 601

LTM Error Log Information ........................................................... 601LTM Message Types ............................................................. 602

APPENDIX C HDS Datatype Translation Mapping .......................................... 605DB2 Class-Level Translations ...................................................... 605Informix Class-Level Translations ................................................ 607Microsoft SQL Server Class-Level Translations........................... 610Oracle Class-Level Translations................................................... 612

Glossary ...................................................................................................... 615

INDEX .......................................................................................................631

xvii

About This Book

Replication Server® maintains replicated data at multiple sites on a network. Organizations with geographically distant sites can use Replication Server to create distributed database applications with better performance and data availability than a centralized database system can provide.

This book, Replication Server Administration Guide, provides an overview of how Replication Server works, and describes Replication Server administrative tasks, including:

• Configuring and running Replication Server and other replication system components

• Managing user accounts and security

• Enabling users to access replicated data, using replicated tables and stored procedures, replication definitions, publications, and subscriptions

• Managing routes (between Replication Servers) and connections (from Replication Servers to data servers)

• Setting up warm standby applications

• Modifying a replication system

• Managing resources and fine-tuning Replication Server performance

• Handling replication system errors

• Recovering from system failure

AudienceThe Replication Server Administration Guide is for Replication System Administrators, who manage the routine operation of their Replication Servers. Any user who has been granted the sa permission can be a Replication System Administrator, although each Replication Server usually has just one.

How to Use This Book

xviii

How to Use This BookThis book contains the following:

• Chapter 1, “Introduction” introduces you to Replication Server, describing the role it plays in a distributed database system and its concepts and components.

• Chapter 2, “Replication Server Technical Overview” provides a technical overview of the replication system, giving you the background necessary to maintain and troubleshoot the system.

• Chapter 3, “Managing Replication Server with Sybase Central”describes using Sybase Central’s Replication Server Manager™ (RSM), which is a graphical tool for managing Replication Server.

• Chapter 4, “Managing a Replication System” describes basic operations such as starting, stopping, and configuring Replication Server.

• Chapter 5, “Managing Routes” describes how to create and manage routes between source and destination Replication Servers.

• Chapter 6, “Managing Database Connections” describes how to prepare databases for replication and how to create and manage connections between databases and Replication Servers.

• Chapter 7, “Managing Replication Server Security” describes how to create and modify login names, passwords, and permissions and how to set up network-based security.

• Chapter 8, “Managing Replicated Tables” describes how to set up and manage replicated tables.

• Chapter 9, “Managing Replicated Functions” describes how to copy the execution of user stored procedures to remote sites in a replication system using replication definitions.

• Chapter 10, “Managing Subscriptions” describes how to create and manage subscriptions, which allow Replication Server to replicate data between databases.

• Chapter 11, “Verifying and Monitoring Replication Server” describes checking error logs, verifying that the components of a replication system are running, and monitoring the status of system components and processes.

About This Book

xix

• Chapter 12, “Customizing Database Operations” describes how to use functions, function strings, and function-string classes to customize data replication with Sybase® Adaptive Server™ Enterprise and data servers from other vendors.

• Chapter 13, “Managing Warm Standby Applications” describes how to create and manage warm standby applications.

• Chapter 14, “Performance Tuning” describes how to manage resources effectively and optimize the performance of individual Replication Servers.

• Chapter 15, “Handling Errors and Exceptions” discusses error conditions and failed transactions and how to customize data server responses to errors.

• Chapter 16, “Replication System Recovery” describes replication system failure conditions and provides procedures for recovering from them.

• Appendix A, “Asynchronous Stored Procedures” describes a method for replicating stored procedures associated with table replication definitions.

• Appendix B, “LTM for SQL Server” describes the Log Transfer Manager (LTM), the replication agent for SQL Server™ databases.

Related DocumentsOther documents that may be helpful include:

• Replication Server installation and configuration guides for your platform, which describe the installation procedure for Replication Server, including how to use the rs_init program.

• What’s New in Replication Server Version 11.5?, which contains information about the new features in this release.

• Replication Server Reference Manual, which contains syntax and detailed descriptions of the commands in the Replication Command Language (RCL).

• Replication Server Design Guide, which contains information on designing a replication system, and on integrating heterogeneous data servers into a replication system.

• Replication Server Troubleshooting Guide, which contains information that helps you diagnose and correct problems in a replication system.

Other Sources of Information

xx

• Replication Server online help, which contains information about using Sybase Central™ to manage Replication Server.

Other Sources of InformationUse the Sybase Technical Library CD and the Technical Library Web site to learn more about your product:

• Technical Library CD contains product manuals and technical documents and is included with your software. The DynaText browser (included on the Technical Library CD) allows you to access technical information about your product in an easy-to-use format.

Refer to the Technical Library Installation Guidein your documentation package for instructions on installing and starting Technical Library.

• Technical Library Web site is an HTML version of the Technical Library CD that you can access using a standard Web browser.

To use the Technical Library Web site, go to www.sybase.com and choose Documentation, choose Technical Library, then choose Product Manuals.

ConventionsThis section describes style and syntax conventions, RCL command formatting conventions, graphic icons, and Sybase Central’s RSM conventions used in this book.

Style ConventionsSyntax statements (displaying the syntax and options for a command) are printed as follows:

alter user userset password new_passwd[verify password old_passwd]

See “Syntax Conventions” on page xxi for more information.

Examples that show the use of Replication Server commands are printed as follows:

About This Book

xxi

alter user louise set password somNIfic verify password EnnuI

Command names, command option names, program names, program flags, keywords, configuration parameters, functions, and stored procedures are printed as follows:

Use alter user to change the password for a login name.

Variables, parameters to functions and stored procedures, and user-supplied words are in italics in syntax and in paragraph text, as follows:

The set password new_passwd clause specifies a new password.

Names of database objects, such as databases, tables, columns, and datatypes, are in italics in paragraph text, as follows:

The base_price column in the Items table is a money datatype.

Names of replication objects, such as function-string classes, error classes, replication definitions, and subscriptions, are in italics.

Syntax ConventionsSyntax formatting conventions are summarized in the following table. Examples combining these elements follow.

Obligatory Choices • Curly braces and vertical bars – choose only one option.

{red | yellow | blue}

• Curly braces and commas – choose one or more options. If you choose more than one, separate your choices with commas.

{cash, check, credit}

Key Definitionvariable Variables (words standing for values that you fill in) are in italics.

{ } Curly braces mean you must choose at least one of the enclosed options. Do not include braces in the command.

[ ] Brackets mean you may choose or omit enclosed options. Do not include brackets in the command.

| Vertical bars mean you may choose no more than one option (enclosed in braces or brackets).

, Commas mean you may choose as many options as you need (enclosed in braces or brackets). Separate your choices with commas, to be typed as part of the command.

Commas may also be required in other syntax contexts.

( ) Parentheses are to be typed as part of the command.

... An ellipsis (three dots) means you may repeat the last unit as many times as you need. Do not include ellipses in the command.

Conventions

xxii

Optional Choices • One item in square brackets – choose it or omit it.

[anchovies]

• Square brackets and vertical bars – choose none or only one.

[beans | rice | sweet_potatoes]

• Square brackets and commas – choose none, one, or more options. If you choose more than one, separate your choices with commas.

[extra_cheese, avocados, sour_cream]

Repeating Elements An ellipsis (...) means that you may repeat the last unit as many times as you need. For the alter function replication definition command, for example, you can list one or more parameters and their datatypes for either the add clause or the add searchable parameters clause:

alter function replication definition function_rep_def{deliver as ’proc_name’ |add @parameter datatype[, @parameter

datatype]... |add searchable parameters @parameter

[, @parameter]... |send standby {all | replication definition}

parameters}

RCL Command FormattingRCL commands are similar to Transact-SQL® commands. The following sections present the formatting rules.

Command Format and Command Batches

• You can break a line anywhere except in the middle of a keyword or identifier. You can continue a character string on the next line by typing a backslash (\) at the end of the line.

• Extra space characters on a line are ignored, except after a backslash. Do not enter any spaces after a backslash.

• You can enter more than one command in a batch, unless otherwise noted.

• RCL commands are not transactional. Replication Server executes each command in a batch without regard for the completion status of other commands in the batch. Syntax errors in a command prevent Replication Server from parsing subsequent commands in a batch.

About This Book

xxiii

Case Sensitivity

• Keywords in RCL commands are not case-sensitive. You can enter them with any combination of uppercase or lowercase letters.

• Identifiers and character data may or may not be case-sensitive, depending on the sort order that is in effect.

• If you are using a case-sensitive sort order such as “binary,” you must enter identifiers and character data using the correct combination of uppercase and lowercase letters.

• If you are using a sort order that is not case-sensitive, such as “nocase,” you can enter identifiers and character data using any combination of uppercase or lowercase letters.

Identifiers

• Identifiers are names you give to database or replication objects. They include object names, column names, variable names, and parameter names.

• Identifiers can be 1–30 bytes long (equivalent to 1–30 single-byte characters). The first character must be a letter or the @ or _ character.

• Replication Server function parameters are the only identifiers that can begin with the @ character. Function parameter names can include up to 30 characters after the @ character.

• After the first character, identifiers can include letters, digits, and the #, $, or _ character. You cannot embed spaces in identifiers.

Parameters in Function Strings

• Parameters in function strings have the same rules as identifiers, except:

• They are enclosed in question marks (?), allowing Replication Server to locate them in the function string. Use two consecutive question marks (??) to represent a literal question mark in a function string.

• The exclamation point (!) introduces a parameter modifier that indicates the source of the data to substitute for a parameter at runtime. See Chapter 12, “Customizing Database Operations” for a complete list of modifiers.

Conventions

xxiv

Datatype SupportReplication Server supports all of the Adaptive Server datatypes.

User-defined datatypes are not supported. The timestamp, double precision, nchar, and nvarchar datatypes are indirectly supported by mapping them to other datatypes. Columns using the timestamp datatype are mapped to varbinary(8).

Refer to “Datatypes” in Chapter 2, “Topics,” in the Replication Server Reference Manual for more information about the supported datatypes, including how to format them.

Graphic IconsIllustrations in this book use the following graphic icons to represent the components of a replication system.

Replication Server

This icon represents Replication Server, the Sybase server program that maintains replicated data on a local-area network (LAN) and processes data transactions received from other Replication Servers on the wide-area network (WAN).

Adaptive Server or Other Data Servers

This icon represents Adaptive Server, the Sybase data server. Data servers manage databases containing primary or replicate data. Replication Server works with heterogeneous data servers, so unless specifically noted, the graphic can represent any data server in a replication system.

About This Book

xxv

Client Application

This icon represents a client application. A client application is a user process or application connected to a data server. It may be a front-end application program executed by a user or a program that executes as an extension of the system.

Replication Server Manager

This icon represents Replication Server Manager (hereafter referred to as RSM), which is a Sybase Central graphical administration tool that enables a Replication System Administrator to monitor, diagnose, troubleshoot, and administer a replication system.

Sybase Central’s Replication Server Manager and Online HelpThis icon, which appears in the margins of the book, pinpoints text that identifies:

• Tasks that can be performed in Sybase Central

• The Replication Server online Help pages describing how to perform the tasks

If You Need HelpEach Sybase installation that has purchased a support contract has one or more designated people who are authorized to contact Sybase Technical Support. If you cannot resolve a problem using the manuals or online help, please have the designated person contact Sybase Technical Support or the Sybase subsidiary in your area.

RSM

If You Need Help

xxvi

1

C H A P T E R 1 Introduction

This chapter introduces you to Replication Server and its role in a distributed database system. It also discusses the benefits and features of Replication Server, methods and concepts for replicating data, and Replication Server’s support for heterogeneous data servers, as well as defining user roles in maintaining a replication system.

About Replication Server Replication Server maintains replicated data in multiple databases while ensuring the integrity and consistency of the data. It provides clients using databases in the replication system with local data access, thereby reducing load on the network and centralized computer systems.

The Replication Command Language (RCL) enables you to customize replication functions and to monitor and maintain the replication system. For example, you can request subsets of data for replication at the table, data row, or column level. This feature further reduces overhead by allowing you to replicate only the data that is needed at the replicate site.

Replication Server supports heterogeneous data servers. You can build a replication system from existing databases and applications without having to convert them. As your enterprise grows and changes, you can add data servers to your replication system to meet your needs.

Replication Server uses a basic publish-and-subscribe model for replicating data across networks. Users “publish” data that is available in a primary database, and other users “subscribe” to the data for delivery in a replicate database. Users can replicate both changes to the data (update/insert/delete operations) and stored procedures using this method.

About Replication Server

2

Instructions to publish and subscribe to data are given at Replication Servers that control, or have a connection to, each database. The user creates a replication definition at a primary Replication Server, which controls the primary database containing the data to be published. The replication definition specifies information such as which columns are to be replicated. The user creates a subscription at a replicate Replication Server, which controls the replicate database that will receive the information.

Replication Servers communicate with each other via user-defined routes. Most commonly, a primary Replication Server sends data to a replicate Replication Server through one or more routes set up to transmit data from the primary database to the replicate database. Users may also transmit stored procedures from the replicate to the primary to request updates of the primary data; in this case, data flows through one or more routes from the replicate Replication Server to the primary Replication Server.

Connections and routes define the structure of the replication system. They allow Replication Servers to send messages to each other and to send commands to databases. A connection transfers messages from a Replication Server to a database. A route transfers requests from a source Replication Server to a destination Replication Server.

Asynchronous Transaction ReplicationReplication occurs asynchronously—that is, updates to data at the primary are transferred to replicate databases in transactions separate from the update itself. While asynchronous replication provides important advantages, system designers should remain aware of the latency between initial and replicated updates.

Advantages of Replicating Local DataReplicating tables on local data servers provides clients with local access to enterprise data, which results in improved performance and greater data availability.

Improved Performance

In a typical Replication Server system, data requests are completed on the local data server without accessing the WAN. Therefore, local clients gain improved performance because:

CHAPTER 1 Introduction

3

• Data transfer rates are faster on a LAN than they are on a WAN.

• Local access remains unaffected by network traffic over the WAN. Local clients that share local data server resources do not compete with the enterprise-wide user community for central resources.

Greater Data Availability

Because data is replicated at local and remote databases in a Replication Server system, clients can operate in a fault-tolerant environment so that:

• When a failure occurs at a remote database, clients can use local copies of replicated data.

• When a WAN failure occurs, clients can use local copies of replicated data.

• When the local data server fails, clients can use replicated data at another site.

Network failure or database failure at other locations do not halt work at the local database. When WAN communications fail, Replication Server stores operations on replicated tables in stable queues (disk storage). The replicated tables at the unavailable databases are updated when communications resume. If a local data server fails, clients can continue working by temporarily accessing a replicate copy of the data.

Replication Server and Distributed Database SystemsDistributed database systems allow client applications to access data on multiple database servers throughout an enterprise—even geographically dispersed enterprises. Replication Server ensures that data on replicate databases stays updated while off-loading processing responsibilities from the source database.

As Figure 1-1 illustrates, these enterprises may consist of many LANs and one or more WANs.

Replication Server and Distributed Database Systems

4

Figure 1-1: Replication system in a distributed environment

Replication Server minimizes performance and data-availability problems typically associated with remote access in distributed systems. Since Replication Server provides multiple copies of data, clients can rely on their own local data instead of remote, centralized databases. In addition, you can copy only the data you want to destination databases. Replication Server allows you to create a replication definition that identifies all or part of a table to replicate. You can then subscribe to only the rows you want. You can also create a replication definition of a stored procedure (called function replication definition) to facilitate rapid replication of large amounts of data and to replicate updates from replicate databases back to the primary database. If your application requires it, you can consolidate or “roll up” replicated data from primary tables into a centralized database.

New York

Client

Paris London

WAN

Adaptive Server

Open Interoperability

DB2

Rdb

non-relationaldata services

to otherReplication Servers

LocalCopy

Replication Server

NY1_DB NY2_DB

PAR_DB

ORACLE


5

You can group replication definitions, both table replication definitions and functions replication definitions, in a publication and subscribe to them all at once. Publications allow you to organize subscriptions and then monitor them with a single command.

A replication agent—Log Transfer Manager (LTM) for sites where Sybase SQL Server is running and RepAgent for sites running Adaptive Server—transfers transaction information from a database to a Replication Server for distribution to replicate databases. Sybase also offers Replication Agents™ for Informix, Microsoft SQL Server, DB2, Oracle, IMS, VSAM, and Lotus Notes. RepAgent is an Adaptive Server thread; all other replication agents are separate processes.

Several models for replicating data in distributed systems exist in Replication Server. Consult the Replication Server Design Guide to help you determine which model best suits your application. The model that you choose determines how you set up your system.

Setting up a replication system based on your distribution model involves:

• Creating tables to store primary and replicate data

• Setting up routes and connections between Replication Servers and establishing permissions that control access to primary data

• Creating replication definitions that identify the data you want replicated

• Creating subscriptions from replicate databases to those replication definitions

See Chapter 2, “Replication Server Technical Overview” for a discussion of Replication Server components, concepts, and terminology. See Chapter 4, “Managing a Replication System” for a more detailed overview of setting up a Replication Server system.

Replication Server’s Basic Primary Copy ModelThe simplest approach Replication Server uses to copy data is to distribute updates from one source (primary) database to one or more destination (replicate) databases. To ensure consistency, a source table is designated as the primary table. All other versions of the table are replicates. In this approach, replicate tables are read-only and used for operations that do not modify the data.


6

As updates occur at the primary table, Replication Server captures the updates and sends them to replicate data servers. In this model, clients at remote sites can also update primary data, either directly by accessing the primary database over the network or indirectly through replicated stored procedures.

For more information, see “Specifying Data for Replication” on page 33, and Chapter 9, “Managing Replicated Functions”

If communication between the primary and destination databases fails, operations executed in the primary database are stored in Replication Server stable queues until they can be delivered to replicate sites. Likewise, operations executed remotely are held in stable queues until they can be delivered to the primary database.

This arrangement lets remote client applications take advantage of Replication Server’s fault tolerance while preserving the basic primary copy model. See “Transaction Handling with Replication Server” on page 43 for more information about stable queues.

Figure 1-2 illustrates Replication Server configurations using the primary copy method of replicating data.


7

Figure 1-2: Replication Server’s basic primary copy model

Replication System Processing

This section describes a typical replication system, according to the basic primary copy model, in which a primary Replication Server and a data server are separated across a WAN from replicate Replication Servers. It does not cover the case where primary data is updated at the replicate database.

Client

Decision-support applications

OLTP applications

Remote sites Decision-support applications

Data Server

Replication

Updates to primary database

WAN

OLTP applications

Server

via request function delivery


8

Figure 1-3: Replication system overview

Figure 1-3 illustrates how data is replicated from a primary database to replicate databases. The following actions take place:

1 RepAgent (or Log Transfer Manager in SQL Server systems) reads the primary database log and converts transactions for tables or stored procedures that are marked for replication into commands that are sent to Replication Server.

The Replication Server stores the transactions in a stable queue (see “Distributed Concurrency Control” on page 47).

2 The primary Replication Server:

a Determines which Replication Servers manage replicate databases with subscriptions for the data

The primary Replication Server may have a direct route to a subscribing Replication Server or an indirect route, with one or more intermediate Replication Servers in between.

b Forwards the transaction to the appropriate replicate Replication Server, where it is stored in a stable queue

c Applies the transaction to any local replicate database for which there is a subscription for the data

Transactions

TransactionsPrimary

Replicate

Stable Queues

Log Transfer

Other Replicate

ReplicatePrimary

Language (LTL)

Replication Server Replication Server

Replication Servers

Data Server

Data Server

Transactions

WAN

Stable Queues


9

3 The replicate Replication Server performs one or both of the following actions:

• Routes the transaction to another Replication Server

• Applies the transaction to replicate databases that it manages

Setting Up a Primary Copy Model System

In order to set up a system according to the basic primary copy model, you need to:

• Set up routes and connections between Replication Servers.

See Chapter 5, “Managing Routes”and Chapter 6, “Managing Database Connections”for information on these topics.

• Create the table in the primary and replicate databases. The table should have the same structure in each database.

• Create indexes and grant appropriate permissions on the tables.

See Chapter 7, “Managing Replication Server Security”for information on setting permissions for a Replication Server system.

• Allow for replication on the tables using the sp_setreptable system procedure.

• Create a replication definition for the table at the primary site.

Refer to Chapter 8, “Managing Replicated Tables” for information about creating replication definitions.

• At each site, create a subscription for the table replication definition at the primary site.

See Chapter 10, “Managing Subscriptions” for information about creating subscriptions.

Other Distributed Data ModelsBesides the basic primary copy model, Replication Server also lets you design your system based on other distributed data models, including:

• Distributed primary fragments

• Corporate rollup


10

• Redistributed corporate rollup

These models are discussed briefly in this section. Refer to Chapter 3, “Implementation Strategies,” in the Replication Server Design Guide for complete information about these distributed data models.

Warm standby applications represent another type of application model. See Chapter 13, “Managing Warm Standby Applications” for more information.

Distributed Primary Fragments

Applications that use the distributed primary fragments model include distributed tables that contain both primary and replicated data. The Replication Server at each site distributes modifications made to local primary data to other sites and applies modifications received from other sites to the data that is replicated locally.

Figure 1-4 diagrams the flow of data for distributed primary fragments.


11

Figure 1-4: Distributed primary fragments model

The tasks needed to set up a distributed primary fragment system are similar to those for creating a basic primary copy system, with the following exceptions and additions:

• Your application should avoid or handle cases where multiple sites update the same data at the same time. Sybase recommends that each fragment have a single “owner” site.

DSCHI

RSCHI

DBNY RSNY

RSSF

Chicago

New York

San Francisco

DSSF

DSNY

DBSF

DBCHI


12

• Databases can be both primary and replicate. Make sure that tables with the same structure exist at both primary and replicate sites.

• Create routes from each primary site to all sites that subscribe to its data.

• Create a replication definition at any site where there is primary data, even if it is a “remote” site.

• Create subscriptions at each site for the replication definitions at the other sites. If n is the number of sites, create n-1 subscriptions for each replication definition.

Corporate Rollup

The corporate rollup model has distributed primary fragments and a single, centralized consolidated replicate table. The table at each primary site contains only the data that is primary at that site. No data is replicated to these sites. The corporate rollup table is a “roll-up” of the data at the primary sites.

Figure 1-5 illustrates the flow of data for a corporate rollup application model:


13

Figure 1-5: Distributed primary fragments with corporate rollup

Primary

Primary

Corporate Rollup Data

Fragment

Fragment

DSNY

RSNYRSHQ

DSHQ

DSSF

RSSF

Chicago

Headquarters

San Francisco

New York

DSCHI

PrimaryFragment

RSCHI


14

The corporate rollup model requires distinct replication definitions at each primary site. The site where the data is consolidated subscribes to the replication definition at each primary site.

To create a corporate rollup application from distributed primary fragments:

• Activate a replication agent at each primary site. However, you do not need to activate a replication agent at the central site, since data is not replicated from that site.

• Create tables in each primary database and in the database at the central site.

• Allow for replication on tables at each remote database where primary data is stored.

• Create replication definitions for tables at each remote site where primary data is stored.

• At the headquarters site, where the data is to be consolidated, create subscriptions for the replication definitions at the remote sites.

Redistributed Corporate Rollup

The redistributed corporate rollup model is similar to the corporate rollup model. Primary fragments distributed at remote sites are rolled up into a consolidated table at a central site. At the site where the fragments are consolidated, however, a replication agent processes the consolidated table as if it were primary data. The data is then forwarded to Replication Server for distribution to subscribers.

Figure 1-6 illustrates the flow of data in an application based on the redistributed corporate rollup model:


15

Figure 1-6: Distributed fragments with redistributed corporate rollup

Consolidated data

Corporate Rollup

Primary Fragment

Primary Fragment

Chicago

New York

San Francisco

Headquarters

Primary Fragment

RepAgent’ssend_maint_xacts_to_replicate


16

The consolidated table is described with a replication definition. Other sites can then subscribe to this table. Do not allow applications to update the corporate rollup table directly. All updates should originate from the primary sites.

The tasks associated with creating a redistributed corporate rollup replication system are identical to the corporate rollup model, except that:

• A replication agent must be activated at the headquarters site for the consolidated database so that all updates are submitted to the Replication Server as if they were made by a client application.

RepAgent must be configured with its send_maint_xacts_to_replicate option set to “true.” (LTM must be started with the -A flag.) Otherwise, the replication agent filters will not redistribute replicated data as primary data.

See Chapter 4, “Managing a Replication System”for information on configuring RepAgent. See Appendix B, “LTM for SQL Server”for information on starting LTM.

• A replication agent is required for the headquarters Replication Server, since data will be redistributed from that site.

• At the headquarters site a replication definition must be created for each table. Other sites can create subscriptions to this replication definition, but the primary sites cannot subscribe to their own primary data.

• The headquarters Replication Server must have routes to the other sites that create subscriptions for the consolidated replicate table. If the primary sites create subscriptions, routes must be created to them from headquarters.

• Do not allow rollup sites to re-create subscriptions to their primary data. If they do, transactions could loop endlessly through the system.

Replication Server and Heterogeneous Data ServersReplication Server supports heterogeneous data servers through an open interface. You can use any data-storage system as a data server if it supports a set of required basic data operations and transaction-processing directives.


17

Sybase Client/Server Interfaces (C/SI) include routines and protocols for client/server communication. Replication Server connects with data servers as a client using C/SI. If a data server does not support C/SI, you can create an Open Server™ gateway to allow Replication Server to access the data server or you can use a Sybase DirectConnect™ product, which provides access to other databases. When the data server returns results, the Open Server gateway can return them to the client using C/SI routines.

Other open architecture components include:

• Replication agents

A replication agent detects modifications made to primary data and submits them to Replication Server for distribution to other databases.

The RepAgent thread in Adaptive Server is the replication agent for Adaptive Server databases. The Log Transfer Manager (LTM) is the replication agent for users with SQL Server databases. See Appendix B, “LTM for SQL Server” and the Replication Server Administration Guide for Replication Server version 11.0 for more information about the LTM.

Replication Agents for Informix, Microsoft SQL Server, SQL Anywhere™, Lotus Notes, DB2, Oracle, IMS, and VSAM databases are available from Sybase. If you use non-Adaptive Server data servers, you must provide a replication agent for them. Refer to the Replication Server Design Guide for details.

• Error classes and error processing actions

Error classes allow you to tailor your system to handle database errors for a type of data server. You can specify error actions in response to errors that a data server returns to Replication Server. Replication Server provides a default error class for Adaptive Server. See Chapter 15, “Handling Errors and Exceptions” for details.

• Functions, function strings, and function-string classes

Replication Server uses function strings to format replicated operations correctly for a type of destination database. To aid Replication System Administrators, Replication Server groups all the function strings for a particular type of database into a function-string class.

Warm Standby Applications

18

Replication Server provides default function-string classes for Adaptive Server, Informix, Oracle, Microsoft SQL Server, Adaptive Server Anywhere, IMS, VSAM, and DB2 databases. You can customize function strings to execute commands appropriate for your database and application. See Chapter 12, “Customizing Database Operations” for details.

Warm Standby ApplicationsWarm standby applications are used to maintain a pair of databases, one of which functions as a standby copy of an active database. As clients update the active database, Replication Server copies transactions to the standby database, maintaining consistency between the two. Should the active database fail for any reason, you can switch to the standby database, making it the active database, and resume operations with little interruption.

Active and standby databases, which must be Adaptive Server or SQL Server databases, must be managed by the same Replication Server.

A warm standby application, which is considered a single logical unit in a Replication Server system, can act as either a primary or replicate database with respect to other databases in the system. It can also act as a standalone Replication Server application.

The way you set up a warm standby application differs from the way you set up a Replication System using any of the models. Refer to Chapter 13, “Managing Warm Standby Applications” for detailed information.

Mixed-Version Replication SystemsA replication system can include Replication Servers or Adaptive Servers of different versions. Each program presents different issues.

You can use Replication Server version 11.5 with earlier versions of Replication Server. In earlier versions, all Replication Servers had to be at the same version before you could set the system version and enable certain features. Now, this restriction has been relaxed for systems running Replication Server version 11.0.2 and higher.


19

• When all Replication Servers are at least version 11.0.2 and the system version is set to 11.0.2, each Replication Server uses features according to its site version. Replication Servers running version 11.5 can use all 11.5 features among themselves, while Replication Servers running 11.0.2 can only use 11.0.2 features. Such a system is called a mixed-version system; each Replication Server can use all of its features.

See “Restrictions in Mixed-Version Systems” on page 19 for more information.

• If the replication system includes Replication Servers prior to version 11.0.2, then the system version number must be set to match the Replication Server with the earliest software version, for example 11.0.1 or 10.1.1. Certain new features that were introduced in later versions, including features of version 11.5, will not be available to any Replication Server. Such a replication system is not called a mixed-version system, because new feature use is restricted.

Restrictions in Mixed-Version SystemsInteraction between Replication Servers of different versions is restricted to the capabilities of the oldest version. Information associated with new features may not be available to Replication Servers of earlier versions.

See the documentation for each feature introduced in a new version, such as function-string inheritance or multiple replication definitions, for additional information about usage restrictions in mixed-version environments.

Refer to the installation and configuration guides and the release bulletin for your platform for more information about mixed-version systems and about setting the site version and system version.

Mixed Versions of Adaptive ServerYou can use Replication Server version 12.0 with different versions of Adaptive Server and SQL Server. Although you can use data sources and destinations other than Adaptive Server, Replication Server requires Adaptive Server or SQL Server for warm standby databases and for Replication Server System Databases (RSSDs).

Replication System Security

20

Some capabilities of Replication Server version 12.0, such as support for Sybase Failover in high availability systems require you to use an Adaptive Server version 12.0 or later.

If you are using SQL Server version 11.0.x or earlier, you must use an LTM program for SQL Server instead of a RepAgent thread, and you cannot use schema replication in a warm standby application.

See “Managing RepAgent” on page 96 for more information about RepAgent; see Appendix B, “LTM for SQL Server” for details about LTM software. Also refer to the installation and configuration guides and the release bulletin for your platform for more information about using Adaptive Server with Replication Server.

Replication System SecurityReplication Server provides for careful management of the login names, passwords, and permissions that are essential for system security. In addition, Replication Server supports third-party security mechanisms that safeguard data transmission across the network.

See Chapter 7, “Managing Replication Server Security” for more information about security.

Replication Server Security FeaturesReplication Server enforces security using the following features:

• Replication Server login names

Each Replication Server has its own set of login names, which are distinct from data server login names. This distinction gives the Replication System Administrator control over replicated data and other aspects of the replication system.

• Data server login names

Data server login names are used with client applications to connect to data servers. Clients are generally given permission to update primary data. On replicate tables, however, clients are generally granted permission to select or view data, but are prohibited from making changes to data. These permissions are controlled in the data server, according to the application.


21

• Data server maintenance user login names

Replication Server uses a special data server maintenance user login name for each local data server database that contains replicate tables. This allows Replication Server to maintain and update the replicate tables in the database.

• Password encryption

You can encrypt passwords in sensitive areas of the replication system.

• Permission system

Replication Server permissions are assigned to and rescinded from Replication Server login names using the grant and revoke commands.

See “Replication Server Roles and Responsibilities” on page 22 for more information about Replication Server and data server login names and roles.

Network-Based Security FeaturesReplication Server supports third-party, network-based security mechanisms that can:

• Establish unified logins to servers on the network

The security mechanism authenticates users at login. Each authenticated user is given a security credential that can be presented to remote servers as needed. As a result, users can seamlessly access different servers using a single login.

• Ensure secure data transmission across the network

A choice of different data protection services can:

• Encrypt and decrypt data transmissions

• Verify that a transmission has not been tampered with

• Verify the origin of each transmission

• Verify that a transmission has not been captured and re-sent

• Verify that transmissions are received in the order sent

See “Managing Network-Based Security” on page 183 for more information about establishing network security.

Replication Server Roles and Responsibilities

22

Replication Server Roles and ResponsibilitiesAdministering the replication system is primarily the role of the Replication System Administrator. The Database Administrator plays a subsidiary role by supporting some Replication Server administration tasks. At some sites, role distinctions may not be clear-cut and some responsibilities can overlap. The following sections describe user roles and Replication Server tasks.

Replication System AdministratorThe Replication System Administrator installs, configures, and administers the replication system. On a WAN, this role may be performed by different people at different locations. If this is the case, various tasks for administering Replication Server may require coordination between Replication System Administrators.

The Replication System Administrator has sa user permissions, which provide that person with the ability to execute nearly all commands in the replication system. In managing the system, the Replication System Administrator may need to coordinate with Database Administrators for both local and remote databases.

Database AdministratorThe Database Administrator is responsible for:

• Administering local data servers, including login names and permissions.

• Managing data in a distributed database system. Various tasks may require coordination between Database Administrators for different databases.

Replication Server Tasks and ResponsibilitiesTable 1-1 lists the tasks required to maintain the replication system.


23

Table 1-1: Replication Server tasks and responsibilities

Task and Reference Roles

Installing Replication Server. Refer to the Replication Server installation and configuration guides for your platform.

Replication System Administrator (RSA), Database Administrator (DBA)

Starting up and shutting down Replication Server. See Chapter 4, “Managing a Replication System”

RSA

Quiesing Replication Server. See Chapter 4, “Managing a Replication System” RSA, DBA

Adding login names, database users, and administering appropriate permissions. See Chapter 7, “Managing Replication Server Security”

RSA, DBA

Monitoring Replication Server. See Chapter 4, “Managing a Replication System” RSA

Configuring Replication Server. See Chapter 4, “Managing a Replication System” RSA

Adding replicated tables and stored procedures or changing table schemas.

• Creating and modifying replicated tables and stored procedures.

• Creating and modifying table and function replication definitions.

• Creating and materializing subscriptions at replicate sites.

See Chapter 8, “Managing Replicated Tables” Chapter 9, “Managing Replicated Functions” and Chapter 10, “Managing Subscriptions”

RSA, DBA

Defining data server function-string classes and function strings. See Chapter 12, “Customizing Database Operations”

RSA, DBA

Maintaining routes.

• Creating and modifying routes.

See Chapter 5, “Managing Routes”

RSA

Maintaining and monitoring database connections.

• Suspending and resuming connections.

See Chapter 6, “Managing Database Connections”

RSA

Creating a warm standby application. See Chapter 13, “Managing Warm Standby Applications”

RSA, DBA

Localizing Replication Server. Refer to the Replication Server Design Guide. RSA

Adding a primary or replicate database. See Chapter 6, “Managing Database Connections” RSA, DBA

Adding or removing a Replication Server. See Chapter 4, “Managing a Replication System” RSA

Processing rejected transactions. See Chapter 15, “Handling Errors and Exceptions” RSA, DBA

Administering local data server.

• Suspending or resuming data server.

See Adaptive Server or local server documentation

DBA

Managing the RSSD. See Chapter 4, “Managing a Replication System” RSA, DBA

Creating, deleting, and modifying databases for replication. See Adaptive Server or local server documentation.

DBA

Replication Server Roles and Responsibilities

24

Setting up database user login names and passwords. See Adaptive Server or local server documentation.

DBA

Performing regular backups. See Chapter 11, “Verifying and Monitoring Replication Server”

DBA

Applying database recovery procedures. See Chapter 16, “Replication System Recovery” RSA, DBA

Reconciling database inconsistencies. See Chapter 10, “Managing Subscriptions” RSA, DBA

Task and Reference Roles

25

C H A P T E R 2 Replication Server Technical Overview

This chapter provides a technical overview of Replication Server and the replication system.

This chapter introduces the components of a distributed database system based on Replication Server and illustrates the movement of transactions from a primary database to a replicate database. It also identifies the aspects of Replication Server that play a role in receiving and distributing data at primary and replicate sites.

This chapter can aid in diagnosing and troubleshooting replication system problems.

Replication System ComponentsThis section describes the components and resources that must be present or assembled before you can run Replication Server. Refer to the Replication Server Design Guide for component requirements and performance considerations of different replication topologies.

Figure 2-1 illustrates a simple configuration for a WAN-based distributed database system based on Replication Server.

Replication System Components

26

Figure 2-1: Replication system components

Table 2-1 lists the replication system components.

Table 2-1: Replication system components

Primary

ClientApplication

(or other data server)Adaptive Server

ReplicateReplication Server

Replicate

(or other data server)Adaptive Server

ClientApplication

Primary Site Replicate Site

RSM Server Domain

RSM Server

Sybase Central

with RSM Client

WANPrimary

Replication Server

ComponentRequired/ Optional Description

Replication Server Required Coordinates data replication with local databases and exchanges messages with other Replication Servers. Includes ID Server.

CHAPTER 2 Replication Server Technical Overview

27

Each component uses the Open Client/Server Interface to communicate with other components.

The remainder of this section describes each component.

Replication Server

Replication Server coordinates data replication activities for local databases and exchanges data with Replication Servers that manage data at other sites. A Replication Server:

• Receives transactions from primary databases and distributes them to subscribing replicate databases

• Receives requests for data updates from a replicate database and applies them to a primary database

See “Replication Server Internal Processing” on page 477 for more information about the internal elements of the Replication Server.

ID Server

The ID Server is a Replication Server that registers all Replication Servers and databases in the replication system. The ID Server must be running each time a:

• Replication Server is installed

• Route is created

• Database connection is created or dropped

Data Source Required Adaptive Server, SQL Server, or other data server. Includes:

• Replication agent

• RSSD (Adaptive Server or SQL Server)

Client Applications Optional Update primary database, query replicate database.

Sybase Central Recommended Includes Replication Server Manager client and server components.

ComponentRequired/ Optional Description


28

Because of this requirement, the ID Server is the first Replication Server that you start when you install a replication system.

The ID Server must have a login name for Replication Servers to use when they connect to the ID Server. The login name is recorded in the configuration files of all Replication Servers in the replication system by the rs_init configuration program.

See Chapter 4, “Managing a Replication System” for information about the configuration file.

Replication System Domain

Replication system domain refers to all replication system components that use the same ID Server. You can set up multiple replication system domains, with the following restrictions:

• Replication Servers in different domains cannot exchange data. Each domain must be treated as a separate replication system with no cross-communication between them. You cannot create a route between Replication Servers in different domains.

• A database can be managed by only one Replication Server in one domain. Any given database is in one, and only one, ID Server’s domain. This means that you cannot create multiple connections to the same database from different domains.

See “Adding a Replication System Domain” on page 90 for guidelines and restrictions on adding multiple system domains.

Adaptive Server or Other Data Server

Adaptive Server manages databases containing either primary or replicate data. Client applications use Adaptive Server to store and retrieve data and to process transactions and queries.

Each Replication Server requires an Adaptive Server database for its Replication Server System Database (RSSD), which contains the Replication Server system tables.


29

Replication Server also supports heterogeneous data servers through an open interface. You can use any system for storing data if it supports a set of required basic data operations and transaction processing directives. For data servers that contain primary databases, you must use a compatible replication agent program.

See Chapter 6, “Replicating Data into Foreign Data Servers,” in the Replication Server Design Guide for details on heterogeneous data server support.

Replication Agent

A replication agent notifies Replication Server of actions in a primary database that must be copied to other databases. The replication agent reads the database transaction log and transfers log records for replicated tables and stored procedures to the Replication Server managing the database, which distributes the modifications to databases that subscribe to the data.

A replication agent is needed for every database that contains primary data and for every database where stored procedures that need to be replicated are executed. A database that contains replicated data and no stored procedures marked for replication does not require a replication agent.

Replication agents communicate with Replication Server by executing commands in Log Transfer Language (LTL).

See Chapter 5, “Creating a Replication Agent,” in the Replication Server Design Guide for more information about LTL commands.

Which Replication Agent For Your System?

The replication agent you use depends on the data servers in your replication system. Supported replication agents are:

• RepAgent – for Adaptive Server data servers. RepAgent, a thread in Adaptive Server, is the replication agent described in this book.

• Log Transfer Manager (LTM) – for SQL Server data servers. Refer to Appendix B, “LTM for SQL Server” and the Replication Server Administration Guide for Replication Server version 11.0 for information about the LTM.

• Replication Agents for foreign data servers:

• SQL Anywhere

• Lotus Notes


30

• DB2

• Oracle

• IMS

• VSAM

Refer to the Sybase documentation for these products for more information. Refer also to the release bulletin for your platform for a list of all supported replication agents for this version of Replication Server.

You also can create a replication agent to replicate data from a foreign data server. Refer to Chapter 5, “Creating a Replication Agent,” in the Replication Server Design Guide for details.

Replication Server System Database (RSSD)

The Replication Server System Database (RSSD) is an Adaptive Server database that contains the Replication Server system tables. Each Replication Server requires an RSSD and each RSSD holds the system tables for one Replication Server. The Adaptive Server that manages the RSSD can also manage client databases.

System Tables

The Replication Server system tables are loaded into the RSSD during Replication Server installation. System tables hold information that Replication Server requires to send and receive replicated data, and include:

• Descriptions of replicated data and related information

• Security records for Replication Server users

• Routing information for other sites

• Access methods for the local databases

• Other administrative information

See Chapter 8, “Replication Server System Tables,” in the Replication Server Reference Manual for a comprehensive list of system tables.

System table contents are modified during Replication Server activities, such as the execution of RCL commands or Sybase Central procedures. Only the Replication System Administrator, or members of the rs_systabgroup group, can alter the system tables.

To query the system tables and find status information:


31

• Use Sybase Central to view replication system details and properties. See the Replication Server online help in Sybase Central.

• Use Replication Server’s system information or system administration commands. See “System Information Commands” and “System Administration Commands” in Chapter 1, “Introduction to the Replication Command Language,” in the Replication Server Reference Manual.

• Use Adaptive Server stored procedures to display information about the replication system. See Chapter 5, “Adaptive Server Commands and System Procedures” in the Replication Server Reference Manual.

Warning! RSSD tables are for internal use by Replication Server only. You should never modify RSSD tables directly unless directed by Sybase Technical Support.

RSSD and Replication Agent Specifications

The RSSD is dedicated to the Replication Server that it supports; do not use it to store user data. However, a single data server may contain the RSSD and user databases. The database device space for the RSSD must be at least 20MB (10MB for data and 10MB for the log). It is best to put the database and the database log on separate devices.

A replication agent is needed for the RSSD if the Replication Server is the source for any route. If this is true, Replication Server distributes some of the information in its RSSD to other Replication Servers. See Chapter 5, “Managing Routes” for more information.

Client Applications

A client application is a program that accesses a data server. When the data server is Adaptive Server, applications can be programs created with Open Client Client-Library™ or DB-Library™, Embedded SQL™, APT Workbench™, or any other front-end development tool that is compatible with the Open Client/Server Interfaces such as PowerBuilder®. Open Client/Server includes routines and protocols for client/server communications.


32

In a simple replication system, clients update primary databases and Replication Server updates replicate databases. By replicating stored procedures, clients can update primary data from any replicate database.

Sybase Central

Sybase Central is a graphical administration tool that uses a Replication Server Manager (RSM) client application to connect to an RSM Server. The RSM Server is an Open Server application that translates and responds to requests from Sybase Central and monitors and responds to replication system events.

With its easy-to-use interface, Sybase Central allows you to perform many administrative tasks that you would otherwise use RCL commands to perform, including:

• Managing and monitoring the Replication Servers, data servers, and replication agents that make up a replication system

• Managing replication system objects, such as users, routes, connections, replication definitions, and subscriptions.

• Managing replication agents and heterogeneous servers

• Performing diagnostics to troubleshoot the system

• Receiving automatic notification or programmed response to system events

For a list of tasks that you can perform in Sybase Central, see the Replication Server online help topic “Tasks and Concepts.”

Note Sybase Central is available only on the Windows NT and Windows 95 platforms.


33

Specifying Data for ReplicationReplication Server uses the relational database model to represent data in tables that have a fixed number of columns and a varying number of rows. Each table you want to replicate must have one or more columns that can be used as a primary key to uniquely identify each row.

Replication Server lets you define the data and stored procedures that you want to replicate at remote databases, as well as letting you specify the destination databases themselves. As part of design and planning, you designate source and destination databases for your replication system and create the routes that replicated data follows from one Replication Server to another.

In general, a source database contains primary data and may be called the primary database, while a destination database contains replicate data and may be called the replicate database. Depending on your implementation, the same database may contain both primary and replicate data. Transactions or stored procedure executions are replicated from primary to replicate databases. Stored procedure executions may also be replicated from replicate to primary databases.

See “Replication Server’s Basic Primary Copy Model” on page 5 for details.

Replication Definitions and Subscriptions for TablesYou create one or more replication definitions to describe each primary (source) table. A replication definition lists a table’s columns and datatypes, the columns that make up the primary key, the columns that can be used in subscribing to the primary data, and specifies the location of the primary version of the table.

A replication definition may include additional settings to let you customize how you will use it. For example, you can create a replication definition just for replicating into a standby database in a warm standby application. Or, see Chapter 8, “Managing Replicated Tables” for more information.

You then create subscriptions for transactions on the data defined in the replication definition. A subscription instructs Replication Server to copy transactions for all rows or for qualifying rows only. Copies of a table can be limited to only the rows or columns needed.

Specifying Data for Replication

34

Typically, creating a subscription causes Replication Server to copy the initial requested data from the primary database to the replicate database. This process is called subscription materialization. Once the subscription is created and materialized, Replication Server begins distributing database operations for the primary data as they occur. See Chapter 10, “Managing Subscriptions” for details.

Replication Definitions for Stored ProceduresFor certain operations, replication of stored procedures may offer significant performance improvements over table replication. In addition, you can replicate stored procedures to update data from a replicate database to a primary database. A replication definition of a stored procedure is called a function replication definition.

Benefits of Replicated Functions Over Normal Replication

Adaptive Server logs a record for each row modified by a Transact-SQL command. When a single Transact-SQL command modifies multiple rows, Replication Server treats each log record received from the replication agent as a separate command in the transaction. For example, to replicate the results of a single update command that modifies 1000 rows in the primary database, Replication Server may execute 1000 update commands in each replicate database.

Commands that modify many rows can affect performance of replicate Adaptive Servers and the replication system. The volume of rows delivered through the replication system may use all available space in stable queues.

If an application updates multiple rows in a primary table, you can use replicated stored procedures to maintain data in destination databases. Because commands in stored procedures can modify multiple rows, using stored procedures allows you to update rows in replicate databases without passing images of the rows through the replication system. Only a single record reflecting stored-procedure execution and its parameters replicates through the system.

Using Replicated Functions

A function replication definition describes a replicated stored procedure and includes:


35

• The parameters and datatypes

• The location of the primary data that the stored procedure may modify

• Parameters that can be used in subscribing to stored-procedure executions

• The name of the stored procedure to execute at the destination database

Function replication definitions can be delivered to primary or replicate databases. There are two types of replicated function delivery:

• Applied – executed at primary databases first and affect primary data. Replication Servers propagate the stored procedure and its parameters, applying data changes asynchronously at replicate sites that have subscriptions for a function replication definition.

• Request – executed at replicate databases to modify data in primary databases. Request functions also have function replication definitions, although no subscriptions are required because requests are always carried out at the primary site.

Typically, request delivery is used by a remote application to modify primary data asynchronously. The changes are replicated back to the originating replicate site via either normal data replication or applied function delivery.

See Chapter 9, “Managing Replicated Functions” and Chapter 10, “Managing Subscriptions” for details.

PublicationsA publication lets you collect replication definitions for related tables and stored procedures and then subscribe to them as a group. You create publications at the primary Replication Server and subscribe to them at the destination Replication Server.

When you use publications, you create and manage these objects:

Article – identifies a replication definition, primary database, and publication. It may also limit the number of rows or parameters sent to the replicate database.

Publication – a collection of articles from a primary database.

Publication subscription – a subscription to a publication. When you create a publication subscription, Replication Server creates a subscription for each article in the publication.

Specifying Data for Replication

36

Publications allow you to group replication definitions and subscriptions in a manner that makes sense for your system. It also allows you to create and check the status of only one subscription for a set of tables and procedures.

Overview of Replicating TablesThis section summarizes how to replicate transaction data between a primary (source) and destination table. For more details, see “Marking Tables for Replication” on page 238 and “Subscription Example” on page 338.

• At the destination data server: Create a copy of a table into which data will be replicated from the primary table. The copy may contain all or a subset of the columns from the primary table.

At the primary Replication Server: Create a replication definition to identify the table data you want to replicate. You can create one or more replication definitions per table that can be replicated into different destination databases. You can also create replication definitions for stored procedures. See Chapter 9, “Managing Replicated Functions” for details.

Once you have created a replication definition, transactions are available for replication to qualifying destination Replication Servers that subscribe to the replication definition.

You can create a set of articles that reference replication definitions and group them in a publication. If you want to limit the transactions sent to the destination database to those that affect certain rows, use a where clause in the article.

• At the primary Adaptive or SQL Server: Use the sp_setreptable system procedure to mark a table as replicated.

When you mark a table as replicated in the primary data server, the replication agent for the primary database can forward the table’s transactions to the primary Replication Server.

If you want to replicate text or image columns, you may also need to use the sp_setrepcol system procedure.

If you use a different data source with a replication agent, refer to your replication agent documentation for information about marking primary objects for replication.


37

• At destination Replication Servers: Create a subscription for replication definitions that were created in primary Replication Servers. A subscription allows the destination table to receive the initial data from the primary (source) table through a process known as materialization, and to begin receiving subsequent replicated data updates.

You can create multiple subscriptions for each replication definition, but a replicate table can subscribe to only one replication definition. You can set up a subscription to receive all transactions for a destination table, or use a where clause to receive just the transactions that affect certain rows.

Create publication subscriptions for publications created at the primary Replication Server. When you do so, Replication Server creates an article subscription for each article in the publication.

Creating subscriptions completes the process of replicating data. See Chapter 10, “Managing Subscriptions” for details.

Commands for Managing Replicated DataRefer to the following resources for detailed information about each command used to manage replicate data:

• Replication Server online help lists tasks and concepts for working with table replication definitions, function replication definitions, and subscriptions in Sybase Central.

• Table 8-1 on page 220 lists the Replication Server commands for working with table replication definitions.

• Table 9-1 on page 297 lists the Replication Server commands for working with function replication definitions.

• Table 8-3 on page 273 lists the Replication Server commands for working with publications.

• Table 10-3 on page 327 lists the Replication Server commands for working with subscriptions.

• Table 10-5 on page 351 lists the commands for working with publication subscriptions.

Establishing Replication Server Connections

38

Establishing Replication Server ConnectionsReplication Server uses the Open Client/Server Interfaces to communicate between client applications and servers.

Server programs, including Replication Servers, Adaptive Servers, and gateway software for other data servers, are registered in an interfaces file so that client applications and other server programs can locate them.

Note If you are using network-based security, available with version 11.5, use the directory services of your network security mechanism to register Replication Servers, Adaptive Servers, and gateway software. Refer to the documentation that comes with your network-based security mechanism for details.

Interfaces FileThe interfaces file contains network definitions for servers in the replication system, including Replication Servers and data servers.

Note If you are using the LTM as your replication agent, it requires an entry in the interfaces file. See Appendix B, “LTM for SQL Server” for details. Replication Server version 11.5 used with Adaptive Server uses the RepAgent thread, which does not require an entry in the interfaces file.

Generally, one interfaces file at each site contains entries for all local and remote Replication Servers and data servers. The entry for each server includes its unique name and the network information that other servers and client programs need to connect with it. The interfaces file at a site requires entries for these components:

• ID Server (if Replication Server is not also the ID Server)

• Replication Server

• RSSD Adaptive Server for this Replication Server

• Data servers with databases managed by this Replication Server

• Backup Server™ to back up Adaptive Server databases, including RSSDs (for SQL Server version 10.0.1 or later)


39

• Replication Servers at other sites that manage databases containing primary data that is replicated to this site

• Replication Servers at other sites with subscriptions for primary data maintained at this site

• Other Replication Servers to which this Replication Server has a route with no intermediate Replication Servers

You can use the default interfaces file or you can specify an alternative interfaces file at the command line when you start Replication Server. The interfaces file is usually located in the Sybase release directory. Use the ds_edit program to modify the interfaces file. Refer to the Replication Server installation and configuration guides for your platform for more information.

Making Replication Server ConnectionsTo connect data servers and Replication Servers at the sites on a LAN or WAN, the Replication System Administrator at each site defines connections and routes.

Organizing connections and routes is fundamental in planning replication. The connections and routes you establish determine the number of Replication Server components you need. In addition, how you map replication between source and destination databases can impact system performance and data availability.

To specify where data is copied requires that you create the following paths or message streams between Replication Servers and between Replication Servers and databases in the system:

• A connection from a Replication Server to a database

Replication Servers distribute transactions received from primary databases through connections to the replicate databases they manage. A Replication Server may have connections to several databases, but each database can have only one connection from a Replication Server.

Warm standby applications also use a logical connection, which represents both a database and its standby database.

• A route from a Replication Server to another Replication Server

From each source Replication Server that manages databases containing primary data, you must specify a route to each destination Replication Server that subscribes to the data.

Establishing Replication Server Connections

40

You can specify a direct route from a source Replication Server to a destination Replication Server, or an indirect route, with intermediate Replication Servers between the source and destination Replication Servers.

Figure 2-2 depicts an enterprise with several locations in Europe. A New York Replication Server routes all information for Europe through the London Replication Server. This arrangement reduces the number of direct connections the New York Replication Server makes and reduces WAN traffic. Data is sent once from New York to London, rather than from New York to each European location. The London Replication Server distributes the replicated data to the other European locations.

Refer to the Replication Server Design Guide for details and rules on designing routes and connections for a replication system.

See Chapter 5, “Managing Routes” and Chapter 6, “Managing Database Connections” for guidelines and procedures on when and how to create routes and connections.

See Chapter 13, “Managing Warm Standby Applications” for more information about logical connections.


41

Figure 2-2: Routes and connections

Specifying Database OperationsReplication Server distributes database operations from a primary database to destination Replication Servers as functions that consist of a name and a set of data parameters. The destination Replication Server then uses function strings to map functions to the commands recognized by the destination data server. These commands represent transaction-control directives (begin transaction or commit transaction) or data-manipulation instructions (insert, update, or delete). The function string serves as a template or meta-command that transforms a function to a data-server-specific command. The use of function strings makes it possible for a primary site to replicate data to multiple heterogeneous data servers. Function strings are categorized into function-string classes according to data server type.

New York

London Intermediate

Rome Bonn

Source Replication Server

DestinationReplication

Servers

Connection Indirect routeDirect route

Replication Server

Specifying Database Operations

42

For example, a primary Replication Server transmits the rs_insert function to a destination Replication Server, which uses the appropriate function string to translate the function into the insert command specific for the data server in use at that site, whether the database is Adaptive Server, DB2, or another database.

There are two types of functions:

• System functions – represent data-server operations with function strings supplied by Replication Server or available when you install a new database to the replication system.

• User-defined functions – allow you to customize Replication Server applications to distribute stored procedures.

See Chapter 12, “Customizing Database Operations” for details.

Function StringsFunction strings for functions can be automatically generated for function-string classes that come with Replication Server. Function strings must be customized for any function-string class that the user creates that does not inherit its functions strings from one of the provided classes. To customize a function string, you modify an existing function string with data-server-specific commands or by invoking a remote procedure call (RPC). A customized function string can also contain function string variables that represent the values of columns, procedure parameters, system-defined information, and user-defined variables. Replication Server replaces the variables with actual values before sending function strings to the data server.


Function-String ClassesA function-string class comprises all of the function strings used with a type of database. Replication Server provides three function-string classes: two for Adaptive Server and one for DB2. Although function strings may contain data-server-specific instructions, they can often be used with several databases maintained by the same data server type. You can create classes with all new function strings or create a derived class that inherits function strings from an existing parent class.


43

Transaction Handling with Replication ServerReplication Server depends on data servers to provide the transaction-processing services needed to protect stored data. To ensure the integrity of distributed data, data servers must comply with the following transaction-processing conventions:

• A transaction is one unit of work. Either all operations in the transaction are performed or none are performed.

• Transaction results are permanent. A transaction cannot be arbitrarily undone after it is committed.

Replication Server copies committed transactions from primary sites to destination sites. It distributes transactions in the order they are committed so that copied data passes through the same states as the primary (source) data.

Figure 2-3 illustrates Replication Server’s method for translating transactions.

Figure 2-3: Translating transactions

Once the primary Replication Server sends transactions to subscribing sites, destination Replication Servers store the transactions in the outbound Data Server Interface (DSI) stable queue.

LTL

Transact-SQLFunction strings

Messages

Primary Replication Server

Destination

DestinationReplication Server

Data Server

Stable Queues

Outbound DSI

PrimaryData Server

Transaction Handling with Replication Server

44

Stable QueuesWhen you install Replication Server, you set up a disk partition that Replication Server uses to establish stable queues. During replication operations, Replication Server temporarily stores updates in these queues. You can add more partitions later if your replication system requires more space for stable queues.

There are three types of stable queues, each of which stores a different type of data:

• Inbound queue – holds messages only from a replication agent. If the database you add contains primary data, or if request stored procedures are to be executed in the database for asynchronous delivery, Replication Server creates an inbound queue and prepares to accept messages from a replication agent for the database.

• Outbound queue – holds messages for a replicate database or a replicate Replication Server. There is one outbound queue for each of these destinations:

• For each replicate database managed by a Replication Server, there is a Data Server Interface (DSI) outbound queue.

• For every Replication Server to which a Replication Server has a route, there is a Replication Server Interface (RSI) outbound queue.

• Subscription materialization queue – holds messages related to newly created or dropped subscriptions. This queue stores a valid transactional “snapshot” from the primary database during subscription materialization or from a replicate database during dematerialization.

See “Partitions for Stable Queues” on page 46 for physical queue requirements.

See the Replication Server’s online help topics in Sybase Central and the Replication Server Troubleshooting Guide for information on how to examine queue contents for troubleshooting purposes.

Queue Management

Each queue is managed by a Stable Queue Manager (SQM) thread. Threads are subprocesses that manage specific tasks, such as receiving messages. Some queues also have an additional Stable Queue Transaction (SQT) thread. See “Processing in the Primary Replication Server” on page 478 for details on the SQM and SQT threads.


45

When transactions are ready to leave the stable queue, one of following threads submits the transactions in the queue:

• Data Server Interface (DSI) thread – manages the connection with the data server.

• Replication Server Interface (RSI) thread – manages the connection with the replicate Replication Server

DSI Thread

The DSI thread translates the transaction modifications into RPCs or the language as specified by the function strings in the function-string class assigned to the destination database.

Replication Server starts DSI threads to submit transactions to a replicate database to which it has a connection.

The DSI thread performs the following tasks:

• Collects small transactions into groups by commit order

• Maps functions to function strings according to the function-string class assigned to the database connection

• Executes the transactions in the replicate database

• Takes action on any errors returned by the data server; depending on the assigned error actions, also records any failed transactions in the exceptions log

To improve performance in sending transactions from a Replication Server to a replicate database, you can configure a database connection so that transactions are applied using multiple DSI threads. See “Using Parallel DSI Threads” on page 486 for a description of this feature.

The DSI thread may apply a mixture of transactions from all data sources supported by the Replication Server. The transactions are processed in the single outbound stable queue for the destination data server.

RSI Thread

RSI threads send messages from one Replication Server to another. There is one RSI thread for each destination Replication Server.


46

The primary Replication Server processes transactions, causing those destined for other Replication Servers to be written to RSI outbound queues. An RSI thread logs in to each destination Replication Server and transfers messages from the stable queue to the destination Replication Server.

When a direct route is created from one Replication Server to another, an RSI thread in the source Replication Server logs in to the destination Replication Server. When an indirect route is created, Replication Server does not create a new stable queue and RSI thread. Messages for indirect routes are handled by the RSI thread for the direct route. For more information, see “Establishing Replication Server Connections” on page 38.

Partitions for Stable Queues

Replication Server stores messages destined for data servers or other sites on partitions. It allocates the space in partitions to stable queues and operates in 1MB chunks called segments. Each stable queue holds messages to be delivered to another Replication Server or to a database.

The rs_init program assigns the initial partition to the Replication Server. Refer to the Replication Server installation and configuration guides for more information about working with partitions in rs_init.

The minimum initial partition is 20MB. You may need additional partitions, depending on the number of databases the Replication Server manages and the number of remote sites to which the Replication Server distributes messages. Larger partitions may also be necessary when subscriptions are initiated or when there are long-running transactions.

A Replication Server can have any number of partitions of varying sizes. The sum of the partition sizes is the Replication Server’s capacity for queued transactions.

Use the add partition command to assign additional partitions. Refer to “add partition” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for details on this command.

When choosing a partition for Replication Server, consider these guidelines:

• Replication Server partitions should be operating system raw partitions.

• Do not mount the partition for use by the operating system.

• Do not use the partition for any other purpose, such as storing file systems, maintaining swap space, or locating Adaptive Server devices.


47

• Allocate the entire partition to Replication Server. If you allocate just a portion of a partition for Replication Server, you cannot use the remainder for any other purpose.

• Do not allow any users read/write permissions on the partition unless the user is going to start Replication Server.

Using Disk Files for Stable Queues

Partitions can be either raw disk partitions, which is preferable, or operating system files. For Windows NT, all partitions must be operating system files. Where a choice is available, raw disk partitions provide the best recoverability, since disk writes to raw disk partitions are not buffered by the operating system.

To use a disk file for a partition, create the file before you execute the add partition command. You can create an empty file and set its permissions so that Replication Server can read and write to the file. Replication Server extends the file to the size you specify.

Distributed Concurrency ControlData servers that store primary data provide most of the concurrency control needed for the distributed database system. If a transaction fails to update a primary version of a table, the primary Replication Server does not distribute the update to other sites.

When a transaction succeeds in updating primary data, the Replication Server distributes the changes. Unless a failure occurs, the update succeeds at all sites with subscriptions to the data.

Transactions That Modify Data in Multiple Databases

A transaction that modifies primary data in more than one data server may require additional concurrency control. According to the transaction processing requirements, either all of the operations in the transaction must be performed, or none of them. If a transaction fails on one data server, it must be rolled back on all other data servers updated in the transaction.

If a multi-database transaction is replicated, updates to each database flow to replicate databases as independent transactions because there is one replication agent per database.


48

Failed Replicate Table Updates

A modification to primary data may fail to update a copy of the data at a subscribing site. The primary version is the “official” copy and updates that succeed there are expected to succeed at subscribing sites with copies.

If the updates do not succeed, one of the following reasons may explain why:

• Replicate and primary versions are out of sync following a system recovery and a loss has been detected.

See Chapter 16, “Replication System Recovery” for more information.

• The data server storing the copy of the table has constraints that are not enforced by the data server storing the primary version.

• The data server storing the copy of the table rejects the transaction due to a system failure, such as lack of space in the database or a full transaction log.

When a transaction fails, Replication Server records the transaction in an exceptions log for handling that is appropriate to the application. Replication Server offers error handling flexibility through its error action feature. This feature allows responses to data server errors based on your own defined configuration settings. For example, you can specify that transactions be retried at the site where they failed.

A client at each site must resolve transactions in the exceptions log, because the appropriate resolution is application-dependent. In some cases, you can automate the resolution by encapsulating the logic for handling rejected transactions in an intelligent application program.

Transaction Processing by the Replication AgentThe replication agent scans the database transaction log and sends transaction information to the Replication Server for distribution to subscribing databases.

This section describes transaction processing by Adaptive Server’s RepAgent thread. Other replication agents may work differently. For information about transaction processing in the LTM, refer to Appendix B, “LTM for SQL Server” or the Replication Server Administration Guide for Replication Server version 11.0.x.


49

Coordinating Adaptive Server Log Truncation

As long as there is space in the Adaptive Server database transaction log, Adaptive Server continues to process transactions. To prevent the log from filling up, it must be emptied (“truncated”) periodically. You can use the Adaptive Server dump transaction command or set the Adaptive Server trunc log on chkpt option to “on” so that the log truncates automatically.

Each primary database maintains primary and secondary truncation points in its database log. The primary truncation point marks the last log record Adaptive Server has finished processing. The secondary truncation point normally marks the log record that contains the begin transaction command for the oldest open transaction not yet fully applied by Replication Server. Replication Server stores a copy of the latest secondary truncation point in the rs_locater table of the RSSD.

RepAgent requests a new secondary truncation point when it has scanned a predetermined number (batch) of records or has reached the end of the log and there is no new activity. Replication Server acknowledges receipt of a batch of transaction records by giving RepAgent the information that allows it to move the secondary transaction point.

Adaptive Server makes sure that only transactions already processed and passed to the Replication Server are deleted by never truncating the log past the secondary truncation point.

RepAgent updates the secondary truncation point as shown in Figure 2-4.

Figure 2-4: Adaptive Server log truncation

Primary1. Request for new

truncation point

2. Truncation point

ReplicationServer

2. New truncation point

stored in rs_locatersystem table

3. RepAgent updates secondary truncation point

Dump tran

-----------------------------

New secondary truncation point

Previous secondary truncation point

-----------------------------

PrimaryAdaptive Server

4.Adaptive Servertruncates the logup to the newsecondary truncationpoint.


50

1 RepAgent requests a new secondary truncation point from the primary Replication Server.

2 The primary Replication Server returns the latest secondary truncation point to the RepAgent and also writes it into the rs_locater system table.

3 RepAgent updates the secondary truncation point in the transaction log.

4 At the next checkpoint or dump transaction command, the log is truncated up to the new secondary truncation point.

Schema information describes the structure of the database. Each time you change the schema of a database object—such as dropping a table, creating a clustered index, or renaming a column—Adaptive Server records current schema information for that object. Thus, when RepAgent scans the transaction log, it can always retrieve the correct schema for a table or procedure—even if the original database object has been changed or no longer exists. You do not need to drain the transaction log before executing schema changes at the primary site.

51

C H A P T E R 3 Managing Replication Server with Sybase Central

Sybase Central is a graphical tool that provides a common interface for managing Sybase and Powersoft® products. This chapter describes how to use Sybase Central with Replication Server version 11.5 and later.

With Sybase Central, you use a graphical interface to monitor the components of the replication system and perform Replication Server tasks you would otherwise use RCL commands to perform. Replication Server online help provides detailed instructions.

Note Sybase Central is available only on the Windows NT and Windows 95 platforms.

If you are unfamiliar with Sybase Central, see:

• “Using Online Help” ,

• “Using Windows and Dialog Boxes” ,

• “Using Menus and Toolbars” , and

• “Performing Common Tasks”

to become familiar with this product.

If you are already familiar with Sybase Central, see “Managing Replication Server” on page 70 for instructions specific to using Sybase Central with Replication Server.

The following section describes Sybase Central and the Replication Server Manager (RSM).

Replication System Management with Sybase Central

52

Replication System Management with Sybase CentralSybase integrates its systems management tools into one desktop product, Sybase Central, which users navigate using a central viewer. Each server product, such as Replication Server or Adaptive Server, is managed by a service provider “plug-in” that co-exists with other service providers in the Sybase Central framework.

Replication Server uses Replication Server Manager (RSM) as a Sybase Central plug-in. This Replication Server systems management front-end:

• Uses a graphical user interface (see Figure 3-1)

• Allows you to manage, monitor, and troubleshoot all replication system components

• Contains extensive online help that provides a quick reference for Replication Server concepts and tasks

Figure 3-1: Sybase Central

Replication Server ManagerRSM consists of:

CHAPTER 3 Managing Replication Server with Sybase Central

53

• An RSM Client (Sybase Central + the Replication Server plug-in): an Open Client application that lets you monitor, diagnose, and manage your replication system. The RSM Client includes a graphical user interface (GUI) integrated with Sybase Central.

• An RSM Server: an Open Server application that translates and communicates requests from an RSM Client. The RSM Server also monitors for and responds to replication system events.

Once you have installed and configured Replication Server and RSM Server software:

• Start Sybase Central and connect to an RSM Server.

• Set up a new RSM Server domain by adding the data servers, Replication Servers, and Sybase Replication Agents that you want the RSM Server to manage.

Note An RSM Server domain is the set of servers that a specific RSM Server can monitor and manage. The RSM Server domain is described by the server list in the RSM Server domain file. A domain typically contains the servers of a replication system and may also include other RSM Servers.

When you have connected to an RSM Server and have set up a domain, Sybase Central displays a two-paned window that contains icons for the servers managed by the RSM Server. (See Figure 3-1.) Use this window to monitor the status of the servers and to execute menu commands that let you diagnose and manage the servers and other components of your replication system.

From Sybase Central windows, you can manage geographically distributed components of a replication system, whether the servers in the system are local or distributed around the world.

The following sections describe:

• Using online help

• Stopping and starting Sybase Central

• The user interface

• Performing common tasks

• Using RSM to manage Replication Server

For a list of tasks that you can perform using the Sybase Central Replication Server plug-in, see Table 3-3 on page 76 and Table 3-4 on page 78.

Using Online Help

54

Using Online HelpOnline help is the primary documentation for the Replication Server plug-in to Sybase Central.

There are three types of help:

• Topic help

• Context-sensitive help

• Tooltips and status bar messages

This section describes each type of help and how to use it to access the information you want.

Topic HelpTopic help describes how to use Sybase Central to manage Replication Server. To display topic-level help, select Help from the Sybase Central main menu, then select “Replication Server Help” from the menu that displays.

You see the online help dialog box. See Figure 3-2.


55

Figure 3-2: Online help dialog box

The dialog box has three tabs: Contents, Index, and Find.

Contents Tab

Click the Contents tab to browse through topics by category.

• Book icons represent headings. Double-click a book icon to see the subentries under that heading. Subentries can be other book icons or page icons.

Headings are organized around Replication Server concepts (for example, Managing User, Monitoring a Replication System, and so on), similar to the Replication Server Administration Guide.

• Page icons represent topics that describe tasks or concepts that correspond to the heading under which they are listed. Topics are generally organized in the order that you would perform procedures under that heading. Double-click a page icon to display a topic.

Starting and Stopping Sybase Central

56

Index Tab

Click the Index tab to see a list of index entries. Type the word you’re looking for or scroll through the list.

Find Tab

Click the Find tab to search for words or phrases that a help topic may contain.

Context-Sensitive HelpContext-sensitive help provides field descriptions for dialog boxes and property sheets. To get help for a particular item, do one of the following:

• Click the Help button [ ? ] in the upper-right corner of the dialog box or property sheet, then click the item about which you want information. This opens a pop-up window that describes the item.

To close the pop-up window, click anywhere on the screen.

• If the dialog box doesn’t have the Help button, tab to the item (or place the cursor on the item) to make it active and press F1.

• Right-click the area you want help on, then click the What’s This? command.

Note To print or copy the information in a pop-up window, right-click inside the pop-up window, then click Print Topic.

TooltipsTooltips are small pop-up windows that provide a description of a control (that is, a toolbar button or menu option) when you move the pointer over that control.

Starting and Stopping Sybase CentralThis section explains how to start and stop Sybase Central.


57

Starting Sybase CentralStart Sybase Central using any of the standard methods for your Windows operating system, such as:

• From the Start menu, choose Programs→Sybase→Sybase Central.

• In the Sybase program group or folder, double-click the Sybase Central icon.

• Create a shortcut on your desktop for Sybase Central.

• Double-click scview.exe in the Sybase\Sybase Central\win32 directory.

• Add Sybase Central to your Startup program group.

Stopping Sybase CentralTo stop Sybase Central, select the File menu and choose Exit.

Using Windows and Dialog BoxesThis section discusses Sybase Central windows and dialog boxes as they apply to managing Replication Server.

Navigating the Sybase Central Main WindowThe Sybase Central main window allows you to access an RSM Server domain and server objects. This section describes the Sybase Central main window and how to:

• Move through the Sybase Central hierarchy

• Customize the display

• Use drag-and-drop shortcuts

Figure 3-3 shows the Sybase Central main window, which is similar to the Windows 95 Explorer.

Using Windows and Dialog Boxes

58

Figure 3-3: Sybase Central main window

The main window is split into left and right panes. When you are connected to an RSM Server and have set up an RSM Server domain:

• The left pane displays a hierarchical list, or object tree, which shows:

• Icons for Replication Server folders and objects in the RSM Server domain.

• Icons for other plug-ins (applications), such as the Sybase Central plug-in for Adaptive Server or dbQueue™ if they are installed.

• The right pane displays the contents of the folder or object selected in the left pane.

To adjust the size of the panes, drag the splitter bar to the left or right with the mouse pointer.

Folder and Object Icons

The main window includes folder icons and object icons:


59

• Each folder icon represents all objects of its type within an RSM Server domain. For example, the Publications folder shown in the rdb1 database (see Figure 3-3) represents all of the publications associated with rdb1. Folder icons can appear in either the left or right pane.

• Each object icon represents on server object, such as a database, a table, a replication definition, a route, and so on. Some objects contain other objects; for example, a publication contains articles, a database contains tables, and so on.

The left pane shows only objects that contain other objects. For example, the left pane may show a publication icon, but not the articles contained in the publication, which display in the right pane.

Selecting Objects

For most activities, you must select an object before you can perform any operation on it. To select an object, click its icon. The type of object selected determines the range of commands available.

Moving Through the Sybase Central Object Tree

To see different parts of the object tree, use the following techniques.

• To move vertically through the current display, use the scroll bar on the left or right pane.

• To expand or collapse the list to show different levels of detail, do one of the following:

• Click plus or minus buttons. A plus button next to an icon indicates that the list of objects for that icon can be expanded. A minus button indicates that the list of objects for the icon is fully expanded.

• Double-click a folder icon or its label.

Double-clicking a folder icon in the right pane also expands the list in the right pane and changes the view to a list of objects in the folder. For most objects, double-clicking an object icon in the right pane opens a property sheet that displays information about the object.

Figure 3-4 illustrates the Replication Server object tree within an RSM Server domain. The top level is the root of the Replication Server plug-in.

Using Windows and Dialog Boxes

60

Figure 3-4: Replication Server object tree

Customizing the Display

You can customize the Sybase Central window by selecting from several display formats.

Selecting Display Formats

To select the display format for the right pane, choose one of the following commands from the Display menu:

• Large Icon – shows each object as a large icon with its label underneath.


61

• Small Icon – shows each object as a small icon with its label next to it.

• List – lists objects.

• Details – lists objects and displays detailed information about each one. The details vary with the type of object.

Turning the Toolbar and Status Bar On and Off

To hide the toolbar or status bar, choose Toolbar or Status Bar from the View menu. To redisplay the toolbar or status bar, repeat the procedure.

Using Drag-and-Drop Shortcuts

A quick way to perform operations involving the interaction of two Replication Servers or database objects is to drag the icon for one object on top of an icon or folder for another object. When you drag and drop icons for supported operations, the application completes the operation if possible.

Drag-and-drop is limited to situations where the source object is visible in either the left or right pane and the target object can be viewed (either simultaneously or by scrolling the window) in the other pane.

To drag and drop an icon:

1 Place the cursor on top of an icon.

2 Press and hold the left mouse button.

3 Continuing to hold the button down, move the mouse to drag the icon on top of another icon.

As you drag the icon, a faint image of the icon travels across the screen, along with the illegal drop symbol (a circle with a diagonal line through it) that indicates that you cannot yet legally drop the icon. When the icon reaches its target location, the illegal drop symbol disappears, and you can release the mouse button (unless your intended target is illegal, in which case, you cannot complete the drag-and-drop operation).

Note To drag and drop an object within its folder (making a copy of it), hold down the Control key while you drag the object into empty space in the folder.

If you drag an object and the ghost image of the object has the illegal drop symbol on it, it is because the object is not in a place where it can do something.

4 Release the mouse button. Some tasks require confirmation, some do not.

Using Menus and Toolbars

62

Using Keyboard Shortcuts

In addition to using a mouse, you can use keyboard shortcuts to choose menu commands and complete dialog boxes.

Every menu title and most menu commands have an underlined letter, called a mnemonic. To select a menu, press Alt-mnemonic. To choose a menu command, press the mnemonic key. Some commands can be run directly by pressing Ctrl plus another key or by pressing a function key. These shortcuts are listed on the menus.

To navigate to different boxes and buttons in a dialog box or property sheet, use the Tab key. To select different tabs in a property sheet, use the Tab key to select the current tab, then use the left and right arrow keys to select other tabs.

Using Menus and ToolbarsThis section describes the Sybase Central menus and toolbar.

Standard MenusThe menu bar in the Sybase Central window contains the following menus:

• File

• Edit

• View

• Tools

• Help

The File menu is sensitive to the folder or object selected in the left pane. Menu commands change to meet the requirements of the object. When you highlight a menu command, a brief description of the command displays in the status bar at the bottom of the main window. Table 3-1 summarizes the activities to which the menus provide access.


63

Table 3-1: Activities available from standard menus

Shortcut (Pop-Up) MenusTo activate a pop-up menu, right-click the mouse over a folder icon or an object icon. From the menu that displays, choose the appropriate command.

Shortcut menus have the same commands as the File menu.

Toolbar and Status BarThe Sybase Central toolbar provides quick alternatives to executing frequently-used menu commands. The status bar (see Figure 3-3) displays helpful information about highlighted window controls and objects.

To display or hide the toolbar or status bar, toggle the Toolbar or Status Bar command on the View menu. When these menu commands have a check mark next to then, they are visible in the window.

Toolbar The toolbar has the following controls:

Menu Activities

File • Open folders or objects

• Create a new object

• Delete folders or objects

• Open an object’s property sheet

• Perform object-specific activities such as suspending a connection or viewing a server’s log file

• Exit Sybase Central

Edit • Cut, copy, or paste an object definition

• Select one or an entire group of objects

View • Hide or display the standard toolbar and status bar

• Select the format for displaying object icons in the right pane of the Sybase Central window

• Update the display with fresh data

Tools • Connect to or disconnect from an RSM Server or other Sybase Central plug-in

• Create a connection profile

• Manage plug-ins for Sybase Central

Help • Display online help for Sybase Central plug-ins

• Display the About dialog box for Sybase Central

Using Menus and Toolbars

64

• A drop-down list box that displays the hierarchy of the currently-selected object. You can select an object higher up in the hierarchy to change the focus of the main window.

• Buttons that provide a quick way to execute menu commands.

Figure 3-5 illustrates the toolbar. Table 3-2 describes the controls.

Figure 3-5: Sybase Central toolbar

Table 3-2: Toolbar controls

To help identify the buttons in the toolbar, Sybase Central displays a tool tip—a floating label that appears when the cursor rests over a toolbar button. To display a tool tip, place the cursor over a toolbar button; do not click the button.

Status Bar The status bar is an information display bar located at the bottom of the application window. In Sybase Central, the status bar displays a brief description of the menu command the cursor is pointing at. The help line appears on the left side of the status bar.

Control Function

Drop-Down Hierarchy

Displays the hierarchy of the currently-selected object. Allows you to jump to a higher point on the hierarchy without scrolling.

Connect Opens the New Connection dialog box so you can connect to another data server or Sybase Central application.

Disconnect Opens the Disconnect dialog box so you can choose a data server to disconnect from.

Up Moves the Sybase Central display up one level in the object hierarchy. For example, if the current focus is on a database, clicking this button moves the focus to the data server in which the database is located.

Properties Opens the property sheet for the selected object.

Delete Deletes the selected object.

Large Icon Displays objects in the right pane of the Sybase Central window using large icons.

Small Icon Displays objects in the right pane of the Sybase Central window using small icons.

List Displays objects in the right pane of the Sybase Central window as a list of object names, along with small icons.

Details Displays objects in the right pane of the Sybase Central window as a list of object names, along with details about each object. The information shown varies by object type.


65

Refreshing Window and Dialog Box DisplaysAs you work, information in open dialog boxes and the Sybase Central window can get unsynchronized. To update the contents of the main window or a dialog box, choose Refresh Folder or Refresh All from the View menu or press F5.

Performing Common TasksThis section describes how to do the following tasks common to most Sybase Central objects:

• Create an Object

• View an Object’s Properties

• Delete an Object

Create an ObjectUsers with the appropriate permissions can create new publications, subscriptions, routes, connections, and other Replication Server objects in Sybase Central.

To create an object:

1 Select the folder for the type of object you want to create.

2 From the File menu, choose New. From the cascading menu, choose the object name.

• If a wizard exists to help you create the object, the wizard dialog box opens. Respond to the wizard prompts.

• If no wizard exists, a property sheet displays; fill in the information for the new object.

Note Wizards are a special form of dialog box that walk you through a procedure. Each page of a wizard provides information or asks you to enter information or make a choice. The steps are described in text in the dialog box.

Performing Common Tasks

66

Shortcuts to Create a New Object

View an Object’s PropertiesAfter you create an object, it is represented by an icon in the right pane of the Sybase Central window when you select the folder that includes this type of object. You can display or update the object by opening its property sheet.

A property sheet contains information about the object and about how it relates to other objects in the RSM Server domain or replication system. The property sheet may also provide a direct navigation path to its related objects.

To view an object’s properties, open the property sheet for that object:

1 Select the icon of the object you want to view.

2 From the File menu, choose Properties.

Shortcuts to View an Object’s Properties

In the right pane, double-click the add object icon.

Place the cursor in an empty area in the right pane. Click the right mouse button. From the pop-up menu, choose New. From the cascading menu, choose the object name.

Double-click the object icon.

Select the object icon, then select the Properties toolbar button.


67

Using Property Sheet Tabs

Information about objects appears on multiple panels within property sheets. These panels are called tabs, referring to the row of tab-shaped controls across the top of the property sheet.

Figure 3-6: Property sheet tabs

The tabs vary according to the function of each object. To display a different tab, click on the tab control at the top of the property sheet.

Changing an Object’s Properties

Most objects have properties that can be changed. To change the properties of an object:

1 Open the property sheet for the object.

2 Select the tab with the property you want to change.

3 Change the property.

See the Replication Server online help in Sybase Central for instructions about changing specific properties.

Right-click over the object icon, then choose Properties from the pop-up menu.

Performing Common Tasks

68

Closing a Property Sheet

To close a property sheet and save any changes you have made, click OK. To close a property sheet without saving changes, click Cancel. A confirmation dialog box opens asking if you want to close the dialog box without saving the changes. Click Yes or No.

Navigating to the Properties of a Related Object

On many property sheets, you specify a relationship from the object you are viewing to another object.

For example, on the Create Replication Definition property sheet, there is a reference to the primary table associated with the replication definition. You can click the Properties button to open the property sheet for the specified table. This allows you to examine the table to be sure you want to create the replication definition.


69

Figure 3-7: Properties button

Delete an ObjectTo delete an object:

1 Select the icon of the object you want to delete.

2 From the File menu, choose Delete.

3 Confirm the deletion in the confirmation dialog box.

Managing Replication Server

70

Shortcuts to Delete an Object

Managing Replication ServerBefore you can use Sybase Central to manage and/or monitor a replication system, you must first complete the following tasks:

1 Install Replication Server, RSM Server, and Sybase Central software.

See the release bulletin and Replication Server Installation Guide for your platform.

2 Install the data servers you will use in your replication system.

See the installation guide for your specific data server.

3 Configure Replication Server using rs_init.

See the Replication Server Configuration Guide for your platform.

4 Configure an RSM Server for use by an RSM Client.


5 To upgrade from RSM Server version 11.5, you must use rsmsetup to upgrade the NT registry entries for this RSM Server.

Select the icon of the segment you want to delete, then select the Delete toolbar icon.

Click the right mouse button over the object you want to delete, then choose Delete from the shortcut menu.


71

To perform the upgrade, follow the directions for modifying an existing RSM Server configuration definition.

Note RSM Server version 12.0 upgrades RSM Server version 11.5 files automatically.

6 If you upgrade from Replication Server Manager (RSM) version 11.0, convert the RSM configuration files to a version 11.5 format.


7 If you upgrade from Replication Server version 10.1.x or 11.0.x to Replication Server version 11.5, upgrade the Replication Server System Database (RSSD) for that Replication Server before you add the Replication Server to an RSM Server domain.

If you upgraded from version 10.1.x, you must also upgrade all existing user databases managed by that Replication Server.


8 If is not already started, start the RSM Server.


9 Start Sybase Central (see “Starting Sybase Central” on page 57) and connect to a configured RSM Server (see “Connecting to an RSM Server” on page 72).

10 In Sybase Central, select the RSM Server, then choose File→Add Server to add the data servers and Replication Servers you want the selected RSM Server to manage.

See the Replication Server online help in Sybase Central for detailed instructions.

Connecting to RSM Server and Defining an RSM Server DomainBefore you can perform any Replication Server management activities in Sybase Central, you must connect to an RSM Server and establish an RSM Server domain.


72

Connecting to an RSM Server

Sybase Central must know the host name, port, and method of connection for any RSM Servers to which you want to connect. This information is stored in a sql.ini file. The sql.ini file is the equivalent of the interfaces file used with Replication Server on UNIX platforms. You can update the sql.ini file using a text editor or the dsedit utility.

If the RSM Client and the RSM Server run on different machines, the sql.ini file on the RSM Client machine needs entries only for the RSM Servers to which the RSM Client will connect. However, you may need or choose to add other server entries to the sql.ini on the RSM Client machine under certain circumstances:

• When you add servers (Replication Servers, data servers, LTMs, open servers, non-Adaptive Server data servers, Sybase Replication Agents, or RSM Servers) to an RSM Server domain in Sybase Central, entries in the sql.ini on the RSM Client machine are optional. However, if that sql.ini file does contain an entry for the server you want to add:

• The server name will be available from a drop-down list during the “Add Server” procedure.

• The user names and passwords you specify when you add the server will be validated as you enter them.

• When you add a Replication Server, the RSM Client will automatically receive the name of that Replication Server’s RSSD.

• When you view Replication Server queue data and when you create or drop partitions, the Replication Server must have an entry in the RSM Client machine’s sql.inifile.

For more information about sql.ini see the Replication Server Configuration Guide for Windows NT.

Note If you update sql.iniwhile Sybase Central is running, you need only to restart any wizard or reopen any dialog box in progress. It is not necessary to restart Sybase Central for the changes to take effect.

You can maintain multiple RSM Server connections simultaneously.

To connect to an RSM Server:

1 From the Tools menu, choose Connect, then select Sybase Replication Server from the list of Sybase Central plug-ins that displays.


73

The Logon dialog box opens.

2 In the User ID box, enter the login name you want to use to connect to an RSM Server.

3 In the Password box enter the password for the login.

4 Select an RSM Server from the Server Name drop-down list.

5 Click OK.

6 If the connection is successful, an RSM Server icon appears in the Sybase Central main window in the left pane.

After you establish a connection, the view includes an icon for the RSM Server.

Disconnecting from an RSM Server

To disconnect from an RSM Server in Sybase Central:

1 Select the RSM Server from which you want to disconnect.

2 Select Tools→Disconnect.

Establishing an RSM Server Domain

Before an RSM Server can interact with the servers in a replication system, you must define the RSM Server’s domain. The RSM Server domain is the set of Replication Servers, Adaptive or SQL Servers, replication agents, RSM Servers, and Open Servers that you want an RSM Server to manage.

The servers that you add to a Sybase Central RSM Server domain can be anywhere in your network. This allows you to manage replication systems that are distributed worldwide.


74

An RSM Server must have an entry in its interfaces file (for UNIX) or its sql.inifile (for NT) for every server (data server, Replication Server, LTM, or Open Server) in its domain. For more information about sql.ini see the Replication Server Configuration Guide for Windows NT.

Adding a Server Sybase Central provides a wizard to assist you when you add a server to an RSM Server domain. Depending on the type of server you are adding (Adaptive/SQL Server, Replication Server, RepAgent/LTM, Open Server, non-Adaptive Server data servers, Sybase Replication Agents, or RSM Server), the wizard prompts you to provide different information.

Before you add a server:

• Read “Before you add a server to an RSM Server domain” in Sybase Central under the Replication Server online help title, “Managing Servers.”

• Gather the following information:

• The server’s name.

• The type of server you are adding.

• If you are adding a non-Adaptive Server data server, you need to know:

• The access method you use to connect to the server (Sybase Replication Agent or Sybase DirectConnect).

• The name of the server or name of the Sybase Replication Agent that you use to mange the server.

• If you are adding a Sybase Replication Agent, you need to know the source data server and source database, which must match the Replication Server parameters, RS_source_ds and RS_source_db.

• The user name and password used to administer the server. The login must have System Administrator privileges on the server.

• The user name and password of the RSSD primary user (Replication Server only).

• The user name and password of the RSSD Database Owner if it is different from the primary user (Replication Server only).

• The location of the log file to monitor.

To add servers to an RSM Server domain in Sybase Central:

1 Select an RSM Server.


75

2 Select File→Add Server or double-click the add object icon in the right pane of the main window.

3 Enter the required information in the wizard dialog boxes.

Once you add servers to the RSM Server domain, the Sybase Central view includes a “Replication Server” tree with icons (also known as objects) that represent the primary components in the domain managed by that RSM Server. See “Replication Server Views” on page 75 for more information.

Dropping a Server To drop a server from an RSM Server domain in Sybase Central:

1 Select the server you want to drop.

2 Select File→Drop Server.

Although Sybase Central removes the server from the RSM Server’s server list and removes the server icon from RSM Server domain, the server is not removed from your replication system.Therefore, the server name may still appear in dialog boxes because of routes or database connections associated with it.

Replication Server ViewsThe Replication Server tree in Sybase Central contains the following views:

• A logical view, which manages data-specific information: tables, replication definitions, subscriptions, and publications. You display this view by double-clicking on a database object.

• A physical view, which manages Replication-Server-specific information: users, queues, threads, partitions, and function-string classes. You display this view by double-clicking on a Replication Server object.

• A topology view, which displays the one or more servers in one or more RSM Server domains and their topology, with status information and grouping capabilities. You display this view by selecting the Topology folder from the tree view.

Logical View

The logical view resides in the left pane of the RSM main window. The logical view manages data-specific information: tables, replication definitions, subscriptions, and publications. You display this view by double-clicking on a database object.


76

Figure 3-8 shows the logical view, which you display by selecting/opening databases from the object tree.

Figure 3-8: Logical view

Table 3-3 lists the objects within a database, along with the operations you can perform on them.

Table 3-3: Logical view objects and procedures

Object Sybase Central Operations

Heterogeneous Data Servers • Expand the object hierarchy on the Tree View

• Drop server from the RSM environment

• Display and alter properties

• Create, modify, delete replication definitions, subscriptions, and publications for tables and stored procedures

Replication Agents • Display and alter properties

• Display system log

• Display and alter configuration properties

• Shutdown

• Drop server from RSM environment

• Force to Admin mode

• Switch to Replicating mode

• Empty queues and switch to Admin mode

• Display statistics for queue information and transaction latency


77

Physical View

Figure 3-9 shows the physical view of a replication system in Sybase Central, which you display by clicking on the objects beneath Replication Server icons in the tree view.

Tables • Display properties

• Display replication definitions

• Display subscriptions

Replication Definitions • Display and alter column datatypes

• Define column-level translations

• Manage JCS datatypes in a replication definition

• Assign user defined datatypes to a heterogeneous datatype

• Generate DDL

Publications and Articles • Display properties

• Create publications

• Add articles to new publications

• Display articles in the publications

• Add articles to existing publications

• Subscribe to publications

• Delete publications

• Generate DDL

Stored Procedures • Display properties of stored procedures, function-string classes, and functions

• Create and view subscriptions

• Subscribe to stored procedures

• Create function-string classes

Subscriptions (Table, Publication, and Stored Procedure)

• Display properties, including subscription status

• Create or define subscriptions

• Activate, validate, and delete subscriptions

• Rematerialize publication subscriptions

• Generate DDL



78

Figure 3-9: Physical view

Table 3-4 lists the objects within a Replication Server, along with their associated operations.

Table 3-4: Physical view objects and procedures


Connections (database) • Display properties and properties of subscriptions where the database is the primary or replicate

• Resume and suspend connections

• Drop/delete a connection

• Add a new database connection

• View subscriptions

Logical Connections • Display properties, including active and standby database information

• Switch active database

• Drop logical connection

• Add a new logical connection

Routes • Display properties

• Add a new route

• Suspend, resume, or drop a route

• Upgrade a route

Replication Server Users • Display properties

• Add/change/delete a new user

Threads • Display properties


79

Topology View

Figure 3-10 shows the topology view, which displays the relationship between server objects. Edges (lines between servers) represent database connections and routes between servers. A status grid can display a variety of information about selected replication system components.

Figure 3-10: Topology view

Topology Folders You can group replication system servers into any number of folders. For example, you could have a folder of all the servers at one geographical site (for example, New York City), and a folder of all Replication Servers. New York City Replication Servers would be included in both folders.

Queues • Display the properties of a stable queue

• Dump the queue and display its contents

Partitions • Display properties

• Add and drop a partition

Function-string Classes • Display properties

• Add/change/delete function strings



80

A server icon in a folder does not represent the original server object, but an alias or “shortcut” to that object. Deleting an object from the topology view or from a topology view folder simply removes it from the topology view, but does not affect the original object. You can also place folders within other folders.

Note Folders also display in the tree view. An object may appear several times in the tree view in different folders; however, the folder contents are only aliases to the original object.

Topology Edges Edges are lines between objects, such as between Replication Servers or between data servers and Replication Servers (see Figure 3-10). Edges may represent multiple objects in the following cases:

• The edge is between Replication Servers and represents bi-directional routes.

• The edge is from a Replication Server to a data server and represents multiple connections.

• The edge is connected to a folder and represents multiple routes and/or connections.

Topology Status Information

Status information that indicates whether a server is up, down, or suspect displays as status icons and is associated with each folder and object. A suspect status (a question mark icon) indicates that the object is active but has some state indicating a problem, such as a replication server that is up but has an unexpected thread down. If the object is a folder, then the status indicates the worst state of the objects that the folder contains.

A status grid is included at the bottom of the topology screen. You select one or several objects, then select the system component for which you want to see status information from a list box.

For example, you could select all Replication Servers, then select routes. The status grid would display specific properties for all of the routes associated with the selected replication servers.

Note For detailed instructions on how to perform specific tasks, see the Replication Server online help in Sybase Central.

81

C H A P T E R 4 Managing a Replication System

This chapter tells you how to perform various Replication Server operations, including starting and shutting down Replication Server, and monitoring, maintaining, and configuring the replication system.

Setting Up a Replication SystemThis section lists the basic steps in setting up a replication system. This process requires planning and careful attention to the replication needs of your organization. If you are new to Replication Server, refer first to the Replication Server Design Guide for information that can help you plan your replication system.

You can perform some of these steps in rs_init, Replication Server’s configuration utility, which allows you to configure Replication Servers and add databases to your system. You can use Sybase Central to perform most of the tasks listed here, including adding databases, creating replication definitions, and creating subscriptions.

Installing the Software Installation is the process of copying Sybase software files to your disk. Install your Sybase software according to the Replication Server installation guide for your platform.

Configuring the Replication System

After you install Replication Server, use the rs_init utility program to start and configure the replication system and to add databases.

Refer to the Replication Server Configuration Guide for more information about rs_init.

Creating Connections and Routes

To replicate data from one database into another, you must first establish the routes and connections that allow Replication Server to move the data from its source to its destination.

• Create connections

Setting Up a Replication System

82

When you use Sybase Central or rs_init to add a database to your replication system, the program creates the connection for you. You never have to create a connection using the command-line option create connection unless you are replicating data into a database that is not an Adaptive Server database.

Refer to the Replication Server Configuration Guide for information about using rs_init.

For instructions on creating connections in Sybase Central, see “Creating database connections” in Replication Server’s online help.

Refer to Chapter 6, “Managing Database Connections” for detailed information about connections.

• Create routes

Create routes using Sybase Central or the create route command at the source Replication Server.

Refer to Chapter 5, “Managing Routes” for more information about how to create routes.

For instructions on creating routes in Sybase Central, see “Creating direct routes” and “Creating indirect routes” in Replication Server’s online help.

Setting Permissions and Security

Set up login names, passwords, and permissions to establish Replication Server security for the replication system. Replication Server login names and specific permissions are required for:

• Users who are setting up replicated data or monitoring and managing the Replication Server. You can create these users in Sybase Central or at the command line.

See “Creating Replication Server user accounts” in the Replication Server online help for information about creating users in Sybase Central.

Refer to “Managing Replication Server User Security” on page 173 for information about creating users at the command line.

• Components of the replication system, such as the data server and the Replication Server. You can create system users in rs_init or at the command line.

Refer to the installation and configuration guides for your platform for information about rs_init. Refer to “Managing Replication Server System Security” on page 168 for information about creating system users at the command line

RSM

RSM

RSM

CHAPTER 4 Managing a Replication System

83

If network-based security is enabled at your site, you can set up secure pathways and choose message protection options for Replication Server to Replication Server communications. Refer to “Managing Network-Based Security” on page 183 for detailed information about setting up network-based security.

Verifying the Replication System

You must verify that the entire replication system is working before you create replication definitions or subscriptions or perform system diagnostics.

See “Viewing the status of a server or folder,” and the other topics in “Using the Topology View” in Replication Server’s online help for information about verifying a replication system using Sybase Central.

Refer to “Verifying a Replication System” on page 362 for a detailed description of verifying the replication system.

Creating Replication Definitions

To set up a table for replication, mark it as replicated in Adaptive Server and define a replication definition for it in Replication Server. The replication definition describes the table and contains information about the columns to be replicated.

• If you plan to replicate stored procedures, create the stored procedure in both the primary and replicate database.

• If you are replicating the procedure from the primary to replicate database, mark the stored procedure for replication in the primary database.

• If you are replicating the procedure from the replicate to the primary database, mark the stored procedure for replication in the replicate database.

Create a function replication definition for the stored procedure at the primary Replication Server, even if you are replicating the stored procedure from a replicate database to the primary database.

Refer to Chapter 8, “Managing Replicated Tables” for more information about creating replication definitions. Refer to Chapter 9, “Managing Replicated Functions” for more information about replicated function delivery.

Creating Subscriptions

A subscription instructs Replication Server to copy data from primary tables to specified replicate databases. If you create a replication definition for a table at Replication Server, you must create a subscription for that table replication definition at the replicate database. Similarly, if you create a function replication definition for a stored procedure, you must create a subscription for that function replication definition at the replicate database. However, you do not need to create subscriptions for table or function replication definitions that update primary databases.

RSM

Performing Replication Server Tasks

84

Refer to Chapter 10, “Managing Subscriptions” for more information.

Performing Replication Server TasksThis section describes several tools that you use when interacting with Replication Server.

rs_init allows you to set up a new Replication Server and add new databases to the system.

You execute RCL commands by connecting to Replication Server using a client application. You can use a utility program such as Sybase Central or isql, or you can use a custom application program that you create with Open Client Client-Library.

Sybase Central’s Replication Server client component provides a graphical user interface for performing many of the tasks associated with managing a Replication Server system.

Since many of the commands described in this book are used on an as-needed basis, isql is a convenient way to execute them.

RCL commands are similar to Transact-SQL commands. See “Conventions” on page xx for command formatting rules. Refer to Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for complete syntax for all RCL commands.

Using rs_initUse the rs_init utility to configure a new Replication Server and to add databases to your replication system. If you have an existing Replication Server, you can use rs_init to upgrade to a new version or downgrade to a previous version. rs_init is installed with the Sybase software. You can use it interactively or with a resource file.

Refer to the Replication Server Configuration Guide for complete instructions on using rs_init.


85

Managing Replication Server with Sybase CentralSybase Central is Replication Server’s system management tool. It provides a graphical user interface that allows you to monitor the components of the replication system and perform Replication Server tasks.

With Sybase Central, you can view a graphical representation of the topology of the replication system, which allows you to group objects and view status information. Sybase Central also provides menus for performing tasks and monitoring objects.

With Sybase Central, you can:

• Perform many of the tasks available from the Replication Server command line and isql, often more quickly than using equivalent Transact-SQL or RCL commands. For example, you can manage users, create routes and connections, create replication definitions and subscriptions, and manage warm standby applications.

• Display multiple Replication Server connections and selectively view the contents of queues.

Refer to Replication Server’s online help for complete information on Sybase Central, and to Chapter 3, “Managing Replication Server with Sybase Central” for information about navigating Sybase Central.

Using isqlYou can use the isql utility to execute:

• RCL commands interactively

• Scripts stored in text files

For simple operations, using isql interactively may be easiest.

For more complex operations, Sybase recommends using isql to execute scripts, so you can keep a record of the RCL commands you have executed to set up a Replication Server. You can edit scripts and resubmit them whenever necessary. Scripts are also useful when you are verifying a new system or investigating the cause of a failure.

You can use isql to log in to Replication Server or Adaptive Server. This section describes both the interactive and script methods for using isql with Replication Server. For information about using isql with Adaptive Server, refer to the Adaptive Server utility programs manual for your operating system.

Performing Replication Server Tasks

86

Using isql Interactively

To use isql interactively:

1 If necessary, start the Replication Server, as described in “Starting Replication Server” on page 87.

2 Log in to the Replication Server using the following command:

isql -Uuser_name -Ppassword -Sserver_name

Specify the name of the Replication Server using the -S flag.

If your login is accepted, isql displays a prompt:

1>

3 Enter the RCL command you want to execute.

When you press the Return key at the end of a line, isql increases the line number. Some commands require more than one line.

4 To execute the command, enter “go” (on a line by itself, with no blanks) and press Return.

To cancel the command, enter “reset” and press Return. The prompt’s line number is reset to 1.

Some RCL commands display immediate results. Others execute asynchronously, that is, they return a system prompt without necessarily having completed the desired action and report only syntax errors.

5 To exit isql, enter “quit” at the beginning of a line.

Note You can check the status of asynchronous commands by executing RCL commands that display status or by querying the RSSD system tables at the affected sites. Refer to Chapter 8, “Replication Server System Tables,” in the Replication Server Reference Manual for more information on system tables and the stored procedures you can use to query them.

Using isql to Execute Scripts

You can create scripts of RCL commands and execute them using isql. This procedure is useful when you need to execute the same set of commands in Replication Servers at multiple sites.

To create and execute a script for isql:


87

1 As necessary, start the Replication Server, as described in “Starting Replication Server” on page 87.

2 Create a text file for your script, and enter into it the RCL commands you want to execute. As with the interactive method, separate each command with the word “go” on a line by itself.

3 Execute the script using the following isql syntax:

isql -Uuser_name -Ppassword -Sserver_name-iscript_name

The isql utility displays the results from the script’s commands on your screen (standard output). Or, you can redirect the output to a file:

isql -Uuser_name -Ppassword -Sserver_name-iscript_name > output_file

Starting Replication ServerNormally, you need to restart Replication Server only if you are reconfiguring system files or if your system experienced a failure that brought down Replication Server. Initially, the installation process starts the replication system for you.

To bring up a Replication Server site, start system components in this sequence:

1 Start the data server containing the databases that Replication Server manages.

2 Start Adaptive Server for the RSSD.

3 Start Replication Server by executing the repserver command on UNIX systems or the repsrvr.exe command on PC systems, or by executing the Replication Server run file.

See “Replication Server Executable Program” on page 88.

4 Start RepAgent for the data server and for the RSSD if RepAgent has not been configured to start automatically at server startup.

If you are using an LTM as the replication agent, start the LTM by executing the ltm command or by executing the LTM run file after starting Replication Server. See “SQL Server LTM Executable Program” on page 590 for details.

Starting Replication Server

88

5 To ensure that Replication Server started with no errors:

• Check the repserver.log file for error messages (indicated with the letter “E” on the left), as described in “Checking Log Files for Information and Error Messages” on page 103.

• Use Sybase Central to check Replication Server status.

You can use the topology view in Sybase Central to check the status of Replication Server components. See “Viewing the status of a server or folder” in Replication Server’s online help.

• Use isql to log in to each Replication Server, or use a script that logs in to each server. See “Verifying Server Status” on page 365.

Replication Server Executable ProgramYou use the repserver or repsrvr.exe command at the operating system prompt to execute the Replication Server program.

For example, to run repserver, log in to the operating system as the “sybase” user, and execute repserver using the following syntax:

repserver [-C config_file] [-i id_server] [-S rs_name][-I interfaces_file] [-E errorlog_file] [-M] [-v][-K keytab_file]

Refer to “repserver” in Chapter 7, “Programs,” in the Replication Server Reference Manual for complete information about each of the parameters of the repserver command.

The rs_init program creates the run file “RUN_name,” where name is the name of the Replication Server. The run file specifies the repserver command with parameters set for the installed Replication Server. Normally, you start Replication Server by executing the run file.

The Replication Server executable program and the Replication Server run file are located in the bin subdirectory of the Sybase release directory. Refer to your platform’s Replication Server installation and configuration guides for more information.

RSM


89

Replication Server Configuration FileReplication Server finds the startup information it needs in a configuration file. The file is created by the rs_init program, but it can be edited with a text editor. If it contains encrypted passwords, however, you must modify them using rs_init. Refer to your platform’s Replication Server installation and configuration guides for more information. The default name for the Replication Server configuration file is the Replication Server name with “.cfg” appended.

Shutting Down Replication ServerTo shut down a Replication Server, log in to it and enter this command at the isql prompt:

shutdown

When you shut down a Replication Server, it refuses additional connections, terminates threads, and exits.

Adding a Replication ServerThe first Replication Server you install must be the ID Server. It must be running when you install new Replication Servers or add databases to the replication system.

To add a Replication Server to a replication system, use the rs_init program, as described in your platform’s installation and configuration guides. Always conduct a careful review and analysis of how the additional Replication Server will fit into your system. Determine the other processes that are required for the server and designate required names and accounts for these processes.

For information about adding a Replication Server in Sybase Central, see “Adding a server to an RSM Server domain” in Replication Server’s online help.

When you install each Replication Server, rs_init performs the following tasks:

• Creates a configuration file for the Replication Server

• Creates an executable run file to start the Replication Server

• Sets RepAgent parameters at Adaptive Server

RSM

Adding a Replication System Domain

90

• Creates and initializes the RSSD

• Starts the Replication Server and RepAgent for the RSSD, as necessary

• If you are using Log Transfer Manager (LTM) as your replication agent, creates the LTM configuration file and starts LTM

After you have executed rs_init for each Replication Server you are adding:

1 Determine the routing for the Replication Server, and modify the routes in the existing system to accommodate the new Replication Server.

See Chapter 5, “Managing Routes” for details.

2 If you want to add a new database, prepare that database for replication.

See Chapter 6, “Managing Database Connections” for details.

3 Grant users the appropriate permissions for Replication Server commands.

See Chapter 7, “Managing Replication Server Security” for details.

4 If applicable, add replication definitions, subscriptions, function-string classes, and error classes for the Replication Server.

See Chapter 8, “Managing Replicated Tables” Chapter 10, “Managing Subscriptions” Chapter 12, “Customizing Database Operations” and Chapter 15, “Handling Errors and Exceptions” for more information.

Adding a Replication System DomainA replication system domain includes all replication system components that use the same ID Server. Most replication systems should be set up as a single domain with a single ID Server. However, you may require replicates of two separate data environments in the following situations if:

• Your enterprise requires data management by separate groups, sites, or independent organizations.

• You need to eliminate an ID Server as a single point of failure, thereby creating a fault-tolerant system.

An ID Server failure in a domain results in system degradation. New Replication Servers and databases cannot be added to a domain as long as the ID Server is shut down.


91

If you do use multiple replication system domains, be sure to have completely independent data environments. For example, assume you have one data environment tracking personnel, and another tracking inventory. As long as there is no data sharing or relationship between these two groups, you can create two separate domains, one for each data environment.

Guidelines for Adding Replication System DomainsWhen creating multiple ID Servers for multiple replication system domains, observe these guidelines:

• Make sure all Replication Server and data server names are globally unique across domains.

By using unique names, you simplify your administration and prevent confusion, especially in the interfaces files, which contain network access information for servers.

• Maintain unique names and distinct ID numbers to accommodate the future possibility of data transfer between domains (that is, merging of domains).

• Provide a different range of database and Replication Server ID numbers for each domain.

• Make sure the ID numbers of any additional domains are large enough so that they do not overlap with the ranges of the first domain. See “Example of Assigning ID Numbers” on page 91.

• Make sure that replication definition names are globally unique within and between ID Server domains.

Example of Assigning ID Numbers

The ID number is increased each time a Replication Server or database is added to the replication system. By default, your first ID number for a data server is 101. For a Replication Server it is 16,777,317. The last possible ID number for a data server is 16,777,316. For a Replication Server it is 33,554,431.

If you are creating two domains, you could assign ID numbers according to Table 4-1.

Setting Replication Server Configuration Parameters

92

Table 4-1: Suggested ID numbers for multiple ID Servers

When you are installing an ID Server using the rs_init program, you can specify the Starting Replication Server ID and the Starting Database ID.

Note Make sure your ranges do not overlap from one domain to another. Make your ranges large enough so that ID numbers can never increase to the next range. For example, a range of 99,999 accommodates nearly all possible cases.

Setting Replication Server Configuration ParametersYou can configure Replication Server or specific objects within the replication system by using one of several methods that update configuration parameters in the rs_config system table in the RSSD. You can also check configuration status information in this table. This section includes:

• An overview of configuration parameters and the objects that these parameters affect

• Information about displaying parameters related to the current Replication Server

Note Replication Server startup information is stored in a configuration file created by rs_init. The default name for the Replication Server configuration file is the Replication Server name with “.cfg” appended. See “repserver” in Chapter 7, “Programs,” in the Replication Server Reference Manual for more information about the configuration parameters stored in this file.

About Configuration ParametersReplication Server reads configuration parameters from the rs_config system table in the RSSD.

Component First ID Number Last ID Number

1st domain data server 101 99,999

2nd domain data server 100,000 16,777,316

1st domain Replication Server 16,777,317 17,777,316

2nd domain Replication Server 17,777,317 33,554,431


93

All configuration parameters have default values, which are inserted in the table when you use the rs_init utility to create the RSSD. The default values are sufficient for most replication systems. Normally, you change default values only for unusual environments or special situations. For example, you may need to adjust parameters for performance tuning if your system has a large number of replication definitions or subscriptions. You can change default values using the configure replication server command. Refer to “Default Configuration Parameters Affecting Performance” on page 484 for information on these parameters.

Parameters governing the names and version numbers of the Replication Server and its components can also be set with rs_init. Table 4-2 describes these basic parameters.

Warning! Do not change the values for the parameters listed in Table 4-2. The values are set when you run rs_init and should only be modified by the rs_init program when you upgrade or downgrade Replication Server.

Table 4-2: Basic configuration parameters

rs_init also sets the password encryption configuration parameter. For information about it, refer to “Enabling and Disabling Password Encryption” on page 175.

Configuration Parameter Description

current_rssd_version The Replication Server version supported by this RSSD. The Replication Server checks this value at startup.

id_server The name of the ID Server for this Replication Server.

minimum_rssd_version The minimum version of the Replication Server that can use this RSSD. When the current_rssd_version is greater than the version of the Replication Server, this value is checked when the Replication Server is started.

oserver The name of the current Replication Server.

prev_min_rssd_version Following an rs_init installation upgrade, this value contains the previous value of minimum_rssd_version.

prev_rssd_version Following an rs_init installation upgrade, this value contains the previous value of current_rssd_version.

rssd_error_class Error class for the RSSD. Default: “rs_sqlserver_error_class”

Setting Replication Server Configuration Parameters

94

Many configuration parameters also have values for specific objects. You set these values after installation when your system requires the fine-tuning that these parameters allow. For example, default route parameters affect all routes that originate at the current Replication Server. If necessary, you change the default settings for these parameters with configure replication server. You also can set parameter values for individual routes by using the alter route command.

Setting some configuration parameters requires a technical understanding of the replication system. See Chapter 2, “Replication Server Technical Overview” and Chapter 14, “Performance Tuning” for information on how the replication system works.

It is important to back up the RSSD periodically and whenever you do anything to change its state. See “Managing the RSSD” on page 107 for more information.

Different Types of Configuration Parameters

Configuration parameters in the rs_config system table affect the Replication Server and different database objects. The method for changing a parameter also varies according to the object that the parameter affects. The different types of configuration parameters are as follows:

• Local Replication Server – parameters whose effects are restricted to the current Replication Server. These parameters are listed in Table 4-2 on page 93 and Table 14-2 on page 484. See “Changing Replication Server Parameters” on page 95 for instructions about setting Replication Server parameter values with configure replication server.

• Route – parameters that affect routes from the current Replication Server to other Replication Servers. See “Changing Routes” on page 130 for information about setting default and per-target values for route parameters.

• Database connection – parameters that affect database connections originating with the Replication Server. See “Setting and Changing Parameters Affecting Physical Connections” on page 152 for information about setting default and per-target values for database connection parameters.


95

• Logical database connection – Replication Server parameters that apply to logical database connections for warm standby applications. See “Changing Parameters Affecting Logical Connections” on page 452 for information about setting default and per-target values for logical connection parameters.

• Network-based security services – parameters that affect network security between Replication Servers. See “Managing Network-Based Security” on page 183 for information about setting security parameters.

• Performance – parameters that affect the performance of a Replication Server. See “Default Configuration Parameters Affecting Performance” on page 484 for information about these parameters.

Changing Replication Server ParametersYou can modify configuration parameters that affect the current Replication Server by using the configure replication server command at the Replication Server.

To change default configuration parameters using configure replication server, log in to Replication Server and execute configure replication server at the isql prompt. The syntax is:

configure replication serverset config_param to ’value’

where config_param is a character string that corresponds to the configuration parameter name and value is a character string representing the setting you want for the parameter. The config_param string must match an entire parameter name. You must restart Replication Server for the new parameters to take effect.

Example 1 For example, to change the maximum number of messages allowed in the Open Server message queue to 5, log in to the source Replication Server and:

1 Execute the configure replication server command:

configure replication server set num_msgs to ’5’

2 Restart the Replication Server.

Refer to “Starting Replication Server” on page 87 for information about starting Replication Server.

Managing RepAgent

96

Example 2 This example uses configure replication server to change the ha_failover parameter to enable Failover support for all non-RSSD connections from a Replication Server to Adaptiver Servers.

1 Execute configure replication server. Log in to the Replication Server for which you want to enable Failover support and enter:

configure replication serverset ha_failover to ’on’

Note You can also enable Failover support for non-RSSD connections from a Replication Server or RSM Server to Adaptive Servers using the Replication Server Manager plug-in to Sybase Central. See “Configuring the Replication System to Support Sybase Failover” in Chapter 16, “Replication System Recovery,” of the Replication Server Administration Guide.

Configuration changes take effect after you restart Replication Server.

Refer to “configure replication server” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for more information about using configure replication server.

Parameters affecting security are covered in Chapter 7, “Managing Replication Server Security” Parameters affecting performance are discussed in Chapter 14, “Performance Tuning”

Managing RepAgentThe section describes setting up, configuring, and managing RepAgent, the replication agent for Adaptive Server. For information about LTM, the replication agent for SQL Server, refer to Appendix B, “LTM for SQL Server” and the Replication Server Administration Guide for Replication Server version 11.0.x.

RepAgent is an Adaptive Server thread; it scans the database transaction log and sends transaction information to the Replication Server for distribution to subscribing databases.

Refer to Chapter 2, “Replication Server Technical Overview” and Chapter 14, “Performance Tuning” for detailed information about how RepAgent processes transaction data.


97

Setting Up RepAgentAfter Replication Server and Adaptive Server are installed on your system, you must enable a RepAgent for each database the Replication Server manages if the database:

• Contains primary data, or

• Contains stored procedures marked for replication

In addition, if Replication Server is the source site for any route, you must enable RepAgent for Replication Server’s RSSD.

There are two possible scenarios for setting up RepAgent:

• If you install a new Replication Server or add a new database, use rs_init to set up RepAgent. rs_init enables RepAgent, sets default parameters, and starts RepAgent. Refer to the Replication Server Configuration Guide for your platform for information about rs_init.

• If you want to upgrade from the LTM to RepAgent, you must use command line options. Both the Adaptive Server and the Replication Server must be version 11.5 or later. You can convert your existing LTM configuration parameters to equivalent RepAgent configuration parameters. Refer to the Replication Server Configuration Guide for your platform for detailed instructions.

The basic steps are:

1 Shut down the LTM.

2 Define the local Adaptive Server using the sp_addserver system procedure.

3 Enable the RepAgent feature on Adaptive Server using the sp_configure system procedure.

4 Enable the RepAgent feature for each database using the sp_config_rep_agent system procedure.

5 Start the RepAgent using sp_start_rep_agent.

Defining the Local Adaptive Server

If you are starting up Adaptive Server for the first time, you must execute the Adaptive Server system procedure sp_addserver to add an entry for the local server to Adaptive Server’s sysservers table. Refer to the Adaptive Server Reference Manual for information about using sp_addserver.

Managing RepAgent

98

Enabling RepAgent on Adaptive Server

Enable the RepAgent feature on the Adaptive Server with the sp_configure system procedure. You need to perform this task only once at each Adaptive Server.

Log in to Adaptive Server and enter this command at the isql prompt:

sp_configure ’enable rep agent threads’, 1

sp_configure ’enable rep agent threads’ is a dynamic option. It takes effect immediately. However, you may want to restart Adaptive Server after enabling RepAgent so that Adaptive Server allocates a fixed number of dedicated static process structures for the thread. Otherwise, RepAgent borrows process structures from the pool dedicated to user connections.

Enabling RepAgent for the Database

Execute sp_config_rep_agent to enable the RepAgent for the database and set default values for RepAgent configuration parameters. You can reset the default values at a later time.

Log in to Adaptive Server. At the isql prompt, enter:

use dbnamesp_config_rep_agent dbname, enable, ’rs_name’,

’rs_username’, ’rs_password’

where dbname is the name of the database for which you are enabling RepAgent, rs_name is the Replication Server to which RepAgent connects, and rs_username and rs_password are the name and password RepAgent uses to log in to Replication Server.

Note Make sure that rs_username is a valid Replication Server user and that it has Replication Server connect source permission. Try out the user name and password at the Replication Server before you use sp_config_rep_agent.

Refer to “Configuring RepAgent” on page 99 for information about setting RepAgent parameters with sp_config_rep_agent.

Once RepAgent has been enabled for a database and started once using sp_start_rep_agent, it will start up automatically whenever the database is restarted. If you stop RepAgent using sp_stop_rep_agent, however, the autostart feature is disabled, and you will have to manually restart RepAgent using sp_start_rep_agent.


99

Configuring RepAgentWhen you enable RepAgent, rs_init sets default configuration parameters. You can change RepAgent configuration parameters with sp_config_rep_agent. You must restart RepAgent for the new parameters to take effect.

Table 4-3 describes the configuration parameters that affect RepAgent. These parameters are stored in the sysattributes table of the database for which RepAgent is enabled.

If your system supports network-based security, refer to “Managing Network-Based Security” on page 183 for a list and description of network security configuration parameters for RepAgent.

Table 4-3: Configuration parameters affecting RepAgent


batch_ltl When set to “true,” sends LTL commands to Replication Server in batches. When set to “false,” sends LTL commands to Replication Server one at a time.Default: true

connect_database The name of the temporary database RepAgent uses when connecting to Replication Server in recovery mode.

connect_dataserver The name of the temporary data server RepAgent uses when connecting to Replication Server in recovery mode.

dbname The name of the database for which RepAgent is enabled.

fade_timeout The number of seconds RepAgent remains inactive when there are no qualifying records in the transaction log before disconnecting from Replication Server.Default: 30 seconds

ha_failover Specifies whether, when Sybase Failover has been installed, RepAgent automatically starts after server failover.Default: true

rs_name The name of the Replication Server to which RepAgent connects and transfers log transactions.

rs_password The password RepAgent uses to log in to Replication Server.

rs_username The username RepAgent uses to log in to Replication Server.

retry_timeout The number of seconds RepAgent remains inactive before attempting to reconnect to Replication Server after a recoverable error or when Replication Server is down.Default: 60 seconds

scan_batch_size The maximum number of log records to send to Replication Server in each batch. When this number of records have been sent, RepAgent asks Replication Server for a new secondary truncation point.Default: 1000 records

Managing RepAgent

100

To configure RepAgent, log in to Adaptive Server and execute the sp_config_rep_agent system procedure at the isql prompt. Here is the syntax:

sp_config_rep_agent [, dbname[, {’enable’, ’repserver_name’, ’repserver_username’, ’repserver_password’}|

’disable’[, ’preserve secondary truncpt’] |’rs_servername’, ’repserver_name’,

’rs_username’, ’repserver_username’, ’rs_password’, ’repserver_password’ |

’scan_batch_size’, ’no_of_qualifying_log_records’ |’scan_timeout’, ’scan_timeout_in_seconds’ |’retry_timeout’, ’retry_timeout_in_seconds’ |’fade_timeout’, ’fade_timeout_in_seconds’ |’skip_ltl_errors’, {’true’ | ’false’} |’batch_ltl’, {’true’ | ’false’} |’send_warm_standby_xacts’, {’true’ | ’false’} |’connect_dataserver’, ’connect_dataserver_name’ |’connect_database’, ’connect_database_name’ |’send_maint_xacts_to_replicate’,{’true’ |’false’} |

scan_timeout The amount of time RepAgent remains inactive after sending a batch to the Replication Server and before querying the Replication Server for the new secondary truncation point. If there are more records in the log, RepAgent will resume scanning. If there are no more records and the Replication Server has still not acknowledged receipt by sending a secondary truncation point, RepAgent will again timeout for the length of time this parameter is set to.Default: 15 seconds

send_maint_xacts_to_replicate When set to “true,” RepAgent sends records from the maintenance user to the Replication Server for distribution to subscribing sites. When set to “false,” RepAgent does not send records from the maintenance user to the Replication Server.Default: false

send_warm_standby_xacts Normally schema and system transactions are not sent to a warm standby database. When set to “true,” RepAgent sends schema, system, and maintenance-user transactions. When set to “false,” RepAgent does not send transactions to the standby database. This option should be used only with the RepAgent for the currently active database.Default: false

skip_ltl_errors When set to “true,” RepAgent ignores LTL errors returned by the Replication Server. This option is normally turned on during recovery.Default: false

skip_unsupported_features Instructs RepAgent to skip log records for features unsupported by the Replication Server. This option is normally used if Replication Server is a lower version than Adaptive Server.Default: false



101

’security_mechanism’, ’mechanism_name’ |’unified_login’, {’true’ | ’false’ }|’mutual_authentication’, {’true’ | ’false’} |’msg_confidentiality’, {’true’ | ’false’ } |’msg_integrity’, {’true’ | ’false’ } |’msg_replay_detection’, {’true’ | ’false’} |’msg_origin_check’, {’true’ | ’false’ } |'msg_out_of_sequence check’ {'true' | 'false'} |‘skip_unsupported_features’, {‘true’ | ‘false’} |‘ha_failover’, {‘true’ |’false’} ]]

where dbname is the name of the database for which RepAgent is enabled. For a complete description of each option, refer to the Replication Server Reference Manual.

Execute sp_config_rep_agent once for each parameter you want to configure. For example, to change the maximum number of log records sent to Replication Server in a batch to 2000, perform these steps:

1 Log in to Adaptive Server and enter:

use dbnamesp_config_rep_agent dbname, ‘scan_batch_size’,

'2000'

2 Restart RepAgent:

sp_start_rep_agent dbname

Refer to “Starting RepAgent” on page 101 for more information about sp_start_rep_agent.

The new parameter takes effect after you restart RepAgent.

Starting RepAgentNormally, you need to start a RepAgent thread only if you have reconfigured RepAgent parameters, if you have explicitly shut RepAgent down, if RepAgent has shut down due to system failure, or if you are upgrading from the LTM.

RepAgent starts automatically when Adaptive Server restarts if the RepAgent has been started at least once with sp_start_rep_agent and not stopped with sp_stop_rep_agent.

To start RepAgent, log in to Adaptive Server and enter sp_start_rep_agent at the isql prompt:

Managing RepAgent

102

sp_start_rep_agent dbname[, for_recovery[, connect_dataserver, connect_database[, rs_servername, rs_username, rs_password]]]

where dbname is the name of the database for which the RepAgent has been enabled.

When “for_recovery” is included with sp_start_rep_agent, RepAgent supports the off-line recovery of old log dumps from a data server and temporary database specified by connect_dataserver and connect_database.

Refer to “sp_start_rep_agent” in Chapter 5, “Adaptive Server Commands and System Procedures,” in the Replication Server Reference Manual for detailed information about each option of the sp_start_rep_agent system procedure.

Stopping RepAgentTo shut down RepAgent, log in to Adaptive Server and execute sp_stop_rep_agentat the isql prompt by entering:

sp_stop_rep_agent dbname[, nowait]

If you shut down RepAgent normally—without using the nowait option—Adaptive Server shuts down RepAgent gracefully at the end of the current batch of transactions.

If you shut down RepAgent with the nowait option, Adaptive Server kills the RepAgent without waiting for currently executing operations to finish. When RepAgent restarts, it scans records starting with the oldest transaction, but it only sends records following the last one processed. As a result, Replication Server does not receive duplicate records.

Once RepAgent has been shut down with sp_stop_rep_agent, it does not automatically start up when the database comes online during data server startup. You must execute the sp_start_rep_agent procedure, which starts up RepAgent and resumes automatic start up.

Disabling RepAgentDisabling RepAgent deletes all RepAgent entries in the sysattributes file.

Note You should disable RepAgent only when you downgrade Replication Server to a prior version or change the primary database to a replicate database.


103

Before disabling RepAgent, you must first shut it down using sp_stop_rep_agent. Then, to disable RepAgent, execute sp_config_rep_agent at the isql prompt:

sp_config_rep_agent dbname, ’disable’[, ’preservesecondary truncpt’]

where dbname is the name of the database for which you are disabling RepAgent.

Normally, when you disable RepAgent, the process also disables the secondary truncation point. Once the secondary truncation point is disabled, the log can get truncated past the secondary truncation point, which may cause loss of replicate data. To disable RepAgent but keep the secondary truncation point—normally useful only when switching back to the LTM—use the preserve secondary truncpt option.

Checking Log Files for Information and Error MessagesError, trace, and information messages for RepAgent are recorded in the Adaptive Server error log file. You can identify RepAgent messages by the “RepAgent (dbid)” string, which occurs in the first line of the message. dbid identifies the database for which RepAgent is enabled. Refer to the Adaptive Server System Administration Guide for more information about the Adaptive Server error log.

Configuring RepAgent for Network SecurityYou can secure the pathway between RepAgent and Replication Server using network-based security features. Using sp_config_rep_agent, you can change settings for:

• The active security mechanism

• Unified login

• Mutual authentication

• Message confidentiality

• Message integrity

• Message replay detection

• Message origin check

Managing RepAgent

104

• Message out of sequence check

Refer to “Managing Network-Based Security” on page 183 for a complete description of network security and instructions for setting parameters for RepAgent.

Reviewing Status and Configuration InformationYou may need to monitor RepAgent and its connections. You can monitor the RepAgent in Sybase Central, or you can use the commands and system procedures described in this section.

Viewing RepAgent Information

You can monitor the RepAgent by using sp_help_rep_agent at Adaptive Server. sp_help_rep_agent displays information about:

• Recovery – status and other information when you are restoring a database.

• Configuration parameters – the current settings for RepAgent’s configuration parameters.

• Process – information about the RepAgent process, including state, sleep status, number of unsuccessful connection retries (if any), and the number of the last error message.

• Scanning – information about the current batch of log transactions: start, end, and current markers; the number of records in the batch; and the oldest transaction.

• All – all of the above information.

Log in to Adaptive Server and execute sp_help_rep_agent at the isql prompt:

sp_help_rep_agent [dbname[, ’recovery’ | ’config’ | ’process’ | ’scan’ | ’all’]]

where dbname is the name of the database for which the RepAgent is enabled.

Refer to Chapter 5, “Adaptive Server Commands and System Procedures,” in the Replication Server Reference Manual for detailed syntax and usage information about sp_help_rep_agent.

Examples of Using sp_help_rep_agent

You can view current status information for one or all options, for example:


105

• To display information about the recovery process, log in to Adaptive Server and enter:

sp_help_rep_agent dbname, ’recovery’

Adaptive Server displays the name of the database for which the RepAgent is enabled, the name of the temporary data server and database, the status of RepAgent, the name of the Replication Server, and the Replication Server user name.

• To display all available information about a RepAgent, log in to Adaptive Server and enter:

sp_help_rep_agent dbname

Viewing Configuration Parameter Values

To view a list of default, current, and runtime configuration parameter values for RepAgent, log in to Adaptive Server and execute the sp_config_rep_agent procedure without options:

sp_config_rep_agent dbname

If you do not specify dbname, sp_config_rep_agent displays configuration values for all RepAgent-enabled databases.

Refer to Chapter 5, “Adaptive Server Commands and System Procedures,” in the Replication Server Reference Manual for more information about sp_config_rep_agent.

Viewing RepAgent Thread Information

To view RepAgent thread status on Adaptive Server, execute the sp_who system procedure. In the display output, Adaptive Server shows RepAgent information in rows with “REP AGENT” in the “cmd” column.

To view RepAgent thread user status on Replication Server, execute the admin who command. Replication Server displays RepAgent thread user information in rows with “REP AGENT” in the “name” column. For more information about admin who, refer to Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual.

Managing RepAgent

106

Managing Log Transfer ActivityIf you are performing recovery, troubleshooting, or diagnostic tasks, you may need to suspend and resume log transfer. This section describes how to use log transfer commands. See Chapter 16, “Replication System Recovery” for information about starting the RepAgent thread in recovery mode so that it can replay database and transaction dumps.

Suspending Log Transfer

To disconnect one or all RepAgents and prevent RepAgents from connecting to Replication Server, execute the suspend log transfer RCL command. Log transfer to Replication Server remains suspended until you resume it using the resume log transfer command.

The suspend log transfer command records information in the RSSD, so if you shut down Replication Server and restart it, log transfer to that Replication Server remains suspended.

Note Suspending log transfer is the first step in quiescing the replication system. See “Quiescing Replication Server” on page 109.

To suspend log transfer, log in to Replication Server and execute suspend log transfer at the isql prompt, by entering:

suspend log transfer from {data_server.database | all}

• data_server – the data server with the database for which log transfer is to be suspended.

• database – the database for which log transfer is to be suspended.

• all – instructs Replication Server to suspend log transfer from all RepAgents and disallow future connections for all RepAgents.

An Adaptive Server RepAgent continues to run when you suspend log transfer to Replication Server.

Examples of Using suspend log transfer

These examples demonstrate the use of the suspend log transfer command.

1 The following command suspends log transfer for the database named pubs2, managed by the TOKYO_DS data server:

suspend log transfer from TOKYO_DS.pubs2

2 The following command suspends log transfer to this Replication Server from all RepAgents:


107

suspend log transfer from all

In both examples, after the command is executed, affected RepAgents are not shut down and may continue to send some messages to Replication Server. To shut down a RepAgent immediately, log in to Adaptive Server and enter sp_stop_rep_agent, with the name of the database for which RepAgent is enabled, and the nowait option.

Resuming Log Transfer

To reconnect RepAgent to a Replication Server, log in to the Replication Server and enter the resume log transfer command at the isql prompt:

resume log transfer from {data_server.database | all}

• data_server – the data server with the database for which log transfer is to be resumed.

• database – the database for which log transfer is to be resumed and for which the RepAgent connection is to be allowed.

• all – allows all RepAgents to connect to this Replication Server.

Examples of Using resume log transfer

These examples demonstrate the use of the resume log transfer command.

1 The following command resumes log transfer for the database named pubs2, managed by the TOKYO_DS data server:

resume log transfer from TOKYO_DS.pubs2

2 The following command resumes log transfer to this Replication Server from all RepAgents:

resume log transfer from all

Managing the RSSDThe data in each Replication Server’s RSSD is essential in keeping the replication system running.

The Replication System Administrator or Adaptive Server System Administrator manages the RSSD by monitoring the condition of the database and performing regular dumps. In the event of disaster recovery, you need to rely on up-to-date backups of the RSSD for full system recovery. Therefore, it is critical that you perform periodic backups of the replication system.

Managing the RSSD

108

It is also important to back up the RSSD after performing tasks that change its state, such as adding routes, replication definitions, and subscriptions, or altering function strings for databases to which you are connected.

The system tables are loaded into the RSSD during Replication Server installation. You can query the system tables to find the status of the system, but in general, you should not make changes to the tables directly. Refer to the Replication Server Reference Manual for detailed descriptions of the system tables.

Enabling Failover Support for an RSSD ConnectionSybase Failover allows you to configure two version 12.0 Adaptive Servers as companions. If the primary companion fails, that server’s devices, databases, and connections can be taken over by the secondary companion.

Note For more detailed information about how Sybase Failover works in Adaptive Server, refer to Using Sybase Failover in a High Availability System, which is part of the Adaptive Server Enterprise version 12.0 documentation set.

For instructions on how to enable Failover support for non-RSSD Replication Server connections to Adaptive Server, see “Configuring the Replication System to Support Sybase Failover” in Chapter 16, “Replication System Recovery,” of the Replication Server Administration Guide.

To enable Failover support for an RSSD connection, use either of the following methods:

• Use rs_init when you install a new Replication Server.

For instructions, see Chapter 2, “Configuring Replication Server and Adding New Databases,” in the Replication Server Configuration Guide for your platform.

• Edit the Replication Server’s configuration file after you have installed the Replication Server.

a Use a text editor to open the Replication Server’s configuration file. The default file name is the Replication Server name with a “.cfg” extension.

The configuration file contains one line per entry.

b Find the line “RSSD_ha_failover=no” and change it to:


109

RSSD_ha_failover=yes

c To disable Failover support for an RSSD connection, change the “RSSD_ha_failover=yes” to:

RSSD_ha_failover=no

These changes take affect immediately; that is, you do not have to restart Replication Server to enable Failover support.

Quiescing Replication ServerTo quiesce a replication system means to put the system in a state in which no Replication Servers have messages to send or receive. You may need to quiesce all Replication Servers in the system to recover databases, alter routes, and troubleshoot the system.

A Replication Server is quiescent when the following conditions are true:

• Subscription materialization queues do not exist.

• Replication Server has read all messages in all queues.

• Transaction caches for inbound queues contain no complete transactions.

• Messages in RSI queues have been sent and acknowledged.

• Messages in DSI queues have been applied and acknowledged.

Quiescing a Replication SystemYou can use Sybase Central or the procedure discussed in this section to quiesce a system consisting of several Replication Servers.

To use Sybase Central, see “Quiescing a Replication Server” in Replication Server’s online help.

Otherwise:

1 Execute the suspend log transfer from all command at each Replication Server. This prevents RepAgents from connecting to the Replication Servers.

2 Execute admin quiesce_force_rsi at each Replication Server.

RSM

Removing a Replication Server

110

This command forces Replication Server to deliver all queued messages to other Replication Servers, then reports whether the system is successfully quiesced.

Quiescing occurs most efficiently if you follow the flow of the data. For example, if data flows from TOKYO_RS to MANILA_RS to SYDNEY_RS, quiesce the Replication Servers in that order.

3 Check that the Replication Server is quiescent using admin quiesce_check. If necessary, repeat steps 2 and 3 until all Replication Servers are quiescent.

4 After all Replication Servers are quiescent, execute admin quiesce_force_rsi once more at each Replication Server. Check that each Replication Server is quiescent using admin quiesce_check. If necessary, repeat this step until all Replication Servers are quiescent.

This step is necessary because, although a Replication Server may be quiescent, it may have recently sent messages to another Replication Server. These messages may initiate more communication between these two Replication Servers or between several Replication Servers in the replication system. Repeating steps 2 and 3 ensures that you have quiesced the entire replication system.

Removing a Replication ServerHow you remove a Replication Server from a replication system depends on whether or not the Replication Server is active (running). Although this section contains procedures for both situations, it is easiest to remove a Replication Server that is active.

The procedures in this section also require that you drop routes and subscriptions. See Chapter 10, “Managing Subscriptions” and Chapter 5, “Managing Routes” for details.

Removing an Active Replication ServerThis section tells you how to remove a running Replication Server from service.

For instructions on removing a Replication Server using Sybase Central, see “Dropping Servers” in Replication Server’s online help.

RSM


111

Otherwise:

1 Query the RSSD to determine what replication definitions are defined at the primary Replication Server (the server you are removing from service). You can use the rs_helpdb stored procedure to do this. Refer to Chapter 8, “Replication Server System Tables,” in the Replication Server Reference Manual for information on the RSSD system tables.

2 Drop subscriptions and replication definitions.

In Sybase Central, see “Deleting subscriptions” in Replication Server’s online help.

a For each replication definition defined at the primary Replication Server, execute the drop subscription command for each subscription on all Replication Servers that manage subscribing data.

To retain data at the replicate, execute the drop subscription command without purge.

To delete data at the replicate, execute the drop subscription command with purge.

See “Using the drop subscription Command” on page 336 for more information about dropping subscriptions.

b Drop all replication definitions for primary data managed by the Replication Server (determined in step 1).

Wait for the replication definitions to disappear from the RSSDs of Replication Servers that the Replication Server has a route to.

c At the Replication Server you are removing, drop all subscriptions to replication definitions on other Replication Servers.

To retain data at the replicate, execute the drop subscription command without purge.

To purge data at the replicate, execute the drop subscription command with purge.

3 If the Replication Server is the primary Replication Server for a function-string class or error class, execute the move primary command at another Replication Server to change the primary Replication Server for each class.

RSM


112

During a move primary operation, routes must exist from the old primary site to the new primary site, and from the new primary site to the old primary site. The Replication Server assuming the role of the primary site also must have routes to all of the same Replication Servers as the old primary site.

4 Drop database connections.

In Sybase Central, see “Dropping database connections” in Replication Server’s online help.

a Stop all RepAgents connected to the Replication Server, using the sp_stop_rep_agent system procedure at Adaptive Server.

b Remove connections to all databases managed by this Replication Server, using the drop connection command.

Note If you want to continue to maintain the replicate data in databases previously managed by a Replication Server that has since been removed from service, you must create connections to those databases from some other Replication Server and create new subscriptions.

5 Perform the following routing tasks:

a If the Replication Server is an intermediate site in a route, use the alter route command so it is no longer an intermediate site.

b Drop all routes from the Replication Server.

To do this, execute the drop route command for each route from the Replication Server to another Replication Server.

c Drop all routes to the Replication Server.

To do this, execute the drop route command on each Replication Server that has a route to the Replication Server you are removing.

See Chapter 5, “Managing Routes” for more information about altering and dropping routes.

In Sybase Central, see “Managing Routes” in Replication Server’s online help.

6 After all subscriptions and routes to and from the Replication Server are dropped, remove the Replication Server from the list maintained by the ID Server. To do this, execute the sysadmin droprs command on the ID Server:

sysadmin droprs, replication_server

RSM

RSM


113

Refer to “sysadmin droprs” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for more information on the sysadmin droprs command.

7 Remove all databases managed by the Replication Server from the database list maintained by the ID Server. Include the RSSD. To remove databases, run the sysadmin dropdb command on the ID Server, for each database:

sysadmin dropdb, data_server, database

Refer to “sysadmin dropdb” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for more information on the sysadmin dropdb command.

Removing an Inactive Replication ServerAn inactive Replication Server is one that is not running. To take an inactive Replication Server out of service, follow these steps:

1 Drop all routes to the Replication Server.

To do this, execute the drop route command with the with nowait option on each Replication Server that has a route to the Replication Server. For example:

drop route to OLD_RS with nowait

This command also deletes information about subscriptions created at OLD_RS for data managed by this Replication Server.

2 If the Replication Server you are removing is primary for any function-string classes or error classes other than the system defaults, rs_default_function_class and rs_sqlserver_error_class, create a replacement for each class at a new primary. To do this:

• Choose a Replication Server that has routes to all other Replication Servers that use the class.

• Create a new class at that Replication Server containing the same function strings or error actions as the original class. See Chapter 12, “Customizing Database Operations” and Chapter 15, “Handling Errors and Exceptions” for details.

• Alter each database connection that is using the original class to use the new class instead. See Chapter 6, “Managing Database Connections” for details.


114

3 On each Replication Server that has a route from the Replication Server, purge the Replication Server route.

To purge a route, execute the sysadmin purge_route_at_replicate command on each Replication Server to which the Replication Server had a route. For example:

sysadmin purge_route_at_replicate, OLD_RS

This command also removes:

• Subscription information for data originating at the Replication Server you are removing from service.

• Function-string and error classes defined at the Replication Server you are removing from service. If the Replication Server is the primary site for rs_default_function_class, rs_sqlserver_function_class or rs_sqlserver_error_class, these classes are not removed but are reset to have no primary Replication Server.

4 Remove the Replication Server from the list maintained by the ID Server. To do this, execute the sysadmin droprs command on the ID Server:

sysadmin droprs, replication_server

See the Replication Server Reference Manual for more information on the sysadmin droprs command.

5 Remove all databases managed by the Replication Server from the database list maintained by the ID Server. Include the RSSD. To remove databases, run the sysadmin dropdb command on the ID Server, for each database:


See the Replication Server Reference Manual for more information on the sysadmin dropdb command.

This completes the removal of an inactive Replication Server from a replication system.

Keep in mind these three additional points:

• If you want to continue to replicate any data in the databases previously managed by the Replication Server, you must reassign those databases to some other Replication Server.


115

• Since the subscriptions to the Replication Server’s data did not go through normal subscription dematerialization, replicate data has not been deleted from replicate Replication Servers.

• You may need to create additional routes to maintain the replication system—for example, if the Replication Server is an intermediate on an indirect route.


116

117

C H A P T E R 5 Managing Routes

This chapter describes creating and managing routes between Replication Servers.

OverviewA route is a one-way message stream from a source Replication Server to a destination Replication Server. From each source Replication Server, you create one route for each destination Replication Server, no matter how many databases are managed by the source or destination Replication Servers.

Routes carry:

• Data modification commands and applied functions or applied stored procedures from primary databases managed at the source Replication Server to replicate databases managed at the destination Replication Server

• System table modification commands from a source Replication Server’s RSSD to a destination Replication Server’s RSSD

• Request functions or request stored procedures from replicate databases to primary databases (in this case, the source is the replicate Replication Server and the destination is the primary Replication Server).

When you create a route, the source Replication Server:

• Creates an RSI outbound queue to hold messages for the destination site

• Starts an RSI thread that logs in to the destination Replication Server and transfers transactions from the RSI outbound queue to the destination Replication Server

Before You Begin

118

Before You BeginBefore you create or modify routes, be sure you have carefully determined where routes are needed in your system. As part of the design process, you must know where each source Replication Server and its destination Replication Servers reside.

Identify which routes are direct and which are indirect. Indirect routes carry messages to destination Replication Servers through one or more intermediate Replication Servers. Using direct versus indirect routes can have a noticeable effect on system performance.

Refer to the Replication Server Design Guide for details on routing and performance issues. Also see “Routing Schemes” on page 119 for a general discussion of direct and indirect routes.

Once you have determined your routing scheme, you can set up the required routes based on these rules:

• Replication Servers that manage databases containing primary data require direct or indirect routes to the Replication Servers that manage databases with subscriptions for the data.

• Replication Servers that manage replicate databases where request functions originate require direct or indirect routes to the Replication Server managing the primary database. If no replicated functions originate in the replicate database, a route from a replicate to a primary Replication Server is not required.

• Each route in an indirect route must be a direct route.

Refer to “Indirect Routes” on page 120 for examples of indirect routes.

• You customize function strings for system functions with class scope at the primary Replication Server for the function-string class. In this instance, you must create routes from the primary Replication Server to the Replication Server managing the databases that use the function strings.

Refer to “System Functions with Function-String-Class Scope” on page 375 for more information.

• You customize error classes at the primary Replication Server. In this instance, you must create routes from the primary Replication Server to the Replication Server managing the databases that use the error mappings.

CHAPTER 5 Managing Routes

119

• A Replication Server that you plan to assign as the new primary site for a function-string class or error class, using the move primary command, has the following requirements:

• It must have routes to and from the Replication Server that is the current primary site for the class, and

• It must have routes to all the same Replication Servers as the Replication Server that is the current primary site for the class

Refer to “Changing the Primary Replication Server for an Error Class” on page 506 for more information. Refer also to “Primary Site for a Function-String Class” on page 388.

Routing PreparationsBefore creating and modifying routes, you need to:

• Make sure the source Replication Server is running.

• If you are creating a direct route, define the destination Replication Server in the interfaces file at the site of the source Replication Server.

You should also have an interfaces file entry for the RSSD of the destination Replication Server.

• Make sure that the RepAgent thread for the source Replication Server RSSD is running.

• Make sure that the destination Replication Server and any intermediate Replication Servers in the route are running.

Routing SchemesReplication Server supports direct and indirect routes. Each type of route is described in the following sections.

Figure 5-1 and Figure 5-2 each show a seven-site enterprise with a single primary site and six replicate sites. Each replicate site has a route originating at the primary site.

In Figure 5-1, all six routes from the primary site are direct. Thus, the primary Replication Server has six stable queues and six RSI threads connected through the network to the six replicate sites.

Routing Schemes

120

In Figure 5-2, only two routes from the primary site are direct; four are indirect. The two intermediate sites each have two direct routes. Table 5-1 lists the routes in Figure 5-2.

Direct RoutesA route with no intermediate sites is called a direct route. A system with direct routes results in network connections between source and destination Replication Servers.

For example, in Figure 5-1, a seven-site enterprise is shown in a star configuration, with one primary site and six replicate sites. If the replicate site TKO_RS is to submit request functions to the primary site NY_RS, your system would also require a direct route from TKO_RS to NY_RS, in addition to the direct route from NY_RS to TKO_RS.

Figure 5-1: Sites connected with direct route configuration

Indirect RoutesA route with intermediate sites is called an indirect route.

Site (source)Primary

HK_RS

NY_RS

LON_RSTKO_RS

PAR_RS

HAM_RS

SYD_RS

Paris Hong Kong

LondonTokyo

Sydney

Hamburg

New York


121

For example, in Figure 5-2, NY_RS to SAC_RS is an indirect route, based on the direct routes NY_RS to SF_RS and SF_RS to SAC_RS. In an indirect route, the source Replication Server sends messages for the destination Replication Server to an intermediate Replication Server, which makes use of a route (direct or indirect) to the destination Replication Server.

To create an indirect route, you create direct routes between each successive Replication Server along the intended indirect route. Once all the direct routes are in place, then you create the indirect route itself. See “Creating Routes” on page 124 for details.

For example, to create the indirect route NY_RS to SAC_RS, first create the direct routes NY_RS to SF_RS and SF_RS to SAC_RS. Then create the indirect route based on the existing direct routes.

Figure 5-2: Sites connected with indirect routes in a hierarchical configuration

NY_RS

SF_RS LA_RS

SD_RS SB_RSSJ_RSSAC_RS

Intermediate Sites

Destination Sites

New York

San Francisco Los Angeles

Sacramento San Jose San Diego Santa Barbara

Primary Site (Source)

Routing Schemes

122

By setting up indirect routes, you reduce the amount of processing at the primary site and distribute the load among intermediate Replication Servers.

Table 5-1: Direct and indirect routes between sites in Figure 5-2

When you use indirect routes, the primary Replication Server can route portions of subscriptions that are common to destination sites through the same intermediate site. When subscriptions overlap, the primary Replication Server is required to send only one message per row modification to the intermediate Replication Server that is common to the destination sites.

For example, in Figure 5-3, the intermediate Replication Server in LON_RS receives row modification changes for customer accounts whenever changes occur at the bank headquarters in New York. The New York modifications are also required at branch bank replicate sites in Zurich and Bonn. Because LON_RS is set up to distribute changes to ZUR_RS and BON_RS, the NY_RS primary Replication Server sends only one copy of each change to LON_RS. The number of direct routes is also reduced through the use of the two indirect routes, NY_RS to ZUR_RS and NY_RS to BON_RS.

Direct Routes Indirect Routes

NY_RS to SF_RS NY_RS to SAC_RS

NY_RS to LA_RS NY_RS to SJ_RS

SF_RS to SAC_RS NY_RS to SD_RS

SF_RS to SJ_RS NY_RS to SB_RS

LA_RS to SD_RS

LA_RS to SB_RS


123

Figure 5-3: Sites with overlapping subscriptions

Although indirect routes are helpful for distributing computing resources among sites on the network, overall propagation of data is slowed somewhat because messages are queued by more than one Replication Server. It is better to use direct routes when there are few replicate sites. When using indirect routes, minimize the number of intermediate sites to obtain the best propagation times.

Unsupported Routing SchemesAn intermediate Replication Server can accept transactions from one or more Replication Servers. Replication Server, however, does not support routing schemes in which routes diverge from the same source Replication Server, then converge at the same intermediate or destination Replication Server.

For example, in Figure 5-4, only one route from NY_RS to LA_RS can be supported. If the route NY_RS to CHI_RS to LA_RS is supported, then NY_RS to LA_RS and the intermediate route SEA_RS to LA_RS are not supported.

NY_RS

ZUR_RS

LON_RS

Customer Accounts

Primary Replication

New York Updates

Server

IntermediateReplication

Server

BON_RS

Subscriptions foraccounts whereBranch = New York

Subscriptions foraccounts whereBranch = New York

Creating Routes

124

Figure 5-4: Example of supported and unsupported routes

Creating RoutesYou create routes at the source Replication Server. As soon as you create a direct route between a source and destination Replication Server, the source Replication Server:

• Creates an RSI outbound stable queue to hold messages for the destination site, and

• Starts an RSI thread that logs in to the destination or next Replication Server in the route.

Note You can create a route from a version 11.5 Replication Server to an older Replication Server (version 11.03 or later).

When you create either direct or indirect routes, the destination Replication Server creates and materializes subscriptions at the destination site for the replicated RSSD system tables. This process lets the destination Replication Server receive available replication definitions and function classes. See Chapter 2, “Replication Server Technical Overview” for details.

NY_RS

CHI_RS SEA_RS

LA_RS

Unsupported

New York

Chicago Seattle

Los Angeles

Routes


125

You cannot create an indirect route (A to C) unless you have already created two direct routes (A to B and B to C). You also must set up the routes in the correct order, as shown in Figure 5-5. For Replication Server to be able to begin transferring system information to the destination Replication Server, you must create direct routes before you create an indirect route.

When you create an indirect route, Replication Server does not create an RSI queue. The indirect route uses the RSI outbound queues of the direct route segments that compose the indirect route.

Figure 5-5: Order for creating direct and indirect routes

Using the create route CommandYou can create routes in Sybase Central or with the create route command.

For instructions on creating routes in Sybase Central, see “Creating direct routes” and “Creating indirect routes” in Replication Server’s online help.

The syntax for the create route command is:

create route to dest_replication_server{set next site [to] thru_replication_server|[set username [to] user][set password [to] passwd][set route_param to ’value’][set security_param to ’value’]}

When creating routes:

• Supply the login name, password, and other parameters for direct routes only.

LON_RS

NY_RS

ROM_RS

3

1

2

NY_RS→LON_RS

NY_RS→ROM_RS

Direct Route

Direct Route

Indirect Route

LON_RS→ROM_RS

.

.

.

RSM

Creating Routes

126

• Before you create a direct route, create its login name and password in the destination Replication Server. Optionally, you can have the rs_init utility create this user.

• If you are enabling network-based security and unified login, user name and password are optional. The default user name is the principal user name, which is specified by the -S flag when you log in to Replication Server or start Replication Server. Refer to “Establishing the Principal User” on page 190 for more information about network-based security and the principal user.

• If you create a route with a user and passwd that do not exist at the destination Replication Server, add or change the user and password at that destination. See also “Changing an Indirect Route to a Direct Route” on page 133.

• If you are establishing a direct route from the current Replication Server to the destination Replication Server, do not use the next site clause.

• Enter one create route command at a time, to ensure you have made no mistakes. Wait for a route to became valid before creating the next one.

If you do make a mistake, drop the route and re-create it only as a last resort. Include the with nowait option with the drop route command. Since the route has not been created, its current state requires that you use the with nowait option to drop it. See “Dropping Routes” on page 138.

When you create a route, you can accept the default values for configuration parameters that manage memory size, the size of the amount of data that can be sent over the route at one time, time-outs, and synchronization intervals. You can also set your own values when you create or alter the route.

Table 5-2 displays the route configuration parameters. If network-based security is enabled at your site, you can also configure security parameters for routes. Refer to “Managing Network-Based Security” on page 183.

Table 5-2: Configuration parameters affecting routes

route_param value

rsi_batch_size The number of bytes sent to another Replication Server before a truncation point is requested, which allows Replication Server to delete messages in the source RSI queue. The range is 1024 to 262,144.Default: 262,144 bytes

rsi_fadeout_time The number of seconds of idle time before Replication Server closes a connection with a destination Replication Server.Default: -1 (Replication Server does not close the connection)


127

Examples of Creating Direct and Indirect Routes

You need to create the direct routes from the primary Replication Server to the intermediate Replication Server and from the intermediate Replication Server to the destination Replication Server before you can create an indirect route.

The following examples are based upon Figure 5-2.

1 To create the direct route NY_RS to SF_RS in Figure 5-2, enter this command in the primary Replication Server, NY_RS:

create route to SF_RSset username SF_rsi_userset password SF_rsi_ps

2 To create the direct routes SF_RS to SAC_RS and SF_RS to SJ_RS in Figure 5-2, enter these commands in the intermediate Replication Server, SF_RS:

create route to SAC_RSset username SAC_rsi_userset password SAC_rsi_pscreate route to SJ_RSset username SJ_rsi_userset password SJ_rsi_ps

3 After these direct routes are created, you can create indirect routes through them. The following example creates the indirect routes from the primary site NY_RS to sites SAC_RS and SJ_RS, through the intermediate site, SF_RS. Enter these commands in the primary Replication Server, NY_RS:

create route to SAC_RSset next site SF_RScreate route to SJ_RSset next site SF_RS

rsi_packet_size Packet size, in bytes, for communications with other Replication Servers. The range is 1024 to 8192.Default: 2048 bytes

rsi_sync_interval The number of seconds between RSI synchronization inquiry messages. The Replication Server uses these messages to synchronize the RSI outbound queue with destination Replication Servers. The value must be greater than 0.Default: 60 seconds

save_interval The number of minutes that the Replication Server saves messages after they have been successfully passed to the destination Replication Server.Default: 0 minutes

route_param value

Creating Routes

128

An Example of Creating a Route and Configuring Parameters

This example is based on Figure 5-2. To set the rsi_packet_size to 4096 bytes for the route to SF_RS, enter:

create route to SF_RSset username SF_rsi_userset password SF_rsi_psset rsi_packet_size to ’4096’

Configuring a Replication Server to Manage Primary TablesIf you want to add a route from a Replication Server that was previously configured as a replicate-only Replication Server, you must first set up the RepAgent for the Replication Server’s RSSD. Any database that functions as a primary database also requires a RepAgent.

To set up RepAgent for the RSSD, follow these steps:

At the Replication Server

1 Create a RepAgent user so that RepAgent can log in to Replication Server. Use the create user command:

create user ra_user_nameset password {ra_password | null}

where ra_user_name is the name of the RepAgent user and ra_password is the RepAgent’s password.

Grant this user connect source permission, using the grant command:

grant connect source to ra_user_name

If the Replication Server already manages a primary database, you can use the “RepAgent user” that already exists for the new primary database.

2 Execute alter connection, using the log transfer on option:

alter connection to data_server.databaseset log transfer to ’on’

At the Adaptive Server 1 If the name of the Adaptive Server has not yet been defined, you must define it:

sp_addserver lname, local

where lname is the RSSD’s name.

2 If RepAgent threads have not been enabled for the Adaptive Server, you must enable them:


129

sp_configure ’enable rep agent threads’

3 Configure RepAgent for the RSSD with the sp_config_rep_agent system procedure:

sp_config_rep_agent dbname, ’enable’, ’rs_name’,’rs_user_name’, ’rs_password’

Refer to “Configuring RepAgent” on page 99 for detailed instruction on configuring RepAgent.

Note The “rs_user_name” and “rs_password” configured at the Adaptive Server must be the same as the “ra_user_name” and “ra_password” created at the Replication Server in step 1.

4 Create the rs_marker stored procedure and set its replicate status to “true,” using the sp_setrepproc system procedure with the function keyword.

You can find the rs_marker stored procedure in the file rs_install_primary.sql or rsinssys.sql in the scripts directory of the Sybase release directory.

See “Creating the rs_marker Stored Procedure” on page 162 for details.

5 Start RepAgent:


Refer to Appendix B, “LTM for SQL Server” for the procedure to use when your replication agent is the LTM.

Suspending and Resuming RoutesWhen you alter a direct route, change its topology, or perform some other maintenance to a remote site, you must suspend the route so that messages are no longer sent to the destination Replication Server. After maintenance is completed for the route, you can then reactivate the route to resume activity.

You can suspend and resume routes in Sybase Central or with the RCL commands suspend route and resume route.

For directions on suspending and resuming routes in Sybase Central, see “Suspending routes” and “Resuming routes” in Replication Server’s online help.

RSM

Changing Routes

130

The suspend route and resume route RCL commands are described in this section.

Using the suspend route CommandThe suspend route command suspends a route to another Replication Server. While a route is suspended, no messages are sent to the destination Replication Server, and the messages for the Replication Server are held in a stable queue. The syntax for the suspend route command is:

suspend route to dest_replication_server

For example, to suspend the route to the CHI_RS Replication Server, enter:

suspend route to CHI_RS

Using the resume route CommandThe resume route command resumes a suspended route. Resuming a route allows the source Replication Server to begin sending queued messages to the destination Replication Server. You can also use this command to resume a route that was suspended automatically as the result of an error. The syntax for the resume route command is:

resume route to dest_replication_server

For example, to resume the route to the CHI_RS Replication Server, enter:

resume route to CHI_RS

Changing RoutesYou can change a direct route’s topology, user name, password, and certain configuration parameters from Sybase Central or with the alter route command. You cannot change an indirect route’s parameters with alter route.

For information about altering routes from Sybase Central, see “Configuring Routes” on the Contents page of Replication Server’s online help.

The syntax for alter route is:

alter route to dest_replication_server{set next site [to] thru_replication_server |set username [to] ’user’ set password [to] ’passwd’ |

RSM


131

set password [to] ’passwd’ |set route_param [to] ’value’ |set security_param [to] ’value’ |set security_services [to] ’default’}

Refer to “Managing Network-Based Security” on page 183 for information about configuring security parameters for routes.

This section provides procedures and examples for using alter route to change a route’s topology, user name, and route configuration parameters. There is also a routing modification example.

Follow these steps when altering a route:

1 Suspend the route.

2 Execute alter route.

3 Resume the route. You must resume the route for the changes to take effect.

Changing Route TopologyYou can modify a route’s topology by:

• Changing a direct route to an indirect route

• Changing the next intermediate site for an indirect route

• Changing an indirect route to a direct route

Changing a Direct Route to an Indirect Route

To change an existing direct route to an indirect route, perform these steps:

1 At the source Replication Server, from which the direct route originates, enter:


2 At each Replication Server that manages a database with a RepAgent, enter:


and follow the instructions in “Quiescing a Replication System” on page 109. This procedure quiesces the replication system so that messages will be redirected to your new routing configuration without error.

Changing Routes

132

3 Create any additional routes that the new indirect route will use. See “Creating Routes” on page 124 for details.

• If the current Replication Server does not already have a direct route to the Replication Server that you will specify as the intermediate site for the new indirect route, create the route.

• If the Replication Server that you will specify as the intermediate site for the new indirect route does not already have a direct or indirect route to the destination site, create the route.

4 For the direct route you are changing to an indirect route, enter the following command at the source Replication Server:

alter route to dest_replication_serverset next site [to] thru_replication_server

where dest_replication_server is the destination Replication Server for the route you are altering, and thru_replication_server is the intermediate Replication Server for the route.

5 Resume log transfer connections by entering the following command at each Replication Server where you previously suspended log transfer:


6 At the source Replication Server, resume the suspended route by entering the following command:


Changing the Next Intermediate Site for an Indirect Route

To change the next intermediate site for an existing indirect route, perform the following steps.

1 Enter the following command at the source Replication Server, from which the direct route originates:






133

3 Create any additional routes that the indirect route will use. See “Creating Routes” on page 124 for details.

• If the current Replication Server does not already have a direct route to the Replication Server that you will specify as the new intermediate site for the indirect route, create the route.

• If the Replication Server that you will specify as the new intermediate site for the indirect route does not already have a direct or indirect route to the destination site, create the route.

4 For the indirect route for which you are specifying a new intermediate Replication Server, enter the following command at the source Replication Server:

alter route to dest_replication_serverset next site thru_replication_server

where dest_replication_server is the destination Replication Server for the route you are altering, and thru_replication_server is the new intermediate Replication Server for the route.



6 Resume the suspended route by entering the following command at the source Replication Server:


Changing an Indirect Route to a Direct Route

To change an existing indirect route to a direct route, perform the following steps.

1 Enter the following command at the source Replication Server, from which the indirect route originates:





Changing Routes

134

3 For the indirect route you are changing to a direct route, enter the following command at the source Replication Server:

alter route to dest_replication_serverset username user set password passwd

where dest_replication_server is the destination Replication Server for the route you are altering, and user and passwd are the RSI user login name and password to use for the direct route.



5 Resume the suspended route by entering the following command at the source Replication Server:


Changing the Password for the RSI User for a Direct RouteTo change the password for the RSI user for an existing direct route, perform the following steps.

1 Suspend each direct route from the source Replication Server by entering:


2 At the source Replication Server, enter:

alter route to dest_replication_serverset password passwd

where dest_replication_server is the destination Replication Server for the route you are altering, and passwd is the password to use for the RSI user login name.

3 Resume each suspended route from the source by entering:


Changing Parameters Affecting Direct RoutesAfter a route is created, you can change its configuration parameters with Sybase Central or the alter route command. Refer to Table 5-2 on page 126 for a list and descriptions of configuration parameters that affect routes.


135

See “Configuring Routes” in Replication Server’s online help for instructions on changing a route’s configuration parameters using Sybase Central.

To change default configuration parameters for all routes originating at the source Replication Server, use the configure replication server command. Refer to “Changing Configuration Parameters for All Routes” on page 135 for more information.

Here is an example of using alter route to change the rsi_sync_interval parameter to 120 seconds. To execute the command, log in to the source Replication Server and perform these steps:

1 Suspend the route. Enter:


2 Execute the alter route command. Enter:

alter route to dest_replication_serverset rsi_sync_interval to ’120’

3 Resume the suspended route by entering:


Configuration changes take effect after you resume the route.

Changing Configuration Parameters for All Routes

To set default configuration parameters for all routes originating at the source Replication Server, use the configure replication server command. Table 5-2 on page 126 has a list and descriptions of configuration parameters that you can set.

Configuration parameters set for individual routes with alter route override default parameters set with configure replication server. Thus, you can set default parameters with configure replication server and then customize settings for individual routes with alter route.

The syntax for changing route parameters with configure replication server is:

configure replication server set route_param to ’value’

Here is an example of using configure replication server to change the rsi_save_interval parameter to 2 minutes for all routes originating at the Replication Server. To execute the command, log in to the source Replication Server and perform the following steps:

RSM

Changing Routes

136

1 Suspend all routes from the source Replication Server. For each route, enter:


2 Execute the configure replication server command:

configure replication server set rsi_save_interval to ’2’

3 Resume suspended routes from the source Replication Server. For each route, enter:


Configuration changes take effect after you resume the routes.

Routing Modification ExampleFigure 5-6 revises the routes illustrated in Figure 5-2 on page 121. LA_RS becomes an intermediate site between NY_RS and SF_RS, while direct and indirect routes to SB_RS are dropped.

Figure 5-6: Indirect routes altered

New York

Los Angeles

San Diego

San Jose

NY_RS

LA_RS

San FranciscoSF_RS

SacramentoSAC_RS SJ_RS

SD_RS


137

Here’s how you would revise the routing scheme shown in Figure 5-2 to resembles the scheme in Figure 5-6.




2 LA_RS needs a direct route to SF_RS; create one by entering the following command at Replication Server LA_RS:

create route to SF_RSset username SF_rsi_userset password SF_rsi_ps

3 LA_RS requires indirect routes to SAC_RS and SJ_RS, through SF_RS.

Creating these routes instructs LA_RS to send messages to SF_RS that are destined for SAC_RS and SJ_RS. SF_RS already has direct routes to SAC_RS and SJ_RS. Enter the commands in Replication Server LA_RS:

create route to SAC_RSset next site SF_RScreate route to SJ_RSset next site SF_RS

4 The primary Replication Server, NY_RS, was previously configured with indirect routes through SF_RS to SAC_RS and SJ_RS. Alter those routes so that Replication Server LA_RS is the next Replication Server. Enter these commands in Replication Server NY_RS:

alter route to SAC_RSset next site LA_RSalter route to SJ_RSset next site LA_RS

5 The direct route from the primary Replication Server, NY_RS, to SF_RS needs to be changed to an indirect route, with LA_RS as the intermediate Replication Server. Enter these commands in Replication Server NY_RS:

alter route to SF_RSset next site LA_RS

6 At each Replication Server where you previously suspended log transfer, resume log transfer connections to each Replication Server by entering:


Dropping Routes

138

See Chapter 4, “Managing a Replication System” for more information on resuming log transfer.

7 Remove the indirect route from NY_RS to SB_RS. Enter this command in NY_RS:

drop route to SB_RS

8 Remove the direct route from LA_RS to SB_RS. Enter this command in LA_RS:

drop route to SB_RS

The indirect route from NY_RS to SD_RS, through LA_RS, is intact.

Dropping RoutesYou can drop routes from Sybase Central or from the command line with the drop route command.

See “Dropping routes” in Replication Server’s online help for instructions on dropping routes using Sybase Central.

Dropping a route closes the route from the Replication Server where you execute the command to a specified remote Replication Server. It performs the following actions on participating Replication Servers:

• Drops system table subscriptions.

• If the route is direct, the outbound stable queue is dropped and the RSI thread is stopped.

• Deletes information regarding the route.

You cannot drop the route if:

• It is a direct route used by any indirect routes to additional destination Replication Servers.

• The source Replication Server has replication definitions that are subscribed to by the destination Replication Server.

• The source Replication Server is designated as the primary site of a function-string class or error class. The primary site of a derived function-string class is the same as its parent class.

You can monitor the status of the route while it is being dropped:

RSM


139

• In Sybase Central, view status information in the right pane of the Sybase Central main window.

• From the command line, execute the rs_helproute stored procedure.

Using the drop route CommandThe syntax for the drop route command is:

drop route to dest_replication_server [with nowait]

The with nowait option instructs Replication Server to close the route even if it is unable to communicate with the destination Replication Server.

Warning! Use the with nowait clause only if you do not intend to ever use the destination Replication Server, or if you must drop the route from the source Replication Server while the destination Replication Server is unavailable, or if you are attempting to add or change login names and passwords for direct routes. Avoid using the with nowait clause whenever possible.

After you use drop route with the with nowait clause, use the sysadmin purge_route_at_replicate command to remove all references to a primary Replication Server from the Replication Server at the replicate site.

Using the sysadmin purge_route_at_replicate CommandThe sysadmin purge_route_at_replicate command removes all subscriptions and route information originating from a specified primary Replication Server after a route is dropped from that server. Before you execute this command, drop the route from the replicate Replication Server to the primary Replication Server, if it exists. The Replication Server performs a validation check before it processes the command.

Execute sysadmin purge_route_at_replicate at the replicate Replication Server, using this syntax:

sysadmin purge_route_at_replicate, replication_server

where replication_server is the primary Replication Server.

Upgrading Routes

140

Upgrading RoutesThe route version is the earliest site version of the source and destination Replication Server. After you upgrade the source and destination Replication Servers on either end of a route to version 11.5 or later and also set their site versions to a higher Replication Server version, you need to upgrade the route. Upgrading the route allows the Replication Servers to exchange information about newer software features.

Upgrading a route rematerializes data in system tables, making information associated with new features available to a newly upgraded Replication Server. After upgrading, new types of information that were not previously allowed can be exchanged.

To display the current version number of routes that originate or terminate at a Replication Server, use the admin show_route_versions command. Refer to “admin show_route_versions” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for complete syntax and usage information.

You can use Sybase Central or command line options to upgrade a route to match the site version of the route’s source and destination Replication Servers.

There are three possible scenarios for route upgrade:

• If you have RSM Client, see “Upgrading routes” in Replication Server’s online help for more information.

• If there is no RSM Client and if new features have not been used at the source Replication Server, use sysadmin fast_route_upgrade to upgrade routes.

• In all other cases, use the RSM Server commands route_upgrade, route_upgrade_recovery, and route_upgrade_status to upgrade routes.

You cannot downgrade a route after you have upgraded it.

See “Mixed-Version Replication Systems” on page 18 for more information about site versions and system versions.

See the installation and configuration guides for your platform for more information about upgrading routes and setting the site version for a Replication Server.

RSM


141

Monitoring RoutesRoutes may display different statuses at different times. When you create a route, the destination Replication Server subscribes to the source Replication Server’s system tables. Depending on the volume of your data, it may take several minutes for subscriptions to materialize. Dropping a route also may take some time.

• You can use Sybase Central to check on the status of routes (except routes you are creating) and threads.

• For directions on viewing route status information, see “Viewing route properties or status” in Replication Server’s online help.

• For directions on viewing thread status information in Sybase Central, see “Viewing thread status.”

• You can use the admin who command to display thread status information.

• For comprehensive status information, including the current state of routes you are creating, use rs_helproute, described in “Using the rs_helproute Stored Procedure” on page 141.

Displaying RSI Thread Status Using admin whoTo view status information about RSI threads, use the admin who command:

• admin who displays all threads in the system, including RSI threads.

• admin who, rsi displays the status of the RSI thread, which Replication Server starts to submit information to other Replication Servers.

Refer to “admin who” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for detailed thread status information.

Using the rs_helproute Stored ProcedureExecute the Adaptive Server stored procedure rs_helproute in the RSSD at the source or destination Replication Server for the route. The syntax for the rs_helproute stored procedure is:

rs_helproute [replication_server]

RSM

Monitoring Routes

142

If you specify the name of a Replication Server, rs_helproute returns information only for routes for which the named Replication Server is a source or destination. Otherwise, it returns information for all routes for which the current Replication Server is a source or destination.

rs_helproute returns two types of information:

• Route status, which reflects the state of the route at the site where rs_helproute is executed. A route is valid when rs_helproute at both source and destination returns “Active.”

Other route status values are:

• Being created

• Being dropped

• Being dropped with nowait

• List of system table subscriptions, which tells you the system table subscriptions that are being created. If a route is being dropped, it tells you which subscriptions are being dropped.

If no system table subscriptions are listed, the route has been created and is in working order.

Refer to the Replication Server Troubleshooting Guide for information about correcting route creation problems.

143

C H A P T E R 6 Managing Database Connections

This chapter describes connecting databases to a replication system and managing those database connections.

Preparing Databases for ReplicationBefore you can add databases to a replication system, you need to prepare them so that Replication Server can distribute the primary data and maintain the replicated data stored in them.

• If your databases are managed by Sybase Adaptive Servers:

Use Sybase Central or rs_init to prepare Adaptive Server databases for use with Replication Server. For information about Sybase Central, refer to Replication Server’s online help. rs_init is described in the Replication Server installation and configuration guides for your platform.

• If your databases are managed by non-Sybase data servers:

Refer to the Replication Server Design Guide for required preparations. In addition, to find out how to prepare your database for the heterogeneous dataype support (HDS) feature, see the Replication Server Configuration Guide for your platform. HDS enables the translation of primary database column values of one datatype to another datatype acceptable to the replicate database.

Refer to “Translating Datatypes Using HDS” on page 281 for more information about HDS.

When you are connecting a new database to an existing system, always conduct a careful review and analysis of how the database will fit into your system. Determine which other processes are required for the database, and designate required names and login names for these processes.

Preparing Databases for Replication

144

If you anticipate that an existing “replicate-only” database may in the future be the source of replicated function delivery or contain primary data, you can set up the database so that it can manage primary tables. You can then avoid upgrading the replicate-only database in the future.

Steps in Preparing Databases for Replication

Note To prepare non-Sybase databases for replication, use instructions in your Sybase replication agent documentation, the Replication Server Configuration Guide for your platform, and the Replication Server Design Guide to perform these steps.

To prepare Adaptive Server databases for replication, use Sybase Central or rs_init to perform these steps:

• Create the rs_lastcommit system table.

• Load the rs_update_lastcommit and rs_get_lastcommit stored procedures (for both primary and replicate databases) and the rs_marker stored procedure (for primary databases only).

• Create the rs_threads system table.

• Load the rs_initialize_threads and rs_update_threads stored procedures for the database.

• Create the maintenance user login name and verifies that the maintenance user can log in to the database. For details, see “Managing Maintenance User Login Names” on page 145.

• Create a connection from Replication Server to the database, allowing Replication Server to manage the database.

• If the database has primary data, Sybase Central or rs_init:

• Enables RepAgent at the Adaptive Server.

• Enables and configures RepAgent at the database.

• Sets the secondary truncation point to “valid” in the Adaptive Server database, preventing Adaptive Server from truncating database log records before RepAgent has read them.

• Creates the RepAgent user name and password in the Replication Server, if necessary.

CHAPTER 6 Managing Database Connections

145

• Starts RepAgent.

Refer to the Replication Server installation and configuration guides for your platform for details on each step.

Upgrading an Existing Adaptive Server DatabaseYou may need to upgrade a database to work with the latest version of Replication Server so that you can use newer features such as schema replication and RepAgent threads. Use rs_init to upgrade a database.

Upgrading a database ensures that the database maintenance user has the Replication role and the necessary permissions (update, insert, and delete) in the database. The Replication role gives the maintenance user authorization to execute any necessary replication-related Adaptive Server commands.

You can check the authorizations that have been granted to a database by using the sp_displaylogin system procedure in the database.

To grant the Replication role to the maintenance user, execute the following system procedure in the database:

sp_role "grant", replication_role, maintenance_user

If you need to grant permissions on the tables in the database, execute the following command in the database for each table:

grant all on table_name to maintenance_user

Managing Maintenance User Login NamesTo update replicated data, Replication Server logs in to the data server as the maintenance user. The Database Owner or the System Administrator must grant to the maintenance user the permissions required to insert, delete, and update rows in replicated tables and to execute replicated stored procedures.

Initially, Sybase Central or rs_init creates the login name for the maintenance user and adds the user to the replicate database. For details, refer to the Replication Server installation and configuration guides for your platform.

Managing Maintenance User Login Names

146

The maintenance user login name and password are provided to Replication Server with the create connection command for the database. Sybase Central or the rs_init program executes this command automatically. If you change the password for the login name in the data server, use Sybase Central or the alter connection command to change the password for the Replication Server connection.

Finding the Current Maintenance UserTo determine the login name that is currently assigned as maintenance user for a database, you can:

• See “Viewing database connection properties” in Replication Server’s online help.

• Enter the rs_helpuser Adaptive Server stored procedure at the RSSD:

rs_helpuser [user]

where user is the login name about which you want information.

Granting Permissions in the DatabaseEither Sybase Central or rs_init grants the maintenance user permission to access the rs_lastcommit system table and the stored procedures that use it.

Neither Sybase Central nor rs_init grants permissions to the maintenance user for user tables and stored procedures. You must grant permissions on replicated tables and stored procedures before you can either replicate transactions for replicated tables or replicate executions of the replicated stored procedures.

For each table that is replicated in the database, and for each stored procedure that is executed due to replication, execute the following grant command:

grant all on table_name to maint_user

Note Among the permissions granted to the maintenance user is replication_role. If you revoke this permission, you will not be able to replicate truncate table unless the maintenance user has been granted sa_role, owns the table, or is aliased as the Database Owner.

RSM


147

Granting Permissions for a Primary Database

If a replicate database holds primary data, then it is also a primary database. In a primary database, special permissions are necessary on two replication objects: subscriptions and request functions.

When subscriptions are created, the rs_marker stored procedure is executed at the primary database. Any database user who can create subscriptions must have permission to execute rs_marker.

A primary database may also receive transactions via request function delivery from clients at replicate sites. These transactions are executed at the primary site as if by the user executing the request function. Any user login name with permission to execute request functions must also have permission to execute rs_update_lastcommit, which executes in every DSI transaction.

The permission requirements are the same for request functions and request stored procedures. See Chapter 9, “Managing Replicated Functions” for more information on using request functions.

The following grant commands allow any user in the database to execute rs_marker and rs_update_lastcommit:

grant execute on rs_marker to publicgrant execute on rs_update_lastcommit to public

These stored procedures should only be executed by Replication Server on behalf of users. Sybase Central or rs_init grants these permissions to “public.” You may want to restrict permissions to the database users who are allowed to create subscriptions, execute request functions, or request stored procedures.

Creating Database ConnectionsA connection defines a database to the Replication Server. A Replication Server is designated to manage the database and, if it is a replicate database, to distribute transactions to the database. The database connection provides Replication Server with:

• The name of the data server and database the connection is for

• The error class used to process errors returned from the data server

• The function-string class to use with the database

• The maintenance user login name and password

Creating Database Connections

148

• Information about whether there is a RepAgent thread for the database connection

• Options for creating active and standby databases for warm standby applications

• Configuration parameters that affect connections

You can create a database connection in these ways:

• To create a standard connection to an Adaptive Server database, use Sybase Central or rs_init.

• To create a connection to a non-Sybase database, use the create connection command.

Information for Adding a Database ConnectionThe Replication Server installation and configuration guides for your platform describe how you use rs_init to add databases.

Replication Server’s online help provides instructions for adding Adaptive Server database connections to a replication system in Sybase Central.

See “Creating database connections” in Replication Server’s online help.

When you add a database, you specify:

• Replication Server name

• Replication Server System Administrator user name and password

• Adaptive Server name

• Adaptive Server System Administrator user name and password

• Database name

• Whether the database requires a RepAgent

• Maintenance user name and password

• Database Owner user name and password

• Whether the physical connection is for an existing logical connection

RSM


149

Adding Databases for Logical Connections

If you are adding a physical connection for an existing logical connection (which you create with Sybase Central or the create logical connection command), you also specify the following information:

• Active or standby connection

• Logical data server name

• Logical database name

In addition, if you are adding a standby connection, you specify the following information in Sybase Central or rs_init:

• Active data server name

• Active database name

• Active database System Administrator user name and password

• Whether to initialize standby database using dump and load method

• Whether to use dump marker to start replication

See Chapter 13, “Managing Warm Standby Applications” for more information about warm standby operations.

For instructions on using heartbeats in Sybase Central, see “Creating a logical connection” in Replication Server’s online help.

Adding a Database That Requires a RepAgent Thread

If you are adding an Adaptive Server primary database that requires a RepAgent, you specify the Replication Server user name and password.

Using the create connection CommandTo add a database for a non-Sybase data server, use the create connection command.

To add a database for a Sybase data server, you normally use Sybase Central or rs_init, both of which prepare the database for replication. If you use create connection, you must prepare the database for replication yourself. Refer to “Steps in Preparing Databases for Replication” on page 144.

Enter create connection at the Replication Server that is to manage the database. The syntax is:

RSM

Altering Database Connections

150

create connection to data_server.databaseset error class [to] error_classset function string class [to] function_classset username [to] user[set password [to] passwd][set database_param [to] ’value’][set security_param [to] {‘required’ | ‘not_required’}][with {log transfer on, dsi_suspended}][as active for logical_ds.logical_db |as standby for logical_ds.logical_db[use dump marker]

You must use the with dsi_suspended clause, which starts the connection with the DSI suspended, when you create a connection to a database that will not be a replicate database.

The as active, as standby, and use dump marker clauses are used only when you create physical connections for a logical connection for a warm standby database. Only Adaptive Server and SQL Server databases may be used in warm standby applications.

If your system supports network-based security, use the set security_param [to] {‘required’ | ‘not_required’}] option according to instructions in “Managing Network-Based Security” on page 183.

Refer to “create connection” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for more information about the create connection command.

Altering Database ConnectionsTo change the attributes of a database connection, use Sybase Central or perform the following steps at the Replication Server where the connection was created:

1 Use suspend connection to suspend activity on the connection. See “Suspending Database Connections” on page 151 for details.


151

2 Execute the alter connection command. See “Setting and Changing Parameters Affecting Physical Connections” on page 152 for detailed instructions.

Note Using the set log transfer off clause for the alter connection command drops the RepAgent connection from a primary site. Before using this clause, be sure there are no replication definitions defined for data in the database.

3 Use resume connection to resume activity on the connection. See “Resuming Database Connections” on page 160 for more information.

For instructions on changing the attributes of a connection in Sybase Central, see “Altering database connections” in Replication Server’s online help.

When you alter a connection in Sybase Central, you do not need to suspend or resume connections yourself; RSM Server performs these tasks for you.

Suspending Database ConnectionsIf you have sa permission, you can temporarily suspend access to a data server. You must suspend a database connection before you alter it or when you remove a data server from service for maintenance.

While data server access is suspended, the Replication Server queues transactions for the data server so they can be applied when the connection is resumed.

You can temporarily suspend access to a data server using Sybase Central or you can use the following command:

suspend connection to data_server.database[with nowait]

By default, suspend connection completes the current transaction before suspending. Use the with nowait clause to suspend the connection in mid-transaction. This may be appropriate if a large transaction is responsible for a failure in a replicate database.

For instructions on suspending a connection in Sybase Central, see “Suspending database connections” in Replication Server’s online help.

RSM

RSM


152

Setting and Changing Parameters Affecting Physical ConnectionsYou set configuration parameters for a connection when you create it. Later, you can update those parameters with Sybase Central or the alter connection command.

For information on altering database parameters in Sybase Central, see “Altering database connections” in Replication Server’s online help.

You can change the configuration of either a single database connection or of all database connections that originate from a single Replication Server. If you are adding many database connections to a Replication Server, you may want to change configuration parameters affecting all connections in order to fine-tune server performance.

To change configuration parameters for all connections originating at the current Replication Server, use the configure replication server command. Refer to “Changing Parameters Affecting All Connections” on page 158 for more information.

Configuration parameters that are set for individual connections with alter connection override parameters that are set with configure replication server. Thus, you can set default parameters with configure replication server and then customize settings for specific connections with alter connection.

Changing Parameters Affecting a Single Connection

After a connection is created, you can change its configuration parameters with the alter connection command. Refer to Table 6-1 on page 154 for a list and description of configuration parameters that affect connections.

Using the alter connection Command

alter connection lets you change the attributes of a database connection. Use this command, for example, if you have added an Adaptive Server database connection using Sybase Central or rs_init, and then decide that you want the database connection to use a derived function-string class instead of a system-provided class. The syntax for alter connection is:

alter connection to data_server.database {set function string class [to] function_class |set error class [to] error_class |set password [to] passwd |set log transfer [to] {on | off} |set database_param [to] ’value’} |set security_param to {‘required’ | ‘not_required’} |set security_services [to] “default’

}

RSM


153

You indicate the data server and database that is connected to the Replication Server and specify one or more of the attributes to change. These include:

function_class – the function-string class to use with the database connection.

error_class – the error class to use for handling database errors.

passwd – the new password to use with the login name for the database connection.

log transfer on – allows transactions to be sent, using this connection, to the Replication Server.

log transfer off – stops transactions from being sent, using this connection, from a primary database to the Replication Server.

database_param – updates a configuration parameter that affects connections. See Table 6-1 for a list of parameters you can change.

security_param – updates a network security configuration parameter that affects connections. See “Managing Network-Based Security” on page 183 for a list and description of parameters you can change.

set security_services [to] ‘default’ – resets all network-based security features for the connection to “not required.” See “Managing Network-Based Security” on page 183 for a description of network security for Replication Server.

An Example of Using alter connection

To change the function-string class for the pubs2 database in the SYDNEY_DS data server to sqlserver_derived_class, enter the following commands in the SYDNEY_RS Replication Server:

suspend connection to SYDNEY_DS.pubs2alter connection to SYDNEY_DS.pubs2

set function string to classsqlserver_derived_class

resume connection to SYDNEY_DS.pubs2

Refer to “alter connection” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for more information about the keywords and options of the alter connection command.


154

Configuration Parameters Affecting Connections

Table 6-1 displays the configuration parameters that affect database connections. (These configuration parameters affect physical database connections only. For parameters that affect logical database connections, see “Changing Parameters Affecting Logical Connections” on page 452.)

If your system supports network-based security, refer to “Managing Network-Based Security” on page 183 for information about security parameters that affect connections.

Table 6-1: Configuration parameters affecting connections

Parameter (database_param) Value (value)

batch The default, “on,” allows command batches to a replicate database.Default: on

batch_begin Indicates whether a begin transaction can be sent in the same batch as other commands (such as insert and delete).Default: on

command_retry The number of times to retry a failed transaction. The value must be greater than or equal to 0.Default: 3

db_packet_size The maximum size of a network packet. During database communication, the network packet value must be within the range accepted by the database. You may change this value if you have a System 10 or later SQL Server or Adaptive Server that has been reconfigured.Default: 512-byte network packet for all Adaptive Server databases

dsi_charset_convert The specification for handling character set conversion. This parameter applies to all data and identifiers to be applied at the DSI in question. The values are:

• “on” – convert from the primary Replication Server character set to the replicate Replication Server character set; if character sets are incompatible, shut down the DSI with an error.

• “allow” – convert where character sets are compatible; apply any unconverted updates to the database, as well.

• “off” – do not attempt conversion. This option is useful if you have different but compatible character sets and do not want any conversion to take place. During subscription materialization, a setting of “off” behaves as if it were “allow.”

Default: on

dsi_cmd_batch_size The maximum number of bytes that Replication Server places into a command batch.Default: 8192 bytes


155

dsi_cmd_separator The character that separates commands in a command batch.For example, if you have specified a different separator character and want to change it back to the default character, enter:

alter connection to data_server.databaseset dsi_cmd_separator to ’<Return>’

Press the Return key, and no other characters, between the two single-quote characters.Default: newline (\n)

dsi_exec_request_sproc Turns on or off request stored procedures at the DSI of the primary Replication Server.Default: on

dsi_fadeout_time The number of seconds of idle time before a DSI connection is closed. -1 means to never fade out a connection.Default: 600 seconds

dsi_keep_triggers Specifies whether triggers should fire for replicated transactions in the database.Set to “off” to cause Replication Server to set triggers off in the Adaptive Server database, so that triggers do not fire when transactions are executed on the connection. Use this setting for standby databases.Set to “on” for all databases except standby databases.Default: on (except standby databases)

dsi_large_xact_size The number of commands allowed in a transaction before the transaction is considered to be large for using a single parallel DSI thread. The minimum value is 4.Default: 100

dsi_max_cmds_to_log The number of commands to write into the exceptions log for a transaction.Default: -1 (all commands)

dsi_max_text_to_log The number of bytes to write into the exceptions log for each rs_writetext function in a failed transaction. Change this parameter to prevent transactions with large text or image columns from filling the RSSD or its log.Default: -1 (all text and image columns)

dsi_num_large_xact_threads The number of parallel DSI threads to be reserved for use with large transactions. The maximum value is one less than the value of dsi_num_threads.Default: 0

dsi_num_threads The number of parallel DSI threads to be used. The maximum value is 20.Default: 1



156

dsi_replication Specifies whether or not transactions applied by the DSI are marked in the transaction log as being replicated.When dsi_replication is set to “off,” the DSI executes set replication off in the Adaptive Server database, preventing Adaptive Server from adding replication information to log records for transactions that the DSI executes. Since these transactions are executed by the maintenance user and, therefore, usually not replicated further (except if there is a standby database), setting this parameter to “off” avoids writing unnecessary information into the transaction log.dsi_replication must be set to “on” for the active database in a warm standby application for a replicate database, and for applications that use the replicated consolidated replicate application model.Default: off (“on” for active database in a warm standby application)

dsi_serialization_method Specifies the method used to maintain serial consistency between parallel DSI threads, when applying transactions to a replicate data server.

• “isolation_level_3” specifies that transaction isolation level 3 locking be used in the replicate data server.

• “single_transaction_per_origin” prevents conflicts by allowing only a single active transaction from a primary data server.

• “wait_for_commit” maintains transaction serialization by instructing the DSI to wait until one transaction is ready to commit before initiating the next transaction.

• “none” assumes that your application is designed to avoid conflicting updates, or that lock protection is built into your database system.

Default: “wait_for_commit”



157

dsi_sql_data_styleNote This parameter is necessary only for connections to pre-version 12.0 Adaptive Servers.

Formats datatypes (particularly date/time, binary, bit and money) to be compatible with:

• DB2 (“db2”)

• Lotus Notes (“notes”), or

• SQL Anywhere, formerly Watcom SQL (“watcom”), or

• SQL Remote (“sqlremote”)

To support Transact-SQL, set this parameter to any value except those shown above.When you are configuring a connection to DB2, also specify the name of the NetGateway using the data_server parameter in the main clause of the alter connection command.When you are configuring a connection to Lotus Notes, SQL Anywhere, or any other ODBC data source, specify the connection as replication_driver_name.odbc_data_source_name. Refer to the Replication Driver for ODBC User’s Guide for more information.Default: “ ” or “sql” (for Adaptive Server)

dsi_sqt_max_cache_size Maximum SQT (Stable Queue Transaction) interface cache memory for the database connection, in bytes.The default, 0, means the current setting of the sqt_max_cache_size parameter is used as the maximum cache size for the connection. To confirm the current value of thesqt_max_cache_size parameter, execute the rs_configure stored procedure.This parameter controls the use of parallel DSI threads for applying transactions to a replicate data server.Default: 0

dsi_xact_group_size The maximum number of bytes, including stable queue overhead, to place into one grouped transaction. A grouped transaction is a set of transactions that the DSI applies as a single transaction. -1 means no grouping.Default: 65,536 bytes

dump_load Set to “on” at replicate sites only to enable coordinated dump. See “Loading from Coordinated Dumps” on page 536 for details.Default: off

ha_failover Set to “on” to enable Sybase Failover support for new database connections from the Replication Server to Adaptive Servers.

Default: off



158

Changing Parameters Affecting All Connections

To set default configuration parameters for all connections originating at the source Replication Server, use the configure replication server command. Refer to Table 6-1 for a list of configuration parameters that affect connections that you can set with configure replication server.

The syntax for configure replication server is:

configure replication server set database_param to ’value’

Example 1 Here is an example of using configure replication server to change the dsi_fadeout_time parameter so that the DSI connection does not close. Log in to the source Replication Server and enter:

1 Suspend all connections from the source Replication Server. For each connection, enter:

suspend connection to data_server.database

2 Execute configure replication server. Enter:

configure replication serverset dsi_fadeout_time to ’-1’

md_source_memory_pool Bytes of memory available for holding pending writes for each source database. The allowed range is 65,536 to 983,040.

Note This configuration parameter affects the source database, not the destination database. It cannot be set with the alter connection command.

Default: 100,000 bytes

parallel_dsi Provides a shorthand method for configuring parallel DSI threads.A setting of “on” sets dsi_num_threads to 5, dsi_num_large_xact_threads to 2, dsi_serialization_method to “wait_for_commit”, and dsi_sqt_max_cache_size to 1 million bytes.A setting of “off” sets these parallel DSI values to their defaults.You can set this parameter to “on” and then set individual parallel DSI configuration parameters to fine-tune your configuration.Default: off

save_interval The number of minutes that the Replication Server saves messages after they have been successfully passed to the destination data server.Default: 0 minutes



159

3 Resume suspended connections from the source Replication Server. For each connection, enter:

resume connection to data_server.database

Configuration changes take effect after you resume the connections.

Example 2 Here is an example of using configure replication server to change the ha_failover parameter to enable Failover support for all non-RSSD connections from a Replication Server to Adaptive Servers.

1 Execute configure replication server. Log in to the Replication Server for which you want to enable Failover support and enter:


Note You can also enable Failover support for non-RSSD connections from a Replication Server or RSM Server to Adaptive Servers using the Replication Server Manager plug-in to Sybase Central. See “Configuring the Replication System to Support Sybase Failover” in Chapter 16, “Replication System Recovery,” of the Replication Server Administration Guide

Configuration changes take effect after you resume the connections.

Changing Replication Server Connection Parameters to Improve Performance

If you are adding many new connections, you may want to change the memory_limit or num_threads Replication Server parameters to improve performance.

Increasing the memory_limit Parameter

To increase the amount of memory specified for Replication Server, increase the value specified for the memory_limit parameter by using configure replication server at Replication Server.

For example, execute configure replication server in the following manner to increase memory_limit to 25MB:

configure replication serverset memory_limit to ’25’

Increasing the num_threads Parameter

You may need to increase the number of Open Server threads that the Replication Server can use. To do this, increase the value specified for the num_threads parameter, using configure replication server at the Replication Server.


160

For example, execute configure replication server in the following manner to increase num_threads to 70:

configure replication serverset num_threads to ’70’

See Table 4-3 on page 99 for more information about the memory_limit and num_threads parameters.

Resuming Database ConnectionsOnce you have changed the attributes of a database connection, you can resume activity on the connection either in Sybase Central or by using the resume connection command.

For information about resuming a connection in Sybase Central, see “Resuming database connections” in Replication Server’s online help.

To resume a database connection from the command line, enter:

resume connection to data_server.database[skip transaction | execute transaction]

When the connection is resumed, Replication Server retrieves rows from the rs_lastcommit system table so that it can find the correct place in the transaction stream to begin submitting transactions.

The optional skip transaction clause instructs Replication Server to resume execution with the second transaction in the connection’s queue. The first transaction is written to the exceptions log.

The skip transaction clause is necessary if the first transaction causes Replication Server to suspend the connection and the cause of the failure cannot be corrected. For example, the transaction may have produced a data server error that is assigned the retry_stop or stop_replication error action. Or, perhaps it was necessary to use suspend connection and the with nowait clause to manually interrupt the transaction.

Warning! If you execute resume connection with the skip transaction clause, you must correct any inconsistency that results from the lost transaction. Only use the skip transaction clause when the condition causing the transaction to fail cannot be corrected.

RSM


161

The optional execute transaction clause instructs Replication Server to execute the first transaction in the connection’s queue. Use this clause only when a system transaction has failed to execute. See “Duplicate Detection for System Transactions” on page 515 for information about error handling for system transactions.

Changing Replicate Databases to Primary DatabasesEach primary database must have a replication agent that scans the database log and transfers data to the Replication Server for distribution to replicate databases. If you want to change an Adaptive Server database that is designated as replicate-only to be a source of replicated functions or to contain primary data, you must enable the RepAgent thread for the database by following these steps:


1 Create a RepAgent user so that RepAgent can log in to Replication Server.

Use the create user command:

create user ra_user_nameset password {ra_password | null}

where ra_user_name is the name of the RepAgent user and ra_password is the RepAgent’s password.


grant connect source to ra_user_name


2 Execute the alter connection command using the log transfer on option:

alter connection to data_server.databaseset log transfer to ’on’

At the Adaptive Server 1 If the name of the local Adaptive Server has not yet been defined, you must define it:

sp_addserver lname, local

where lname is Adaptive Server’s name.

2 If RepAgent threads have not been enabled for the Adaptive Server, you must enable them:

sp_configure ’enable rep agent threads’


162

3 Configure RepAgent for the database with the sp_config_rep_agent system procedure:

sp_config_rep_agent dbname, ’enable’, ’rs_name’,’rs_user_name’, ’rs_password’

Refer to “Configuring RepAgent” on page 99 for detailed instruction on configuring RepAgent.

Note The “rs_user_name” and “rs_password” configured at the Adaptive Server must be the same as the “ra_user_name” and “ra_password” created at the Replication Server in step 1.

4 Create the rs_marker stored procedure and set its replicate status to “true”, using the sp_setreplicate system procedure.

You can find the rs_marker stored procedure in the file rs_install_primary.sql or rsinssys.sql in the scripts directory of the Sybase release directory.

See “Creating the rs_marker Stored Procedure” on page 162 for details.

5 Start RepAgent:


Refer to Appendix B, “LTM for SQL Server” for the procedure to use when your replication agent is the LTM.

Creating the rs_marker Stored Procedure

Replication Server executes the rs_marker system function in a primary database during subscription materialization. The function works by executing a replicated stored procedure that is also named rs_marker. The procedure checks to make sure it is marked replicated and issues a warning if it is not. Because the rs_marker stored procedure is replicated, Adaptive Server records its executions in the transaction log for the database, where they can be read by RepAgent.

Sybase Central and rs_init create rs_marker when you designate a database as having primary data. It is not required in databases that have no primary data. The exact text of the stored procedure can always be found in rs_install_primary.sql or rsinssys.sql in the scripts directory of the Sybase release directory.

Here is a sample text:


163

create procedure rs_marker@rs_api varchar(255)

asdeclare @rep_constant smallintselect @rep_constant = -32768if not exists (select sysstat from sysobjects

where name = ’rs_marker’and type = ’P’and sysstat & @rep_constant != 0)

beginprint "Have your DBO execute’’sp_setreplicate’’ on the procedure’’rs_marker’’"

return(1) end

The rs_marker stored procedure does not modify data in the database. Its purpose is to execute so that it can be recorded in the transaction log.

If rs_marker is not marked as replicated, you can mark it with sp_setreplicate:

sp_setreplicate rs_marker, ’true’

Changing Primary Databases to Replicate DatabasesIf you want to change a primary database to a replicate database, use the following procedure:

At the current replicate Replication Server

1 Drop all subscriptions and publication subscriptions to the replication definitions in this database.

At the current primary Replication Server

1 Drop all replication definitions defined for this database.

At the Adaptive Server 1 Shut down RepAgent:

sp_stop_rep_agent dbname

2 Disable RepAgent:

sp_config_rep_agent dbname, disable


1 Log in to the Replication Server that manages the database and execute alter connection using the log transfer off option:

alter connection to data_server.databaseset log transfer off

Dropping Database Connections

164

At the Adaptive Server 1 Set the status of rs_marker to “false:”

sp_setreplicate rs_marker, ’false’

2 Set the replicate status of all replicated objects to “false”:

a Execute sp_setreptable and sp_setrepproc without any arguments to generate a list of all replicated tables and stored procedures in the database.

b One by one, set the replicate status of each table and stored procedure to “false,” using sp_setreptable and sp_setrepproc.

Dropping Database ConnectionsTo remove a database from the replication system, use Sybase Central or execute drop connection. Before you execute the command, drop any subscriptions for replication definitions for data in the database. If you are dropping a connection to a primary database, first drop all replication definitions for tables in the database.

For instructions on dropping connections in Sybase Central, see “Dropping database connections” in Replication Server’s online help.

Note drop connection removes database connection information from the Replication Server system tables. It does not remove replicate data from any database in the system. To remove replicate data, use drop subscription using the with purge option.

To drop a connection, specify the data server with the database whose connection is to be dropped. The syntax is:

drop connection to data_server.database

For example, to drop the connection to the pubs2 database in the SYDNEY_DS data server, enter:

drop connection to SYDNEY_DS.pubs2

Note If you are using RepAgent for log transfer, you should also stop (if necessary) and then disable RepAgent at the primary database. See “Disabling RepAgent” on page 102 for information about disabling RepAgent.

RSM


165

For information about dropping logical connections, see “Dropping Logical Database Connections” on page 456.

Dropping a Database from the ID ServerReplication system databases, data servers, and Replication Servers are listed in the rs_idnames system table in the RSSD for the ID Server. Occasionally, you may need to remove the entry for a database from this system table.

For example, the drop connection command fails and you want to reuse the connection name. You must force the ID Server to delete from the rs_idnames system table the row that corresponds to the database. (Physical database connections have a “P” in the ltype column in this system table.)

Log in to the ID Server and execute the sysadmin dropdb command to delete the entry for the specified database. The syntax for sysadmin dropdb is:


You must have sa permission to execute any sysadmin command.

Monitoring Database ConnectionsThis section describes how you can monitor your database connections. Refer to the Replication Server Troubleshooting Guide if you need to monitor connections for troubleshooting purposes.

For instructions on monitoring database connections in Sybase Central, see “Viewing database connection properties” or, to view status information from the Topology View, “Viewing the information grid” in Replication Server’s online help.

Viewing Current Database ConnectionsTo check the status of current database connections:

• Use Sybase Central, or

RSM

Monitoring Database Connections

166

• Use the admin show_connections command to display information about all database connections from the Replication Server. This command also displays information about all routes from the Replication Server. Refer to “admin show_connections” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for details.

Listing Databases Managed by a Replication ServerThe rs_databases system table contains entries for all of the databases managed by the Replication Server, including databases managed by other Replication Servers that have a route to the Replication Server.

To list the databases that a Replication Server manages:

• Use Sybase Central, or

• Use the rs_helpdb stored procedure at the Replication Server’s RSSD.

The syntax for rs_helpdb is:

rs_helpdb [data_server, database]

Refer to “rs_helpdb” in Chapter 6, “Adaptive Server Stored Procedures,” in the Replication Server Reference Manual for detailed usage and syntax information.

Displaying DSI Thread StatusTo view DSI thread status, use Sybase Central or the admin who commands to display thread status information.

• For information about displaying thread status information using Sybase Central, see “Viewing thread status” in Replication Server’s online help.

• admin who displays all threads in the system, including DSI threads.

• admin who, dsi displays the status of the DSI thread, which Replication Server starts to submit transactions to the data server.

See Chapter 4, “Managing a Replication System” for more information about admin who commands. Also refer to the Replication Server Reference Manual, which provides complete thread status listings.

167

C H A P T E R 7 Managing Replication Server Security

This chapter describes the RCL commands for managing Replication Server security, including creating and modifying login names, passwords, and permissions; it also describes the dependencies involved in making modifications.

This chapter also describes how to set up and manage third-party, network-based security systems to authenticate users and ensure secure data transmissions.

OverviewCareful management of login names, passwords, and permissions is essential to the security of the replication system. Replication Server login names and specific permissions are required for:

• Each component of the replication system, such as the data server and the Replication Server

• Each user who is setting up replicated data or monitoring and managing the Replication Server

You can set up encrypted passwords throughout the replication system and change passwords that are encrypted. Refer to the Replication Server installation and configuration guides for your platform for details on password encryption. Also see “Enabling and Disabling Password Encryption” on page 175 for a brief overview of encryption capabilities.

In addition, Replication Server supports third-party security services that ensure secure message transmission over the network and enable user authentication for seamless login to Replication Servers in the replication system. See “Managing Network-Based Security” on page 183.

Managing Replication Server System Security

168

Managing Replication Server System SecurityThis section provides details on replication system login names and passwords.

Often, one process must log in to another, remote process. In such cases, the login name and password assigned to the process logging in must also exist at the remote process. If a password used to log in to the remote process is changed at the current process only, login attempts fail. This section also describes these dependencies.

You must establish login names and passwords for the various components of the Replication Server system, including RSSDs, RepAgents, the ID Server, and Replication Servers themselves.

As a general rule, if you are specifying or modifying system login names, keep the names unique. If you use the same login name for different roles, then any time you change the password, many of the dependencies described in this section are affected.

Table 7-1 lists all login names required in a replication system.

Table 7-1: Overview of replication system login names

RSSD Login Names and PasswordsWhen you install Replication Server, the rs_init program creates the primary and maintenance Adaptive Server login names to maintain the RSSD.

Replication Server uses the primary user login name to modify the system tables in the RSSD for the primary Replication Server. Modifications may include route, replication definition, and function-string information changes to be replicated to RSSDs for other Replication Servers. You set up the primary user when you create the primary RSSD using rs_init.

Source Server Destination Server/Database Login Name Description

Primary Replication Server Primary Adaptive Server/RSSD RSSD primary user

Replicate Replication Server Replicate Adaptive Server/RSSD RSSD maintenance user

Replicate Replication Server Replicate Adaptive Server/replicate database

database maintenance user

RepAgent for RSSD Replication Server RepAgent user for RSSD

RepAgent for primary database Replication Server RepAgent user for primary database

Replication Servers ID Server (Replication Server) ID Server user

Replication Servers Other Replication Servers Replication Server user (RSI user)

CHAPTER 7 Managing Replication Server Security

169

Replication Server uses the maintenance user login name to apply modifications to replicate RSSDs. RepAgent filters out RSSD modifications made by the maintenance user to avoid replicating them to other RSSDs. You set up the maintenance user when you create the replicate RSSD using rs_init.

If the login name or password is changed for either the primary or maintenance user, edit the Replication Server configuration file to match these changes, and restart the Replication Server.

Changing RSSD Primary User Login Name and Password

Observe these guidelines when you change the RSSD primary user login name and password. Refer to Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for command syntax details.

• Never change the RSSD primary user login name and/or password while routes are being created.

While a route is being created, the destination Replication Server uses the primary user login name and password to create and materialize subscriptions at the destination site for replicated RSSD system tables.

• Be sure to also apply the same RSSD primary user login name and/or password changes to the Replication Server.

• To change an encrypted or clear text password, use alter user with the set password clause.

• To change both a login name and password (encrypted or clear text), use drop user to drop the old login name and create user to create the new login name and password. Then grant the user primary subscribe permission.

See “Managing Replication Server Permissions” on page 176 for more information.

• Update the Replication Server configuration file with the new login name and/or password. Use rs_init if the password is encrypted.

• For the updates to take effect, restart the Replication Server.

Replication Server Login Name and Password for the RepAgentRepAgent retrieves information about changes to the replicated system tables in the RSSD or to the primary database from the database transaction logs and submits them to the Replication Server for distribution.

Replication Server needs a login name for RepAgent. The rs_init program uses the create user command to add this Replication Server user.


170

Observe these guidelines when you change the Replication Server login name and/or password for the RepAgent. The login name and password you create at the Replication Server must be the same as that used to configure the RepAgent at Adaptive Server. Refer to Chapter 3, “Replication Server Commands,” and Chapter 5, “Adaptive Server Commands and System Procedures,” in the Replication Server Reference Manual for syntax details.

At Replication Server • To change the password, use the alter user command with the set password clause.

• To change both the login name and password, use the drop user command to drop the old user login name and the create user command to create the new login and password. Then grant the user connect source permission.

At Adaptive Server • To change the login name and password, use the sp_config_rep_agent system procedure with the dbname, rs_servername, rs_username, and rs_password options.

This updates the login name and password in the database sysattributes table. The password is always encrypted.

• For the updates to take effect, restart RepAgent.

ID Server Login Name and PasswordThe ID Server registers Replication Servers and databases in a replication domain. Replication Servers use the ID_user configuration parameter in the Replication Server configuration file to connect to the ID Server. For each Replication Server, the ID Server login name and password must match the ID Server entry.

The ID Server must be the first Replication Server installed. The ID Server login name and password are established using rs_init.

If you change the login name and/or password for the ID Server, be sure to modify ID_user in the Replication Server configuration file of each Replication Server that is defined to the ID Server, as well as the Replication Server configuration file for the ID Server itself. You can make password changes using rs_init.

You also must change the ID Server login name and/or password in the Replication Server. See “Managing Replication Server Login Names and Passwords” on page 173 for more information on changing login names and/or passwords.


171

Replication Server Login Name and Password for Replication Servers

To send operations, Replication Servers log in to other Replication Servers. The login name is created using rs_init. The login name is used when a direct route is created, from one Replication Server to another.

To change the password for a login name used for a direct route, execute the alter route command. See Chapter 5, “Managing Routes” for details.

To change the password in Sybase Central, see “Changing the password of a direct route” in Replication Server’s online help.

Maintenance User Adaptive Server Login Name and PasswordReplication Servers log in to Adaptive Server for the RSSD database or a user database using the maintenance user login name. When applying primary changes (insert, delete, or update operations) to replicate databases, Replication Server uses the maintenance user login name and password.

Note Among the permissions granted to the maintenance user is replication_role. If you revoke maintenance user’s replication_role, Replication Server will not replicate truncate table unless the maintenance user has been granted sa_role, owns the table, or is aliased as the Database Owner.

To change the password for the maintenance user, use the alter connection command.

Sybase Central DependenciesSybase Central logs in to the Replication Server and the RSSD using the login names and passwords specified in the RSM.Servers file.

If you have a Replication Server that uses Sybase Central, be sure to change the values in the RSM.Servers file whenever you change the following login names and passwords:

• Replication Server login name and/or password that Sybase Central uses to log in to the Replication Server

RSM


172

• Adaptive Server login name and/or password that Sybase Central uses to log in to Adaptive Server

Typically, the RSM.Servers file is located in $SYBASE/admin/config directory.

Replication Server Object Creation DependenciesLogin name and password dependencies also apply when you create Replication Server objects, specifically subscriptions and replicated functions (applied and request functions) that are executed at primary or replicate Replication Servers. This section addresses these dependency issues.

Subscriptions

When you create a subscription, the login name that you used to log in to the replicate Replication Server must exist on both the primary Replication Server and the primary Adaptive Server. The login name must have the same password on all three servers.

When you drop a subscription, the replicate Replication Server logs in to the primary Replication Server using the login name and password you used to log in to the replicate Replication Server. Do not change the password of this login name on the primary Replication Server before the drop subscription process is complete.

The RSSD’s “primary” user login name that is automatically created on the Replication Server is used as the “subscribing user” when routes are created. The rules for a user creating a subscription apply to the RSSD primary user.

Suggestions • Do not create subscriptions as the sa user.

• The select command, issued at the primary Replication Server when creating the subscription, does not include a table owner name unless an owner name is specified in the replication definition. If no owner name is specified, make sure that either the user owns the table or the table is owned by the “dbo” user.

• Do not change passwords while subscriptions are materializing or dematerializing.


173

Replicated Functions and Stored Procedures

When a primary Replication Server receives a request function or a request stored procedure from a replicate Replication Server, it logs in to the primary data server with the login name and password of the user who initiated the request function or request stored procedure at the replicate site.

Therefore, to execute a request function or request stored procedure at a replicate data server, the user must have the same login name and password at the primary data server, and must have execute permission for the stored procedure at the primary data server.

When a replicate Replication Server receives an applied function or applied stored procedure from a primary site, the replicate Replication Server uses the maintenance user login name and password to execute the stored procedure in the replicate database.

Managing Replication Server User SecurityReplication Server has its own set of login names, which are separate from data server login names. Users do not need Replication Server login accounts to access data replicated by Replication Server. Replicated data is available to users if they have permissions to access specific databases. The Database Administrator is responsible for creating databases and authorizing access to them.

Replication Server login names are required so that administrative users of the system can execute Replication Server commands. See “Examining Users, Passwords, and Permissions” on page 182 for information on viewing current Replication Server login names. Password encryption for users can be enabled or disabled.

Managing Replication Server Login Names and PasswordsThe Replication System Administrator, or any other user who has sa permission, manages login names. Table 7-2 summarizes the RCL commands for managing login names.

Table 7-2: Commands for managing login names

Command Task

create user Create a new login name.

Managing Replication Server User Security

174

You can also create, alter, and drop users in Sybase Central.See “Managing Users” in Replication Server’s online help for instructions.

Creating a Replication Server Login Name

The create user command adds new user login names to Replication Server. All users have permission to execute all admin commands. See “Permission Summary” on page 179 for individual commands.

You must specify a password for the user when the login name is created. If the user has no password, you must set the password to “null,” which specifies an empty string.

The create user command requires sa permission. The syntax for create user is:

create user userset password {passwd | null}

A user’s password can be up to 30 characters long and include letters, digits, and symbols. Case is significant. If the password contains spaces, enclose the password in single quotation marks.

Users can change their own passwords using the alter user command, which is described in the section “Changing a Replication Server Password” on page 174.

The following example creates a login name for the user “thomk” with the password “vacUUm”:

create user thomk set password vacUUm

Changing a Replication Server Password

The Replication System Administrator can change any user’s password. Also, a user can change his or her own password. The alter user command is used in each case.

The syntax for alter user is:

alter user Change the password for a login name.

drop user Drop a user login name.

Command Task

RSM


175

alter user userset password {new_passwd | null} [verify password old_passwd]

The same rules that you use for specifying the password using create user also apply to alter user.

The verify password clause, which prevents users from altering each other’s passwords, is required for users without sa permission.

The following command changes the password for user “louise” from “null” to “polyESter”:

alter user louise set password polyESter verify password null

Dropping a Replication Server Login Name

The drop user command removes an existing login name from the Replication Server. This command requires sa permission. The syntax for drop user is:

drop user user

For example, the following command removes the “thomk” login name:

drop user thomk

Enabling and Disabling Password EncryptionThe password the RepAgent thread uses to log in to Replication Server is always encrypted before it is stored in the sysattributes file of the database. However, you can choose whether or not to encrypt other replication system passwords.

The rs_init program allows you to enable password encryption when you install or upgrade the replication system. This allows you to encrypt passwords throughout sensitive areas of the replication system. Once the system is installed or upgraded, you can use rs_init at any time to enable encryption.

If you enable password encryption for a Replication Server, new passwords, passwords contained in the Replication Server configuration file, and passwords stored in the RSSD are all encrypted.

For details on enabling password encryption using the rs_init program, refer to the Replication Server installation and configuration guides for your platform.


176

Disabling Encryption on New and Existing Passwords

Use this procedure to disable password encryption:

1 Disable encryption on new passwords that are entered for Replication Server, using configure replication server. At Replication Server, enter:

configure replication server set password_encryption to ’0’

2 Change existing passwords in the RSSD to clear text.

To do this, change each user’s password using the alter user command, the alter connection command for maintenance users, and the alter route command for routes.

3 In the Replication Server configuration file, manually reenter, in clear text, passwords that are currently encrypted.

4 Restart the Replication Server to pick up the new password_encryption configuration parameters.

Changing Encrypted Passwords in the Configuration Files

To change an encrypted password (to another encrypted password) in a Replication Server configuration file, use the rs_init program. You cannot change encrypted passwords directly in the Replication Server configuration files.

For details on dependencies involved in changing passwords for specific login names, see “Managing Replication Server System Security” on page 168.

Managing Replication Server PermissionsReplication System Administrators manage Replication Server permissions with the grant and revoke commands. Permissions determine which RCL commands users are permitted to execute.

Any user with a Replication Server login name can execute all admin commands and the check subscription command. Other commands can be executed only by users who have been granted the required permissions.

Replication Server users can be granted any of four permissions.


177

Table 7-3: Replication Server permissions

Requirements for Creating Subscriptions

A subscription creator must have accounts on both the primary and replicate Replication Servers, and the accounts must have the same login name and password. The subscription creator enters a command or a series of commands at the replicate Replication Server, which passes the request to the primary Replication Server.

At the replicate Replication Server (the destination of the subscription data), the subscription creator must have, at minimum, create object permission in order to materialize the subscription.

At the primary Replication Server (the source of the subscription data), the subscription creator must have, at minimum, primary subscribe permission in order to enter at the replicate site all commands involved in creating subscriptions:

• create subscription (for atomic and nonatomic materialization)

• define subscription (for bulk materialization)

• activate subscription (for bulk materialization)

• validate subscription (for bulk materialization)

Permission Description

sa Users with sa permission are Replication System Administrators. They can execute any Replication Server command and may grant and revoke other permissions, including sa, to and from other users.

create object Users with create object permission can create objects such as replication definitions, subscriptions, and function strings. Users with create object permission automatically have primary subscribe permission.

primary subscribe Users with primary subscribe permission can execute the commands needed to create subscriptions for primary data stored in databases managed by the Replication Server.Users with primary subscribe permission at the primary site and create object permission at the replicate site can create a subscription for data at the primary site, but cannot create replication definitions or function strings at the primary site.

connect source The connect source permission is required for:

• Login names that RepAgents use to log in to Replication Server, allowing RepAgent to execute the subset of RCL commands known as Log Transfer Language (LTL). Refer to the Replication Server Design Guide.

• Login names that a source Replication Server uses to connect to a destination Replication Server for the purpose of sending replicated data or replicated functions. You provide this login name using the create route command.


178

• drop subscription

The primary subscribe permission, a subset of create object permission, is provided at the primary Replication Server. It lets users at replicate sites create subscriptions to data stored at primary sites. From replicate sites, these users cannot create any other objects at primary sites, only subscriptions.

Note Users with create object and sa permissions can also create subscriptions from replicate Replication Servers. The minimal permission required at the primary Replication Server for a user at a replicate site to create subscriptions is primary subscribe.

A user creating a subscription must have the following Adaptive Server permissions:

• select permission on the table in the primary database

• insert, update, and delete permission on the replicate table

• execute permission on the rs_marker stored procedure in the primary database

If you are a Replication System Administrator, restrict primary subscribe and create object permissions at primary sites to users who require them in order to create subscriptions.

It is possible for a user who has primary subscribe or create object permission to begin creating a subscription without having select permission on the table. If this occurs, Replication Server responds in the following manner:

• If the subscription is created with atomic materialization, the select with holdlock operation fails at the primary database during materialization. The subscription retry daemon (dSUB) retries the select with holdlock until the subscription is dropped or until the select permission is granted to the user for the table at the primary database.

• If the subscription is created with nonatomic materialization, the select operation fails at the primary database during materialization. The subscription retry daemon (dSUB) retries the select until the subscription is dropped or the select permission is granted.

• If the subscription is created with bulk materialization, there is no select transaction, so no error messages are logged, and the subscription succeeds.


179

Permission Summary

Table 7-4 lists the minimum permission required to execute each RCL command. Users with create object permission automatically have primary subscribe permission. Users with sa permission can execute any command.

Table 7-4: Minimum permissions to execute RCL commands

To Execute Minimum Permission Required

abort switch sa

activate subscription create object at replicate, primary subscribe at primary

add partition sa

admin commands Can be executed by any user

allow connections sa

alter connection sa

alter function create object

alter function replication definition create object

alter function string create object

alter function string class sa

alter logical connection sa

alter replication definition create object

alter route sa

alter user sa – Users can change their own passwords by including the verify clause

assign action sa

check publication Can be executed by any user

check subscription Can be executed by any user

configure connection sa

configure logical connection sa

configure replication server sa

configure route sa

create article create object

create connection sa

create error class sa

create function create object

create function replication definition create object

create function string create object

create function string class sa

create logical connection sa

create publication create object

create replication definition create object


180

create route sa

create subscription create object at replicate, primary subscribe at primary

create user sa

define subscription create object at replicate, primary subscribe at primary

drop article create object

drop connection sa

drop error class sa

drop function create object

drop function replication definition create object

drop function string create object

drop function string class sa

drop logical connection sa

drop partition sa

drop publication create object

drop replication definition create object

drop route sa

drop subscription create object at replicate, primary subscribe at primary

drop user sa

grant sa

ignore loss sa

move primary sa

rebuild queues sa

resume connection sa

resume distributor sa

resume log transfer sa

resume route sa

revoke sa

set proxy sa

set autocorrection create object

set log recovery sa

shutdown sa

suspend connection sa

suspend distributor sa

suspend log transfer sa

suspend route sa

switch active sa

sysadmin commands sa



181

Granting Permissions

The ability to grant and revoke permissions is reserved for the Replication System Administrator. Any user who has been granted sa permission can play the role of Replication System Administrator, and can transfer the grant and revoke ability to other users by granting them sa permission.

For information about granting permissions in Sybase Central, see “Creating Replication Server user accounts” or “Changing Replication Server user information” in Replication Server’s online help.

The syntax for the grant command is:

grant {sa | create object | primary subscribe | connect source} to user

The user is the login name of the user to receive the permission. You can grant only one permission at a time.

Permissions are assigned to Replication Server users—not database users. A Replication Server user who has create object permission can create Replication Server objects that are associated with any database managed by the Replication Server.

In the following example, the Replication System Administrator grants create object permission to the “thomk” login name:

grant create object to thomk

Revoking Permissions

To remove permissions previously granted to a user, use Sybase Central or the revoke command.

For information about revoking user permissions in Sybase Central, see “Changing Replication Server user information” in Replication Server’s online help.

The syntax for the revoke command is:

validate subscription create object at replicate, primary subscribe at primary

wait for create standby sa

wait for switch sa


RSM

RSM


182

revoke {sa | create object | primary subscribe | connect source} from user

Note You cannot revoke the sa permission from, or drop, the sa login name. This ensures that Replication Server is never without a Replication System Administrator.

The four permissions are managed independently. They can be granted and revoked in any order and the result is the same.

The following revoke command prevents user “louise,” who does not have sa permission, from creating replication definitions:

revoke create object from louise

Examining Users, Passwords, and PermissionsYou can display the login names, passwords, and permissions for Replication Server users and threads by using the rs_helpuser stored procedure or by querying the rs_maintusers and rs_users system tables in the RSSD.

You can also use Sybase Central to view information on Replication Server login names.

For instructions, see “Viewing Replication Server user properties” in Replication Server’s online help.

Using the rs_helpuser Stored Procedure

Use the rs_helpuser stored procedure to display information about user login names known to a Replication Server. The syntax for rs_helpuser is:

rs_helpuser [user]

With no parameters, rs_helpuser displays information about all user login names known to the current Replication Server. Permissions are displayed for each primary or maintenance user login name.

If you supply a login name parameter, rs_helpuser displays information about that login name only.

RSM


183

Querying the rs_maintusers System Table

The rs_maintusers system table in the RSSD contains the login name and password information for maintenance users.

rs_maintusers includes a column to identify if the password is encrypted or clear text, and a column to hold the encrypted password.

For example, the following query, executed in the RSSD, lists all available information, including login names, for maintenance users:

select * from rs_maintusers

Querying the rs_users System Table

The rs_users system table in the RSSD contains the login name and password information for Replication Server users.

rs_users also includes a column to identify if the password is encrypted or clear text, and a column to hold the encrypted password.

The rs_users system table also includes a permissions column, which stores the permissions for each login name. The permissions column is a bit-mask of the permissions granted to users.

Table 7-5 lists the mask values for each of the four permissions.

Table 7-5: Permission bitmask values in the rs_users system table

For example, the following query, executed in the RSSD, lists users who have sa permission:

select username, uid from rs_users where permissions & 0x0001 != 0

Managing Network-Based SecurityIn a client/server environment, it is important to provide secure data pathways so data transmission remains confidential. Replication Server version 12.0 supports third-party, network-based security mechanisms that focus on:

Permission Mask Value

sa 0x0001

connect source 0x0002

create object 0x0004

primary subscribe 0x0008

Managing Network-Based Security

184

• Authentication and unified login

• Secure message transmission

With network-based security, users are authenticated—the process of verifying that users are who they say they are—by the security system at login. They receive a credential that can be presented to remote servers in lieu of a password. As a result, users have seamless access to the components of the replication system through a single login.

Replication Server version 12 supports CyberSafe Kerberos version 5 Security Server and Transarc DCE version 1.1 Security Server. Depending on which of these security mechanisms you choose, you can select one or more of these features to secure data transmission:

• Unified login – enables the user to log in to components of the replication system with a single credential issued by the security mechanism.

• Confidentiality – enables the sending and receiving of encrypted data.

• Integrity – ensures that data has not been tampered with.

• Replay detection – verifies that data has not been intercepted.

• Origin check – verifies the source of each data packet.

• Out-of-sequence detection – checks that data packets are received in the order sent.

The security mechanism allows Replication Server to establish secure connections with other Replication Servers version 11.5 or later, with Adaptive Server version 12 or later, and with other data servers that support the Kerberos or DCE security mechanism and certain Replication Server requirements. You choose the method or methods to secure data transmission between them.

How Security Services WorkClients use the security mechanism to ensure a secure pathway to a remote server. Replication Server logs in to remote servers (acting as a client) and also accepts incoming logins (acting as a server). How security services work depends on whether Replication Server (or Adaptive Server or other data server) is acting as client or server.


185

Replication Server, when acting as the client, uses the security mechanism to ensure a secure pathway to a remote Replication Server or Adaptive Server. Once the secure pathway is established, the security mechanism can provide message protection. When Replication Server acts as a server, it accepts or rejects logins based on its default security settings.

Login Authentication

If a client requests authentication services:

1 The client validates the login with the security mechanism and receives a credential, which contains relevant security information.

2 The client sends the credential to the server and informs the server it wants to establish a secure connection.

3 The server authenticates the client’s credential with the security mechanism. If the credential is not valid, the secure connection is rejected.

4 The server checks message protection properties, if the properties are compatible, the connection is established.

Message Protection

If the current Replication Server (the client) requests data protection services:

1 The client uses the security mechanism to prepare the data packet it will send to the server.

For example, if the client requests message confidentiality, the security mechanism encrypts the commands that will be sent to the remote server. If the client requests out-of-sequence checking, the security mechanism time-stamps each data packet.

2 The client sends the data to the destination server.

3 When the server receives the data, it uses the security mechanism to perform the appropriate decryption or validation.

4 The server returns the results to the client, using the security mechanism to perform the security action requested. For example, the server returns results in encrypted form or time-stamps each data packet returned to the client.


186

Requirements and RestrictionsTo enable network-based security you need:

• A network-based security mechanism installed on all machines for which network security is to be enabled. The security mechanism must be supported by Replication Server.

Note Make sure that you use either the CyberSafe Kerberos or Transarc DCE security mechanism. Sybase network-based security will not run on other Kerberos or DCE security mechanisms.

• Replication Server version 11.5 or later for all client and destination Replication Servers.

• Adaptive Server version 12 or later and/or compatible heterogeneous data servers for all client and destination data servers.

Compatible heterogeneous data servers must support the security mechanism installed on Replication Server and the set proxy concept. See the version 12.0 Replication Server Reference Manual for a description of this Adaptive Server command.

• Replication Server Manager (RSM) version 12 or later. See “Managing Security in a Replication System” in Replication Server’s online help in Sybase Central.

These restrictions apply:

• Both ends of a secured pathway (client and server) must support the same security mechanism, and the security parameters must have the same feature settings. See “Managing Network Security” on page 208 for more information about security settings.

• User names must be unique throughout the replication system.

If your replication system supports multiple security systems, and you cannot guarantee unique user names, you may need to turn off request stored procedures to avoid a potential security breach. See “Potential Security Issue” on page 212 for details.

Setting Up Network-Based SecurityTo set up network security, perform these steps:

• Modify configuration parameters and environment variables, as necessary.


187

• Identify the Replication Server principal user.

• Activate the security mechanism.

• Configure security services for connections, routes, and other Replication Server pathways.

Each of these tasks is described in the following sections.

Modifying Configuration Parameters and Environment VariablesConfiguration files are created during installation at default locations in the Sybase directory structure. The configuration files you may need to configure for network security are:

• libtcl.cfg

• objectid.dat

• The interfaces file

If you are using Kerberos security services, you may also need to modify the CSFC5KTNAME environment variable.

Configuring libtcl.cfgDrivers are libraries that provide an interface to an external service provider. The libtcl.cfg file provides a template into which you enter all the configuration information about the security drivers installed on a machine. It is located in the $SYBASE/SYBASE_REP/config directory (UNIX) or the %SYBASE%\ini directory (Windows NT).

This section provides the information you need to configure the security driver. Refer to the Open Client/Server Configuration Guide for more information about Sybase drivers.

The syntax for a security driver entry is:

provider=driver init-string

where

• provider is the local name for the security mechanism, for example, “dce.” The mapping of the local name to a global object identifier is defined in objectid.dat.

• The default local name for the DCE security mechanism is “dce.”


188

• The default local name for the Kerberos security mechanism is “csfkrb5.”

If you use a local mechanism name other than the default, you must change the local name in the objectid.dat file.

• driver is the name of the security driver, for example, libsdce.so.

• init-string is the initialization string for the driver.

• For the DCE driver, the syntax for init-string is:

secbase=/.:/cell_name

where cell_name is the name of your DCE cell.

• For the Kerberos driver, the syntax for init-string is:

secbase=@domaine_name

where domaine_name is the name of your Kerberos domaine.

Use a text editor to customize libtcl.cfg for your site. Make sure that lines you do not want are preceded with the “;” character. Change one parameter at a time and reboot Replication Server to effect the changes you make.

• An example of an entry for a DCE driver is:

[SECURITY]dce=libsdce.so secbase=/.:/cell_name

• An example of an entry for a Kerberos driver is:

[SECURITY]csfkrbs=libskrb.so secbase=@domaine_name

Configuring objectid.datThe objectid.dat file maps global object identifiers (OIDs) to local names. It is located in the $SYBASE/SYBASE_REP/config directory (UNIX) or the %SYBASE%/ini directory (Windows NT). You need to edit this file only if you have changed the local name of a security service in the libtcl.cfg file.

• A sample entry in the objectid.dat file for DCE is:

[secmech]1.3.6.1.4.1.897.4.6.1 = dce

• A sample entry in the objectid.dat file for Kerberos is:

[secmech]


189

1.3.6.1.4.1.897.4.6.6 = csfkrb5

Configuring the Interfaces FileThe interfaces file contains network and security information for servers. It is located in $SYBASE/SYBASE_REP/interfaces (UNIX) or %SYBASE%\ini\sql.ini (Windows NT). If you use network security, you must include a secmech line that gives the global identifiers of supported security services. Supported security mechanisms are listed by their OIDs. Multiple security mechanisms are separated by commas.

A sample entry for the interfaces file for either DCE or Kerberos is:

#server_principal_user_name

query tcp ether plum 1050master tcp ether plum 1050secmech 1.3.6.1.4.1.897.4.6.1

where server_principal_user_name is the name of the Replication Server principal user. See “Identifying the Principal User” on page 190 for more information.

Setting Environment Variables (Kerberos)If you are using the Kerberos network security, you may need to reset the shared-library path and CSFC5KTNAME environment variables.

• Make sure that the shared-library file is in a directory specified in the shared library path so that the client can find the shared-library file at runtime. Shared-library files are:

• libgss.so on Sun Solaris

• libgss.sl on HP-UX

• libgss.dll on Windows NT

• If the server key table file is in a location other than the Kerberos system default, set the CSFC5KTNAME environment variable to the fully qualified pathname of the key table file.

• Make sure that the LD-LIBRARY_PATH environment variable includes the path to the CyberSafe lib directory as well as the lib directories for Adaptive Server, Open Client/Server, and Replication Server.


190

• Similarly, make sure that the PATH environment variable includes the path to the CyberSafe bin directory as well as the bin directories for Adaptive Server, Open Client/Server, and Replication Server.

Establishing the Principal UserWhen network security is not enabled, Replication Server logs in to remote servers as one of several possible users, depending on the task to be performed. When network-based security is enabled with unified login, Replication Server must log in to remote servers as the principal user. The principal user credential is the only credential Replication Server has to log in to other processes when network security is active.

When Replication Server logs in to another Replication Server or a data server, the principal user name contained in the credential is mapped to the server name space and a secure connection is established.

Note Make sure that principal user names are unique. Replication Server cannot log in to another server of the same name.

Replication Server executes the set proxy command in the remote server (as the principal user) and switches to the appropriate user for the current task.

Identifying the Principal User

It is the responsibility of the Replication System Administrator to establish a principal user for each Replication Server. Sybase recommends that you use the name of the Replication Server as the principal user name. When you log in to or start Replication Server, you can specify the principal user name with the -S flag.

If you do not specify a principal user name using the -S flag, Replication Server uses the Replication Server name.

Identifying the Principal User to the Security Mechanism

The security administrator for the security mechanism must define the Replication Server principal name to the security mechanism.

For DCE:


191

• Use the DCE dcecp tool’s user create command to create the principal user.

When you are defining a server to DCE, use options that specify that the new principal user can act as a server.

• Use the keytab create command of the dcecp utility to create a DCE key table file, which contains a principal user’s password in encrypted form.

For Kerberos:

• Use the Kerberos csfadml tool to create the principal user.

• Use csfadml to extract the key table file.

Refer to documentation from the security mechanism provider for detailed information about identifying servers and users to the security mechanism.

Identifying Principal Users to Replication ServerThe principal user for other processes—including RepAgents, data servers, and other Replication Servers—using system security and unified login to connect to Replication Server must be identified in the rs_users table for the current Replication Server. You can use the create user command to add principal user names to rs_users.

Refer to the Replication Server Administration Guide for information about adding login names to Replication Server.

Identifying the Replication Server Principal User to the Replication System

You must add Replication Server’s principal user name to destination processes—Replication Servers and data servers—including the ID Server and the RSSD to which Replication Server is connecting using unified login.

Refer to the Adaptive Server System Administration Guide for information about adding login names to Adaptive Server.

Activating Network-Based SecurityBefore configuring security services, you must turn on network-based security for the Replication Server using the configure replication server command.

Starting Server and Clients

192

To activate network security, follow these steps:

• Log in to Replication Server and enter:

configure replication server set use_security_services to ’on’

• Shut down Replication Server.

• Restart Replication Server by executing the repserver command or the Replication Server run file.

• If you are using the DCE security mechanism, make sure you include the -K flag to specify the key table file location.

• If you are using the Kerberos security mechanism, the key table location must be specified by the CSFC5KTNAME environment variable (UNIX) or the key table registry key entry (NT).

Refer to the Replication Server Reference Manual for syntax and other information about the repserver command.

To turn off security services, see “Disabling Network-Based Security” on page 208.

Starting Server and ClientsFor the network security environment to work properly, both servers and clients should be started only after they have a valid credential.

For CyberSafe Kerberos systems:

• On UNIX systems, servers and clients should be started after a kinit.

• On Windows NT systems, server and clients can be started automatically using the single sign-on feature or manually using the CyberSafe credentials manager.

Refer to your CyberSafe documentation for more information.

Transarc DCE systems behave in similar manner, refer to your Transarc documentation for information about setting up the proper environment.


193

Configuring Security Services for Replication ServerReplication Server provides parameters for configuring network-based security. Configuration parameters enable:

• Unified login

• Mutual authentication

• Choice of supported security mechanism

• Message confidentiality through encryption

• Other secure message transmission features: message integrity, origin check, replay detection, and out-of-sequence detection

Note Depending on the security mechanism you choose, one or more of these security features may not be available at your site.

You set default parameters in the rs_init program during system configuration. Refer to the Replication Server Configuration Guide for your platform for information about rs_init. This section describes how you set these parameters at the command line.

Identifying Replication Server PathwaysReplication Server coordinates data replication activities for local data servers and exchanges data with Replication Servers and data servers at other sites. Each of these pathways can be configured for network-based security.

• When Replication Server is acting as a client, you can configure security for:

• All pathways established when Replication Server logs in to another server. These are default global settings.

• The connection to the RSSD.

• Individual connections.

• Individual routes.

• Replication Server to ID Server pathway.

• Pathways used to create a route, create a subscription, or drop a subscription.

Configuring Security Services for Replication Server

194

• When Replication Server is acting as a server, you can configure security for:

• All incoming logins. These are default global settings.

• RepAgent to Replication Server (set from Adaptive Server).

• User connection to Replication Server (set when logging on).

Table 7-6: Network pathways

Pathway How to secure itSpecial parameters and exceptions

All pathways initiated by the current Replication Server (acting as a client)

Set global security parameters using configure replication server. This is the default setting for all outgoing logins unless overridden for individual pathways.

Use use_security_services to turn off all network security with a single command. See “Disabling Network-Based Security” on page 208.

Connection to the RSSD Use a text editor to configure the rs_config file.

Security parameters have an “RSSD_” prefix. For example: RSSD_unified_login.

Individual connections Set security parameters for a connection to a remote database with:

• create connection, or

• alter connection

See the Replication Server Reference Manual for more information about these commands.

Use dsi_exec_request_sproc to suspend request stored procedures. See “Configuring Security for Database Connections” on page 199.

Individual routes defined using the create route command

Set security parameters using:

• create route, or

• alter route

See the Replication Server Reference Manual for more information about these commands.

Replication Server to ID Server Set security parameters with configure replication server.

See the Replication Server Reference Manual for more information about this command.

Security parameters have an “id-” prefix. For example: id_msg_confidentiality.


195

Configuration ParametersTable 7-7 describes the configuration parameters generally available for all pathways. Exceptions and special cases are listed in CCC and described in detail in each pathway section.

Table 7-7: Security parameters affecting Replication Server

Replication Server to primary Replication Server and primary database to:

• create a route

• create or drop a subscription

Replication Server duplicates the security settings used when the user creating the route or creating or dropping the subscription logs in to Replication Server.

See “Borrowing Security Settings to Secure Other Pathways” on page 207 for more information.

All incoming logins (Replication Server acting as server)

Set parameters for incoming logins with configure replication server. Default parameters for outgoing and incoming parameters are set at the same time and are identical.

RepAgent to Replication Server Set security parameters at Adaptive Server with the sp_config_rep_agent system procedure.

See the Replication Server Reference Manual for more information about this system procedure.

Configure RepAgent from Adaptive Server.

Security parameter settings are “true” and “false” instead of “required” and “not required.”

Pathway established when user logs in to Replication Server.

Set security parameters with the isql utilities.

Security parameters set for this pathway must be compatible with those set at the Replication Server for all incoming logins.

Security for this pathway cannot be configured using the rs_init utility.

Pathway How to secure itSpecial parameters and exceptions

configuration_parameter Description

msg_confidentiality Indicates whether Replication Server sends and receives encrypted data. If set to “required,” outgoing and incoming data must be encrypted. If set to “not_required,” Replication Server accepts incoming data that is encrypted or not encrypted. Values are “required” or “not_required.”Default: not_required


196

Planning for Compatible SettingsReplication Server accepts incoming logins and initiates logins to other servers. Security parameters for all incoming logins (when Replication Server is acting as a server) are set with the configure replication server command. Security parameters for outgoing logins (when Replication Server is acting as a client) are set as described in Table 7-6.

msg_integrity Indicates whether data is checked for tampering. Values are “required” or “not_required.”Default: not_required

msg_origin_check Indicates whether the source of data must be verified.Values are “required” or “not_required.”Default: not_required

msg_replay_detection Indicates whether data should be checked to make sure it has not been intercepted and re-sent.Values are “required” or “not_required.”Default: not_required

msg_sequence_check Indicates whether data packages should be checked to ensure that they have been received in the order sent. Values are “required” or “not_required.”Default: not_required

mutual_auth Requires remote server to provide proof of identify before a connection can be established. Values are “required” or “not_required.”Default: not_required

security_mechanism Specifies the name of the network-based security mechanism.Default: First security mechanism listed in libtcl.cfg.

unified_login Indicates how Replication Server seeks outgoing connections and accepts incoming connections. The values are:

• “required” – always seeks to log in to remote server with a credential; only accepts incoming logins with a credential.

• “not_required” – always seeks to log in to remote server with a password; accepts incoming logins with a credential or a password.

Note unified_login must be “required” before other security parameters can take effect.

Default: not_required

configuration_parameter Description


197

When you set up network-based security, you must plan for the interaction between security settings at each end of the secured pathway. Security settings at both ends of each pathway must be compatible.

Note It is the Replication System Administrator’s responsibility to choose and set security features for each server. Replication Server does not query the security features of remote servers before attempting to establish a pathway. An attempted login fails if security features at both ends of the pathway are not compatible.

Use configure replication server with the use_security_services parameter to activate or deactivate all security services. Table 7-8 describes compatible security settings for client/server interaction. If the security services parameters are not compatible, for example, if a parameter is set to “not_required” at the client and “required” at the server, the server does not allow the client to log in.

Table 7-8: Compatible client/server settings

Configuring Default ValuesUse configure replication server to establish default security settings for all outgoing logins (when Replication Server acts as a client) and incoming logins (when Replication Server acts as a server).

You can override default security settings for these outgoing pathways:

• Individual connections – see “Configuring Security for Database Connections” on page 199

Client Server

use_security_services “off”: no security services

Compatible settings:

• use_security_services “off”, or

• use_security_services “on” and security feature “not required”

use_security_services “on” and security feature “not required”


• use_security_services “on” and security feature “not required,” or

• use_security_services “off”

use_security_services “on” and security feature “required”


• use_security_services “on” and security feature “required”


198

• Individual routes – see “Configuring Security for Routes” on page 201.

• The pathway from Replication Server to ID Server – see “Configuring Security to the ID Server” on page 203.

Note You cannot override any default security settings that control security for incoming logins.

When Replication Server seeks to open a pathway to another server, it checks to see if security parameters have been set specifically for that pathway. If not, Replication Server uses the default security settings determined using configure replication server.

To set global security parameters, log in to Replication Server and execute configure replication server at the isql prompt. Here is the syntax:

configure replication server { set security_mechanism to ’mechanism_name’ | set security_parameter to { ’required’ | ’not_required’ }}

You can set all of the configuration parameters listed in Table 7-7 on page 195. They are stored in the rs_config table in the RSSD. You must have sa permission to execute them.

Examples

This section provides examples of using configure replication server.

Requiring Unified Login

To require all servers and users that connect to Replication Server to be authenticated by the security mechanism, set unified_login to “required.” Log in to Replication Server and execute this command at the isql prompt:

configure replication server set unified_login to ’required’

If unified_login is “not_required”, Replication Server allows servers and users to connect with either a credential or a password.

Note unified_login must be “required” for other security services to take effect.


199

Requiring Data Encryption

To require all data sent or received by Replication Server to be encrypted, log in to the Replication Server and execute this command at the isql prompt:

configure replication server set msg_encryption to ’required’

Configuring Security for the Connection to the RSSDAt startup, Replication Server contacts the RSSD for configuration information. You can secure this pathway using network-based security.

When you set up Replication Server, rs_init creates the RSSD connection and places default security information in the Replication Server configuration file, Rep_Server_name.cfg. By default, rs_init sets all network security parameters to “not required.” If you want to secure the pathway, you must use a text editor to change desired default values to “required.”

Configuration values for the RSSD are preceded by an “RSSD_” prefix. For example:

• RSSD_mutual_auth

• RSSD_msg_origin_check

See Table 7-7 for a list and description of the available parameters.

Configuring Security for Database ConnectionsTo configure security for individual connections, use create connection or alter connection. Security parameters configured with these commands affect security for the outgoing connection to the data server. They override parameters set with configure replication server.

Creating a Secure Connection

You can set security parameters when you create a connection with create connection. Normally, you use this command to add connections to non-Sybase databases.

Here is the syntax for including security features with the create connection command. See create connection in the Replication Server Reference Manual for detailed information about using create connection.


200

create connection to data_server.database... set username [to] user [set password [to] passwd] [set security_mechanism [to] ’mechanism_name’ | set dsi_exec_request_sproc [to] { ’on’ | ’off’ } | set security_mechanism [to] ’mechanism_name’ | set security_parameter [to] { ’required’ | ’not_required’ } ]

Table 7-7 on page 195 describes the security parameters you can set with create connection. In addition, you can set the dsi_exec_request_sproc parameter described in Table 7-9 on page 200.

Connections parameters are stored in the rs_config table in the RSSD, and you must have sa permission to execute them.

Table 7-9: Special security parameters for connections

Security parameters set at both ends of a connection must be compatible. See “Planning for Compatible Settings” on page 196 for details.

Modifying Security for a Connection

To change the security settings for a database connection, use alter connection.

Here is the syntax for altering security:

alter connection to data_server.database { ...set password to passwd |set security_mechanism to ’mechanism_name’ |set dsi_exec_request_sproc to { ’on’ | ’off’ } |set security_parameter to { ’required’ |’not_required’ }}

Refer to Table 7-7 on page 195and Table 7-9 on page 200 for a list and description of parameters you can alter.

security_parameter Description

dsi_exec_request_sproc Indicates whether request stored procedures at the primary Replication Server are “off” or “on.” Use in multiple security-system environments. Refer to “Using More Than One Security Mechanism” on page 211 for more information.

Default: off


201

To change the security parameters of a database connection, perform these steps at the Replication Server:

• Execute suspend connection to suspend activity on the connection.

• Execute alter connection to change security parameters. Set one parameter at a time.

• Execute resume connection to resume activity on the connection.

Examples

This section provides some examples of using alter connection.

To require Replication Server to connect to the target database (TOKYO_DS.pubs2) with a credential, execute:

alter connection to TOKYO_DS.pubs2 set unified_login to ’required’

Note unified_login must be “required” for other security services to take effect.

To turn “off” request stored procedures at the TOKYO data server in a multiple security-system environment, execute:

alter connection to TOKYO_DS.pubs2 set dsi_exec_request_sproc to ’off’

Configuring Security for RoutesYou can configure security for individual routes using create route or alter route. Security parameters configured with these commands affect security for the outgoing login to the destination Replication Server. They override default parameters set with configure replication server.

Creating a Secure Route

You can set security parameters when you create a route. Here is the syntax for including security features using the create route command.

create route to dest_replication_server { ...[set username to ’user’ ][set password to ’passwd’ ]


202

[set security_mechanism to ’mechanism_name’ |set security_parameter to { ’required’ | ’not_required’ } ]

Table 7-7 on page 195 describes the security parameters you can set with create route. They are stored in the rs_config table in the RSSD. You must have sa permission to execute them.

Security parameters set at both ends of a route must be compatible. See “Planning for Compatible Settings” on page 196 for details.

Modifying Security for a Route

To change the security settings for a route, use the alter route command.

Log in to Replication Server and execute alter route at the isql prompt. Here is the syntax for altering security:

alter route to dest_replication_server { ...set password to ’passwd’ |set security_mechanism to ’mechanism_name’ |set security_parameter to { ’required’ |

’not_required’ }}

Table 7-7 on page 195 describes the security parameters you can change with alter route.

To change the security parameters of a route, you must first suspend the route. Perform these steps at the Replication Server:

1 Execute suspend route to suspend activity on the route.

2 Execute alter route to change a security parameter. Change one parameter at a time.

3 Execute resume route to resume activity on the route.

Examples

This section provides some examples of using alter route.

• To require Replication Server to connect to the target Replication Server (TOKYO_RS) with a password, execute these commands:

alter route to TOKYO_RS set username ’TOKYO_rsi_user’alter route to TOKYO_RS set password ’TOKYO_rsi_pw’


203

alter route to TOKYO_RS set unified_login to ’not_required’

Note If unified_login is “not_required,” you must specify an RSI user and password.

• To specify that all messages exchanged with the target Replication Server (TOKYO_RS) are checked for tampering, execute:

alter route to TOKYO_RS set msg_integrity to ’required’

Configuring Security to the ID ServerTo configure network-based security for the network connection from Replication Server to ID Server, use configure replication server. The syntax is:

configure replication server set id_security_param to { ’required’ |

’not_required’ }

Refer to the Replication Server Reference Manual for complete syntax and usage information about configure replication server.Table 7-7 on page 195 describes the security parameters you can set for the pathway to the ID Server. They are stored in the rs_config table in the RSSD. You must have sa permission to configure them. To distinguish settings for this pathway, all ID Server parameters begin with the “id_” prefix. For example:

• id_msg_confidentiality

• id_security_mechanism

ID Server security parameters configured with configure replication server are dynamic. They take effect immediately and do not require that you restart Replication Server.

Examples

• To require that the source of all messages be verified, log in to the source Replication Server and enter:

configure replication server set id_msg_origin_check ’required’


204

• To require that Replication Server logs in to ID Server with a credential, enter:

configure replication server set id_unified_login to ’required’

Configuring Security for the RepAgent PathwayTo set or change security parameters for the pathway that RepAgent uses to log in to Replication Server, use the sp_config_rep_agent system procedure. Refer to sp_config_rep_agent in the Replication Server Reference Manual for information about this Adaptive Server stored procedure.

To configure the RepAgent pathway, log in to Adaptive Server and execute sp_config_rep_agent at the isql prompt. Here is the syntax:

sp_configure_rep_agent dbname,{’security mechanism’ ’mechanism_name’ |’security_parameter’ {’true’ | ’false’ }}

Table 7-7 on page 195 describes the security parameters you can set with sp_config_rep_agent. They are stored in the sysattributes table of the database for which RepAgent is enabled. RepAgent parameters are dynamic. They take effect immediately and do not require a reboot of Adaptive Server. You must have sa or dbo permission to execute them.

Settings for the RepAgent pathway differ from typical Replication Server settings in two ways:

• For compatibility with other Adaptive Server parameters, parameters for the RepAgent to Replication Server pathway are set to “true” or “false” instead of “required” or “not_required,” respectively. The default value of all parameters is “false.”

• The RepAgent parameter that specifies whether to validate the sequence of messages received by Replication Server is msg_out_of_sequence_check and not msg_sequence_check.

To enable, or disable, network-based security at Adaptive Server, or to make other security changes at the Adaptive Server that affect RepAgent, refer to the Adaptive Server System Administration Guide.

Examples

This section provides some examples of using sp_config_rep_agent to configure security.


205

• To require that all messages be encrypted, execute:

sp_configure_rep_agent pubs2, ’msg confidentiality’ ’true’

• To change the security mechanism for the RepAgent pathway to DCE, execute:

sp_configure_rep_agent pubs2, ’security mechanism’ ’dce’

Logging In to Replication Server Connect to Replication Server using a client application such as isql or a custom application program you create with Open Client Client-Library. The isql utility includes command line options that enable network-based security services for the connection to Replication Server.

Table 7-10 describes the command line options that you can use with isql to enable network-based security on the connection.

Table 7-10: isql command line options for security

Option Name Meaning

-K keytab_file Use only with DCE security. It specifies a DCE keytab file that contains the security key for the user logging into the server. Keytab files can be created with the DCE dcecp utility—see your DCE documentation for more information. Replication Server must have read permission on this file.

Note For Kerberos users: Specify the location of the key table file using CSFC5KTNAME environment variable (UNIX) or the key table registry key entry (Windows NT).

-S server_name Specifies the server’s network name. If unified login is enabled, this option also specifies the principal user.


206

Examples of Connecting to Replication Server

You can connect to Replication Server by logging in to the security mechanism and then logging in to Replication Server, or you can log directly in to Replication Server.

You must include the -S flag to identify the principal user. Some sample logins follow.

Connecting to Replication Server From the Security Mechanism

To log in first to the DCE security mechanism and then to Replication Server, you can follow these steps:

1 Log in to the DCE security mechanism and receive a credential:

• For DCE, enter

dce_login user_name password

• For Kerberos, enter

kinit user_name password

2 Log in to Replication Server with isql:

-V security_options Specifies unified login. With this option, the user must log in to the network’s security system before running the isql utility. If a user specifies the -U option, the user must supply the network user name known to the security mechanism; any password supplied with the -P option is ignored.

-V can be followed by a string of options that enable additional security services. Here is a list of options and the services they enable.

• c – data confidentiality

• i – data integrity

• m – mutual authentication

• o – data origin stamping service

• r – data replay detection

• q – out-of-sequence detection

-Z security_mechanism Specifies the name of a security mechanism to use on the connection to Replication Server.

Supported security mechanism names are listed in the libtcl.cfg file. If no security mechanism is supplied, the default is used, which is the first security mechanism listed under SECURITY in libtcl.cfg.

Option Name Meaning


207

• For DCE, enter

isql -Srs_server_name -Vsecurity_option


isql -Srs_server_name -Vsecurity_option

Note When using DCE, if you want to log in as another user, you must include the -U and -K options.

Connecting to Replication Server from Outside Security

To connect to Replication Server from outside the security mechanism, you can enter:

• For DCE, enter

isql -Srs_server_name -Uuser_name -Kkeytab_file


isql -Srs-server_name -Yuser_name

Borrowing Security Settings to Secure Other PathwaysThe security services you use when logging in to Replication Server from the command line not only secure the pathway between the client and the server, they may also be duplicated later on in the session when Replication Server opens other pathways.

Replication Server logs in to the primary Replication Server and the primary database over informal pathways when executing these commands:

• create subscription

• drop subscription

• create route

To secure these pathways, Replication Server borrows the security settings entered by the user executing create subscription, drop subscription, or create route when that user logged in to Replication Server.

Managing Network Security

208

Managing Network SecurityThis section describes the tasks you perform to manage and maintain network security.

Using set proxy to Switch LoginsWhen unified_login is enabled, Replication Server always logs in to remote processes as the principal user. Nonetheless, Replication Server commands must be executed on the target data server by the correct user for a particular operation. For example, Replication Server must use the maintenance user login name when applying changes to replicate databases. Replication Server uses the Adaptive Server set proxy command to switch automatically from the login user to the required user.

You can customize the set proxy command with the rs_setproxy function string. rs_setproxy changes the login name in a data server. rs_setproxy has function-string-class scope.

Refer to the Replication Server Reference Manual for more information about rs_setproxy.

Disabling Network-Based SecurityYou can disable all security services with the configure replication server command and the use_security_services to ’off’ parameter.

When you disable network security, Replication Server does not accept incoming logins with security credentials and does not attempt to log in to other processes with a security credential. No security services are active.

Here is the procedure for disabling security:

1 Log in to the Replication Server, and at the isql prompt enter this command:

configure replication server set use_security_services to ’off’

2 Restart Replication Server by executing the repserver command or the Replication Server run file. Refer to “Replication Server Executable Program” on page 88 for information about the repserver command.


209

To enable network-based security at the Replication Server, refer to “Setting Up Network-Based Security” on page 186.

Changing the Security MechanismTo change to another security mechanism, log in to Replication Server and execute this command at the isql prompt:

configure replication server set security_mechanism to ’mechanism_name’

The security mechanism you change to must be installed and listed in the SECURITY section of the libtcl.cfg file.

Resetting Per-Target Values to Default ValuesYou can change all of your per-target security values for connections or routes using the set security_services to ‘default’ option.

For Connections

Use alter connection to change per-target security settings to global values set with configure replication server .

Follow this procedure:

1 Log in to the Replication Server and execute the suspend connection command at the isql command. Here is the syntax:

suspend connection to dataserver.database

2 Change security settings with the alter connection command. Here is the syntax:

alter connection to dataserver.databaseset security_security services to ‘default’

3 Resume the root or connection with the resume connection command for the changes to take effect. Here is the syntax:

resume connection to dataserver.database

Changes take effect after you resume the connection. This procedure does not affect the configuration of use_security_services.


210

For Routes

Use the set security_services to ’default’ parameter with alter route to change per-target security settings to global values set with configure replication server.

Follow this procedure:

• Suspend the route. Enter:


• Alter the route. Enter:

alter route to dest_replication_server set security_services to ’default’

• Resume the route. Enter:


Changes take effect after you resume the route. This procedure does not affect the configuration of use_security_services.

Viewing Information About Security ServicesYou can display information about Replication Server’s network-based security using the admin security_property and admin security_setting commands.

What Security Mechanisms and Services Are Available?

To find out which security mechanisms and services are supported at the Replication Server, execute the admin security_property command at the isql prompt:

admin security_property[, security_mechanism]

Replication Server displays the name of supported security mechanisms, the security services available for that mechanism, and whether or not those services are supported at your site.


211

What Are the Current Security Settings?

To determine the status of supported security services, use the admin security_setting command. You can view status information for security parameters that have been set for routes and/or the ID Server. Here is the syntax:

admin security_setting[, rs_idserver |, rep_server ]

where rs_idserver is the name of the ID Server and rep_server is the name of the destination Replication Server.

Mapping a Security System Login to a Replication Server LoginYour network-based security mechanism may use login names that are not valid on Replication Server. For example, login names on Replication Server must not exceed 30 characters or include certain special characters such as *, (, and %. Login names on Replication Server must be valid identifiers, which are described in “Identifiers” in Chapter 2 of the Replication Server Reference Manual.

If the security login name is not a valid identifier, Replication Server automatically maps invalid characters to valid characters and truncates login names at 30 characters. Table 7-11 describes how Replication Server translates invalid characters.

Table 7-11: Replication Server converts invalid characters

Using More Than One Security MechanismIf your replication system supports multiple security mechanisms, you may need to install more than one security mechanism on your Replication Server to ensure that both ends of each pathway can support the same mechanism. In this scenario, you can:

1 Configure the Replication Server, for all routes, connections, and other pathways, using configure replication server. Make sure that the default security mechanism name is the first one listed under SECURITY in the libtcl.cfg file.

Invalid Characters Convert to

\ % & , : = > ‘ ' ~ an underscore: _

! ^ ( ) . < ? { } a dollar sign: $

“ - ; * + / [ ] | a pound sign: #


212

2 Configure security for the individual pathways that use a different security mechanism. Make sure that the security mechanism is listed in libtcl.cfg. Table 7-6 lists pathways and the methods for securing them.

To find out the security mechanisms and supported security parameters of the Replication Server, use the admin security_property command. To find out the security mechanisms and current settings of a particular pathway, use the admin security_settings command. Refer to “Viewing Information About Security Services” on page 210 for more information.

Potential Security Issue

If different security mechanisms are used at the primary and replicate databases and Adaptive Server user names cannot be guaranteed unique at these sites, a potential security breach exists for request stored procedures.

If this scenario exists on your system, you can make sure that security is maintained by turning “off” the dsi_exec_proc parameter for the connection with the primary database. Executing alter connection and turning dsi_exec_proc “off” disables Replication Server’s request-stored-procedures feature.

Here is the syntax:

alter connection to data_server.database set dsi_exec_request_sproc ’off’

213

C H A P T E R 8 Managing Replicated Tables

This chapter describes setting up and managing replicated tables.

Replication Server allows you to copy and update data from a table in one database—the primary—to a table in another database—the replicate.

Note The primary database is also referred to as the “source.” The replicate database is also referred to as the “destination.”

To establish a table as the source, you create a replication definition that specifies the location of the data you want to copy and describes the structure of the table in which the data resides.

Before you copy data from the source table, you must also create a duplicate of the table in the destination data server. Then, in the Replication Server that manages the destination table, you create a subscription to the replication definition. A subscription resembles a SQL select statement.

If you don’t want to duplicate all of a table’s data, Replication Server lets you specify a subset of columns to copy in the replication definition or use a where clause in the subscription to specify a subset of rows to receive.

You can include replication definitions for related tables and stored procedures in a publication and then create subscriptions against all of them as a group. When you use publications you can organize your subscriptions and monitor status information for all subscriptions in the group with a single command.

You can change the datatype of replicated values using the heterogeneous datatype support (HDS) feature. HDS allows you to translate the datatype of a replicated column value to a datatype acceptable to the replicate data server. You can use HDS in Sybase environments, in non-Sybase environments, and in mixed Sybase and non-Sybase data server environments.

This chapter discusses the preparations, the procedures, and the specific commands used to manage replicate tables, replication definitions, and publications.

Planning a Replication System

214

See Chapter 9, “Managing Replicated Functions” for information on creating replication definitions that copy replicated procedures.

See Chapter 10, “Managing Subscriptions” for information on creating subscriptions for individual replication definitions and for publications. See “Subscription Example” on page 338 for an example of the entire transaction replication process.

Planning a Replication SystemThis section summarizes the information you need to consider when planning your replication system. See the Replication Server Design Guide for more information.

Design ConsiderationsWhen you set up a replication system, consider the following:

• Security, including user login names and passwords, permissions required for executing commands, and third-party security systems. See Chapter 7, “Managing Replication Server Security”

• Concurrency control; specifically, protecting your replication system from conflicts that may result from data being modified by one client when it is also being used by another. See “Transaction Processing and Distributed Concurrency Control” in Chapter 1 of the Replication Server Design Guide.

• CPU, memory, disk, and network resources. See Appendix A, “Capacity Planning,” in the Replication Server Design Guide.

• Consider your replicated data model and routing scheme. See Chapter 1, “Introduction” and Chapter 5, “Managing Routes”

• Requirements for using heterogeneous data servers as data sources or data destinations. Refer to “Heterogeneous Data Server Support” in Chapter 1, “Introduction,” in the Replication Server Design Guide.

• Compatibility between Adaptive Servers and Replication Servers of different versions. See “Restrictions on Data Replication” on page 215.

For information about Sybase compatibility issues, see the release bulletin for your platform.

CHAPTER 8 Managing Replicated Tables

215

Restrictions on Data ReplicationWhen you design your replication system, you should also consider the following restrictions.

• Adaptive Server and Replication Server system tables cannot be copied during normal replication. However, the execution of supported commands and system procedures on certain system tables can be copied in warm standby applications. Refer to “What Information Is Replicated?” on page 420 for more information. In addition, some data is automatically copied between RSSDs in the replication system.

• Tables that you want to copy must have unique primary keys.

• Client applications should not update unique index or primary key columns in a way that a key could duplicate the key of another row. Because of the way Replication Server copies transactions, this type of update could result in duplicate rows or errors at replicate databases.

For example, if pk_col is the primary key column for table1, the following command could cause errors or incorrect data at the replicate database:

update table1set pk_col = pk_col + 1

If there is a primary key or unique index constraint on the replicate table, the updates fail and the DSI thread for the replicate database is suspended.

• Replication Servers of different versions can work together in the same replication system, but certain features may be restricted. See “Mixed-Version Replication Systems” on page 18 for more information.

Preparing a Replication SystemBefore you replicate data, complete the following preparatory tasks:

• Set up the replication system:

• Install Replication Servers. See the Replication Server installation and configuration guides for your platform.

• Create the databases that will be the primary and replicate. See the Adaptive ServerEnterprise Reference Manual or the documentation for your non-Sybase database software.

• Establish connections from Replication Servers to the primary and replicate databases.

Summarizing the Process

216

See the Replication Server configuration guide for your platform and Creating Database Connections in Chapter 6, “Managing Database Connections”

• Establish all necessary routes between Replication Servers. See Chapter 5, “Managing Routes”

• Configure and start up database RepAgents for source databases. See Chapter 4, “Managing a Replication System”

• Verify that all replication system components are working. See Chapter 11, “Verifying and Monitoring Replication Server”

Refer to the Replication Server installation and configuration guides for your platform for more information. Also see Chapter 4, “Managing a Replication System” for more information about starting and stopping Replication Servers.

Summarizing the ProcessThis section describes how to replicate data between tables. For more information, see “Specifying Data for Replication” on page 33, and the following tables:

• Table 8-1 on page 220



For information about how to group replication definitions in publications and create publication subscriptions against them, see “Using Publications” on page 271 and “Using Publication Subscriptions” on page 350.

Replication ProcedureThe following procedure summarizes the steps required to replicate data using table replication definitions and subscriptions, and where to turn for detailed instructions. For an example of the entire process, see “Subscription Example” on page 338.

1 Be sure you understand the issues described in “Planning a Replication System” on page 7-2. Verify that you prepared the replication system as described under “Preparing a Replication System” on page 7-3.


217

2 Create the table as the Database Owner in the primary database, if it does not already exist, or, if there is a different table owner, specify the table owner name when you create the replication definition.

• In Adaptive Server, use create table to create the table, or use sp_help to verify that the table exists.

• If you are replicating data from a source other than Adaptive Server, create the table according to the instructions for your database software. Other data server steps in this procedure may vary for heterogeneous replication.

3 In the primary Replication Server, create one or more replication definitions for the table from which you want to copy data. Each replication definition can be subscribed to by a different site that uses a different table view.

When you create replication definitions, anticipate the requirements for the subscribing table, as described in step 8. The replication definition may contain all or a subset of the columns in the source table. It may specify the same or different table names, owner names, column names, or datatypes for the source and destination tables. It may change the datatype of the replicated value.

See “Using the create replication definition Command” on page 223 for details. See “Creating Multiple Replication Definitions Per Table” on page 234 also.

In Sybase Central, see “Creating table replication definitions” in Replication Server’s online help.

4 If you are using publications, execute the following steps at the primary Replication Server.

• Create one or more publications for the tables you want to replicate using create publication.

• Create one or more articles, replication definition extensions, for each replication definition you want to include in the publication using create article. You can include a where clause to specify a subset of rows to send to the destination database.

• Validate the publications, using validate publication, so that you can create subscriptions against them.

See “Using Publications” on page 271 for more information about creating publications.

RSM


218

In Sybase Central, see “Managing Publications” in Replication Server’s online help.

5 Mark the source table for replication.

In the primary Adaptive Server, use sp_setreptable to enable table replication. This step allows the RepAgent thread to forward transactions for the table to the primary Replication Server.

Note For non-Adaptive Server primaries, see your replication agent documentation for instructions on marking tables and columns.

See “Marking Tables for Replication” on page 238 for details.

6 If the source table contains text, image, or rawobject columns, you may need to use sp_setrepcol in the primary Adaptive Server to adjust the replication status for these columns.

Note For non-Adaptive Server primaries, see your replication agent documentation for instructions.

See “Replicating text, image, and rawobject Columns” on page 246 for details.

7 Prepare a login name for the user creating the subscription. Login names that create subscriptions at destination Replication Servers must also exist at the source Replication Server.

See Chapter 7, “Managing Replication Server Security”

In Sybase Central, see “Creating Replication Server user accounts” in Replication Server’s online help.

8 In the replicate database, create a table that matches the schema published by the replication definition. Create the destination table as the Database Owner or as the same table owner specified in the replication definition.

In Adaptive Server, use create table to create the table, or use sp_help to verify that the table exists.

RSM

RSM


219

The destination table may have the same or different name and/or the same or different owner name as the source table. It may contain all or a subset of the columns in the source table, with the same or different column names or datatypes. The replication definition must specify any such differences between the source and destination tables.

Note The destination table may include a column that is not in the replication definition if the column accepts null values, has a defined default value, or you use a custom function string to apply a value to that column.

9 Grant the replicate database maintenance user login name select, insert, delete, and update permissions on the destination table. The maintenance user executes commands for replicated transactions.

See Chapter 7, “Managing Replication Server Security”.

In Sybase Central, see “Managing Security in a Replication System” in Replication Server’s online help.

10 If necessary, customize your database operations using functions, function strings, and function-string classes. Replication Server function strings execute data server operations.


11 Create a subscription in the replicate Replication Server. If you are using publications, proceed to step 12.

Log in to a replicate Replication Server and create one or more subscriptions to the table replication definition for the data you want to copy. You can subscribe to all the rows in the replication definition’s columns, or use a where clause to copy only certain rows.

A replicate database can subscribe to multiple replication definitions of a primary (source) table, but a replicate table can subscribe to only one replication definition of a source table.

When you create a subscription, the destination table is filled in with the initial table data in a process called materialization. In most cases, Replication Server copies data into the destination table automatically. You can also manually materialize the data.

See Chapter 10, “Managing Subscriptions” for more information about creating and materializing subscriptions.

RSM


220

In Sybase Central, see “Creating table replication definition subscriptions” in Replication Server’s online help.

12 If you are using publications, create a publication subscription against the publications created in step 4. Execute create subscription at the replicate Replication Server.

When you create a publication subscription, Replication Server creates subscriptions against each article in the publication. Article subscriptions do not contain where clauses.

See “Using Publication Subscriptions” on page 350 for more information about publication subscriptions.

In Sybase Central, see “Creating publication subscriptions” in Replication Server’s online help.

13 Check the subscription status.

Verify that the subscription data has fully materialized in the replicate database and that transactions are replicating successfully.

See Chapter 10, “Managing Subscriptions” for details.

In Sybase Central, see “Viewing or changing publication subscription properties” in Replication Server’s online help.

Commands for Managing Table Replication DefinitionsTable 8-1 lists the Replication Server commands for working with table replication definitions.

Table 8-1: Commands for managing table replication definitions

RSM

RSM

RSM

Command Task

create replication definition Creates a replication definition for a primary table, which describes the columns you want to copy, the location of the table, and other information. See “Creating Replication Definitions” on page 221.


221

Creating Replication DefinitionsA replication definition describes the source table to Replication Server, specifying the columns you want to copy. It may also describe attributes of the destination table. Destination tables that match the specified characteristics can subscribe to the replication definition. You can create multiple replication definitions for the same primary table, each customized for a particular use. See “Creating Multiple Replication Definitions Per Table” on page 234.

To create a replication definition, use create replication definition at the Replication Server managing the source table. See “Using the create replication definition Command” on page 223.

See “Managing Replication Definitions” in Replication Server’s online help for instructions on creating replication definitions in Sybase Central.

Information about each replication definition is sent to each qualifying Replication Server with a route from the primary Replication Server. Replication Server version 11.5 (and later) receives information about all replication definitions. Replication Server version 11.0.x (and earlier) receives information about no more than one replication definition per primary table. See“Replication Definition Restrictions in Mixed-Version Systems” on page 237 for details.

alter replication definition Modifies an existing replication definition in a variety of ways, including:

• Adding columns

• Add or drop primary keys

• Add or drop searchable columns from the replication definition

• Specifying different replicate table, table owner, column name, or datatype

• Changing minimal column replication

• Add or alter column-level datatype translations

• Change text, image, or rawobject column replication status

• Change how the replication definition is used in replicating to a standby database

See“Altering Replication Definitions” on page 261.

drop replication definition Removes a replication definition from the replication system. You must drop all subscriptions for a replication definition before you can drop the replication definition. See “Dropping Replication Definitions” on page 267.

Command Task

RSM


222

Replication definitions are stored in the rs_objects and rs_columns system tables in the RSSD. The primary version of a replication definition resides at the primary Replication Server.

Replication Definition SettingsEach replication definition must include the following information:

• The name of the replication definition.

• The names of the source and destination tables.

Replication Server assumes that the replication definition name is the name of both the source and destination tables, unless you specify differently.

• The name of the data server and database where the source table is located.

• The column names and datatypes that you want to copy. You can copy all or a subset of the source table’s columns. The replicate column names and datatypes are the same as the primary column names and datatypes, unless you specify differently.

• The primary key—one or more columns that uniquely identify each row in the source table.

Optionally, a replication definition may also include:

• The names of the owners of the source and destination tables. The default table owner is the Database Owner (dbo).

• The names of searchable columns—columns that can be specified in the where clause of a subscription to indicate the rows from the primary table to copy into the destination table.

• For a warm standby application, whether to use the replication definition to copy data into a standby database and whether to copy all of the table’s columns or just the columns in the definition’s column list.

• Whether to copy only the minimal number of columns required for update and delete operations. This option may enhance overall system performance.

• Replication options for text, image, and rawobject columns.

• Column-level datatype translations


223

Using the create replication definition CommandUse create replication definition to describe characteristics to Replication Server of a table you want to replicate.

See “Creating table replication definitions” in Replication Server’s online help for instructions on creating replication definitions in Sybase Central.

Execute create replication definition at the Replication Server that manages the source table’s database. A replication definition must include the name of the source data server and database.

The following example creates a basic replication definition named publishers for source and destination tables with the same name. The primary database is pubs2 managed by the TOKYO_DS data server. All of the table’s columns are included and the pub_id column is specified as the primary key.

create replication definition publisherswith primary at TOKYO_DS.pubs2(pub_id char(4), pub_name varchar(40),city varchar(20), state char(2))primary key (pub_id)

Each part of the command is discussed in the following subsections. See create replication definition in Chapter 3, “Replication Server Commands” in the Replication Server Reference Manual for complete command syntax and usage guidelines.

Specifying the Replication Definition Name and Table Names

A replication definition has a global name space—that is, at every Replication Server with routes from the primary Replication Server, the name refers to the same replication definition.

Replication Server cannot always enforce the unique-name requirement when you enter create replication definition. You must ensure that there is no existing replication definition (table or function) with the same name when you create a new replication definition.

By default, the replication definition name is the name of both the source and destination tables.

In some instances, you may need to use different names for your source and destination tables, or different names for your tables and replication definitions. Include one of the optional clauses with all tables named, with primary table named, or with replicate table named to specify table names where they differ from the replication definition name.

RSM


224

When Source and Destination Tables Share the Same Name

When the source table and all destination tables share the same name but you want to give the replication definition a different name, use with all tables named to specify the table names.

For example, to create a replication definition named publishers_rep for source and destination tables named publishers, enter this command:

create replication definition publishers_repwith primary at TOKYO_DS.pubs2with all tables named publishers...

When Source and Destination Tables Have Different Names

When the source table and any destination tables have different names, use with primary table named to specify the name of the source table, or use with replicate table named to specify the destination table name. You can use one of these clauses or both of them together.

If you don’t specify different table names, the replication definition name is assumed by Replication Server to be the name of both the source and destination tables.

For example, to create a replication definition named publishers_rep for a source table named publishers1 and destination tables named publishers2, enter:

create replication definition publishers_repwith primary at TOKYO_DS.pubs2with primary table named publishers1with replicate table named publishers2...

For a replication definition and a source table named publishers, and destination tables named publishers2, enter:

create replication definition publisherswith primary at TOKYO_DS.pubs2with replicate table named publishers2...

In this example, the publishers replication definition also becomes the source table’s name.


225

Specifying the Name of the Source or Destination Table Owner

You can specify the table owner’s name as an optional qualifier along with the name of the source or destination table. Data server operations may fail if the table owner does not correspond to what is specified in the replication definition.

For example, to create a replication definition for the publishers source table and the publishers2 destination table owned by the user “ravi,” enter:

create replication definition publisherswith primary at TOKYO_DS.pubs2with replicate table named ravi.publishers2...

Specifying Column Names and Datatypes

When you create a replication definition, you list the names and datatypes of the columns from the table that you want to copy.

A column’s name and datatype will be the same in the replicate table as in the primary table unless you specify a different replicate (published) column name or datatype.

Enclose the names of all of the columns and their datatypes in parentheses. For multiple columns, separate each column and its datatype from the next column with a comma.

For example, the following command creates a replication definition named publishers_rep1 for source and destination tables named publishers. It includes all the columns and their datatypes.

create replication definition publishers_rep1with primary at TOKYO_DS.pubs2with all tables named publishers(pub_id char(4),pub_name varchar(40),city varchar(20),state char(2))primary key (pub_id)

The following command creates a replication definition named publishers_rep2 that omits the city column. Destination sites that do not require this column can subscribe to this replication definition.

create replication definition publishers_rep2with primary at TOKYO_DS.pubs2with all tables named publishers


226

(pub_id char(4),pub_name varchar(40),state char(2))primary key (pub_id)

Performance is best if columns are listed in the same order in the replication definition as in the tables themselves.

You can use only datatypes supported by Replication Server. If a primary table has columns with user-defined datatypes, you must use a compatible supported datatype in the replication definition. You can also employ user-defined datatypes suppled with Repication Server after you install them.

Refer to “Datatypes” in Chapter 2, “Topics,” in the Replication Server Reference Manual for complete details on the datatypes supported by Replication Server.

When Source and Destination Columns Have Different Names

When you want only one replication definition for a source table, and the source column names differ from their destination counterparts, use the column_name as replicate_column_name clause in the replication definition.

For example, for a source table named publishers1 and a destination table named publishers2, where the source column pub1_name corresponds to the destination column pub2_name, enter this:

create replication definition publishers_repwith primary at TOKYO_DS.pubs2with primary table named publishers1with replicate table named publishers2(pub_id char(4),pub1_name as pub2_name varchar(40),city varchar(20),state char(2))primary key (pub_id)

Datatypes in Multiple Primary Table Replication Definitions

When you create multiple replication definitions for the same source table, the declared column datatype (the column datatype in the primary table) must be the same, except when the column’s datatype is rawobject or rawobject in row, which correspond respectively to the image and varbinary datatypes. Specifically you can:


227

• Declare a column’s datatype as rawobject in one replication definition, but declare the same column’s datatype as image in another replication defintion for the same table

• Declare a column’s datatype as rawobject in row in one replication definition, but declare the same column’s datatype as varbinary in another replication definition for the same table

The replicate (published) column datatype can be different between replication definitions for the same table, with no restrictions.

When a column is listed in an existing replication definition for a primary table, specifying the column datatype is optional in subsequent replication definitions for the same primary table—the datatype is inherited from the previous replication definition and retained for the subsequent definition, even if the first definition (where you specified the datatype) is dropped.

To change a column datatype, use the alter replication definition command. Refer to “Altering Column Datatypes” on page 264.

Additional Columns in the Replicate Table

The replicate table may include a column that is not in the replication definition if the column has a defined default value or you use a custom function string to apply a value to that column.

Columns can be specified to accept null values in create table. When source rows are copied to the destination table, extra columns are filled with null values or may be updated separately by the local data server.

Including text, image, and Java Columns

To copy text, image, or the Java datatypes rawobject and rawobject in row column data to any destination site, include those columns in the replication definition. Replicating text, image, or Java columns involves additional special procedures and considerations.

See “Replicating text, image, and rawobject Columns” on page 246 and “Java Datatypes in Replication Server” on page 242 for more information.

Using Special Datatypes

To distribute updates to particular sites, use the rs_address special datatype. See “Using the rs_address Datatype” on page 255 and “Bitmap Subscriptions” on page 344 for more information.


228

You can also use the identity special datatype if the table you are copying contains an IDENTITY column. See “Replicating IDENTITY Columns” on page 255 for more information.

Using User-Defined Datatypes

To change the datatype of the replicated value at the primary database to a datatype acceptable to the replicate database, use user-defined datatypes. See “Translating Datatypes Using HDS” on page 281 for more information.

Specifying the Primary Key

The primary key is the column or combination of columns that uniquely identifies each row. Although many data servers, including Adaptive Server, allow tables that contain duplicate rows, Replication Server requires that the source and destination tables have unique values for the primary key columns in each row.

You must include the primary key clause in create replication definition to identify the primary key columns in the source table. Primary key columns must also be included in the column list.

When Replication Server applies the default rs_update or rs_delete function string at a destination site, it specifies values for the primary key in the where clause of the update or delete statement.

Enclose the names of the primary key columns in parentheses. For example:

create replication definition publisherswith primary at TOKYO_DS.pubs2(pub_id char(4), pub_name varchar(40),city varchar(20), state char(2))primary key (pub_id)

For multiple primary key columns, separate each column from the next with a comma.

Note You cannot include columns of datatypes text, image, rawobject, rawobject in row or rs_address as part of the primary key.


229

Specifying Searchable Columns

Use searchable columns in create replication definition to specify which columns to use in the where clause of create subscription or define subscription (or create article for publications) to restrict the rows copied to a subscribing site. If you do not include a searchable columns clause in a replication definition, you cannot use a where clause in a subscription or article that references that replication definition.

Enclose the names of the searchable columns in parentheses. For multiple searchable columns, separate each column from the next with a comma.

In the following example, three columns, pub_id, pub_name, and state, are specified as searchable columns. You can include any of these columns in a subscription’s where clause.

create replication definition publisherswith primary at TOKYO_DS.pubs2(pub_id char(4), pub_name varchar(40),city varchar(20), state char(2))primary key (pub_id)searchable columns (pub_id, pub_name, state)

See “Using the where Clause” on page 328 for additional information on using where in subscriptions.

Restrictions on Searchable Columns

Searchable columns have the following restrictions:

• You cannot specify text or image columns or Java rawobject or rawobject in row columns as searchable columns.

• Columns included in the searchable columns clause cannot have null values.

• To perform bitmap comparison using the where clause in the subscription, you must include any columns that use the rs_address datatype in the replication definition’s searchable columns clause. See “Using the rs_address Datatype” on page 255 for more information.

• The more searchable columns in the searchable columns list of a replication definition, the slower Replication Server processes subscriptions; that is, the fewer searchable columns, the more efficiently Replication Server evaluates rows against subscriptions for the table.


230

Replicating the Minimal Set of Columns

Normally, Replication Server sends all the columns in each row when applying updates and deletes, as well as inserts, in each replicate database. Replication Server normally sends maximum columns to the standby database—if replication definitions are not used for the table or the replication definitions are not used for the standby connection.

Note You must send all columns when replicating to SQL Remote databases. Do not send minimal columns or replication will fail.

To enhance replication system performance, specify replicate minimal columns in create replication definition. This clause lets you send only those columns that are required for delete and update operations to replicate databases.

When you set replicate minimal columns:

• For a delete operation, the source Replication Server sends only the primary key columns to destination Replication Servers or the standby database.

• For an update operation, the source Replication Server sends only the columns modified by the update operation and the primary key columns, to destination Replication Servers or the standby database.

Note replicate minimal columns does not apply to insert operations, for which all columns are copied.

A destination Replication Server uses the primary key columns in constructing the data server commands that it applies to the replicate or the standby database.

The following replication definition includes replicate minimal columns:

create replication definition publisherswith primary at TOKYO_DS.pubs2(pub_id char(4), pub_name varchar(40),city varchar(20), state char(2))primary key (pub_id)replicate minimal columns


231

Changing Minimal Columns Setting

Use alter replication definition to change an existing replication definition to replicate only the minimal set of columns or to replicate all columns.

Minimal Columns and rs_update and rs_delete Function Strings

If you specify replicate minimal columns and need to create non-default rs_update and rs_delete function strings, use the rs_default_fs function string variable to represent the default function string behavior. See “Using the Default System Variable” on page 408 for details.

Minimal Columns and Autocorrection

If you specify replicate minimal columns, you cannot also specify autocorrection, which corrects discrepancies that may occur during materialization by converting each update or insert operation into a delete followed by an insert.

If you set autocorrection on before you specify minimal columns (for example, using alter replication definition), autocorrection is not performed. Replication Server logs informational messages for any update operations.

You must set autocorrection on when you create a subscription using nonatomic materialization. If minimal column replication is set for the replication definition and you create a new subscription that uses nonatomic materialization or the bulk materialization method that simulates nonatomic materialization, autocorrection cannot resolve inconsistencies.

See Chapter 10, “Managing Subscriptions” for details on materialization methods. See “Using autocorrection” on page 314 for more information on this command.

Using Replication Definitions with Warm Standby Applications

You do not need to use replication definitions with warm standby applications. However, you can use them to control the flow of information to the standby database—even though no subscriptions are needed. You can create replication definitions just for replication to the standby database or use existing replication definitions for this purpose.

Use send standby in create replication definition as follows:

• Use send standby in any form to replicate transaction data into the standby database using this replication definition. Replication Server uses the replication definition’s primary key and minimal columns setting.


232

See “Specifying the Primary Key” on page 228 and “Replicating the Minimal Set of Columns” on page 230 for more information.

• Use send standby or send standby all columns to send all columns in the table to a standby database.

• Use send standby replication definition columns to send only the columns specified in the replication definition to a standby database.

If you omit send standby, another replication definition may be used in replicating data for this table to the standby database, or no replication definition may be used.

The replication definition in the following example replicates transactions to a standby database. The primary key and minimal set of columns settings will be used in standby replication. Only the columns specified in the replication definition will be replicated into the standby database—the city column is omitted from this replication definition.

create replication definition publishers_wswith primary at LDS.pubs2with all tables named ’publishers’(pub_id char(4),pub_name varchar(40),state char(2))primary key (pub_id)send standby replication definition columnsreplicate minimal columns

If a replication definition already exists for the same primary table and is marked for use by the standby, creating a new replication definition using send standby (or altering another replication definition) unmarks the previous replication definition as being used by the standby.

See “Using Replication Definitions and Subscriptions” on page 464 for more information about using replication definitions with warm standby applications.

Specifying text and image Column Replication

To create a replication definition for a table that contains text or image columns datatypes:

• Include each text or image column that you want to replicate in the column list, and


233

• Include each column in the optional clauses replicate_if_changed or always_replicate.

In each clause, enclose the names of the text and image columns in parentheses. For multiple columns, separate each column from the next with a comma.

• Ensure that each text and image column has a corresponding status in Adaptive Server.

See “Replicating text, image, and rawobject Columns” on page 246 for more information on replicating text and image columns.

See“Replicating text, image, and rawobject Data” on page 426 for information about replicating text and image columns in warm standby applications.

Specifying rawobject and rawobject in row Column Replication

You can include Java columns in a replication definition. Replication Server replicates Java columns as either rawobject or rawobject in row datatypes. To create a replication definition for a table that contains Java datatypes:

• Include each rawobject or rawobject in row column that you want to replicate in the column list, and

• Include each rawobject column in the optional clauses replicate_if_changed or always_replicate.

In each clause, enclose the names of the rawobject columns in parentheses. For multiple columns, separate each column from the next with a comma.

Note rawobject in row columns do not have replication status.

• Ensure that each rawobject column has a corresponding status in Adaptive Server.

See “Replicating text, image, and rawobject Columns” on page 246 for more information about replicating Java columns.

Specifying Column-Level Datatype Translations

You can specify column-level datatype translations in the replication definition. Sybase provides a set of datatype definitions that you install using instructions from the Replication Server Configuration Guide for your platform.


234

• The declared_datatype defines the datatype of the value delivered to the Replication Server from the replication agent. It must be the Replication Server base datatype or a datatype definition for the datatype in the primary database.

• The published_datatype defines the datatype of the value after a column-level translation. It must be the Replication Server base datatype or a datatype definition for the datatype in the replicate database.

See “Translating Datatypes Using HDS” on page 281 for detailed information about datatype translations.

Creating Multiple Replication Definitions Per TableYou can create multiple replication definitions for the same primary table and customize each one so that it can be subscribed to by a replicate table whose characteristics are different from those of the primary table or from other replicate tables.

For example, you can create two separate replication definitions for the same primary table, one that replicates columns A and B, and another that replicates columns C and D. Each subscribing site receives only the columns that it needs (see Figure 8-1).


235

Figure 8-1: Using multiple replication definitions from one primary table

In addition to describing the primary table, each replication definition can specify a smaller number of columns, different column names, different published datatypes, or a different table name for a replicate table. Replicate tables that match the specified characteristics can subscribe to the replication definition.

Different replication definitions created for the same primary table must use the same declared column datatype (unless the datatype is rawobject or rawobject in row) and the same null and not null status for text and image columns. To change a column’s datatype or null status, use alter replication definition. Refer to “Altering Column Datatypes” on page 264 for instructions.

You can change replication status using alter replication definition. For example, you can change the replication status of text and image columns from replicate_if_changed to always_replicate. The replication status for the column will also change for other replication definitions for the same primary table.


236

See “Creating Multiple Replication Definitions Per Table” on page 234 for more information.

Restrictions

When you have multiple replication definitions for the same primary table, the following restrictions apply:

• A replicate database can subscribe to multiple replication definitions. However, a replicate table can subscribe to only one replication definition of a particular primary table.

• A pre-version 12.0 Replication Server may not subscribe to replication definitions that either declare columns with User-Defined Datatypes or employ column-level translations.

• Different replication definitions created for the same primary table must use the same column datatype (unless it the datatype is rawobject or rawobject in row) and, for text, image, and rawobject columns, the same null or not null status and the same replication status.

See “Specifying Column Names and Datatypes” on page 225.

• You cannot create multiple replication definitions for a single primary stored procedure.

• Multiple replication definitions for one primary table are only supported in Replication Server version 11.5 and later; however, one replication definition can be marked and propagated to a Replication Server of a previous version, if compatible; that is, has the same primary and replicate table names, same primary and replicate column names, and does not include table owner name.

See “Replication Definition Restrictions in Mixed-Version Systems” on page 237 for additional information.

Replication Definitions and Function StringsFunction strings map Replication Server functions to data server commands for execution in a database.


237

For each replication definition, the primary Replication Server creates default function strings for the system functions with replication definition scope (rs_insert, rs_update, rs_delete, rs_select, and so on). These function strings are distributed with the replication definition to other qualifying Replication Servers with routes from the primary Replication Server.

Some circumstances may require you to create the function strings for system functions (that is, Replication Server does not create them for you).

See Chapter 12, “Customizing Database Operations” for details on function strings and function-string classes. See Chapter 2, “Replication Server Technical Overview” for more information about how Replication Servers share information.

Replication Definition Restrictions in Mixed-Version Systems• If you create or alter a replication definition that includes a rawobject or

rawobject in row column, only Replication Server version 12.0 or later can subscribe to that replication definition.

• You can introduce column-level and class-level datatype translations only between Replication Servers of version 12.0 or later.

• If your replication system uses different versions of Replication Server (for example, version 11.0.x and version 11.5 or later), Replication Server version 11.0.x is subject to the following limitations:

• You cannot subscribe to a replication definition that specifies any of the following information:

• Different source and destination table names

• Different source and destination column names

• Source or destination table owner names

Such a replication definition is incompatible with and unavailable to Replication Servers earlier than version 11.5.

Marking Tables for Replication

238

• You can receive information about and subscribe to only one replication definition per table; however, when a Replication Server version 11.5 or later primary table has multiple replication definitions, the first replication definition created for the table can be marked and propagated to a Replication Server of a previous version, if it is compatible; that is, has the same primary and replicate table names, same primary and replicate column names, and does not include table owner name.

If you drop that replication definition, the next oldest 11.0.x-compatible replication definition created for that table is available for Replication Server version 11.0.x.

If subscriptions exist from Replication Server version 11.0.x, you must not alter an 11.0.x-compatible replication definition so that it is no longer compatible with 11.0.x. If you do so, that replication definition is no longer available to 11.0.x Replication Servers and the next oldest 11.0.x-compatible replication definition (if any) is available to the 11.0.x Replication Servers.

• You cannot create multiple replication definitions per table or customize them for destination tables.

See “Mixed-Version Replication Systems” on page 18 for more information.

Marking Tables for ReplicationAfter you create a replication definition for a table, use sp_setreptable to mark the table for replication. After a table is marked for replication, RepAgent begins forwarding the table’s log records to the Replication Server.

If you have marked a table for replication, you do not need to mark it again for another replication definition.

See “Subscription Example” on page 338 for an example of setting up replication for one table.

Note Refer to your Replication Agent documentation for instructions on marking tables for replication in non-Sybase data servers.


239

Using the sp_setreptable System ProcedureTo designate a primary Adaptive Server table for replication, use sp_setreptable. To use sp_setreptable, you must be the Database Owner or the System Administrator for the data server.

Refer to sp_setreptable in Chapter 5, “Adaptive Server Commands and System Procedures” in the Replication Server Reference Manual for complete syntax and usage guidelines.

Enabling Replication

To mark a table for replication, log in to the Adaptive Server managing the database for that table and enter:

sp_setreptable table_name, ’true’

Marking the table in this way specifies that the table name must be unique.

Note Do not mark a table for replication in unless you also create a replication definition for the table in the Replication Server managing that database. The RepAgent will begin forwarding to the Replication Server data for transactions for the affected table. If a replication definition does not exist, Replication Server may report message 32032 and its error log file may fill up. In addition, Replication Server performance may be significantly reduced. Warm standby applications, which do not require replication definitions, are not subject to this problem.

Checking Replication Status

To check replication status for the table, enter:

sp_setreptable table_name

To check replication status for all tables in the database, enter:

sp_setreptable

Enabling Replication with owner_on Status

Note Refer to your Replication Agent documentation to see if your non-Sybase data server allows user tables with the same name but different owners.

Marking Tables for Replication

240

User tables may have the same name but different owners. Adaptive Server allows you to mark a table for replication and specify that table owner information should be considered when identifying the table.

To mark the table for replication with the “owner on” status, log in to Adaptive Server and enter:

sp_setreptable table_name, ’true’, owner_on

At the Replication Server, the replication definition for the table must identify the table owner. For example, if you set owner status for a table to “owner on” with sp_setreptable, you must include an owner name when you create the replication definition or Replication Server will be unable to find the correct table at the replicate database.

The owner of the source table and the owner of the destination table can be different.

Note If you specify “owner off” status for a table, Replication Server does not send table owner information to the replicate site. However, if you are replicating to a standby database, Replication Server sends “dbo” as the table owner.

Modifying the Owner Status of a Table

You can change the owner status of a table previously marked for replication by using the sp_setrepdefmode system procedure.

To change the status of a table already marked for replication to “owner on,” log in to Adaptive Server and enter:

sp_setrepdefmode table_name, owner_on

To change the status of a table already marked for replication to “owner off,” log in to Adaptive Server and enter:

sp_setrepdefmode table_name, owner_off

You must reflect a change in owner status by including owner information in the replication definition. Use create replication definition at the Replication Server to create a new replication definition that includes the table owner.

Checking the Owner Status of a Table

To check the owner status of a table, enter:

sp_setreptable table_name

Disabling Replication

To turn off replication for the table, enter:


241

sp_setreptable table_name, ’false’

Note Refer to your Replication Agent documentation for instructions on disabling replication in non-Sybase data servers.

Replicating Java ColumnsYou can replicate Java columns stored in your primary database to your standby and replicate databases. Replication Server passes Java objects through the replication system in serialized format without altering the Java objects in any way.

Refer to Java in Adaptive Server Enterprise for complete information about Java classes in the Adaptive Server database.

RestrictionsAlthough you prepare replication definitions and subscriptions for Java columns in the usual manner, certain restrictions apply:

• Both the primary and replicate databases must be Sybase Adaptive Server version 12.0 or later.

• Replication Server does not replicate stored procedures that have Java objects as parameters. However, the effect of such a stored procedure can be duplicated through normal table replication.

• You cannot use Java columns as part of the primary key.

• You cannot evaluate Java columns in subscription expressions because Java columns are not searchable.

Upgrade ConsiderationsAfter you have upgraded the current Replication Server and set its site version to the current release, the RSM Server route upgrade utility automatically copies replication definitions with Java columns from upstream Replication Servers to the current Replication Server.

Replicating Java Columns

242

Although Replication Server does not propagate replication definitions with Java columns to pre-12.0 version Replication Servers, you can replicate Java columns to older Replication Servers by manipulating function strings. See “Using Function Strings to Replicate to Older Replication Servers” on page 1-8 for more information.

Java Datatypes in Replication ServerJava columns pass through the replication system as one of two Replication Server datatypes:

• As rawobject, in which the information is stored in the database in a separate location in the same way that image data is stored. The base datatype of rawobject is image. This is the default datatype for Java columns in Replication Server. Replication Server handles rawobject data in the same way it handles image data.

Refer to “Replicating text, image, and rawobject Columns” on page 246 for information about replication for rawobject columns.

• As rawobject in row, in which the information is stored in the database on consecutive data pages allocated to the table in the same way that, for example, char data is stored. The base datatype of rawobject in row is varbinary(255). Replication Server handles rawobject in row data in the same way it handles varbinary(255) data.

rawobject and rawobject in row are compatible only with their base datatypes. They are not compatible with each other; that is, you cannot replicate rawobject to rawobject in row or vice versa.

The Replication Server reconciliation utility rs_subcmp treats Java datatypes as their base datatypes. Refer to the Replication Server Reference Manual for more information about rs_subcmp.

Creating Replication Definitions for Java ColumnsYou can create replication definitions for Java columns using create replication definition and the rawobject and rawobject in row datatypes.

When creating a replication definition:

• rawobject values have replication status. You can choose whether they are always replicated or replicated only if changed. They also have null status.


243

Refer to “Replicating text, image, and rawobject Columns” on page 246 for information about replication for rawobject columns.

• rawobject in row values do not have replication or null status.

rawobject and rawobject in row values:

• Cannot be part of the primary key.

• Cannot be evaluated in subscription expressions. Java columns are not searchable, and thus they cannot be used in a subscription or article where clause.

This example creates a sample replication definition p1 for a table t that contains Java columns.

create replication definition p1with primary at ds.dbwith all tables name t

(c1 int,c2 rawobject null,c3 rawobject not null,c4 rawobject in row)

primary key (c1)replicate_if_changed (c2)always_replicate (c3)

Columns c2 and c3 are rawobject columns; they have replication and null status. Column c4 is a rawobject in row column; it does not have replication or null status. Columns c2, c3, and c4 are neither part of the primary key nor are they searchable.

Function Strings for Java ColumnsReplication Server uses the rs_raw_object_serialization function string to pass Java columns to the replicate database in serialized format, which allows Replication Server to update Java columns directly. rs_raw_object_serialization is contained in rs_sqlserver_function_class and rs_default_function_class.

When a replication definition references the rawobject datatype, Replication Server creates rs_get_textptr, rs_textptr_init, rs_datarow_for_writetext, and rs_writetext function strings for each rawobject column just as it does for image data.

Replicating Java Columns

244

Using Function Strings to Replicate Java Columns to Older Replication Servers

Replication Server version 12.0 does not propagate replication definitions with Java datatypes to pre-12.0 Replication Servers. However you can replicate Java columns through older Replication Servers if you use the corresponding base datatype (image and varbinary(255)) and manipulate the rs_usedb and rs_insert function strings.

The following example illustrates the method.

1 Create tables containing Java columns in the primary and replicate databases:

create table tInfo(c1 integer,c2 Name rawobject in row,c3 Address rawobject null,c4 AccountInfo rawobject not null)

Name, Address, and AccountInfo are Java classes; c2, c3, and c4 are Java columns.

2 Create a replication definition for table tInfo.

If at least one of the Replication Server is pre-12.0, you must create a replication definition using the base datatypes for rawobject in row (varbinary(255)) and rawobject (image):

create replication definition tInfo1with primary at DS-1.dbasewith all tables name TInfo(c1 integer,c2 varbinary(255),c3 image null,c4 image not null,primary key (c1)...

If the primary and replicate databases are managed by Replication Servers version 12.0 or later, a replication definition could be:

create replication definition tInfowith primary at DS-1.dbasewith all tables named tInfo

(c1 integer,c2 rawobject in row,c3 rawobject null,c4 rawobject not null)primary key (c1)


245

...

3 Alter the rs_usedb and rs_insert function strings for both the primary and replicate database connections. Refer to “Altering Function Strings” on page 400 for general information about customizing function strings.

• For rs_usedb:

alter function string rs_usedbfor function_string_class_nameoutput language‘use ?rs_destination_db!sys_raw? setraw_object_serialization on’

This change tells Adaptive Server to return Java column data as serialized binary values at subscription materialization. It also allows Replication Server to insert and update Java columns with serialized binary values.

• For rs_insert:

alter function string tInfo1.rs_insertfor function_string_class_nameoutput language‘insert tInfo(c1, c2, c4)values (?c1!new?, ?c2!new?, 0xaced000574000130)’

This change alters rs_insert for tInfo1 to insert the special binary value 0xaced000574000130 in column c4. If you do not alter rs_insert, the default value may cause Adaptive Server to return a serialization error.

So, you can create two replication definitions for the same table where the columns between the two replication definitions have different primary (declared) datatypes. If the primary Replication Server is version 12.0 or later, you can create both replication definitions tInfo and tInfo1 for table tInfo. In this case, replicate Replication Servers version 12.0 and later can subscribe to tInfo and Replication Servers version pre-12.0 can subscribe to tInfo1.

Note You cannot use this method to replicate Java columns to standby databases. The standby connection uses the function-string class rs_default_function_class, which cannot be altered.

Replicating text, image, and rawobject Columns

246

Replicating text, image, and rawobject ColumnsReplication Server lets you replicate columns that use the Adaptive Server datatypes text, image and rawobject.

When you replicate text, image, and rawobject columns you must specify a compatible replication status for each text, image, and rawobject column in both the replication definition and in Adaptive Server.

You cannot include text, image, or rawobject columns as part of the primary key or as searchable columns.

See “Managing Replication Definitions” in Replication Server’s online help for instructions on using Sybase Central to replicate text, image, and rawobject columns.

To replicate text, image, and rawobject columns, follow these steps:

1 Use create replication definition to create a replication definition for a table that contains text, image, or rawobject columns.

Refer to create replication definition in Chapter 3, “Replication Server Commands” in the Replication Server Reference Manual for complete command syntax and usage guidelines.

2 Use sp_setreptable to mark the table for replication.

sp_setreptable sets the replication status of text, image, or rawobject columns to always_replicate.

See sp_setreptable in Chapter 5, “Adaptive Server Commands and System Procedures” in the Replication Server Reference Manual for complete syntax and usage guidelines.

3 If you do not want to replicate some of the text, image, or rawobject columns, use sp_setrepcol to change the replications status of those columns.

See “Changing Column Status for text, image, or rawobject Columns” on page 249 for instructions.

4 Use create subscription to make subscriptions for the replication definition and begin replicating the text, image, or rawobject data.

RSM


247

See “Using the create subscription Command” on page 330.

Note When you execute an update at the primary database, you can update a text, image, or rawobject column and a non-text, non-image, or non-rawobject column--a char column, for example--with a single command. When those updates are copied to the replicate database, however, Replicate Server executes two commands, one for text, image, and rawobject updates and one for other datatype updates. If you choose to have DSI ignore certain replication errors, only a portion of the row may be replicated, which creates an inconsistent replicate table.

Creating a text, image, or rawobject Replication DefinitionWhen you create a table replication definition for text, image, or rawobject columns, use these guidelines:

• Include each text, image, or rawobject column that you want to replicate in the column list.

• Specify the datatype for each text, image, or rawobject column.

• Specify whether a null is allowed for the column in destination tables. This setting must be consistent with the way the source and destination tables are defined.

• Include each column in the optional clauses replicate_if_changed or always_replicate.

Specifying a Null Value for text, image, and rawobject Columns

To specify whether or not a null value is allowed in the replicate table for each text, image, or rawobject column, specify null or not null after the datatype for the column in the replication definition.

This setting must be consistent with the way the primary and replicate tables are defined. For text, image, and rawobject columns, the default is not null, meaning that the replicate table does not accept null values.

If you are using multiple replication definitions, the null value setting should be the same for all replication definitions on a primary table.

Do not specify null or not null for columns using datatypes other than text, image, or rawobject. Columns with null values cannot be searchable.


248

The following example replication definition for the table au_pix includes a column pic of datatype image, for which null values are allowed in replicate tables. The pic column is included in the replicate_if_changed clause.

create replication definition au_pixwith primary at TOKYO_DS.pubs2(au_id char(11),pic image null)primary key (au_id)replicate_if_changed (pic)

Marking Tables with text, image, or rawobject ColumnsUse sp_setreptable to set the initial replication status for text, image, and rawobject columns in Adaptive Server when you mark the table for replication. sp_setreptable sets the replication status of text, image, or rawobject columns to always_replicate.

Note If you do not want to replicate text, image, and rawobject columns, use sp_setreplicate to mark the table for replication, which sets the replication status of text, image, and rawobject columns to do_not_replicate.

If you use sp_setreptable to mark a table for replication and the table includes text, image, or rawobject columns, a modification record (64 bytes in length) is logged for every text, image, or rawobject column in every data row of the table. For large tables, this operation may be time-consuming and involve a significant amount of data.

Before you use sp_setreptable on a large table that has text, image, or rawobject columns, be sure that you have enough log space for this operation. You may also want to choose a time that will be least disruptive for client applications or replication system administration.

Refer to sp_setreptable in Chapter 5, “Adaptive Server Commands and System Procedures” in the Replication Server Reference Manual for complete syntax and usage guidelines.

Note Refer to your Replication Agent documentation for instructions on marking tables for replication in non-Sybase data servers.


249

Changing Column Status for text, image, or rawobject ColumnsWhen you mark a table with text, image, or rawobject columns for replication, sp_setreptable sets the replication status of text, image, or rawobject columns to always_replicate.

The replication status is the same for all replication definitions of a primary table. If you change the replication status for one replication definition with alter replication definition, you change the replication status for all replication definitions on the same primary table.

If you do not want to replicate some of the text, image, or rawobject columns in a marked table (or you marked the table using sp_setreplicate, which sets the replication status of text, image, and rawobject columns to do_not_replicate), use sp_setrepcol to adjust the replication status. You can set the replication status for one or all columns to always_replicate, do_not_replicate, or replicate_if_changed. Table 8-2 describes each status.

Table 8-2: text, image, or rawobject column replication status

To use sp_setrepcol, you must be the Database Owner or System Administrator for the data server.

Note If you have marked the database for replication to a standby database using sp_reptostandby and marked database tables for replication to a replicate database using sp_setreptable, Replication Server copies text, image, and rawobject columns to standby and replicate databases as always_replicate. If you want to copy text, image, and rawobject columns as replicate_if_changed, use sp_setrepcol to adjust the replication status. See “Replicating text, image, and rawobject Data” on page 426 for more information about replicating text and image and rawobject columns in a warm standby application.

See sp_setrepcol in Chapter 5, “Adaptive Server Commands and System Procedures” in the Replication Server Reference Manual for complete syntax and usage guidelines.

Status clause Description

always_replicate Adaptive Server logs replication information for the text, image, or rawobject column whenever any column in the row changes.

replicate_if_changed Adaptive Server logs replication information for the text, image, or rawobject column only when the column data changes.

do_not_replicate Adaptive Server does not log replication information for the text, image, or rawobject column.


250

Enabling Column Replication

To mark a column with an image or rawobject datatype for replication, enter:

sp_setrepcol table, column, status

For example, to mark the pic column of datatype image for replication in the table au_pix, enter one of the following:

sp_setrepcol au_pix, pic, always_replicatesp_setrepcol au_pix, pic, replicate_if_changed

Disabling Column Replication

To turn off replication for the an image or rawobject column, enter:

sp_setrepcol table, column, do_not_replicate

For example, to disable replication of the pic column of datatype image for replication in the table au_pix, enter:

sp_setrepcol au_pix, pic, do_not_replicate

Enabling or Disabling Replication for All Columns

To mark all text, image, and rawobject columns in the table with the same replication status, enter “null” instead of a column name. For example, to mark all text, image, and rawobject columns with the replicate_if_changed status:

sp_setrepcol table, null, replicate_if_changed

Execute sp_setrepcol with the table name and a text, image, or rawobject column name to display the replication status of the specified column. For example:

sp_setrepcol table, column

Execute sp_setrepcol with a table name to display the replication status of all of the text, image, and rawobject columns in the table. For example:

sp_setrepcol table

Altering Replication Status for text, image, and rawobject ColumnsWhen you replicate text, image, and rawobject columns you must specify a compatible replication status for each text, image, and rawobject column in both the replication definition and in Adaptive Server.


251

If you change the replication status of text, image, and rawobject columns in one table replication definition, the replication status automatically changes in all other replication definitions for the same table that include those text, image, and rawobject columns.

Changing from replicate_if_changed to always_replicateTo change the replication status of a text, image, or rawobject column from replicate_if_changed to always_replicate:

1 Let all transactions with a replicate_if_changed status finish processing.

2 Use sp_setrepcol to change the status of the column in Adaptive Server to always_replicate.

3 Use alter replication definition to change the status of the column to always_replicate.

Changing from always_replicate to replicate_if_changedTo change the replication status of a text, image, or rawobject column from always_replicate to replicate_if_changed:

1 Use alter replication definition to change the status of the column to replicate_if_changed.

2 Use sp_setrepcol to change the status of the column in Adaptive Server to replicate_if_changed.

Resolving Inconsistencies in Replication StatusThe replication status for text, image, and rawobject columns in the Adaptive Server database is carried in the data modification commands that the RepAgent sends to the Replication Server. If the status is different at the Adaptive Server than in the replication definition, problems may result:

• Scenario 1: If a text, image, or rawobject column has a status of replicate_if_changed at the Adaptive Server database and always_replicate in the replication definition, Replication Server detects the inconsistency when the modification is being replicated, and RepAgent may shut down.


252

• Scenario 2: If a text, image, or rawobject column has a status of do_not_replicate at the Adaptive Server database and the replication definition includes that column for replication, processing continues and the Replication Server sends the modifications to the replicate database without the text, image, or rawobject data. The Replication Server also issues a warning message.

The following procedures enable you to resolve inconsistencies in the replication status of text, image, and rawobject columns for the two conflict scenarios described above and to resume replication operations.

Scenario 1

• Adaptive Server text, image, and rawobject status: replicate_if_changed

• Replication text, image, and rawobject definition status: always_replicate

When RepAgent shuts down because a text, image, or rawobject column has a status of replicate_if_changed at the Adaptive Server database and always_replicate in the replication definition, take the following steps to resolve inconsistencies:

Setting replicate_if_changed

To replicate text, image, or rawobject columns only when their values change:

1 Execute the alter replication definition command and change the status of the text, image, or rawobject columns to replicate_if_changed. Wait for the modified replication definition to arrive at the replicate sites.

2 Restart RepAgent.

Setting always_replicate

To always replicate text, image, or rawobject columns:

1 Stop updates at the primary table.

2 Execute the alter replication definition command, and change the status of the text, image, or rawobject columns to replicate_if_changed. Wait for the modified replication definition to arrive at the replicate sites.

3 Restart RepAgent to let transactions with a replicate_if_changed status finish processing.

4 Execute the sp_setrepcol system procedure at the Adaptive Server and change the status to always_replicate.


253

5 Execute alter replication definition and change the status of the text, image, or rawobject columns to always_replicate. Wait for the modified replication definition to be replicated to the replicate sites.

6 Resume updates to the primary table.

Scenario 2

• Adaptive Server text, image, and rawobject status: do_not_replicate

• Replication definition text, image, and rawobject status: always_replicate or replicate_if_changed

When the Replication Server reports that the status of a text, image, or rawobject column is do_not_replicate at the Adaptive Server database and the replication definition includes that column for replication and specifies either always_replicate or replicate_if_changed, take the following steps to resolve inconsistencies.

Setting do_not_replicate

If you do not want to replicate text, image, or rawobject columns:

1 Stop updates to the primary table.

2 Drop subscriptions to the replication definition.

3 Drop the replication definition.

4 Re-create the replication definition without the text, image, or rawobject columns, and re-create subscriptions.

5 Resume updates to the primary table.

Setting always_replicate or replicate_if_changed

If you do want to replicate text, image, or rawobject columns:

1 Execute sp_setrepcol at the Adaptive Server database and change the status of the text, image, or rawobject column to always_replicate or replicate_if_changed. It should match the status in the replication definition.

2 Wait for subsequent transactions that modify the text, image, or rawobject column to be processed by the Replication Server.

Working with Special Datatypes

254

3 Consider correcting any inconsistencies with the rs_subcmp program. See “Verifying Subscription Consistency” on page 347 for more information.

Subscription Issues for replicate_if_changed StatusIf you create subscriptions for replication definitions with text, image, or rawobject columns that have the status replicate_if_changed, see “Bulk Materialization” on page 315 and “Materializing text, image, and rawobject Data” on page 342.

Function Strings for Replicating text and image DataIf you replicate columns with text or image datatypes to a non-Adaptive Server database, you must create rsdatarow_for_writetext, rs_get_textptr, rs_textptr_init, and rs_writetext function strings for each text or image column. The function string name must be the text or image column name for the replication definition.

Note You cannot replicate rawobject or rawobject in row columns to non-Sybase databases unless you replicate these columns as their base datatype. The base datatype of rawobject is image; the base datatype of rawobject in row is varbinary.

See the Replication Server Design Guide for more information.

See Chapter 4, “Replication Server System Functions” in the Replication Server Reference Manual for complete syntax and usage guidelines.

Working with Special DatatypesThis section describes how to use the special datatype rs_address and IDENTITY columns in replication definitions.


255

Using the rs_address DatatypeThe rs_address special datatype makes a unique subscription resolution technique possible: bitmaps of the rs_address datatype (based on the underlying int datatype) are compared with a bitmask in a subscription’s where clause to determine whether a row should be replicated.

To use this subscription resolution method:

1 Create tables that use columns of the int datatype.

2 Create a replication definition that includes these columns in the column list, but declare the datatype as rs_address instead of int.

You must include any columns that use the rs_address datatype in the searchable columns clause of the replication definition in order to perform bitmap comparison using the where clause.

See “Bitmap Subscriptions” on page 344 for more information on using rs_address columns for bitmap subscription resolution.

Replicating IDENTITY ColumnsIDENTITY columns store sequential numbers (such as invoice numbers, employee numbers, or record numbers) that are generated automatically. The value of the IDENTITY column uniquely identifies each row in a table.

IDENTITY columns use the numeric underlying datatype with scale 0, between 1 and 1038 -1, inclusive.

IDENTITY columns are never updated by the update command. update applied to primary data from a replicate site (using a request function) can never update the IDENTITY column with IDENTITY data.

Specifying an IDENTITY Column in a Replication Definition

To create a replication definition for a table that contains an IDENTITY column, specify “identity” as the declared datatype for the column or use a column-level translation to specify “identity” as the published datatype for the column.

A replication definition, or multiple replication definitions for the same table, may not publish more than one column that has the datatype IDENTITY.

Modifying Replication Definitions

256

Note that if one replication definition publishes a column as “identity,” another replication definition may publish the column as numeric and avoid having the extra commands sent with an insert for subscribers to the second replication definition.

How Replication Server Replicates IDENTITY Columns

Replication Server applies the following command to the replicate table before insert:

set identity_insert table_name on

Replication Server applies the following command to the replicate table after insert:

set identity_insert table_name off

For any table containing an IDENTITY column, the maintenance user must be the owner of the table (or must be the “dbo” user or aliased to the “dbo” login name) at the replicate database in order to use the Transact-SQL identity_insert option.

Modifying Replication DefinitionsThis section provides information on viewing, altering, and dropping replication definitions. It also describes how Replication Server supports table changes resulting from the alter table command when the table

• Has subscriptions from a replicate site, or

• Is replicated to the standby database using a replication definition with a send standby replication definition columns clause.

Note Adaptiver Server Enterprise version 12.0 allows users to alter existing tables— add non-nullable columns, drop columns, and modify column datatypes.

See “alter table Support for Warm Standby” on page 465 for more information aboutr alter table changes that affect warm standby tables with no subscriptions.

For descriptions of procedures that require altering or dropping replication data, see “Modifying Replicated Data” on page 267.


257

Maintaining Table SchemaReplication Server stores information about table schema in a table’s replication definition. During alter table operations, new or modified data rows may reach Replication Server while old data rows are still being processed farther down the data stream. When replication definitions exist for a table, the discrepancies between the columns in the table and the columns in the replication definition may cause Replication Server threads (executor, distributor, or DSI) to shutdown.

Note See the section on alter table in the Adaptive Server Enterprise Reference Manual (version 12.0 or later) for syntax and details on how alter table works in Adaptive Server.

Figure 8-2: Replicate Table Schema Inconsistency

As Figure 8-2 illustrates, because the replication definition cannot describe the old data rows and the new data rows (Figure 8-2, A & B) at the same time, discrepancies between a replication definition and its corresponding table may cause Replication Server to behave incorrectly; that is, not able to read or write data rows to inbound and outbound queues.

PrimaryData Server

ClientApplication

pubs

ReplicateData Server

Replication Server

Primary Database

Replicate Database

pubs

Publishers tableSubscription

Replication definition of Publishers 4 column table

here

alter table command adds 2 columns to Publishers table; 6 column table transactions in

data stream

1 2 3 4 5 6

A

B

A

data stream

old data rows

new data rows

4 column table transactions in

data stream


258

For example:

If Replication Server receives the following from RepAgent:

old_datarow1old_datarow2...alter table commandnew_datarow1new_datarow2...

both the old and new data rows need to be replicated with the correct number of columns and the correct column datatype.

If alter table drops columns, old data rows still have these columns replicated while the new data rows do not.

If alter table adds new columns, the new columns need to be included only in the new data rows. Figure 8-2 illustrates that when you add new columns to the Publishers table using alter table (“B”), because the new rows are not in the table’s replication definition, the new rows will not be replicated, causing you to lose data.

If alter table alters a column datatype, both the old and new data rows need to be replicated in their own column types. When you modify primary table column datatypes, there is also a period of time when the replication definition column datatype does not match the table column datatype. This mismatch may cause problems in Replication Server when column datatypes are used.

Migration Procedure

The only way to guarantee consistency between tables and replication definitions and ensure that replication works correctly, is to use the steps in the following procedure when you want to add or modify columns in a primary table within a replication system.

Note This procedure is required only when a table has subscriptions, or when send standby replication definition columns is used to replicate to a standby database.

❖ To alter a primary table that is part of a replication system and avoid data inconsistency or Replication Server thread shutdown:

1 Stop all primary database activity.


259

2 Send an intentional fake “update” command. When this transaction’s results appear at the replicate site, you know that all operations have been completed by the Replication Server.

3 Use the Transact-SQL dump transaction command to make a copy of the primary database’s transaction log (syslog) and remove the inactive portion.

See the Adaptive Server Enterprise Reference Manual for instructions.

4 Quiesce the replication system. Make sure that the last update (step 2) has reached the replicate.

See the “Quiescing a Replication System” on page 109 for instructions.

5 Use alter table to change the primary table schema.

See the alter table command in the Adaptive Server Enterprise Reference Manual (version 12.0 or later) for instructions.

6 Use alter replication definition to change the corresponding replication definitions. Verify that the replication definition changes reach all destination RSSDs.

Note If the alter table changes involve columns that are used in a subscription or article where clause, drop the subscription (without purge) or article before you alter the replication definition. If you use alter table to drop columns that are not used in a where clause, replication definition changes are not necessary.

See “Altering Replication Definitions” on page 261 for details.

In Sybase Central, see “Altering table replication definitions” in Replication Server’s online help.

7 If you dropped subscriptions in step 6, recreate them using create subscription without materialization or define subscription.

See create subscription and define subscription in Chapter 3 of the Replication Server Reference Manual (version 11.5 or later) for instructions.

8 Change the replicated table schema if necessary.

9 Resume activity in the primary database.

RSM


260

alter table support for Replicate Databases

Prior to version 12.0, when Replication Server received a data row, the columns that were defined in the replication definition but missing in the data row were sent as null. This could cause the Data Server Interface (DSI) to shutdown when the columns were dropped from the replicate or standby table.

Beginning with version 12.0, to support alter table [add | drop | modify] column, Replication Server sends only the values that are received from the data server. Columns that are defined in the replication definition but missing in the data row are ignored instead of receiving a null value. The exception is when you use custom function-strings. If a missing column value is expected in a custom function-string, then Replication Server will continue to send null for the column.

If you use a column in a subscription or article where clause, you must drop the subscription or article before you can change or drop that column. If you do not use a column in a subscription or article where clause, then you do not need to drop the subscription.

Warning! You always need to follow the manual procedure specified in “Migration Procedure” on page 258 for alter table [add | drop | modify] columns when subscriptions are involved, or when you use send standby replication definition columns to replicate to a standby database. Failure to do so may cause data loss or Replication Server thread problems.

Note See “alter table Support for Warm Standby” on page 465 for information on how Replication Server support Adaptive Server version 12.0 enhancements to alter table.

Recovery Procedures

This section discusses the recovery procedures to use if data loss or problems occur as a result of alter table changes.

Recovering from Executor Thread Problems

Executor thread problems require no extra recovery. Data may be discarded when there is a normalization error in an executor thread.

When datatype conversion has completed, and if the table has been altered such that the executor thread cannot normalize the data, the data row may be discarded. Use the “Migration Procedure” on page 258 to avoid data loss.


261

Recovering from Inbound Queue Problems

If data in the inbound queue is incompatible with the column datatype in a replication definition, the distributor thread may shut down. The resume distributor command has been extended to allow you to skip one transaction:

resume distributor ds.dbskip transaction

Recovering from Outbound Queue Problems

When there is bad data in the outbound queue, use resume connection skip transaction to skip the bad data. In the case of replicate (not standby) Data Server Interface (DSI) threads, you may be able to alter the replication definition and resume the DSI to recover the data.

Viewing Existing Replication DefinitionsTo display information about existing replication definitions, use the Adaptive Server procedures rs_helpuser and rs_helpreptable. See rs_helprep and rs_helpuser in Chapter 6, “Adaptive Server Stored Procedures” in the Replication Server Reference Manual for complete information about this command.

To display information about replication definitions in Sybase Central, see the Replication Server online help topics, “Viewing replication definition properties,” “Viewing replication definition details,” and “Viewing object details.”

Altering Replication DefinitionsYou may need to alter a replication definition after a column has been added to a primary table or if a destination database requires a column that was not specified in the original replication definition.

In most instances, you alter replication definitions in conjunction with changing database schema in the source or destination table. Be sure to coordinate schema changes between the source and destination sites. See “Modifying Replicated Data” on page 267.

This section describes how to use alter replication definition to modify a replication definition. You can alter the replication definition in one of the following ways:

• Provide a different replicate table name

• Add columns to the columns list

RSM


262

• Provide different replicate column names

• Change the specifications for replicating text, image, or rawobject columns

• Add columns to the primary keys column list

• Remove columns from the primary keys column list

• Add columns to the searchable columns list

• Drop columns from the searchable columns list

• Change declared or published column datatypes

• Change the specification for replicating minimal columns

• Change how the replication definition is used in replicating to a standby database

To change replication definitions using Sybase Central, see “Altering table replication definitions” in Replication Server’s online help.

Note Function strings with replication definition scope are not automatically altered when you add columns to a table or to a replication definition. In certain cases, you must alter the function strings manually. See “Managing Function Strings” on page 391.

Use alter replication definition at the primary Replication Server where you created the replication definition. See “Creating Replication Definitions” on page 221 for more information about what you can include in a replication definition.

• To rename primary or replicate tables, drop and re-create the replication definition. See “Renaming Replicated Tables” on page 268 for more information about how to accomplish this task.

• To drop or rename primary columns or change column datatypes, drop and re-create all the replication definitions that have the primary columns. See“Deleting Columns in a Source or Destination Table” on page 269 for more information about how to accomplish this task.

Refer to alter replication definition in Chapter 3, “Replication Server Commands” in the Replication Server Reference Manual for complete command syntax and usage guidelines.

Examples follow for different scenarios of altering replication definitions using alter replication definition.

RSM


263

Normally, you should quiesce the system and shut down the RepAgent before altering a replication definition.

Providing a Different Replicate Table Name

To replicate data from a source table into a destination table with a different name, alter the replication definition. For example:

alter replication definition publisherswith replicate table named publishers2

Changing the Specified Columns

Following are examples of how to add or change a column for the primary and destination tables.

Adding a Column

To add a char column named zip (for zip code information) to the source and destination copies of the publishers table:

1 Use the Transact-SQL alter table command to add the column to the tables in Adaptive Server. See the Adaptive Server Enterprise Reference Manual for more information.

2 Use alter replication definition to add the same column to the publishers_rep:

alter replication definition publishers_repadd zip char(10)

3 If the column you added to the destination table has a different name than the source column, enter a command like this:

alter replication definition publishers_repadd zip as rep_zip char(10)

See “Adding Columns in Source and Destination Tables” on page 269 and alter replication definition in Chapter 3, “Replication Server Commands” Replication Server Reference Manual for more information.

Dropping a Searchable Column

You can drop searchable columns from a replication definition only if they are not used in subscription or article where clause.


264

1 Use drop subscription to remove any subscriptions in which you want the where clause to exclude the searchable columns you are dropping. See “Using the drop subscription Command” on page 336.

2 Use alter replication definition to drop the searchable column. For example:

alter replication definition publishers_repdrop searchable columns zip

(This example removes the zip searchable column from the publishers_rep replication definition.)

See alter replication definition in Chapter 3, “Replication Server Commands” in the Replication Server Reference Manual for more information.

3 Use create subscription to re-create subscriptions to the altered replication definition. See “Using the create subscription Command” on page 330.

Adding or Dropping Primary Keys

Replication Server depends on primary keys to find the correct rows at the replicate or standby table. To add a the column zip as a primary key to the replication definition, enter:

alter replication definition publishers_repadd primary key zip

To drop a primary key, enter:

alter replication definition publishers_repdrop primary key zip

To replace all primary key columns, first alter the corresponding replication definition to add the new primary keys, then drop the old primary key columns in the table.

Warning! If all primary key columns are missing from the primary table, the DSI will shut down.

Altering Column Datatypes

• You cannot change the declared column datatype (the datatype in the primary table) if it is used in a subscription or article where clause.


265

• You cannot change the rs_address datatype.

• You can change the column datatype to text/image/rawobject/rawobject in row only if it is not a primary key or searchable column.

• To change the published (replicate) datatype, you must include the declared (primary) datatype of a column (whether it is being changed or not) and the [map to] clause.

• Altering a column’s datatype and nullability affects the same column across all replication definitions for a table.

However, changes between a rawobject or rawobject in row and its base datatype, affects only the current replication definition.

• See “Heterogeneous Datatype Support,” in the Replication Server Administration Guide, which describes how to change datatypes when replication is active.

• Use column nullability changes for text, image, and rawobject columns only.

You can also set Java datatypes in Replication Server Manager.In Sybase Central, see “Changing declared datatypes of columns” in the Replication Server online help.

Providing a Different Replicate Column Name

To replicate data for the source column zip into a destination column named rep_zip2, enter:

alter replication definition publishers_repalter columns with zip as rep_zip

Enter such a command when:

• You alter the existing destination table to add column rep_zip.

• You drop and re-create the destination table to contain the column rep_zip in place of the original column zip.

Changing text, image, and rawobject Replication Status

To change the replication status of text, image, and rawobject columns in a replication definition, use alter replication definition.

See “Altering Replication Status for text, image, and rawobject Columns” on page 250 for more information.

RSM


266

Adding a Searchable Column

A searchable column lets you create subscriptions based on values in the column.

To add and take advantage of a searchable column:

1 Use drop subscription to remove any subscriptions in which you want the where clause to include the added searchable column. See “Using the drop subscription Command” on page 336.

2 Use alter replication definition to add the searchable column. For example:

alter replication definition publishers_repadd searchable columns zip

(This example makes the zip column searchable.)



See “Changing Searchable Columns” on page 270 for more information.

Changing Minimal Column Replication

To specify that Replication Server use the minimal number of columns (as opposed to all columns in each row) when it copies update and delete operations, enter a command like this:

alter replication definition publishers_repreplicate minimal columns

Altering a Replication Definition for Warm Standby Replication

To change whether a replication definition will be used to replicate data into a standby database in a warm standby application, use alter replication definition. See alter replication definition in Chapter 3, “Replication Server Commands” of the Replication Server Reference Manual.


267

You can specify which replication definition to use to replicate data into a standby database in a warm standby application. You can also specify whether to replicate all the columns in the table or only the replication definition’s columns.

See “Using Replication Definitions with Warm Standby Applications” on page 231 for more information.

Dropping Replication DefinitionsBefore you drop a replication definition, first drop all subscriptions and articles that reference that replication definition. See Chapter 10, “Managing Subscriptions” for details on dropping subscriptions. See “Dropping Articles” on page 280 for details on dropping articles.

In Sybase Central, see “Deleting subscriptions” in Replication Server’s online help.

To access a list of existing subscriptions for a specified replication definition, use rs_helpsub. See rs_helpsub in Chapter 6, “Adaptive Server Stored Procedures” in the Replication Server Reference Manual for more information.

To access a list of existing subscriptions for all replication definitions, use rs_helprep. See rs_helprep in Chapter 6, “Adaptive Server Stored Procedures” in the Replication Server Reference Manual for more information.

Enter drop replication definition at the primary Replication Server. For example, to drop the publishers_rep replication definition, enter a command like this:

drop replication definition publishers_rep

Refer to drop replication definition in Chapter 3, “Replication Server Commands” in the Replication Server Reference Manual for complete command syntax and usage guidelines.

Modifying Replicated DataThis section describes how to modify replicated data and perform related operations to maintain replication. Chapter 10, “Managing Subscriptions” for subscription-specific commands.

In Sybase Central, see “Managing Subscriptions” in Replication Server’s online help for subscription-specific instructions.

RSM

RSM

Modifying Replicated Data

268

Before you modify replicated data, carefully review the issues raised in “Planning a Replication System” on page 214. When attempting to modify replicated data, refer to this section for any dependencies that may exist, and for the sequence of tasks required to perform the procedure.

Adding a New TableTo add a new source table, or add a new destination copy for an existing source table, follow the procedure outlined in “Replication Procedure” on page 216.

Renaming Replicated TablesTo rename a replicated table:

1 In Adaptive Server, use sp_setreplicate to disable replication for the table. See sp_setreplicate in Chapter 5, “Adaptive Server Commands and System Procedures” in the Replication Server Reference Manual.

2 Use drop subscription to drop subscriptions to all of the table’s replication definitions. See “Using the drop subscription Command” on page 336.

3 Use drop replication definition to drop all of the table’s replication definitions. See “Dropping Replication Definitions” on page 267.

4 Rename the destination table.

Follow the steps in the “Replication Procedure” on page 216. Be sure to specify the table names correctly, as described under “Specifying the Replication Definition Name and Table Names” on page 223.

Dropping a Replicated TableTo drop a replicated table, follow these steps:

1 Use the Transact-SQL drop table command to drop the table at the primary database. See the

See the Adaptive Server Enterprise Transact-SQL User’s Guide for drop table syntax.


269

2 Use drop subscription to drop the subscriptions to the table. See “Using the drop subscription Command” on page 336.

3 Use check subscription to confirm that the subscriptions are dropped. See “Using the check subscription Command” on page 335.

4 Use drop replication definition to drop the replication definition to the table at the primary Replication Server. See “Dropping Replication Definitions” on page 267.

5 Use rs_helprep to confirm that the replication definition is dropped at all Replication Servers in the replication system. See “Viewing Existing Replication Definitions” on page 261.

Adding Columns in Source and Destination TablesTo add columns to source and destination tables in a warm standby only setup, follow the instructions in “alter table Support for Warm Standby” on page 465.

To add columns to source and destination tables that are replicated through subscriptions, use the “Migration Procedure” on page 258.

Deleting Columns in a Source or Destination TableTo delete columns in source and destination tables in a warm standby only setup, follow the instructions in “alter table Support for Warm Standby” on page 465.

To delete columns in source and destination tables that are replicated through subscriptions, use the “Migration Procedure” on page 258.

Note If you drop columns from a table, it is unnecessary to drop those columns from replication definitions unless they are used in a subscription or article where clause. However, the columns need to be dropped from the searchable columns list and the primary key list.

If you drop table columns that are used in a subscription or article where clause, you need to drop the subscription or article, then recreate it.

Modifying Replicated Data

270

Changing Searchable ColumnsTo add searchable columns to a replication definition, see “Adding a Searchable Column” on page 266.

Dropping a Searchable Column

You can drop searchable columns from a replication definition only if they are not used in subscription or article where clause.

1 Use drop subscription to remove any subscriptions in which you want the where clause to exclude the searchable columns you are dropping. See “Using the drop subscription Command” on page 336.

2 Use alter replication definition to drop the searchable column. For example:

alter replication definition publishers_repdrop searchable columns zip

(This example removes the zip searchable column from the publishers_rep replication definition.)



Changing Column Datatypes in a Source or Destination TableTo change column datatypes in a primary and replicate table in a warm standby only setup, follow the instructions in “alter table Support for Warm Standby” on page 465.

To change column datatypes in source and destination tables that are replicated through subscriptions, use the “Migration Procedure” on page 258.


271

Using PublicationsA publication lets you collect replication definitions for the same or related tables and/or stored procedures and then subscribe to them as a group. You collect replication definitions in a publication at the source Replication Server and subscribe to them with a publication subscription at the destination Replication Server.

With publications, you monitor the status of one publication subscription for a set of tables and procedures.

The following steps summarize the procedure for replicating data using publications.

1 Create or select the replication definitions to include in the publication.

2 Create the publication.

3 Create articles that reference the replication definitions you have chosen.

4 Validate the publication.

5 Create a subscription for the publication.

Note A replicate database can subscribe to different replication definitions of the same primary table directly or through publications—as long as each replication definition references a different table in the replicate database.

To use publications, the primary Replication Server must be version 11.5 or later. To use publication subscriptions, the replicate Replication Server and the route from the primary Replication Server and the replicate Replication Server must be version 11.5 or later.

When you use publications, you create and manage the following objects:

• Articles – replication definition extensions for tables or stored procedures that let you put table or function replication definitions in a publication. Articles may or may not contain where clauses, which specify a subset of rows that the replicate database receives.

• Publications – groups of articles from the same primary database.

• Publication subscriptions – subscriptions to a publication. When you create a publication subscription, Replication Server creates a subscription for each of the publication’s articles. Publication subscriptions do not contain where clauses.

Using Publications

272

In general, you manage publications and publication subscriptions in the same way as you do replication definitions and subscriptions. However, when you create a publication, you can specify the subset of rows that the replicate table receives by including a where clause in the article—not in the subscription.

You can create and manage publications either in Sybase Central or at the command line. These tasks are often simpler and require fewer steps when you use Sybase Central.

The following sections provide detailed instructions for creating publications in Sybase Central and at the command line.

Refer to Chapter 9, “Managing Replicated Functions” for more information about publications for stored procedures. Refer to Chapter 10, “Managing Subscriptions” for information about creating and managing publication subscriptions.

Using Publications To Replicate Data in Sybase CentralThe following procedure describes preparing a publication for subscription and creating a subscription against it in Sybase Central. You can include table replication definitions, but not function replication definitions, in a publication you create through Sybase Central.

When you prepare a publication for subscription in Sybase Central, the system records the procedure in an isql script that you can keep as a record of your work, or edit and execute later on at the command line.

The following steps describe preparing a publication for subscription and then subscribing to the publication.

1 Prepare the publication for subscription.

Open the Create Publications dialog box and select the tables to which you want to subscribe.

For each table you can:

• Create new replication definitions and/or select existing ones.

If you create new replication definitions, you can choose to replicate minimum columns, include the table-owner name, and specify columns to send to the replicate database.

• Specify a subset of rows to send to the replicate database with where clauses.


273

When you save the publication, Replication Server creates the publication, articles, and replication definitions (if appropriate) and validates the publication.

2 Subscribe to the publication.

Open the Create Publication Subscription dialog box and enter the information required.

Replication Server creates the publication subscription and a subscription for each article in the publication.

Refer to “Using Publication Subscriptions” on page 350 for information about publication subscriptions.

For detailed instructions on creating and modifying publications subscriptions in Sybase Central, see the topics under “Managing Subscriptions:Publication subscriptions” in Replication Server’s online help.

Using Publications to Replicate Data at the Command LineThis section describes how to create a publication at the command line and prepare it for subscription. It also contains information on modifying dropping a publication and its associated articles and replication definitions.

Commands for Creating and Managing Publications

Table 8-3 lists the RCL commands for working with publications. All of these commands, except check publication, are executed at the source Replication Server, where they require create object permission. Anyone can execute check publication at the source Replication Server—or at the destination Replication Server if the user has the same login and password at both servers.

Table 10-5 on page 351 lists the RCL commands for working with publication subscriptions.

Table 8-3: Commands for managing publications

RSM

Command Task

create publication Creates a publication for a group of tables or stored procedures that is to be replicated to one or more subscribing databases.

Using Publications

274

Creating Publications and Articles at the Command Line

The following procedure describes the RCL procedure for preparing a publication for subscription and creating a subscription against it.

At the Source Replication Server

1 Create or select replication definitions for the tables or stored procedures from which you want to copy data.

The replication definition specifies the source and destination tables or stored procedure and the columns or parameters that are sent to the subscribing database. Refer to “Creating Replication Definitions” on page 221 for details.

2 Use create publication to create the publication that groups the replication definitions.

Publication information is stored in the rs_publications system table in the source Replication Server’s RSSD. It includes the name of the publication, data server, and database. The publication name must be unique for the source Replication Server and database.

The following example creates a publication named pubs2_pub. The primary database is pubs2 managed by the TOKYO_DS data server.

create publication pubs2_pubwith primary at TOKYO_DS.pubs2

create article Creates an article for a publication, allowing you to add one or more where clauses to specify a subset of rows to send to the destination database.

The publication and the replication definition on which the article is based must exist before you create an article.

validate publication Checks that the publication contains at least one article and marks the publication as VALID and ready for subscription.

check publication Displays the status of the publication and the number of articles it contains.

drop publication Removes the publication from the rs_publications system table.

You can drop the replication definitions associated with the publication if they are not included in other publications or subscriptions.

drop article Removes the article from the publication and from the rs_articles system table.

You can drop the replication definition associated with the article if it is not included in other articles or subscriptions.

rs_helppubs Displays information about publications and articles.

Command Task


275

Publication information is not copied to the destination Replication Server until you create a subscription against the publication at the destination Replication Server.

See “create publication” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for complete syntax and usage guidelines.

3 Use create article to create articles for the publication.

Each article specifies the publication to which it belongs and the table or function replication definition with which it identifies. A publication can contain articles based on the same or different replication definitions. The replication definition and publication must exist when you create the article.

An article includes the names of the publication, the replication definition, and the source data server and database. Article information is stored in the rs_articles and rs_whereclauses system tables. Each article name must be unique within the publication.

The following example creates an article named titles_art based on the replication definition titles_rep for the publication pubs2_pub.

create article titles_artfor pubs2_pub with primary at TOKYO_DS.pubs2with replication definition titles_rep

An article can include where clauses that specify the rows or parameters to be sent to subscribing databases. Refer to “Specifying a where Clause with the create article Command” on page 276 for more information.

Creating an article invalidates the publication, which makes it ineligible for subscription. After you create an article, you must change the status of the publication to VALID, using validate publication, before you can create subscriptions against it.

See “create article” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for complete syntax and usage guidelines.

4 Use validate publication to change the status of the publication to VALID.

When you validate a publication, Replication Server checks that the publication contains at least one article and marks the publication ready for subscription.

Using Publications

276

Whenever you add or drop an article from a publication, Replication Server invalidates the publication. To mark the publication VALID—and ready for subscription—you must execute validate publication.

After you validate a publication, you can create a publication subscription against it.

The following example validates the pubs2_pub publication. The source database is pubs2 managed by the TOKYO_DS data server.

validate publication pubs2_pubwith primary at TOKYO_DS.pubs2

See “validate publication” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for complete syntax and usage guidelines.

At the Destination Replication Server

1 Use create subscription to create the publication subscription.

When you create a publication subscription, Replication Server creates a subscription for each article in the publication.

See “Using Publication Subscriptions” on page 350 for information about creating and managing publication subscriptions.

Specifying a where Clause with the create article Command

You can include one or more where clauses in an article. A where clause sets criteria for the column or parameter values that are to be replicated. If you omit the where clause, Replication Server copies all rows for columns specified in the table replication definition or all parameters specified in the function replication definition.

The where clause syntax for articles is:

[where (column_name | @param_name) {< | > >= | <= | = | &} value

[and {column_name | @param_name}{< | > >= | <= | = | &} value]...]

[or where (column_name | @param_name) {< | > >= | <= | = | &} value

[and {column_name | @param_name}{< | > >= | <= | = | &} value]...]

...


277

Each column name in a where clause must be listed in the searchable columns list of the table replication definition. The value for each column must have the same datatype as the column to which it is compared.

Note Each where clause in a article is joined by the or operator. However, the !=, !<, !>, and or operators are not supported inside a where clause. The & operator is supported only on rs_address columns. For details on using the rs_address datatype, see “Using the rs_address Datatype” on page 255 and “Bitmap Subscriptions” on page 344.

The following example creates an article named titles_art for the publication named pubs2_pub, using a where clause that limits replication to rows where the value in the type column is 'popular_comp'.

create article titles_artfor pubs2_pub with primary at TOKYO_DS.pubs2with replication definition titles_repwhere type = ’popular_comp’

See “create article” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for complete syntax and usage guidelines.

Viewing Publication Information

You can view information about publications and articles with the check publication command and the rs_helppub stored procedure.

Display Publication Status and Number of Articles

To display the number of articles in a publication and its current status, use check publication.

Any user can execute check publication at either the primary or replicate Replication Server. If you execute check publication at the replicate Replication Server, you must have the same login and password at the primary and replicate servers.

The following example displays the status and number of articles in the pubs2_pub publication.

check publication pubs2_pubwith primary at TOKYO_DS.pubs2

Using Publications

278

See “check publication” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for complete syntax and usage guidelines and sample output.

Display Publication and Article Information

To display information about a publication and its articles, use the rs_helppub stored procedure at either the primary or replicate Replication Server’s RSSD.

Note Although you can execute rs_helppub at the primary or replicate site, rs_helppub only displays publication information stored at the site at which it is executed. For example, if you execute rs_helppub at the primary site, rs_helppub displays information about all publications created at that site. If, however, you execute rs_helppub at the replicate site, rs_helppub only displays information about publications for which subscriptions have been created at that site.

Here are some examples of using rs_helppub:

• To list all publications at a site, enter:

rs_helppub

The display output includes publication name, status, the primary Replication Server and database names, the number of articles, and the date of the latest change to the publication.

• To display detailed information about a particular publication, enter:

rs_helppub publication_name, primary_dataserver, primary_db

The display output includes the above information and the names of associated articles, replication definitions, and primary and replicate tables. If subscriptions have been created for the publication, the display includes names of the subscriptions, replicate databases, owners, and the date of the latest change to the subscription.

• To display information about a particular article, enter:

rs_helppub publication_name, primary_dataserver, primary_db, article_name

The output display includes the name of the publication to which the article belongs, associated replication definitions, status information, and where clauses and subscriptions, if any.


279

See “rs_helppub” in the Replication Server Reference Manual for complete syntax and usage guidelines and sample output.

Altering Publication Information

Normally, if you want to alter an article or publication, you must drop the article or publication and re-create it.

If you want to make the where clauses in an article more selective, you can:

• Drop the article and re-create it with altered where clauses, or

• Create another article (for the same replication definition), tailoring the where clauses to the new row or parameter selection.

Refer to “Dropping Publications” on page 279 and “Dropping Articles” on page 280.

Adding Articles to a Publication

To add articles to an existing publication, follow these steps:

At the Source Replication Server

1 Create or select the replication definitions on which the articles are to be based.

2 Use create article to create new articles.

3 Use validate publication to validate the publication so that subscriptions can be created for the new articles.

At the Destination Replication Server

1 To create subscriptions for the new articles, enter create subscription or define subscription and include the for new articles clause. Refer to “Using Publication Subscriptions” on page 350 for more information.

Dropping Publications

Use drop publication to remove a publication and all of its articles from the system tables.

Before you drop a publication, you must, at the replicate Replication Server, drop all subscriptions created against it. See “Dropping Subscriptions for Publications and Articles” on page 356.

Execute drop publication at the Replication Server that manages the source database. You must have create object permission.

Using Publications

280

The following example drops the pubs2_pub publication and the articles it contains.

drop publication pubs2_pubwith primary at TOKYO_DS.pubs2

Publication information is dropped immediately from the primary Replication Server; it is not dropped from the replicate Replication Server until:

• You attempt to create a subscription against the dropped publication, or

• You enter check publication at the replicate Replication Server.

See “drop publication” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for complete syntax and usage guidelines.

Dropping Associated Replication Definitions

To drop replication definitions associated with the publication, include the drop_repdef clause when you execute drop publication. Replication Server drops all replication definitions associated with the publication that are not referenced by other publications or subscriptions.

For example, to drop all replication definitions associated with pubs2_pub, enter:

drop publication pubs2_pubwith primary at TOKYO_DS.pubs2drop_repdef

Dropping Articles

Use drop article to remove an article from a publication.

Before you drop an article, you must drop subscriptions created against it at the replicate Replication Server. See “Dropping Subscriptions for Publications and Articles” on page 356.

Execute drop article at the Replication Server that manages the source database. You must have create object permission.

The following example drops the titles_art article for the pubs2_pub publication.

drop article titles_artfor pubs2_pub with primary at TOKYO_DS.pubs2


281

See “drop article” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for complete syntax and usage guidelines.

Dropping the Associated Replication Definition

To drop a replication definition associated with an article, include the drop_repdef clause when you execute drop article. Replication Server drops the replication definition if it is not referenced in other publications or subscriptions.

For example, to drop the pubs2_pub article and the replication definition it references, enter:

drop article titles_artfor pubs2_pub with primary at TOKYO_DS.pubs2drop_repdef

Translating Datatypes Using HDSIn a heterogeneous replication system, when information is replicated from one data server to another, values stored at the primary data server must often be altered so that they can be copied successfully to a different datatype at the replicate data server.

User-created function strings can produce these datatype translations, but require significant user input and are limited by the capabilities of the replicate data server.

To make datatype translations more readily available for different data servers, Replication Server provides heterogeneous datatype support (HDS), an easy-to-apply methodology for translating datatypes at the Replication Server. HDS supports selected datatype translations between these data servers:

• Adaptive Server Enterprise

• DB2

• Informix

• Oracle

• Microsoft SQL Server

When you use HDS, you can choose which columns and datatypes in the primary database are to be translated, and which replicate data servers will receive the translations.

Translating Datatypes Using HDS

282

This section provides an overview and an instructions for using HDS at Replication Server.

You can also use HDS from Replication Server Manager (RSM). Refer to the following RSM online help topics for instructions:

• Managing Heterogeneous Replication Systems

• Managing Data

• Managing Heterogeneous Servers

Other sources of information:

• Refer to the Replication Server Configuration Guide for your platform for instructions for installing and setting up the objects that enables HDS.

• Refer to the Replication Server Reference Manual for descriptions of the function strings.

OverviewYou can use HDS capabilities when replicating between:

• Adaptive Server databases – one Adaptive Server datatype to another Adaptive Server datatype

• Like non-Sybase databases – for example, DB2 TIMESTAMP to DB2 DATE

• Heterogeneous non-Sybase databases – Oracle to DB2, for example

• Adaptive Server and non-Sybase databases – Adaptive Server to Oracle, for example

If you are replicating information between Adaptive Servers, datatype translations are normally unnecessary. However, you can use HDS to perform datatype translations when datatypes differ in the primary and replicate databases.

HDS handles incompatibilities between the datatypes of the primary data server and the replicate data server. In general, these incompatibilities are of three types:

• Incompatible ranges – for example, the range of acceptable dates for Sybase datetime is January 1, 1753 through December 31, 9999. DB2, however, allows dates from January 1, 0001 through December 31, 9999.

RSM


283

• Incompatible formatting – for example, the primary data server date format is “CCYY-MM-DD,” but the replicate data server requires a date format of “MM/DD/CCYY.”

• Incompatible delimiters – for example, Sybase delimits binary data with an “0x” prefix, whereas Oracle surrounds binary data with single quotation marks.

The replication agent for each data server delivers replicate values to Replication Server in a datatype format that Replication Server understands, which includes the literal value, delimiter information, and other datatype attributes. Replication Server handles the value as its base datatype—one of the native Replication Server datatypes described in the Replication Server Reference Manual.

You can implement datatype translations in two ways:

• Class-level translations – translate all instances of a datatype for a particular connection.

• Column-level translations – translate all instances of a column described by a table replication definition.

Getting Started1 Review the datatype translations available for your primary and replicate

data servers. Determine the translations you want and the methods for delivering them:

• Class-level translations

See Appendix C, “HDS Datatype Translation Mapping”, for lists of supported class-level datatype translations.

• Column-level translations

See Table 8-4, Table 8-5, and Table 8-6 for lists of supported datatypes and data servers.

• A combination of class-level and column-level translations

2 Set up the environment and run the scripts that enable HDS for your system. Refer to the Replication Server Configuration Guide for your platform for instructions.

3 Set up class-level and column-level translations using the procedures described in the following sections.


284

For information about creating subscriptions for replication definitions, refer to Chapter 10, “Managing Subscriptions”. For information about using function replication definitions for class-level translations, see Chapter 9, “Managing Replicated Functions”.

Creating Class-Level TranslationsClass-level translations ensure that each time a value of a certain datatype is replicated from the primary to a particular data server, the datatype of that value is changed. Sybase provides the function strings and function-string classes necessary to produce these translations.

To set up class-level translations, follow these steps:

1 Set up and configure the replicate database gateway server.

Refer to the Replication Server Configuration Guide for your platform for instructions.

2 Set up the database objects and run the scripts that install the function strings and function-string classes for your primary to replicate data server connections.


3 Create or alter the connections to specify the function-string class.

• If you are creating a new connection, Sybase provides a sample script that you can use to create the connection and specify the appropriate function-string class. You will need to modify the script for your installation.


• If you are adding class-level translations to an existing connection, use the alter connection command as described in “Adding Class-Level Translations to an Existing Connection” on page 286.

Sybase provides function-string classes for several Sybase and non-Sybase data servers:

• Adaptive Server Enterprise – rs_sqlserver_function_class

• DB2 – rs_db2_function_class

• Informix – rs_informix_function_class


285

• Microsoft SQL Server – rs_msss_function_class

• Oracle – rs_oracle_function_class

Each of these function classes contains function strings. For example, for the DB2 database, HDS provides these translations:

• DB2 to Adaptive Server and Adaptive Server to DB2

• DB2 to Informix and Informix to DB2

• DB2 to Microsoft SQL Server and Microsoft SQL Server to DB2

• DB2 to Oracle and Oracle to DB2

With the exception of rs_db2_function_class, each function class inherits from rs_default_function_class.

In general, you cannot add to, delete, or change any of these function-string classes or the functions they contain. You can modify rs_sqlserver_function_class for compatibility with earlier releases of Replication Server, but you cannot modify or alter any of its datatype translations. Although you can create classes that inherit from these classes, the classes you create cannot inherit any class-level translations from the parent class.

You are installing translations in the RSSD when you run the class-level installation scripts. If you do not run the scripts, no default class-level translations take place. Running the scripts replaces default Adaptive Server translations that would otherwise be inherited from rs_default_function_class with translations designed for a particular data server.

You activate class-level translations for a connection by specifying the function-string class when you create or alter the connection. When the function-string class is activated, all subsequent data replicated via that connection is translated according to the translations defined for that function-string class.

If a class-level translation is not specified for a published datatype (the datatype of the replicate data server), Replication Server simply translates the value from the replication agent to its base datatype format in the usual manner. For example:

• If no translation is specified for the Sybase datetime datatype, no translation is performed; the base datatype of datetime is datetime.


286

• If no translation is specified for rs_db2_timestamp, any rs_db2_timestamp value routed through the connection is translated to char(26), its base datatype.

Replication Server performs class-level translations after column-level translations and after subscription resolution, but before values are mapped to function strings. See “Using Class-Level and Column-Level Translations Together” on page 292.

You can display a list of active function-string classes using admin show_function_classes. Use RSM to view detailed information about the translations defined for a class.

Adding Class-Level Translations to an Existing Connection

If you want to add class-level translations to an existing connection, use the alter connection command. Follow these steps:

1 Run the appropriate install scripts. Refer to the Replication Server Configuration Guide for your platform.

2 Use the alter connection command to set the function class for the connection.

For example, to enable the translations for rs_db2_function_class, enter this command from the replicate Replication Server:

alter connection to db2_gateway1.db2_subsystem1set error class to ansi_errorset function string class to rs_db2_function_class...

3 Suspend and then resume the connection to active the translations.

Note If you already have a DB2 database configured as a replicate database with an earlier version of Replication Server, continue to use the earlier version with Replication Server 12.0 and its HDS feature. The 12.0 function strings may not be compatible with earlier function string versions.

System-Defined Variables

Class-level translations change the datatype of system-defined variables as well as column values.


287

For example, if a class-level translation changes datetime to rs_db2_timestamp, the rs_origin_begin_time system-defined variable, which is datetime, is translated to rs_db2_timestamp for that connection.

Creating Column-Level TranslationsColumn-level translations affect each replicated instance of a particular column (datatype) and table. They are defined using the create replication definition or alter replication definition command.

To set up column-level translations, you simply create or alter the replication definition, identifying the column to be translated and its initial and final datatypes using the map to option.

• If you are creating a new replication definition, use create replication definition.

See Appendix C, “HDS Datatype Translation Mapping”, for lists of supported datatype translations.

• If you are adding or altering a column in an existing table, use alter replication definition.

Sybase provides a set of datatype definitions and datatype classes that you can use to modify the datatype of the replicated columns. Each datatype class contains datatype definitions for a particular data server:

• Adaptive Server – rs_sqlserver_dt_class

• DB2 – rs_db2_dt_class

• Informix – rs_informix_dt_class

• Microsoft SQL Server – rs_msss_dt_class

• Oracle – rs_oracle_dt_class

Datatype classes are not replicated and cannot be modified. Column-level translations are implemented after subscription resolution and before class-level translations. See “Using Class-Level and Column-Level Translations Together” on page 292 for more information.

You can activate a column-level translation for a particular column when you create or alter a table replication definition. The syntax for create replication definition with column and datatype variables specified for HDS is:

create replication definition replication_definitionwith primary at data_server.database


288

...(column_name [as replicate_column_name] declared_datatype [null | not null][map to published_datatype])...

where:

• The declared datatype depends on the datatype of the value delivered to the Replication Server from the replication agent:

• If the replication agent delivers a native Replication Server datatype, such as datetime, to the Replication Server, the declared datatype is the native datatype.

• Otherwise, the declared datatype must be the datatype definition for the original datatype at the primary database.

For example, the replication agent delivers a value in the DB2 TIMESTAMP datatype, as a character string with delimiters, to Replication Server. In this case, the declared datatype is the datatype definition rs_db2_timestamp. See Table 8-4, Table 8-5, and Table 8-6 for a list of datatype definitions and their datatype equivalents.

• The published datatype is the datatype of the column after the column-level translation (and before a class-level translation, if any). The published datatype is normally either a Replication Server native datatype or a datatype definition for the datatype in the replicate database. If the published datatype is omitted from the replication definition, it defaults to the declared datatype.


289

Both declared and published datatypes have a base datatype. For example, the datatype rs_db2_timestamp has a base datatype of char(26); the native datatype char(26) also has a base datatype of char(26). A datatype definition describes a non-Sybase datatype in terms of a Replication Server native datatype. The base datatype fixes the maximum and minimum length to be associated with the datatype definition and provides defaults for other datatype attributes. The base datatype defines the delimitation of values for the datatype definition when a value of that type is delivered to Replication Server either in Log Transfer Language (LTL) or in a command executed by a Replication Server administrator such as create subscription.

Note Native datatypes include all datatypes supported by Replication Server. However, you cannot use text, image, rawobject, and rawobject in row datatypes for defining a datatype definition; neither can you use these datatypes as the source or target of a translation.

For example, to create a table replication definition ase_employee_repdef_for_db2 that translates values in the birthdate column from datetime (birthdate’s primary table datatype) to DB2 DATE datatype for the replicate database, log in to the primary Replication Server and enter:

create replication definitionase_employee_repdef_for_db2

with primary at ase_server.ase_databasewith all tables named ‘employee’

(empid int,first_name char(20),last_name char(20),...birthdate datetime map to rs_db2_date,salary money, ...

In this example, birthdate is the column name, datetime is the declared datatype, and rs_db2_date is the published datatype. Because the declared datatype is a native datatype, the native and base datatype are the same. That is, the base datatype of datetime is datetime. The published datatype rs_db2_date is a datatype definition for DB2, and its base datatype is char(10).

How Datatype Definitions Work

Datatype definitions allow you to translate from one datatype to another without losing valuable information.


290

When used as the declared datatype, a datatype definition provides the mechanism for capturing both the literal value and its datatype attributes—such as delimiters, range information, precision, scale, length, and maximum and minimum values—and translating them into a native datatype format that Replication Server can process.

When used as a published datatype, a datatype definition takes the value in Replication Server native datatype format, including its attribute information, and translates that information into a datatype format acceptable to another database, retaining as much information as the published datatype can accommodate.

When data definitions are used for both the declared and published datatypes, both translations take place.

The following tables list the available datatype definitions for each supported non-Sybase datatype.

Note Microsoft SQL Server datatypes are directly compatible with, and are handled as, Adaptive Server datatypes.

Table 8-4 lists the supported DB2 datatypes and their datatype definition equivalents.

Table 8-4: Datatype definitions for DB2 datatypes

Table 8-5 lists supported Informix datatypes and their datatype definition equivalents.

DB2 datatype Datatype definition

CHAR FOR BIT DATA rs_db2_char_for_bit

DATE rs_db2_date

TIME rs_db2_time

TIMESTAMP rs_db2_timestamp

VARCHAR FOR BIT DATA rs_db2_varchar_for_bit

TINYINT rs_db2_tinyint

DECIMAL rs_db2_decimal

NUMERIC rs_db2_numeric


291

Table 8-5: Datatype definitions for Informix datatypes

Table 8-6 lists supported Oracle datatypes and their datatype definition equivalent.

Table 8-6: Datatype definitions for Oracle datatypes

Column-Level Translations and Multiple Replication Definitions

In general, a column declared in multiple replication definitions must use the same declared datatype in each replication definition—although published datatypes can differ.

rawobject and rawobject in row (Java) columns declared in multiple replication definitions, however, can use either the rawobject (or rawobject in row) datatype or its base datatype for the declared datatype. For example, you can use rawobject and image or rawobject in row and varbinary in multiple replication definitions for the same Java column. See Java in Adaptive Server Enterprise for detailed information about Java columns in Adaptive Server.

Informix datatype Datatype definition

binary rs_informix_binary

date rs_informix_date

datetime fraction(0) rs_informix_datetime0






datetime (time only) rs_informix_datetime_time

Oracle datatype Datatype definition

RAW rs_oracle_binary

DATE rs_oracle_date

DATE (with time) rs_oracle_datetime

NUMBER (INTEGER) rs_oracle_int

NUMBER (FLOAT) rs_oracle_float

NUMBER (DECIMAL) rs_oracle_decimal


292

Using Class-Level and Column-Level Translations TogetherIf you activate class- and column-level datatype translations for the same column, both are applied. Column-level translations are performed after subscription resolution and before class-level translations, just prior to delivery to the replicate database.

This order of execution ensures that column-level translations supersede class-level translations. That is, translations for a particular connection (class-level translations) do not affect translations defined for a particular table and column (column-level translations).

Verifying TranslationsYou can verify how translations alter values before you set up column- or class-level translations. Use the admin translate command to view the results of a particular translation. admin translate accepts a value and a source and target datatype and returns the target value. It is most useful with the diagnostic version of Replication Server, which, if the translation fails, allows you to trace the reason for the failure.

The syntax is:

admin translate, value, source_datatype, target_datatype

where:

• value is the literal representation of the value being translated—including delimiters as required by the base datatype of the source datatype.

• source_datatype is the datatype definition or datatype for the value you want to translate.

• target_datatype is the datatype definition or datatype for the value after translation.

If the base datatype of either the source or target datatype requires a length specification, such as char(26), enclose the datatype name in quotes.

For example, to verify the translation of a date from db2_date to datetime, log in to Replication Server and enter:

admin translate, ‘04/29/1989’, db2_date, datetime

In this example, value is the character string “04/29/1989,” and you must enclose it in single quotes. Refer to the Replication Server Reference Manual for a complete description of admin translate and further examples.

293

C H A P T E R 9 Managing Replicated Functions

This chapter describes how to replicate the execution of a stored procedure from the source to the destination database using replicated functions.

When you use function replication, Replication Server copies the execution of a stored procedure to the destination database. That is, you execute a stored procedure at the source database, which invokes the execution of another stored procedure at the destination database. The two stored procedures need not have the same name nor perform the same tasks.

Refer to the Replication Server Design Guide for information about replication system design issues that concern replicated stored procedures.

This chapter covers the distribution of stored procedures via function replication definitions. The distribution of stored procedures associated with table replication definitions is described in Appendix A, “Asynchronous Stored Procedures”

You identify the stored procedure at the source and the information that is to be passed to the destination by creating a function replication definition, which specifies:

• The names of the stored procedures at the source and destination databases (if they are different)

• The datatypes and parameters that are to be passed to the destination stored procedure

To satisfy the requirements of distributed applications, Replication Server provides two ways to implement replicate functions. Use:

• An applied function to distribute, to replicate databases, an operation first performed in a primary database. See “Applied Functions” on page 298 for more information.

• A request function to deliver a transaction from a replicate database to the primary database. See “Request Functions” on page 298 for more information.

Prerequisites and Restrictions

294

Prerequisites and RestrictionsBefore you implement applied or request functions in your replication system, be sure that you have met the prerequisites discussed below, and that you understand the restrictions on the use of replicated stored procedures.

Replicated Function Prerequisites• Understand how you will use applied or request functions to meet your

application needs. Refer to the Replication Server Design Guide for more information.

• Set up a RepAgent, if necessary, for each database from which replicated functions will be delivered. For applied functions, this is the primary database; for request functions, this is a replicate database. Refer to Chapter 4, “Managing a Replication System”and the Replication Server Configuration Guide for details.

• Set up routes, if necessary, between each source and each destination Replication Server. See Chapter 5, “Managing Routes” to learn how to set up routes.

• To use applied functions, a route from the primary to the replicate Replication Server must exist.

• To use request functions, a route from a replicate Replication Server to the primary Replication Server must also exist.

• Replicated functions can be used with applications that involve fragmented primary data. To do this, create a function replication definition and a stored procedure for each primary fragment. Refer to the Replication Server Design Guide for more information about working with fragmented primary data.

In general, the information in this chapter assumes Replication Server’s basic primary copy model, where a single source (primary) database distributes data to one or more destination (replicate) databases. Refer to “Replication Server’s Basic Primary Copy Model” on page 5 for a detailed description of this model.

CHAPTER 9 Managing Replicated Functions

295

Replicated Function Restrictions• If you use function replication definitions, do not attempt to replicate

affected data using table replication definitions and subscriptions. If the stored procedures are identical, they will make identical changes to each database. If the affected tables are also replicated, duplicate updates would result.

• The names of all replication definitions, including function replication definitions, must be unique in the replication system. If you want to replicate stored procedures that have the same name, they must use different replication definitions.

To replicate a stored procedure with a non-unique name, invoke it with a stored procedure that has a unique name and that is executed in the source database. For example, the non-unique stored procedure upd_sales may invoke the unique stored procedure upd_salesA or vice versa. Mark the unique stored procedure, upd_salesA, for replication using the sp_setrepproc system procedure, and leave upd_sales, the stored procedure that invokes it, unmarked.

Alternatively, you can declare the first parameter of the stored procedure with a non-unique name as @rs_repdef and pass the unique name of the replication definition in this parameter when the stored procedure is executed. Do not include the @rs_repdef parameter in the create function replication definition command. This method works only with RepAgent for Adaptive Server and LTM for SQL Server.

• Replication Server does not support nested transactions within replicated stored procedures.

When replication for a stored procedure is enabled, using sp_setrepproc or sp_setreplicate, Adaptive Server always executes the stored procedure within a transaction. If you have not explicitly executed the replicated stored procedure within a transaction, Adaptive Server places an implicit begin transaction at the start of the procedure.

If the replicated stored procedure contains nested transaction commands, such as begin transaction, commit transaction, or rollback transaction, errors may result when you execute the procedure. For example, a rollback transaction command might roll back to the start of the stored procedure, rather than to the nested begin transaction command that was the intended rollback point.

Prerequisites and Restrictions

296

• Replicated functions, like Adaptive Server stored procedures, cannot contain parameters with text and image datatypes. Refer to the Adaptive Server Reference Manual for more information.

• Adaptive Server logs a replicated stored procedure invocation in the database in which the enclosing transaction was started.

• If the user does not begin a transaction explicitly, Adaptive Server begins one in the user’s current database before the stored procedure is invoked.

• If the user begins the transaction in one database and then executes a replicated stored procedure in another database, the execution is still be logged in the database where the transaction began.

• If a single transaction invokes one or more request functions and executes applied functions or contains data modification language (termed a “mixed-mode” transaction), Replication Server processes the request functions after all the other operations. All request operations are processed together in a separate transaction. This can occur if a single Replication Server manages both primary and replicate data.

• When you use replicated functions and heterogeneous datatype translations:

• You cannot alter the datatype of a parameter value using create function replication definition or alter function replication definition. However, you can use datatype definitions to declare parameters for applied function replication definitions, which are then subject to class-level translations.

• Replication Server does not perform translations on parameter values for request functions. However, during function-string mapping, the delimiters defined for the parameter values of their declared datatype are used to generate the SQL.

Commands for Managing Function Replication DefinitionsTable 9-1 lists the Replication Server commands used to work with function replication definitions.


297

Table 9-1: Commands for managing function replication definitions

Also see Table 8-1 on page 220 and Table 10-3 on page 327.

Using Replicated FunctionsA replicated stored procedure is an Adaptive Server stored procedure that you’ve marked for replication using either sp_setrepproc or sp_setreplicate.

A function replication definition describes a replicated stored procedure, its parameters, and its location. When you create a function replication definition, Replication Server creates a function, which contains the information in the function replication definition.

When a replicated stored procedure that has its own function replication definition is invoked, its function is transferred from the source to a destination Replication Server. The function passes parameters to a corresponding stored procedure that is, in turn, invoked in the destination database. A function string translates the function to syntax the subscribing database can interpret.

Function replication improves performance because it encapsulates multiple operations in a single function. Replicated stored procedures do not have to modify any data in order to be replicated.

Command Task

create function replication definition

Creates a function replication definition that describes the stored procedure, and its parameters, for replication. It also describes the location of the primary data.See “Implementing an Applied Function” on page 299 and “Implementing a Request Function” on page 302.

alter function replication definition

Modifies a function replication definition. For example, it:

• Specifies a different name for the stored procedure invoked at the destination database

• Adds parameters or searchable parameters

• Changes how the replication definition is used in replicating to a standby database

See “Modifying or Dropping Replicated Functions” on page 306.

drop function replication definition

Removes a function replication definition from the replication system. You must drop all subscriptions for a function replication definition before you can drop the replication definition.See “Modifying or Dropping Replicated Functions” on page 306.

Using Replicated Functions

298

Applied FunctionsUse an applied function to distribute operations first performed in a primary database to replicate databases. Applied functions allow you to realize important performance benefits. For example, if a client application must update a large number of row changes, you can create an applied function that changes many rows, rather than replicating the rows individually.

To use an applied function, you first create a stored procedure in the primary database and a corresponding stored procedure in the replicate database. At a primary Replication Server, you create a function replication definition for the stored procedure. Replicate Replication Servers can subscribe to the function replication definition. When the stored procedure in the primary database is invoked, it in turn causes the invocation of the stored procedure in the replicate database managed by the subscribing replicate Replication Server.

Because Replication Server does not know in advance what data is needed by the stored procedure at the replicate databases, you must use bulk materialization or the no-materialization method when you subscribe to a function replication definition.

Replication Server executes the stored procedure in the replicate database as the maintenance user, which is consistent with normal data replication.

See “Implementing an Applied Function” on page 299 for step-by-step instructions.

Request FunctionsUse a request function to deliver a replicated stored procedure from a replicate database to the primary database. For example, a client application at a remote location needs to make changes to primary data. The client application first executes a stored procedure at the replicate site—a procedure that may or may not make changes at the replicate database. When the stored procedure executes, the replicate Replication Server passes a request function to the primary, where a corresponding stored procedure is invoked that updates the primary data.

With a primary copy model, a single primary database contains all the latest updates. A client application at a remote site can update the primary using request functions. As updates occur at the primary table, Replication Server captures the updates and sends them to replicate data servers.


299

If communication between the primary and destination databases fails, operations executed in the primary database are stored in Replication Server stable queues until they can be delivered to replicate sites. Likewise, operations executed remotely are held in stable queues until they can be delivered to the primary database.

To use a request function, create a stored procedure in the primary database and a corresponding stored procedure in the replicate database. Then, at a primary Replication Server, create a function replication definition. You do not need to create any subscriptions. When the stored procedure in the replicate database is invoked, it, in turn, invokes the stored procedure in the primary database.

Replication Server executes the stored procedure in the primary database as the user who executed the stored procedure in the replicate database. This guarantees that only authorized users can change primary data.

In an application, Replication Server may replicate some or all of the data that is changed in the primary database. The changes are distributed to replicate databases managed by Replication Servers that have subscriptions to table replication definitions or as separate applied functions. Either way, the effect of a transaction arrives at the primary and then replicate databases.

When you use request functions, all updates are made at the primary database. This preserves Replication Server’s primary copy data model and protects the replication system from network failure and excess traffic.

Implementing an Applied FunctionTo implement an applied function:

1 Review the requirements described in “Prerequisites and Restrictions” on page 294.

2 Set up replicate databases containing replicate tables that the stored procedure will modify.

3 In the primary database, create the stored procedure. The stored procedure may or may not modify primary data. For example, this stored procedure uses the @pub_name parameter to update the pub_name column of the publishers table:

create proc update_pubs@pub_id char(4), @pub_name varchar(40),asupdate publishers

Implementing an Applied Function

300

set pub_name = @pub_namewhere pub_id = @pub_id

4 In the primary database, mark the stored procedure for replicated function delivery, using the sp_setrepproc system procedure. For example:

sp_setrepproc update_pubs, ’function’

See “Marking Stored Procedures for Replication” on page 305 for details.

5 In the replicate database, create a stored procedure with the same name, parameters, and datatypes as the stored procedure in the primary database. Typically, the two stored procedures perform the same operations. For example:

create proc update_pubspub_id char(4), @pub_name varchar(40),asupdate publishersset pub_name = @pub_namewhere pub_id = @pub_id

Warning! A stored procedure invoked in a replicate database in applied function delivery is invoked inside a user-defined transaction. Refer to the Transact-SQL User’s Guide for information about operations that are not allowed inside user-defined transactions (for example, the dump transaction and dump database commands).

Do not mark this stored procedure as replicated. In applied function delivery, only the stored procedure in the primary database is marked as replicated.

However, if the replicate database modifies a standby database, mark the stored procedure in the active and standby replicate databases as replicated if you want to use stored procedure replication to the standby.

6 In the replicate database, grant execute permission on the stored procedure to the maintenance user. For example:

grant execute on update_pubs to maint_user

7 In the primary Replication Server, create a function replication definition for the stored procedure. For example:

create function replication definition update_pubswith primary at TOKYO_DS.pubs2(@pub_id char(4), @pub_name varchar(40),searchable parameters (@pub_name, @state)


301

The function replication definition must use the same name, parameters, and datatypes as the stored procedure in the primary database. You have the option to include only the parameters you want to replicate. You need not include parameters and their datatypes, but you must include the parentheses for this clause, whether or not you include the parameters.

If you specify searchable parameters, you can subscribe to function invocations based on the value of the function’s parameters. In the preceding example, @pub_name and @state are searchable parameters. Thus, for example, they can subscribe only to “CA” updates.

If you want to replicate the Adaptive Server timestamp datatype, declare the datatype binary(8) in the function replication definition.

Refer to “create function replication definition” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for the full command syntax.

See “Modifying or Dropping Replicated Functions” on page 306 for information about changing function replication definitions.

8 When you create a function replication definition, Replication Server automatically creates a corresponding function in the default function-string class. See “User-Defined Functions” on page 374 for more information.

If you are not using a default function-string class or a class inherited from the default or if you want to customize the function’s invocation, you need to create a function string for the user-defined function. See “Creating or Modifying a Function String for a Replicated Function” on page 307 for more information.

9 In the replicate Replication Server, create a subscription to the function replication definition, using create subscription and the no-materialization method or define subscription and the other bulk materialization commands.

Warning! You must use the no-materialization method or bulk materialization—instead of atomic or nonatomic materialization—because Replication Server cannot determine in advance what data is needed for the stored procedure at the replicate site.

For example:

create subscription pubs_subfor update_pubs

Implementing a Request Function

302

with replicate at SYDNEY_DS.pubs2where @state = ’CA’without materialization

If you specified searchable parameters in the function replication definition, you can subscribe to function invocations based on the value of the function’s parameters. In this example, the subscription only receives rows if the value of the @state parameter is equal to CA.

Refer to “create subscription” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for the full command syntax. See also “Using create subscription for No Materialization” on page 332.

10 Verify that all Replication Server and database objects in steps 1 through 9 exist at the appropriate locations. You should now be able to execute the applied function.

Refer to Chapter 6, “Adaptive Server Stored Procedures,” in the Replication Server Reference Manual for information about stored procedures, such as rs_helpfunc, that you can use to query the RSSD for information about the replication system.

Implementing a Request FunctionTo implement a request function:

1 Review the requirements described in “Prerequisites and Restrictions” on page 294.

2 In the primary Adaptive Server, create a login name and password for the user who will execute the stored procedure at the replicate Adaptive Server.


3 In the primary database, create a stored procedure that updates the primary data. For example:

create proc update_pubs@pub_id char(4), @pub_name varchar(40)asupdate publishersset pub_name = @pub_name


303

where pub_id = @pub_id

Warning! A stored procedure invoked in a primary database in request function delivery is invoked inside a user-defined transaction. Refer to the Transact-SQL User’s Guide for information about operations that are not allowed inside user-defined transactions (for example, the dump transaction and dump database commands).

Do not mark this stored procedure as replicated. In request function delivery, only the stored procedure in the replicate database is marked as replicated.

However, if the primary database is also part of a warm standby application, then mark the stored procedure in the active and standby primary databases as replicated if you want to replicate stored procedures to the standby database.

4 In the primary database, grant execute permission on the stored procedure to the same user for whom you created a login name and password in step 2. For example:

grant execute on update_pubs to pubs_user

5 In the replicate database, create a stored procedure with the same parameters and datatypes as the stored procedure in the primary database. The new stored procedure should either do nothing or should display a message to indicate a pending update. For example:

create proc update_pubs_request@pub_id char(4), @pub_name varchar(40)asprint "Transaction accepted."

Note Sybase recommends that you use a different name for the stored procedure you create in the replicate database. You must use a different name if the function will replicate back to the replicate database as an applied function. When you create the function replication definition in step 8, you must specify the name of the stored procedure in the destination (primary) database.

6 In the replicate database, mark the stored procedure for replicated function delivery using the sp_setrepproc system procedure. For example:

sp_setrepproc update_pubs_request, ’function’

See “Marking Stored Procedures for Replication” on page 305 for details.

Implementing a Request Function

304

7 In the replicate database, grant execute permission on the stored procedure to the replicate Replication Server user who will invoke it. For example:

grant execute on update_pubs_request to pubs_user

8 In the primary Replication Server, which manages the primary data, create a function replication definition for the stored procedure in the replicate database. For example:

create function replication definitionupdate_pubs_request

with primary at TOKYO_DS.pubs2deliver as ’update_pubs’(@pub_id char(4), @pub_name varchar(40))

The function replication definition must use the same name, parameters, and datatypes as the stored procedure in the replicate database. You have the option to include only the parameters you want to replicate.

Refer to “create function replication definition” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for the full command syntax.

In the preceding example, the optional deliver as clause specifies that the stored procedure to execute at the primary data server is named update_pubs, not update_pubs_request.

9 When you create a function replication definition, Replication Server automatically creates a corresponding user-defined function.

If you are not using a default function string or wish to customize the function’s invocation, you need to create a function string for the user-defined function. See “Creating or Modifying a Function String for a Replicated Function” on page 307 for more information.

10 Verify that all Replication Server and database objects in steps 1 through 9 exist at the appropriate locations. You should now be able to execute the request function.

Refer to Chapter 6, “Adaptive Server Stored Procedures,” in the Replication Server Reference Manual for information about stored procedures, such as rs_helpfunc, that you can use to query the RSSD for information about the replication system.


305

Marking Stored Procedures for ReplicationThe system procedure sp_setrepproc is used to mark stored procedures for replication. The syntax is:

sp_setrepproc [proc_name [, {’function’ | ’table’ | ’false’}]]

proc_name – the name of a stored procedure in the current database.

’function’ – enables replication for a stored procedure associated with a function replication definition.

’table’ – enables replication for a stored procedure associated with a table replication definition. For information on replicating stored procedures associated with table replication definitions, see Appendix A, “Asynchronous Stored Procedures”

’false’ – disables replication for the stored procedure.

Use sp_setrepproc according to these guidelines:

• To list all replicated objects in the database, enter sp_setrepproc with no parameters.

• To determine the replication status of the stored procedure, enter sp_setrepproc with the stored procedure name only.

• Enter sp_setrepproc with the stored procedure name and ’function’, ’table’, or ’false’ to enable each type of replication or to disable replication for the stored procedure. You must be the System Administrator or the Database Owner to use sp_setrepproc to change the replication status of a stored procedure.

For applied function delivery, mark the stored procedure in the primary database as replicated. For request function delivery, mark the stored procedure in the replicate database as replicated. In either case, specify ’function’ to indicate the type of replication definition associated with the stored procedure.

Subscribing to Replicated FunctionsYou can create subscriptions to function replication definitions for applied functions using create subscription and the no-materialization method or define subscription and the other commands for bulk materialization: activate subscription, validate subscription, and check subscription.

Modifying or Dropping Replicated Functions

306

You do not need to create a subscription for a request function. The destination database is always the primary database; you create the function replication definition in the primary Replication Server.

If you specified searchable parameters in the function replication definition, you can subscribe to a function based on the value of its parameters.

You drop subscriptions to function replication definitions using drop subscription. They are dropped without purging the replicate data associated with the function. You do not need to specify the without purge option.

Refer to “define subscription” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual, and related commands, for the full syntax for bulk materialization commands. Also see “Bulk Materialization” on page 315.

Modifying or Dropping Replicated FunctionsThis section explains how to modify or drop replicated functions.

Before Modifying a Function Replication Definition1 Change the stored procedure at the primary or replicate data server and

provide defaults for new parameters, if necessary.

2 As a precaution, quiesce the system. Altering functions while updates are in process can have unpredictable results.

See Chapter 4, “Managing a Replication System” for information on how to quiesce the system.

Modifying a Function Replication DefinitionTo add new parameters, add new searchable parameters, or change the name of the destination stored procedure, use alter function replication definition to alter the function replication definition. The syntax for this command is:

alter function replication definition function_rep_def{deliver as proc_name |add @parameter datatype[, @parameter

datatype]... |add searchable parameters @parameter


307

[, @parameter]... |send standby {all | replication definition}

parameters}

The options for alter function replication definition are similar to those for create function replication definition. Refer to “alter function replication definition” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for more information.

See “Creating or Modifying a Function String for a Replicated Function” on page 307 for information about function strings for function replication definitions.

To add new searchable parameters to the where clause of a define subscription command, drop and re-create the subscription for the function replication definition. For more information about subscribing to function replication definitions, see “Implementing an Applied Function” on page 299.

Dropping a Function Replication DefinitionTo change or remove parameters, or to rename a function replication definition, use the drop function replication definition command to drop it. Then re-create it. The syntax for this command is:

drop function replication definition function_rep_def

When you drop a function replication definition, the associated user-defined function and function string are also dropped. Subscriptions to a function replication definition must be dropped first. You can re-create the subscriptions after you re-create the function replication definition.

Creating or Modifying a Function String for a Replicated FunctionWhen you create or alter a function replication definition, Replication Server automatically creates or alters the corresponding user-defined function. You must, however, create a function string for the user-defined function if you are not using a class that inherits function strings from rs_default_function_class, either directly or indirectly.

See “User-Defined Functions” on page 374 for more information.

Using Publications for Stored Procedures

308

Create a function string for a user-defined function in the function-string class assigned to the destination database for the replicated function. Use create function string at the primary Replication Server to create a function string for a user-defined function.

See “Function Strings and Function-String Classes” on page 392 for more information.

When you drop a function replication definition, Replication Server always drops the user-defined function and function strings.

You can customize function strings in function-string classes that allow it. In a typical application, the replicated user-defined function passes stored procedure parameter values to the destination Replication Server, and the function string executes the stored procedure with these values in the destination database.

To change the default function string to perform some other action, such as inserting data into an audit log, use the alter function string command at the primary Replication Server for the replicated function. The function-string class assigned to the destination database for the replicated function must allow you to customize function strings.

See Chapter 12, “Customizing Database Operations” for information on creating and altering function strings. Also refer to “create function string” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual.

Using Publications for Stored ProceduresYou can use publications to select stored procedures and/or tables, along with their replication definitions, and subscribe to all of them as a group. Publications let you organize your replication definitions and subscriptions and then monitor their status with a single command.

Refer to “Using Publications” on page 271 for procedures for creating and managing publications. Refer to “Using Publication Subscriptions” on page 350 for procedures for creating and managing publication subscriptions.

309

C H A P T E R 1 0 Managing Subscriptions

This chapter describes setting up and managing subscriptions for replicated data.

OverviewSubscriptions resemble SQL select statements. They identify the replication definition or publication to which you are subscribing, the source and destination databases and data servers, and the materialization method by which the initial information is to be copied. You can use a where clause to specify a subset of rows or parameters that the destination database receives from the source database. This chapter describes how to materialize subscription data and manage subscriptions.

Materialization is the process of copying data specified by a subscription from a primary database to a replicate database, thereby initializing the replicate table. Replicate data can be transferred over a network, or, for subscriptions involving large amounts of data, loaded initially from media. Initialization from media is called bulk materialization. You use one of four materialization methods, depending on how you want materialization to affect the replication system. See “Subscription Materialization Methods” on page 310 for more information.

Subscriptions for table replication definitions instruct Replication Server to replicate data from primary tables into specified replicate tables. After you have created a replication definition for a primary table, replicate sites must subscribe to the replication definition at the primary database to receive updates.

Subscriptions for function replication definitions require you to use the no-materialization or the bulk materialization methods. See “No Materialization” on page 314 and “Bulk Materialization” on page 315. See also Chapter 9, “Managing Replicated Functions” for information about replicated functions.

Subscription Materialization Methods

310

You can subscribe to a group of replication definition articles by subscribing to a publication. Publication subscriptions cannot contain where clauses. To subscribe to a subset of rows in an article, you must include a where clause when you create the article. See “Using Publication Subscriptions” on page 350 for information about subscribing to publications.

You create subscriptions at the Replication Server managing the database where the replicate data is to be maintained. Your previously created replication definition provides the location of the primary data and defines the structure of the primary table and optionally, of the replicate table, where they differ.

Subscription Materialization MethodsMaterializing a subscription copies the requested data from the primary database to the replicate database, thereby initializing the replicate table. Subscriptions are added to the rs_subscriptions system table for both the primary and the replicate Replication Server. The materialization method you select determines how you create subscriptions.

Because a subscription can replicate a large set of rows, materialization can burden the network or impede applications that use the primary or replicate data. Replication Server offers four methods for creating subscriptions, so you can regulate the effects of materialization on the replication system.

Table 10-1 summarizes the materialization methods you can use to create subscriptions, including commands required for the process.

Table 10-1: Subscription materialization methods

Method Description

Atomic materialization (default)

This method, invoked using the default form of the create subscription command, copies subscription data through the network in a single atomic operation. Replication Server executes the rs_select_with_lock function to retrieve the primary data.This method provides complete consistency throughout the materialization process, but may temporarily obstruct transactions using the primary or replicate data. Do not use this method for large subscriptions if a long-running transaction is unacceptable in the primary database. For more details, see “Atomic Materialization” on page 311.

CHAPTER 10 Managing Subscriptions

311

Atomic MaterializationAtomic materialization is the default materialization method. It is the easiest method to execute and maintains complete data consistency throughout the materialization process.

During atomic materialization, Replication Server logs in to the primary data server as the user creating the subscription and with the password defined at the replicate Replication Server. Therefore, the user must be defined at both the replicate Replication Server and primary database with the same password. The user also needs the same login name and password as the primary Replication Server.

Nonatomic materialization

This method, invoked using the create subscription command with the without holdlock clause, is similar to the atomic method, except that consistency constraints during materialization are relaxed to allow clients at the primary database to process transactions during materialization. Replication Server executes the rs_select function to retrieve the primary data. Subscription data is copied in a series of transactions.Because users are allowed to update primary data, this method may result in transactional inconsistency and incomplete data during materialization. When materialization is complete, all inconsistencies are fully corrected. Autocorrection for the replicate table must be enabled to resolve inconsistencies. For more details, see “Nonatomic Materialization” on page 313.

No materialization This method, invoked using the create subscription command with the without materialization clause, allows you to create a subscription when the subscription data already exists at the replicate database.You can use this method to create subscriptions to table replication definitions and function replication definitions. For more details, see “No Materialization” on page 314.

Bulk materialization This method is appropriate when there is too much data to copy through the network. This is a “manual” materialization method that allows you to load the subscription data from media such as magnetic tape.Use this method for subscriptions to function replication definitions when data must be initialized at the replicate database.The commands used for bulk materialization are define subscription, activate subscription, and validate subscription. For more details, see “Bulk Materialization” on page 315.

Method Description


312

Logged in to the primary data server, the Replication Server selects the subscription rows using a select with holdlock operation specified by the rs_select_with_lock function. The holdlock performs a repeatable read, preventing other transactions at the primary site from updating the data until the select transaction has completed. The rows are transferred to a materialization queue at the replicate site, where they are applied to the replicate database. You must provide the stable queue with adequate partition space to handle the operation.

Atomic materialization is best for smaller subscriptions where the select with holdlock operation does not last long enough to disturb client applications using the primary database. If the subscription selects a large number of rows, you may choose to use nonatomic or bulk materialization, so that clients at the primary database are not affected.

When data already exists at the replicate database, you can use the no-materialization method.

Atomic materialization allows changes to the primary table but effectively delays data server changes until the activation phase of materialization has completed.

Incremental Atomic Materialization

You can avoid long-running transactions at the replicate database by using the incrementally option. The incremental option sends materialization data to the replicate database in a series of transactions, rather than in one large transaction. Otherwise, incremental and non-incremental atomic materialization are identical. Subscription data is available but incomplete until materialization has completed and the subscription is validated.

Rows are removed from the stable queue after they have been successfully inserted, so less partition space is required. You can truncate the database transaction log during materialization, if necessary.

Users at the replicate site will see partial subscription data during materialization, which may invalidate some queries. However, they will have access to inserted rows sooner, which may be beneficial.


313

The publishers_rep replication definition presented in Chapter 8, “Managing Replicated Tables” is used in the following example to create a subscription. The create subscription command in the example has no where clause, so the subscription causes Replication Server to replicate all the rows in the replication definition. The incrementally keyword ensures that the replicate database transaction log does not become full. Clients at the replicate site can be suspended or warned that the publishers table is materializing and will contain incomplete data until the process has completed.

create subscription publishers_subfor publishers_repwith replicate at SYDNEY_DS.pubs2incrementally

Nonatomic MaterializationNonatomic materialization, using the without holdlock option of the create subscription command, is the same as atomic materialization, except for the following:

• The data is selected from the primary database without a holdlock. Clients at the primary site can update the data while the select operation is in process.

• Transactions are always applied incrementally at the replicate database.

Note If the replicate minimal columns feature is set for the replication definition, you cannot create new subscriptions using nonatomic materialization.

In nonatomic materialization, Replication Server inserts rows into the replicate database incrementally in 10-row transactions. Clients at the replicate site that are using the table will see partial subscription data during materialization. This may invalidate some queries. Since the subscription is activated before the data is copied to the replicate database, primary table changes may be applied twice to the replicate table in some circumstances. You must enable autocorrection when you use nonatomic materialization. Autocorrection ensures that a second application of data does not result in an error. See “Using autocorrection” on page 314 for details.


314

Using autocorrection

To enable autocorrection, issue the set autocorrection command with the on option for each replication definition to which you plan to subscribe using nonatomic materialization. When using autocorrection, if Replication Server updates or inserts a row in a primary table, it converts the update or insert into a delete followed by an insert, so that the update or insert operation cannot fail because of an existing row.

During nonatomic subscription materialization, Replication Server selects data without a holdlock. After adding the data to the replicate database, Replication Server applies replicated commands. If you enable autocorrection, Replication Server corrects certain temporary inconsistencies that may be caused by selecting the data using the without holdlock option.

However, if you execute replicated stored procedures that change subscription data during materialization, autocorrection does not always correct the replicate database. During function calls, autocorrection does not protect against inconsistencies.

After a subscription that uses nonatomic materialization has materialized, you can disable autocorrection for better performance. If you disable autocorrection, you can also specify minimal column replication. See “Replicating the Minimal Set of Columns” on page 230 for more information.

Refer to “set autocorrection” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for details.

No MaterializationYou can use create subscription with the without materialization clause to activate a subscription when materialization has already occurred. To use this method:

• The subscription data must already exist at the replicate database

• The primary and replicate tables must be synchronized

• Activity must be stopped on the primary table so that there are no further updates in the Replication Server stable queues

When creating a subscription with the without materialization clause, Replication Server logs in to the primary Replication Server as the user creating the subscription. The user who executes create subscription must have the same login and password at the primary and replicate Replication Servers.


315

You can also use create subscription with the without materialization clause to subscribe to function replication definitions.

Bulk MaterializationWith bulk materialization, you manually transfer subscription data between databases. Use bulk materialization when a subscription is too large to copy through the network. Bulk materialization has very little effect on primary database clients or on the network.

You can use bulk materialization to create subscriptions for function replication definitions. See Chapter 9, “Managing Replicated Functions” for more information about replicated functions.

Bulk materialization uses these commands, which are executed at different points in the materialization process: define subscription, activate subscription, validate subscription. Use the check subscription command to check the status of the subscription.

When you use bulk materialization, you must coordinate:

• The dump to media of the subscription data at the primary site.

• The load from media into the table at the replicate site.

• The application of updates made at the primary site after you make the media dump.

Note Bulk materialization may require special handling if the primary and replicate databases differ in, for example, table or column names.

Three bulk-materialization methods are available to ensure data consistency between the primary and replicate sites. The method you use depends mainly on whether applications using the primary data can tolerate interruptions.

You can use any of these methods for subscriptions to either table or function replication definitions. With subscriptions to function replication definitions, it may not be obvious which replicate tables will be affected by stored replicated procedures executing in the replicate database.

Before you initiate bulk materialization, you must consider these issues in relation to the existing data in the replicate database.

Table 10-2 summarizes the three bulk materialization methods.


316

Table 10-2: Summary of bulk materialization methods

Stop Updates at the Primary Database and Take a Snapshot

You can use this bulk materialization method to retrieve data from the primary database, if you are able to suspend updates to the primary data. To maintain consistency, all updates to the primary database are suspended for the duration of the materialization.

1 Verify that the entire replication system is working. See Chapter 11, “Verifying and Monitoring Replication Server” for details.

2 Suspend updates to the data in the primary database by stopping client applications that generate transactions against the primary data.

3 Quiesce the replication system components involved with replicating data from the primary Replication Server to the replicate Replication Server.

Use the admin quiesce_force_rsi command at the primary and replicate Replication Servers and at any intermediate Replication Servers.

4 Execute the suspend log transfer command for the primary database.

5 Take a snapshot of the subscription data from the primary database using a select statement or a database dump.

Method Summary of Process

Stop updates to the primary table and take a snapshot of the data

Stop all applications from updating the primary data and then retrieve the subscription data from the primary database with a select statement or database dump.Define the subscription and activate it with an option that leaves the DSI suspended for the replicate database. Clients can resume updates to the primary data.After you load the subscription data into the replicate database, you can resume the DSI and validate the subscription. For details on this procedure, see “Stop Updates at the Primary Database and Take a Snapshot” on page 316.

Simulate atomic materialization

Allow client applications to continue executing transactions against the primary data while the subscription data is retrieved. After defining the subscription, you lock the primary data, retrieve the subscription data, and activate the subscription. The activate subscription command leaves the DSI for the replicate database suspended.After you load the subscription data into the replicate database, you can resume the DSI and validate the subscription. For details on this procedure, see “Simulate Atomic Materialization” on page 318.

Simulate nonatomic materialization

This method is the same as simulating atomic materialization, except that you activate the subscription first, and then retrieve the data from the primary database without locking the data. Because of this, the data at the replicate database may be inconsistent with the data at the primary database until the subscription is validated and you are required to enable autocorrection for the replicate data. For details on this procedure, see “Simulate Nonatomic Materialization” on page 319.


317

6 Execute the define subscription command at the replicate Replication Server.

7 Wait for the subscription to be defined at both the primary and replicate Replication Servers. Execute the check subscription command at both the primary and replicate Replication Servers to verify that the subscription status is DEFINED.

8 Execute the activate subscription command, using the with suspension clause, at the replicate Replication Server.

9 Wait for the subscription to become active at both the primary and replicate Replication Servers. Execute the check subscription command at both the primary and replicate Replication Servers to verify that the subscription status is ACTIVE.

When the subscription becomes active at the replicate Replication Server, the DSI connection to the replicate Replication Server is suspended.

10 You can resume updates to the primary data when the subscription status becomes active.

11 Execute the resume log transfer command from the primary database at the primary Replication Server.

12 Begin loading the snapshot data into the replicate database.

Note While you wait for the data to finish loading in the replicate database, you can continue with the next step.

13 Execute the validate subscription command at the replicate Replication Server to validate the subscription.

14 Wait for the subscription to become valid at both the primary and replicate Replication Servers. Execute the check subscription command at the replicate Replication Server to verify that the subscription status is VALID.

15 When the snapshot data has finished loading in the replicate database, execute the resume connection command to resume the connection to the replicate database.

Now the subscription is created, the replicate data is consistent with the primary data, and replication is active.


318

Simulate Atomic Materialization

Use this bulk materialization method when you cannot suspend updates to the primary database.

This method ensures replicated data consistency by retrieving the subscription data, activating the subscription, and suspending the DSI connection to the replicate database all in one transaction at the primary data server.

Use select with holdlock and the rs_marker stored procedure, as in this example:

begin transactionselect from table with holdlockwhere search_conditionsexecute rs_marker’activate subscription subid with suspension’commit transaction

subid is an integer that identifies the subscription. The subid for a subscription and can be found in the subid field of the rs_subscriptions system table in the RSSD. After the subscription is defined, you can find its subid by executing the following query in the RSSD of the primary or replicate Replication Server:

select subid from rs_subscriptionswhere subname = ’subscription’and dbid in (select dbid from rs_databaseswhere dbname = ’replicate_database’and dsname = ’replicate_data_server’)

Here are the steps to follow to simulate atomic materialization:




4 Execute a single transaction as provided in the previous sample transaction that includes select with holdlock and the rs_marker stored procedure. This action activates the subscription.


319

5 Wait for the subscription to become active at both the primary and replicate Replication Servers. Execute the check subscription command at the replicate Replication Server to verify that the subscription status is ACTIVE. When the subscription status is ACTIVE at the replicate Replication Server, the DSI connection to the replicate database will be suspended.

6 Begin loading the subscription data into the replicate database.

7 Resume the DSI connection to the replicate database using the resume connection command.

8 Execute the validate subscription command at the replicate Replication Server.

9 Wait for the subscription to become valid at both the primary and replicate Replication Server. Execute the check subscription command at the replicate Replication Server to verify that the subscription status is VALID.

Now the subscription is created and replication is active.

Simulate Nonatomic Materialization

Use this bulk materialization method when you cannot suspend updates to the primary database or if you cannot lock the primary data during the select or dump operation that retrieves the subscription data.

This method allows a period of flux at the replicate site during which the replicate data may be inconsistent with the primary data. By the time the subscription becomes VALID, however, the data should be consistent. You must set autocorrection on during materialization so that inconsistencies resulting from continuing updates in the primary database can be resolved without errors.

Warning! Do not use this method if the replicate minimal columns feature is set for the replication definition or if you execute applied functions or applied stored procedures from the primary database to modify data in the replicate database. In both cases, autocorrection cannot resolve the inconsistencies.




320


4 Execute the activate subscription command, using the with suspension clause, at the replicate Replication Server.

5 Wait for the subscription to become active at both the primary and replicate Replication Servers. Execute the check subscription command at the replicate Replication Server to verify that the subscription status is ACTIVE. When the subscription status is ACTIVE at the replicate Replication Server, the database connection for the replicate database has been suspended.

6 As soon as the subscription becomes active at the primary Replication Server, retrieve the data from the primary database using a select or a database dump.

7 Find the ID number (subid) for the subscription by querying the rs_subscriptions system table. See “Subscription Example” on page 338 for more information.

8 Execute the rs_marker stored procedure in the primary database:

rs_marker ’validate subscription subid’

Warning! Be sure that you execute the rs_marker stored procedure with

the correct subid number for the subscription. The subid column in the

rs_subscriptions system table contains the unique ID number for each

subscription. Entering any other number or character string may cause

serious problems.

9 Load the subscription data into the replicate database.

10 Enable autocorrection for the replication definition at the replicate database. See “Using autocorrection” on page 314 for more information.

11 Use the resume connection command to resume the database connection for the replicate database.


321

12 Wait for the subscription to become valid at both the primary and replicate Replication Servers. Execute the check subscription command at the replicate Replication Server to verify that the subscription status is VALID. Once the subscription status is VALID, the replicate data is consistent with the primary data.

13 Disable autocorrection for the replicate database. See “Using autocorrection” on page 314 for more information.

Now the subscription is created and replication is active.

Dematerialization ProcessingDematerialization removes subscriptions and, optionally, data from the replicate database. Dematerialization also removes subscription information from the RSSDs at the primary and replicate sites.

Dropping a subscription causes Replication Server to stop sending changes from a primary database to a replicate database. You can use the drop subscription command to drop subscriptions for either table or function replication definitions.

drop subscription removes the subscription from the RSSDs of the primary and replicate Replication Servers.

When you drop a subscription to a table replication definition, you can specify that Replication Server delete the subscription’s rows from the replicate database. Or, you can delete the rows manually.

When you drop a subscription to a function replication definition, the replicate data associated with the function is not deleted from the replicate database.

There are two methods of dematerialization:

• with purge dematerialization, which selectively deletes rows not used by other subscriptions

• without purge dematerialization, which allows you to manually delete rows in replicate tables

Dematerialization Processing

322

In either case, the primary Replication Server stops sending data for the dropped subscription, if the data is not included in other subscriptions at the same replicate site.

Note For heterogeneous datatypes: Subscriptions that specify columns subject to class- or column-level translations in the where clause cannot be dematerialized automatically. You must use the bulk or no-materialization method.

Dematerializing and Purging RowsUse the with purge clause when you want to delete rows replicated by the subscriptions you are dropping. Use the incrementally option to delete rows in 10-row increments. The maintenance user for the replicate database must have select permission on the table to use this option.

Dematerializing a subscription and purging rows from the replicate table uses function strings for the rs_select or rs_select_with_lock system functions. You may be required to create a function string for these system functions.

• If the connection for the replicate database uses a function-string class with default-generated function strings or a function-string class inherited from such a class, Replication Server generates a corresponding default function string for the rs_select_with_lock or rs_select functions.

• If the connection uses any other function-string class, you must create the function string, with an input template that matches the subscription’s where clause. Use the create function string command.

See “Function-String Classes” on page 380 for details.

If you are using a function-string class in which you can customize function strings, you can replace an existing default or custom function string with one that performs a select operation that your application requires, using the alter function string command.

For more information on creating or altering rs_select and rs_select_with_lock function strings, see “Managing Function Strings” on page 391.


323

Dematerialization Without Purging RowsDropping a subscription using the without purge option leaves the rows replicated by the subscription in the replicate table. Subscriptions to function replication definitions are dropped automatically using the without purge option. You do not need to specify this option. You must, however, specify this option if you want to keep the rows in the replicate table. If you want to manually delete rows, you must use the with suspension option as well.

Monitoring Materialization and DematerializationSubscriptions pass through phases before they are fully set up or removed from the replication system. The phases for setting up a subscription are:

• Definition – create subscription or define subscription add the subscription to the RSSD for the primary and replicate Replication Servers.

• Activation – takes place after subscription resolution. The primary Replication Server adds the subscription to the Subscription Resolution Engine (SRE). The SRE compares log records to the current subscriptions to determine where changes to replicated tables must be distributed.

• Materialization – for atomic and nonatomic subscriptions, the primary Replication Server retrieves subscription data from the primary database and copies it to the replicate Replication Server to be applied to the replicate database.

• Validation – both the primary and replicate Replication Server completely materialize the subscription and verify it is consistent with the primary data.

The phases for removing subscription data, using the drop subscription command, are:

• Dematerialization – stops sending updates for the subscription to the replicate database and, if the with purge clause is specified, deletes the subscription data from the replicate database (if the data is not included in other subscriptions). If the without purge clause is specified, then Replication Server does not delete the data from the replicate database.

• Removal – deletes the subscription from the RSSD for both the primary and replicate Replication Servers.

Before You Create Subscriptions

324

Materialization or dematerialization can fail during any of these stages. This is why you need to monitor the progress of a subscription using the check subscription command. See “Using the check subscription Command” on page 335 for more information. In addition to the check subscription command, you can use the admin who command to check the status of the Replication Server threads processing the subscription. For atomic and nonatomic materialization, Replication Server builds a materialization queue that contains rows to be added to the replicate table. The admin who, sqm command can monitor queue activity, and the admin who, dsi command can show you whether the DSI thread is running.

Refer to “admin who” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for information about executing admin who and interpreting its results.

Refer to the Replication Server Troubleshooting Guide for comprehensive troubleshooting information that details the status of a subscription and suggested actions.

Before You Create SubscriptionsBefore creating subscriptions, verify that the replication system is ready. Review each of the steps in this section that follow to ensure that you meet all requirements.

1 Verify that all components in the replication system are working. See “Verifying a Replication System” on page 362 for details.

2 Make sure the following database objects and permissions exist:

• One or more replication definitions exist for the primary table.

• The primary table is marked as replicated with sp_setreptable or sp_reptostandby for warm standby applications.

• A table corresponding to the replication definition exists in the replicate database. Its columns must match those specified for the replicate database in the replication definition. Its datatypes must match the corresponding primary columns.


325

This table must also be visible to the user creating the subscription and the user maintaining it. If an owner name is included in the replication definition, the table must be visible to all database users. If an owner name is not included in the replication definition, the easiest way to make the table accessible is to have the Database Owner create it.

• The replicate database maintenance user must have:

select, insert, update, and delete permissions on the replicate table, and execute permission for functions used in replication.

If the subscription for the table includes the subscribe to truncate table clause, the maintenance user must have replication_role, sa_role, or alias the Database Owner.

3 Make sure that you meet recommended guidelines for the character sets and sort orders used throughout your replication system. These play an important role in processing subscriptions, and they must be consistent everywhere for subscriptions to be valid. Refer to the Replication Server Design Guide for guidelines.

4 Choose one of the subscription materialization methods described in “Subscription Materialization Methods” on page 310, and verify the following requirements for your chosen method:

• For nonatomic materialization, you must enable autocorrection for the replicate table. See “Using autocorrection” on page 314 for more information. Also refer to “set autocorrection” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for details.

If the replicate minimal columns feature is set for the replication definition, you cannot create new subscriptions using nonatomic materialization.

• For atomic and nonatomic materialization:

A default function-string class or a function-string class inherited from a default function-string class generates default function strings for the rs_select_with_lock or rs_select functions. If you use other function-string classes, you must create function strings for the rs_select_with_lock or rs_select functions, with an input template that matches the subscription’s where clause.

See “Function-String Classes” on page 380 and “Using Input Templates” on page 395 for details.

Using Subscription Commands

326

5 When you create subscriptions, use the login name of a regular user. Do not create subscriptions as the maintenance user.

Make sure the user creating the subscription has the following login names and permissions:

• Same login name and password at the replicate Replication Server, the primary Replication Server, and the primary data server. If you are using bulk materialization or the no-materialization method, you are not required to have a login name for the primary data server.

• select permission on the primary table. This does not apply if you are using bulk materialization or no materialization.

• execute permission on the rs_marker stored procedure in the primary database or no materialization.

• create object or sa permission in the replicate Replication Server.

• primary subscribe, create object, or sa permission in the primary Replication Server.

Using Subscription CommandsYou can use RCL commands or Sybase Central to:

• Create subscriptions for atomic and nonatomic materialization and for the no-materialization method.

• Define, activate, and validate subscriptions for bulk materialization.

• Check the status of subscriptions during the materialization process.

• Drop subscriptions to initiate the dematerialization process.

• Enable replication of the truncate table command when you create or define a subscription.

You can use a where clause to control which table rows or function invocations to replicate. The where clause can specify only the searchable columns or searchable parameters specified in the table or function replication definition. If you do not provide a where clause, all the rows of the replication definition’s columns, or all the function invocations, are replicated. See “Using the where Clause” on page 328 for more information.


327

If you are using Adaptive Server Enterprise version 11.5 or later, you can include the subscribe to truncate table keywords to reproduce execution of the truncate table command at the destination database. See “Enabling Replication of truncate table” on page 329 for more information.

Table 10-3 lists the Replication Server commands for working with subscriptions. Also see Table 8-1 on page 220 and Table 9-1 on page 297.

Table 10-3: Commands for managing subscriptions

Command Task

create subscription

Creates a subscription that transfers the initial version of the replicated data using either:

• Atomic materialization, which copies the initial version of the data for a subscription as a single transaction, or

• Nonatomic materialization, which copies the data in a series of transactions. Users at the replicate site can see some of the data before it all arrives. Replication Server does not create a materialization queue for the entire set of subscription data.

Use create subscription with the without materialization clause to activate a subscription for which the initial version of the replicated data already exists at the replicate database.You can also use create subscription to create subscriptions for table replication definitions.Use create subscription, with the without materialization clause, for function replication definitions.

define subscription

The first step in bulk materialization defines a subscription.You can use define subscription and the other bulk materialization commands to create subscriptions for either table or function replication definitions.You must transfer data manually, as necessary.Data replication begins after materialization is complete and a subscription is activated and validated. Use check subscription to verify subscription status. See “Using the check subscription Command” on page 335 for details. See Chapter 9, “Managing Replicated Functions”

activate subscription

Second step in bulk materialization. Activates a subscription at both primary and replicate Replication Servers. This causes the primary Replication Server to start sending changes to the subscription’s data to the replicate Replication Server. See “Using the activate subscription Command” on page 333 for details.

validate subscription

Third step in bulk materialization. Changes the subscription status at both the primary and replicate sites to VALID. See “Using the validate subscription Command” on page 334 for details.

check subscription

Verifies the status of a subscription at both the primary and replicate sites. Use this command with all types of subscription materialization. See “Using the check subscription Command” on page 335 for details.

drop subscription Removes a subscription from the replication system. For subscriptions to table replication definitions, optionally removes subscription rows from the replicate table in a process known as dematerialization. See “Using the drop subscription Command” on page 336 for details.


328

Using the where ClauseYou can include one where clause in a subscription. The where clause syntax is a subset of the Transact-SQL where clause. It is supported by the create subscription and define subscription commands for subscriptions to replication definitions. The supported syntax is the same for both commands and allows you to create very selective subscriptions. It is designed for efficient processing by the Subscription Resolution Engine in Replication Server.

Note You cannot evaluate a Java column in a subscription expression. Thus, you cannot include a column of type rawobject or rawobject in row in a subscription where clause.

For subscriptions to table replication definitions, the where clause syntax is:

where column_name{< | > | <= | >= | = | &} value[and column_name{< | > | <= | >= | = | &} value]...

For subscriptions to function replication definitions, the where clause syntax is:

where @param_name{< | > | <= | >= | = | &} value

[and @param_name{< | > | <= | >= | = | &} value]...

Refer to “Datatypes” in Chapter 2, “Topics,” in the Replication Server Reference Manual for entry formats for values for different datatypes.

Note The !=, !<, !>, and or operators are not supported. You can create multiple subscriptions instead of using the or operator. The & operator is supported only on rs_address columns. For details on using the rs_address datatype, see “Using the rs_address Datatype” on page 255 and “Bitmap Subscriptions” on page 344.

Each column name in a where clause must be listed in the searchable columns list of the table or function replication definition. The value for each column must have the same datatype as the column to which it is compared.

For example, for table replication definition publishers_rep, you would enter:

create subscription publishers_sub1for publishers_repwith replicate at SYDNEY_DS.pubs2where state = ’CA’


329

to specify that you want to subscribe to data where state = CA.

To subscribe to data in publishers, where state = CA or state = MA, you would need to create two subscriptions. In addition to the preceding command, you would enter:

create subscription publishers_sub2for publishers_repwith replicate at SYDNEY_DS.pubs2where state = ’MA’

Note When you use a where clause with a subscription for heterogeneous datatype columns subject to class- or column-level translations, you must make sure that you use the correct datatype in the comparison. See “Subscriptions for Columns with Heterogeneous Datatypes” on page 343

Enabling Replication of truncate tableIf you are using Adaptive Server Enterprise version 11.5 or later, you can enable replication of the truncate table command to particular destination database tables when you create or define a subscription.

To create or define a subscription that enables replication of truncate table, log in to Replication Server and enter:

create subscription subscriptionfor table_rep_def with replicate at data_server.database ...subscribe to truncate table

When truncate table executes at the destination database, Adaptive Server deallocates whole data pages. It does not delete rows one at a time.

Note Replication Server executes truncate table at the replicate database as the maintenance user. Among the permissions granted to maintenance user is replication_role. If you revoke maintenance user’s replication_role, you cannot replicate truncate table unless the maintenance user has been granted sa_role, the maintenance user owns the table, or the maintenance user is aliased as the Database Owner.


330

Warm standby applications can copy the execution of truncate table to standby databases without a subscription. Refer to “Replicating truncate table to Standby Databases” on page 454 for information about using this feature.

See define subscription and create subscription in Chapter 3, “Replication Server Commands” in the Replication Server Reference Manual for complete command syntax and usage guidelines.

Changing the Status of “subscribe to truncate table”

All subscriptions for a replicate table in a particular database must either support or not support replication of truncate table. You cannot create a subscription that enables replication of truncate table if all existing subscriptions for that table do not support replication of truncate table.

Use the sysadmin apply_truncate_table command to change the status of “subscribe to truncate table” for all subscriptions on a replicate table.

For example, to turn on replication of truncate table for all subscriptions to a replicate table, log in to the replicate Replication Server and execute this command at the isql prompt:

sysadmin apply_truncate_table data_server, database, {table_owner| ’’}, table_name’on’

where data_server is the name of the replicate data server, database is the name of the replicate database managed by the data server, table_owner is the owner of the replicate table, and table_name is the name of the replicate table.

If you specified a replicate table owner in the replication definition, you must also specify a table owner with the sysadmin apply_truncate_tablecommand. If you did not specify a replicate table owner in the replication definition, enter '' (two single-quote characters) or ““ (two double-quote characters) for the table owner name.

Refer to “sysadmin apply_truncate_table” in Chapter 3, “Replication Server Commands” in the Replication Server Reference Manual for more information about this command.

Using the create subscription CommandYou use the create subscription command to replicate data by subscribing to a replication definition. There are three methods for creating a subscription:

• Atomic

• Nonatomic

• No materialization


331

You can use a where clause to replicate only certain rows from the primary table, based on values for the searchable columns specified in the table replication definition. If you do not provide a where clause, all rows are replicated. See “Using the where Clause” on page 328 for more information.

If you are using Adaptive Server Enterprise version 11.5 or later, you can include the subscribe to truncate table keywords to reproduce execution of the truncate table command at the destination database. See “Enabling Replication of truncate table” on page 329 for more information.

Note create subscription automatically truncates text and image data larger than 32K.

Refer to “create subscription” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for details on using the create subscription command. See Chapter 8, “Managing Replicated Tables” for more information on creating table replication definitions.

Using create subscription for Atomic Materialization

To create a subscription with atomic materialization, execute the create subscription command at the Replication Server managing the database where the data is to be replicated. The syntax for the create subscription command, with atomic materialization, is:

create subscription subscriptionfor table_rep_def with replicate at data_server.database[where search_conditions]

[incrementally] [subscribe to truncate table]

where subscription is the name of the subscription to activate, table_rep_def is the name of the table replication definition you are subscribing to, and data_server.database identifies the replicate database.

The subscription name must be unique for the replication definition and replicate database.

Subscribing to function replication definitions requires you to use define subscription (the bulk materialization method) or create subscription with the without materialization clause (the no materialization method).

If you use the optional keyword incrementally, Replication Server initializes the subscription by sending 10-row batches of inserts.


332

If you do not use the keyword incrementally, Replication Server inserts all of the subscription rows at the replicate database in a single transaction. All of the rows are held in a stable queue at the replicate Replication Server at one time, and there must be enough partition space to accommodate them. Also, the transaction log for the replicate database must have enough space to log the transaction.

Using create subscription for Nonatomic Materialization

Use the create subscription command with the without holdlock clause to create a subscription with nonatomic materialization. The syntax is:

create subscription subscriptionfor table_rep_defwith replicate at data_server.database[where search_conditions]without holdlock[subscribe to truncate table]

where subscription is the name of the subscription to activate, table_rep_def is the name of the table replication definition you are subscribing to, and data_server.database identifies the replicate database.

Nonatomic materialization is always incremental.

Clients at the replicate site should be suspended or warned that the data in the replicate table is incomplete and possibly inconsistent until all the subscription data has materialized.

See “Monitoring Materialization and Dematerialization” on page 323 for information about monitoring the materialization process.

Using create subscription for No Materialization

To create a subscription that does not initialize the subscription data, execute create subscription with the without materialization clause at the Replication Server managing the replicate database. The syntax for create subscription for no materialization is:

create subscription subscriptionfor {table_rep_def | function_rep_def}with replicate at data_server.database[where search_conditions]without materialization[subscribe to truncate table]


333

where subscription is the name of the subscription to activate, table_rep_def is the name of the table replication definition the subscription is for, function_rep_def is the name of the function replication definition the subscription is for, and data_server.database identifies the replicate database.

The without materialization clause activates the subscription without first initializing the subscription data. Use create subscription with the without materialization clause when there is no activity at the primary database and the data already exists in the replicate database.

Using the define subscription CommandTo create a subscription with bulk materialization, execute the define subscription command at the Replication Server that is managing the database where the data is to be replicated. define subscription sets the subscription status to DEFINED.

The syntax for define subscription is:

define subscription subscriptionfor {table_rep_def | function_rep_def}with replicate at data_server.database[where search_conditions][subscribe to truncate table]


The subscription name must be unique for the replication definition and replicate database.

See Chapter 8, “Managing Replicated Tables” for more information on creating table replication definitions. See Chapter 9, “Managing Replicated Functions” for more information on creating function replication definitions. Also refer to “define subscription” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for details.

Using the activate subscription CommandUse the activate subscription command during bulk materialization to start the distribution of updates from the primary to the replicate database for a subscription. activate subscription sets the subscription status to ACTIVE.


334

Execute active subscription at the Replication Server where you created the subscription using the define subscription command. The syntax for activate subscription is:

activate subscription subscriptionfor {table_rep_def | function_rep_def}with replicate at data_server.database[with suspension [at active replicate only]]


Use the with suspension clause to suspend the DSI after the subscription status changes to ACTIVE. This prevents the replicate Replication Server from sending updates for the replicated table before the subscription data is loaded. After loading the data at the replicate site, execute resume connection to apply the updates.

If you do not use with suspension, you should prohibit updates to the primary table until the subscription is materialized.

If the database is part of a warm standby application, the with suspension clause suspends the DSI for the active and standby databases. This let you load the data into both databases before allowing updates to the active database. If you load the data into the active database with logging, use the with suspension at active replicate only clause so that the standby DSI remains active. In this case, subscription data is replicated from the active database. The DSI for the active database in a warm standby application is suspended. The clause does not suspend the DSI for the standby database.

Refer to “Using the validate subscription Command” on page 334 for more information about the with suspension and with suspension at active replicate only clauses. Refer to “activate subscription” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for detailed usage information for activate subscription.

Using the validate subscription CommandUse the validate subscription command to complete the bulk materialization process and set the subscription status to VALID.

Execute validate subscription at the Replication Server where you created the subscription. The syntax is:


335

validate subscription subscriptionfor {table_ref_def | function_rep_def}with replicate at data_server.database

where subscription is the name of the subscription to validate, table_rep_def is the name of the table replication definition the subscription is for, function_rep_def is the name of the function replication definition the subscription is for, and data_server.database identifies the replicate database.

Using the check subscription CommandThe check subscription command reports the status of a subscription at the Replication Server where you enter the command. The subscription status at the primary and replicate Replication Servers often differs while the subscription is being created, so you should enter check subscription at both sites. If the primary and replicate databases are managed by a single Replication Server, check subscription displays the status of the subscription for both the primary and replicate databases.

Viewing or changing table subscription properties

The syntax for the check subscription command is:

check subscription subscriptionfor {table_rep_def | function_rep_def}with replicate at data_server.database

where table_rep_def is the name of the table replication definition the subscription is for, function_rep_def is the name of the function replication definition the subscription is for, and data_server.database identifies the replicate database.

The message returned by the command contains subscription status information. If the subscription had an error, the message directs you to the log where you should look for specific error messages.

Refer to “check subscription” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for a list of the messages check subscription can return. Refer also to the Replication Server Troubleshooting Guide for more information about monitoring subscriptions.


336

Using the drop subscription CommandDropping a subscription causes Replication Server to stop sending changes from a primary database to a replicate database. You can use the drop subscription command to drop subscriptions for either table or function replication definitions.

Execute the drop subscription command at the replicate Replication Server. It requires create object permission at the replicate Replication Server and create object or primary subscribe permission at the primary Replication Server.

Here is the syntax:

drop subscription subscriptionfor {table_rep_def | function_rep_def }with replicate at data_server.database[without purge [with suspension [at active replicate only ]] |[incrementally] with purge]

If you choose the without purge dematerialization method, Replication Server does not delete subscription data from the replicate database.

If you choose the with purge dematerialization method, Replication Server logs in to the replicate database and selects data from it. If this data does not belong to any other subscriptions, the subscription data is deleted from the replicate database.

When you drop subscriptions to table replication definitions, you can purge subscription rows regardless of the materialization method you used when you created the subscription. Rows are removed only if they do not match another subscription.

You can use the check subscription command to view the progress of the drop subscription command. When the subscription status no longer exists at the primary and replicate Replication Servers, the command is complete.

Subscriptions to function replication definitions are always dropped without purging the replicate data associated with the function. You do not need to specify the without purge option.

When you are dropping subscriptions to table replication definitions, you have two basic methods to choose from. Because each method carries important implications, Replication Server requires that you explicitly choose one of these two methods:


337

• with purge – Replication Server removes, or dematerializes, the subscription’s rows from the replicate database, if they do not belong in other remaining subscriptions. The Replication Server logs in as the maintenance user to perform the select operation. Use the incrementally option to specify that dematerialization occurs in 10-row increments of deletes per transaction.

• without purge – the subscription’s rows remain at the replicate database. The with suspension option leaves the connection to the replicate database suspended when drop subscription has completed, so that you can manually remove the rows.

For warm standby applications, the option with suspension at active replicate only suspends the active replicate database but not the standby replicate database.

Warning! When removing rows manually, do not remove rows for remaining overlapping subscriptions that require those rows.

Example of Dropping Subscription With Purge

To drop a subscription with purge, use a command like this:

drop subscription publishers_subfor publishers_repwith replicate at SYDNEY_DS.pubs2with purge

Examples of Dropping Subscription Without Purge

To drop a subscription without purge, use a command like this:

drop subscription publishers_subfor publishers_repwith replicate at SYDNEY_DS.pubs2without purge

To drop a subscription without purge and also suspend the DSI for the replicate database so that you can manually delete the rows for the subscription, use a command like this:

drop subscription publishers_subfor publishers_repwith replicate at SYDNEY_DS.pubs2without purgewith suspension

Subscription Example

338

If you have a warm standby application for the replicate database, you may want to suspend the connection for the active database only, and leave the standby DSI up. This way, Replication Server will replicate your row deletion transactions from the active replicate database to the standby database. In this case, use a command like this:

drop subscription publishers_subfor publishers_repwith replicate at SYDNEY_DS.pubs2without purgewith suspension at active replicate only

Subscription ExampleThis section contains an example that shows you how to replicate a table from a primary database to a replicate database by creating an atomic subscription to the table replication definition. You can do this in Sybase Central or with RCL commands. The example shows you the steps and RCL commands needed to replicate transactions for a table named publishers between two Adaptive Servers.

Following is a description of the replication system and procedures for setting up replication for the table.

Description of Replication SystemPrimary Site • The Replication Server for the primary site is named TOKYO_RS.

• The primary version of the publishers table is in the pubs2 database of the Adaptive Server named TOKYO_DS. You have added a connection from TOKYO_RS to the pubs2 database using Sybase Central or rs_init and set up a RepAgent for the database.

• The system database for TOKYO_RS is named TOKYO_RSSD and is managed by the TOKYO_DS Adaptive Server.

• A route exists from TOKYO_RS to SYDNEY_RS.

Replicate Site • The Replication Server for the replicate site is named SYDNEY_RS.

• The replicate copy of the publishers table will be in the pubs2 database of the Adaptive Server named SYDNEY_DS. You have added a connection from SYDNEY_RS to the pubs2 database using Sybase Central or rs_init.


339

• The system database for SYDNEY_RS is named SYDNEY_RSSD and is managed by the SYDNEY_DS Adaptive Server.

Procedures for Replicating TablesPreparing to Replicate Tables

To check replication system components, use Sybase Central or isql to log in to the servers identified for the primary and replicate sites.

Preparing the Primary Table

In the TOKYO_DS Adaptive Server, log in to the pubs2 database and ensure that the publishers table exists:

isql -Usa -P -STOKYO_DS> use pubs2> go> sp_help publishers> go

Preparing Login Names for User Creating the Subscription

You will create the subscription using the “pubs2_user” login name. This user must exist in both Replication Servers.

In the TOKYO_DS Adaptive Server, create this login name:

isql -Usa -P -STOKYO_DS> sp_addlogin pubs2_user, pubs2_pw, pubs2> go

In the TOKYO_DS Adaptive Server, add the “pubs2_user” login name to the pubs2 database, and grant the user select permission on the publishers table:

> use pubs2> go> sp_adduser pubs2_user> go> grant select on publishers to pubs2_user> go

In the TOKYO_RS Replication Server, create the “pubs2_user” login name and grant primary subscribe permission to this login name:

isql -Usa -P -STOKYO_RS> create user pubs2_user> set password pubs2_pw> go> grant primary subscribe to pubs2_user> go

In the SYDNEY_RS Replication Server, create the “pubs2_user” login name and grant create object permission to this login name:

Subscription Example

340

isql -Usa -P -SSYDNEY_RS> create user pubs2_user> set password pubs2_pw> go> grant create object to pubs2_user> go

Creating the Replication Definition

In the TOKYO_RS Replication Server, create the replication definition publishers_rep for the publishers table:

isql -Ujohn -P -STOKYO_RS> create replication definition publishers_rep> with primary at TOKYO_DS.pubs2> with all tables named ’publishers’> (pub_id char(4), pub_name varchar(40),> city varchar(20), state char(2))> primary key (pub_id)> searchable columns (pub_id, pub_name)> replicate minimal columns> go

In this example, the user “john” creates the replication definition. This user requires create object permission in TOKYO_RS.

Marking the Primary Table for Replication

In the TOKYO_DS Adaptive Server, mark the publishers table for replication. To mark the table for replication with the sp_setreptable system procedure, you must be the Database Owner or System Administrator for the data server. Enter the following command:

> sp_setreptable publishers, ’true’> go

Verifying That the Table Exists in the Replicate Database

In the SYDNEY_DS Adaptive Server, log in to the pubs2 database, and verify that the publishers table exists:

isql -Usa -P -SSYDNEY_DS> use pubs2> go> sp_help publishers> go

When you add the replicate pubs2 database using Sybase Central or rs_init, the maintenance user is created and given replication_role. The maintenance user must have replication_role, sa_role, or alias the Database Owner to replicate truncate table.

In SYDNEY_DS, make sure the maintenance user has select, insert, delete, and update permissions on the publishers table:


341

> grant all on publishers to SYDNEY_DS_maint> go

Creating the Subscription

Log in to the SYDNEY_RS Replication Server using the “pubs2_user” login name and create the subscription publishers_sub for the replication definition publishers_rep:

isql -Upubs2_user -Ppubs2_pw -SSYDNEY_RS> create subscription publishers_sub> for publishers_rep> with replicate at SYDNEY_DS.pubs2> subscribe to truncate table> go

This subscription uses atomic materialization, the default. No where clause is included, so all rows will be replicated. Execution of the truncate table command will be reproduced at the destination database.

Monitoring Subscription Materialization

While still logged into SYDNEY_RS, use the check subscription command to monitor the status of the subscription:

> check subscription publishers_sub> for publishers_rep> with replicate at SYDNEY_DS.pubs2> go

Verifying Replication You can also check if replication is occurring as expected by verifying that a row you insert is copied to the replicate table.

In the TOKYO_DS Adaptive Server, insert a row into the publishers table:

isql -Usa -P -STOKYO_DS> use pubs2> go> insert publishers> values (’9950’, ’Who Donut’, ’Butler’, ’CA’)> go

In the SYDNEY_DS Adaptive Server, verify that the row you inserted was replicated into the replicate copy of the publishers table:

isql -Usa -P -SSYDNEY_DS> use pubs2> go> select * from publishers> go

Materializing text, image, and rawobject Data

342

Materializing text, image, and rawobject DataIn general, you can use any materialization method for subscriptions for tables with columns that use the text, image, or rawobject datatypes. If you use atomic or nonatomic materialization, the Replication Server managing the replicate database selects all of the subscription data into a subscription materialization queue.

If you want to materialize text, image, or rawobject data, you can use automatic materialization only if the size of your data row is less than 32K. Otherwise, you must use bulk materialization.

If you are materializing many large data rows, make sure that the Replication Server has sufficient queue space for the data before you create the subscription. For tables with a large volume of text, image, and rawobject data, you may need to add temporary partitions to the Replication Server to complete the materialization.

Nonatomic Materialization If you are using nonatomic subscription materialization and you have set the replicate_if_changed replication status for any text, image, or rawobject column, Replication Server displays a warning message in the error log file. You are cautioned that data may be inconsistent if applications modify the primary table during subscription materialization. Run the rs_subcmp program to reconcile the data in the replicate and primary tables.

Row Migration Under certain conditions, text, image, and rawobject column data may be missing in a replicate table as a result of row migration.

Row migration occurs in a subscription that has a where clause. Updating a column specified in the where clause can cause a row to become valid for, or migrate into, the subscription. When this happens, Replication Server executes an insert in the replicate table. To insert a complete row, each insert would require values for all columns, including text, image, and rawobject columns that did not change in the primary table.


343

If your application allows rows to migrate into a subscription and you have set any text, image, or rawobject columns to the replicate_if_changed replication status, Replication Server displays a warning message in the error log. The message states that a row has migrated into the subscription but that its text, image, or rawobject data is missing.

If a text, image, or rawobject column with the replicate_if_changed status was not changed in an update operation at the primary table, and the update causes the row to migrate into a subscription, the inserted row at the replicate table will be missing the text, image, or rawobject data. Run the rs_subcmp program to reconcile the data in the replicate and primary tables.

Subscriptions for Columns with Heterogeneous Datatypes

You create subscriptions for table replication definitions in the normal manner when class-level or column-level translations are defined and active. However, certain restrictions apply to use of the where clause.

• Subscriptions that specify columns subject to class- and column-level translations in the where clause cannot be dematerialized automatically. You must use the bulk or no-materialization method.

• Take care creating or defining subscriptions that specify class- or column-level translations in the where clause. Make sure that the value in the where clause comparison is in the declared datatype format. HDS translations take place after the subscription is presented.

For example, if searchable column starttime is declared as datetime but published as rs_db2_time, then the comparison value in the where clause must be described using datetime format.

create subscription db2_time_subfor table_rep_def XXXXX

with primary at AAAAAwith replicate at BBBBB

where starttime > ‘19000101 23:14:02’

and not “where starttime > ‘23:14:02,’” which is rs_db2_time format.

For a detailed discussion of heterogeneous datatype translations, see Chapter , “Managing Replicated Tables.”

Bitmap Subscriptions

344

Bitmap SubscriptionsBitmap subscriptions allow you to create subscriptions that replicate rows based on bitmap comparisons. When you create a replication definition for a table, specify the datatype of your bitmap columns as rs_address. This special datatype tells Replication Server to treat these int columns as bitmaps.

The create subscription and define subscription commands support a bitmap comparison operator (&) in the where clause for rs_address columns or parameters.

In the Adaptive Server table, you use an int column to hold a bitmap, since Adaptive Server allows bitwise operators on integer values. An int column has 32 bits. You can have multiple rs_address columns in a replication definition if your application requires more than 32 bits.

When you create a subscription, specify bitmap comparisons by comparing each rs_address column to a bitmask using the & operator. Each subscription can have one comparison per rs_address column.

Bitmap Subscription Example

For example, consider an application that uses an rs_address column named book_type to record the categories of books customers are interested in reading. The book categories are mapped into the lower 8 bits of a bitmap column, as shown in Table 10-4:

Table 10-4: Example bitmap comparison

If a bit is set, the customer has expressed interest in books of the corresponding category. The bits are numbered from least significant to most significant. For example, if the customer is interested in mystery, cooking, computer science, and psychology books, the least significant 8 bits are 01101010 and the 32-bit integer value is 106. The book_type column in the customer’s row contains the value 106.

Bit Number Book Category

0 Science fiction

1 Mystery

2 Business

3 Cooking

4 Popular computing

5 Computer science

6 Psychology

7 Reference


345

To create a subscription for customers who are interested in specified book categories, form a bitmask of the desired categories and compare it, using the & operator, to the book_type column in the where clause of the create subscription or define subscription command. The & operator performs a bitwise AND operation. If the result is non-zero, the row matches the subscription.

For rs_address columns only, the bitmap comparison operator & is supported in the where clause, as follows:

where rs_address_column1 & bitmask[and rs_address_column2 & bitmask][and other_search_conditions]

For example, to create a subscription for all customers who are interested in mystery or business books, the lower 8 bits of the mask are 00000110. Converted to a 32-bit integer value, the bitmask is 6. For atomic or nonatomic materialization, you can create the subscription as follows:

create subscription mystery_or_businessfor customerswith replicate at BRANCH_22.BOOK_DBwhere book_type & 6

You can use a similar approach in the define subscription command, used for bulk materialization. For subscriptions to function replication definitions, which require the no-materialization method or bulk materialization, specify parameter names instead of column names.

See “Using the where Clause” on page 328 for more information.

Obtaining Subscription Information

346

In addition to 32-bit integer values, you can also compare rs_address columns to 32-bit hexadecimal numbers in the where clause. If you use hexadecimal numbers, pad each number with zeros, as necessary, to create an 8-digit hexadecimal value.

Warning! Hexadecimal values are treated as binary strings by both Adaptive Server and Replication Server. Binary strings are converted to integers by copying bytes. The resulting bit pattern may represent different integer values on different platforms. For example, 0x0000100 represents 65,536 on platforms that consider byte 0 most significant, and represents 256 on platforms that consider byte 0 least significant. Because of these byte-ordering differences, bitmap subscriptions involving hexadecimal numbers might not work if a replication system involves different platforms. Be very cautious about comparing rs_address columns to hexadecimal numbers in the where clause of a subscription.

Replication Server does not replicate a row if the only changed columns are rs_address columns, unless the changed bits indicate that the row should be inserted or deleted at the replicate database. Because of this filtering, rs_address columns in replicate databases may not be identical to the corresponding columns at the primary database. This is an optimization for applications that use rs_address columns to specify the destination replicate databases.

Refer to “create subscription” and “create replication definition” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for more information about creating bitmap subscriptions.

Refer to the Adaptive Server Enterprise Reference Manual and the Open Client and Open Server Common Libraries Reference Manual for more information about conversions between datatypes.

Obtaining Subscription InformationOnce data is replicating, you may need to obtain information about the subscriptions or verify that data is replicating consistently. Replication Server provides stored procedures for obtaining information and a standalone utility for verifying consistency.

Viewing or changing table subscription properties


347

Displaying Subscription InformationTo display information about subscriptions at a Replication Server, you can use the rs_helpsub and rs_helprepdb stored procedures in the Replication Server’s RSSD.

Use rs_helpsub to display information about subscriptions at a Replication Server. The syntax is:

rs_helpsub [subscription_name[, replication_definition[, data_server, database]]]

Use the rs_helprepdb stored procedure to display information about databases with subscriptions for replication definitions in the current Replication Server. The syntax for the rs_helprepdb stored procedure is:

rs_helprepdb [, data_server, database]

Refer to Chapter 6, “Adaptive Server Stored Procedures,” in the Replication Server Reference Manual for parameter descriptions for each of these stored procedures.

Verifying Subscription ConsistencyAfter you create a subscription, Replication Server propagates transactions from the primary database to the replicate database. The replication system keeps the replicate copy of the table consistent with the primary copy.

The replicate data may become inconsistent with the primary version. For example, if you have not restricted update permissions on a replicate table to the maintenance user for the database, a client may update the replicate data directly, introducing inconsistencies.

Primary and replicate tables may be temporarily inconsistent because Replication Server takes some time to transfer updates from the primary table to the replicate table. However, as soon as the Replication Server applies the updates at the replicate database, inconsistency due to latency no longer exists.

There are three kinds of inconsistency that may occur between primary and replicate tables:

• Missing rows – rows in the primary table are missing from the replicate table.

• Inconsistent rows – rows in the primary table differ from the corresponding rows in the replicate table.

Obtaining Subscription Information

348

• Orphaned rows – rows in the replicate table do not exist in the primary table or do not match subscriptions for the replicate table.

You need to differentiate between temporary inconsistencies caused by delay and real inconsistencies caused by the incorrect use of the system or by system failures. The rs_subcmp program described in the following section helps you make this distinction. You can correct inconsistencies by dropping and recreating subscriptions or by using rs_subcmp.

Using rs_subcmp to Locate and Correct Inconsistencies

For Sybase databases, the standalone executable program rs_subcmp compares a replicate table to the primary version of the table, finding—and correcting if you so choose—missing, orphaned, and inconsistent rows. On UNIX systems, the program is called rs_subcmp. On PC systems, the program is called subcmp.

The rs_subcmp program is located in the bin subdirectory of the Sybase release directory. Refer to the Replication Server installation and configuration guides for your platform for more information.

The program works by logging in to the primary data server and the replicate data server, and selecting and comparing rows from both tables.

Because some differences between primary and replicate data can be attributed to latency, rs_subcmp first identifies inconsistencies, and then performs iterations a specified number of times. rs_subcmp waits for any updates to be replicated before removing the corrected rows from its list.

It is best to use rs_subcmp when latency is low to avoid the program having to perform several iterations through the data.

You can instruct rs_subcmp to display inconsistent rows on the standard output, correct them, or both display and correct them.

Creating a configuration file avoids the need for complex command lines, which are prone to errors. Here is an rs_subcmp configuration file that compares the sales table in the pubs2 database in the data servers TOKYO_DS and SYDNEY_DS:

PDS=TOKYO_DSRDS=SYDNEY_DSPDB=pubs2RDB=pubs2RTABLE=salesRSELECT=select * from sales \

order by stor_id, ord_num


349

RUSER=saKEY=stor_idKEY=ord_numRECONCILE=YRECONCILE_CHECK=YWAIT=15NUM_TRIES=5VISUAL=Y

The PTABLE, PSELECT, and PUSER parameters, which are used for the primary database, are not shown in this example. Their values are the same as those of corresponding parameters in the replicate databases, so they need not be included in the configuration file.

The RSELECT line and the PSELECT line (if used) must be entered on one line. To continue a line onto the next line (row), precede each newline character with a backslash as, for example:

RSELECT=select * from sales \order by stor_id, ord_num

Note Due to update filtering, columns of rs_address datatype may not be identical between the primary and replicate databases. Do not select rs_address columns using RSELECT or PSELECT parameters.

When you execute rs_subcmp, you can override values in the configuration file with command line options. For example, rather than changing the name of the TOKYO_DS data server to TOKYO_DS2 in the configuration file, you can specify it on the command line, using the -S flag, as the following example illustrates:

rs_subcmp -f sales_cmp -S TOKYO_DS2 > sales_badrows

In this example, the -f option specifies a configuration file name, sales_cmp. If the VISUAL parameter is set to “Y” in the configuration file (equivalent to the -V command line option), a list of the inconsistent rows is generated. In this example, the output is redirected to a file.

The rs_subcmp program is intended to reconcile Sybase databases only.

The rs_subcmp program has a large number of options, which you can specify on the command line or in a configuration file. Refer to “rs_subcmp” in Chapter 7, “Programs,” in the Replication Server Reference Manual for a list of these configuration file parameters and command line options.

Using Publication Subscriptions

350

Using Publication SubscriptionsWith publication subscriptions, you create subscriptions for a group of replication definitions using a single command. You collect replication definitions and their articles in a publication at the primary Replication Server. At the replicate Replication Server, you create a publication subscription against that publication.

When you create a publication subscription, Replication Server creates a subscription for each article in the publication.

Publication subscriptions and article subscriptions follow the rules and requirements for single subscriptions with one exception: They cannot contain where clauses. To specify a subset of rows that the replicate Replication Server receives, include where clauses in the article. Refer to “Specifying a where Clause with the create article Command” on page 276 for more information.

To use publications, the primary Replication Server must be version 11.5 or later. To use publication subscriptions, the replicate Replication Server and the route from the primary Replication Server and the replicate Replication Server must be version 11.5 or later.

The following restrictions apply:

• A valid publication must exist before you can create a publication subscription against it.

• The name of a publication subscription must be unique to the publication, to the destination data server, and to the destination database.

• You can include articles in one or more publications that reference different replication definitions for the same primary table. However, you cannot subscribe to more than one replication definition per primary table for each replicate table.

You can create and manage publication subscriptions either in Sybase Central or at the command line. These tasks are often simpler and require fewer steps when you use Sybase Central.

Refer to “Using Publications To Replicate Data in Sybase Central” on page 272 or “Using Publications to Replicate Data at the Command Line” on page 273 for a list of steps for creating publications and publication subscriptions.

Refer to “Using Publications” on page 271 for an overview of creating publications and publication subscriptions.


351

Commands for Creating and Managing Publication SubscriptionsTable 10-5 lists the RCL commands for working with publication subscriptions. All of these commands, except check subscription, require primary subscribe or create object permission at the source Replication Server and create object permission at the destination Replication Server. Anyone can execute check subscription.

See Table 8-3 on page 273 for a list of RCL commands for working with publications.

Table 10-5: Commands for managing publication subscriptions

Command Task

create subscription sub_name for publication pub_name

Creates a subscription for a publication and a subscription for each article in the publication. With create subscription, you can:

• Subscribe to table replication definitions using the atomic, nonatomic, or no-materialization method.

• Subscribe to function replication definitions using the no-materialization method.

See “Using the create subscription Command” on page 353.

define subscriptionsub_name for publicationpub_name

Defines a subscription for a publication and a subscription for each article in the publication. Use with activate subscription and validate subscription.

With define subscription, you can subscribe to articles with table replication definitions or function replication definitions using the bulk materialization method. See “Creating Publication Subscriptions with Bulk Materialization” on page 354.

activate subscriptionsub_name for publicationpub_name

Activates a subscription for a publication and a subscription for each article in the publication. Use with define subscription and validate subscription for bulk materialization. See “Creating Publication Subscriptions with Bulk Materialization” on page 354.

validate subscription sub_name for publication pub_name

Validates a subscription for a publication and a subscription for each article in the publication. Use with define subscription and activate subscription for bulk materialization. See “Creating Publication Subscriptions with Bulk Materialization” on page 354.

check subscription sub_name for publication pub_name

Displays the status of the publication subscription and all of its article subscriptions. See “Display Status Information” on page 358.

check subscriptionsub_name for articlearticle_name inpub_name

Displays the materialization status of an article subscription. See “Display Status Information” on page 358.

rs_helppubsub Displays information about publication subscriptions.

drop subscription sub_name for publication pub_name

Removes the publication subscription and all of its article subscription from the rs_subscriptions system table at the primary and replicate sites. See “Dropping Subscriptions for Publications and Articles” on page 356.


352

Enabling Replication of the truncate table Command

When you create, refresh, or define a publication subscription, you can enable replication of truncate table to the replicate table. If you do not, you must execute truncate table yourself at the replicate database.

For example, to create the publication subscription pubs2_sub and enable replication of truncate table, enter this command at the destination Replication Server:

create subscription pubs2_sub for publication pubs2_subwith primary at TOKYO_DS.pubs2with replicate at SYDNEY_DS.pubs2subscribe to truncate table

All subscriptions to the same replicate table must use truncate table consistently. If a replicate table has an subscription that doesn’t enable replication of truncate table and you add another subscription that does enable replication of truncate table, the publication subscription fails.

You do not need to include subscribe to truncate table when you activate and validate the publication subscription.

Refer to “Enabling Replication of truncate table” on page 329 for more information.

Creating Publication SubscriptionsOnce a publication has been validated, you can create subscriptions against it. When you create a publication subscription, Replication Server creates a subscription for each article in the publication.

Publication subscriptions and article subscriptions specify the publication, the primary and replicate databases, and the materialization method. They do not contain where clauses. To specify a subset of rows to be replicated, include where clauses in the article description. Refer to “Specifying a where Clause with the create article Command” on page 276.

drop subscription sub_name for article article_name in pub_name

Removes the article subscription from the publication subscription and from the rs_subscriptions system table at the primary and replicate sites. See “Dropping Subscriptions for Publications and Articles” on page 356.

Command Task


353

Using the create subscription Command

Use create subscription to create a publication subscription and an article subscription for each article in the publication. You can use create subscription to materialize source data at the destination database using the atomic, nonatomic, or no-materialization method.

Execute create subscription at the Replication Server that manages the destination database. Subscription information is stored in the rs_subscriptions system tables at the primary and replicate sites.

The following example creates a subscription named pubs2_sub for the publication pubs2_pub. It also creates a subscription named pubs2_sub for each article in pubs2_pub. The source database is pubs2 managed by the TOKYO_DS data server. The destination database is also named pubs2; it is managed by the SYDNEY_DS data server.

create subscription pubs2_sub for publicationwith primary at TOKYO_DS.pubs2with replicate at SYDNEY_DS.pubs2

See “create subscription” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for complete syntax and usage guidelines.

Specifying a Materialization Method

Specify materialization methods for publication subscriptions in the same way you specify materialization methods for regular subscriptions. When you use create subscription, you can specify atomic, nonatomic, or the no-materialization method. The default method is atomic materialization, using the select with holdlock operation.

Article subscriptions share the name of the parent subscription and generally, its materialization method. However, function replication definitions require the bulk or no-materialization method. If you use create subscription, and articles in the publication reference function replication definitions, Replication Server uses the no-materialization method for these article subscriptions—regardless of the materialization method specified in the publication subscription.

See “Subscription Materialization Methods” on page 310 for a description of the different materialization methods.


354

Refreshing Publication Subscriptions

When you add articles to an existing publication, you must add article subscriptions to the existing publication subscription to subscribe to the new articles. Use for new articles to refresh the subscription. This clause instructs Replication Server to check the subscription against the publication and then to create subscriptions for any unsubscribed articles.

For example, to refresh the publication subscription pubs2_sub, enter this command at the destination Replication Server:

create subscription sub for publication pubwith primary at TOKYO_DS.pubs2with replicate at SYDNEY_DS.pubs2for new articles

Use check subscription to find out whether a subscription exists for each article in a publication. See “Display Status Information” on page 358 for more information about check subscription.

Creating Publication Subscriptions with Bulk Materialization

Bulk materialization allows you to load subscription data from media such as magnetic tape. Use this method if the amount of data to be transferred is too large to copy through the network. You can also use this method to create subscriptions for function replication definitions.

When you create publication subscriptions with bulk materialization, you must use define subscription, activate subscription, and validate subscription. You use these bulk materialization commands to create publication subscriptions in the same way you create single subscriptions. You cannot include where clauses in publication subscriptions.

Refer to “Specifying a where Clause with the create article Command” on page 276 for information about adding where clauses to articles.

Using the define subscription Command

Use define subscription to create a publication subscription and a subscription for each article in the publication. define subscription always creates a subscription using bulk materialization.

Execute define subscription at the Replication Server that manages the destination database. Subscription information is stored in the rs_subscriptions system tables at the source and destination sites.

All subscriptions in the publication subscription are created at the same time.


355

The following example creates a subscription named pubs2_sub for the publication pubs2_pub.

define subscription pubs2_sub for publication pubs2_pubwith primary at TOKYO_DS.pubs2with replicate at SYDNEY_DS.pubs2

When you define a publication subscription with bulk materialization, you can enable replication of truncate table to the destination table. See “Enabling Replication of the truncate table Command” on page 352for more information.

See “define subscription” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for complete syntax and usage guidelines.

Using the activate subscription Command

Use activate subscription to activate a publication subscription and its subscription subset. Execute activate subscription at the Replication Server that manages the destination database.

Before you execute activate subscription, you must execute define subscription, and the publication subscription status must be DEFINED. Refer to “Display Status Information” on page 358 for information about displaying subscription status.

All subscriptions in the publication subscription are activated at the same time.

The following example activates every subscription in the publication subscription pubs2_sub.

activate subscription sub for publication pubwith primary at TOKYO_DS.pubs2with replicate at SYDNEY_DS.pubs2

See “activate subscription” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for complete syntax and usage guidelines.

Using the validate subscription Command

Use validate subscription to set the subscription status to VALID for the publication subscription, and its subscription subset. Execute validate subscription at the Replication Server that manages the replicate database.


356

Before you execute validate subscription, you must execute activate subscription and the publication subscription status must be ACTIVE. Refer to “Display Status Information” on page 358 for information about displaying subscription status.

All subscriptions in the publication subscription are validated at the same time.

The following example validates every subscription in the publication subscription pubs2_sub.

validate subscription sub for publication pubwith primary at TOKYO_DS.pubs2with replicate at SYDNEY_DS.pubs2

See “validate subscription” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for complete syntax and usage guidelines.

Refreshing Publication Subscriptions Using Bulk Materialization

When you refresh a publication subscription using bulk materialization, use the for new articles clause when you define the publication subscription. You do not need to repeat the clause when you activate and validate the subscription.

The following example refreshes the publication subscription pubs2_sub.

define subscription pubs2_sub for publication pubs2_pubwith primary at TOKYO_DS.pubs2with replicate at SYDNEY_DS.pubs2for new articles

See “define subscription” in the Replication Server Reference Manual for syntax and usage guidelines.

To check whether a subscription exists for each article in a publication, execute check subscription at the primary or replicate Replication Server. See “Display Status Information” on page 358 for more information about check subscription.

Dropping Subscriptions for Publications and ArticlesUse drop subscription to drop a publication subscription and all of its article subscriptions, or to drop a single article subscription.


357

drop subscription removes information about the publication subscription and its article subscriptions from system tables at the source and destination servers. It does not remove publication information from the destination server. Thus, you can create another subscription against the publication, and Replication Server only needs to reload primary site information if it has been changed.

Include the without purge clause to retain existing rows replicated by the subscription to the destination database. The subscriptions are dropped all at once.

This example drops a subscription named pubs2_sub for the publication pubs2_pub using without purge.

drop subscription pubs2_sub for publication pubs2_pubwith primary at TOKYO_DS.pubs2with replicate at SYDNEY_DS.pubs2without purge

Include the with purge clause to delete existing rows replicated by the subscription to the destination database. The subscriptions are dropped one at a time.

This example uses with purge:

drop subscription pubs2_sub for publication pubs2_pubwith primary at TOKYO_DS.pubs2with replicate at SYDNEY_DS.pubs2with purge

The following example deletes the article pubs2_art, without removing rows replicated by the subscription.

drop subscription sub for article pubs2_artwith primary at TOKYO_DS.pubs2with replicate at SYDNEY_DS.pubs2without purge

See “drop subscription” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for complete syntax and usage guidelines.


358

Viewing Publication Subscription InformationYou can view information about publication and article subscriptions with the check subscription command or the rs_helppubsub stored procedure.

Viewing or changing publication subscription properties

Display Status Information

Use check subscription at the primary Replication Server or the replicate Replication Server to check the status of a publication subscription and its article subscriptions or to check the status of an article subscription.

check subscription returns a status (such as VALID, MATERIALIZING, or ACTIVE) along with a descriptive message. See “check subscription” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for syntax and usage guidelines and a list of status messages.

• This example displays the subscription status of the publication subscription pubs2_sub.

check subscription pubs2_sub for publication pubs2_pubwith primary at TOKYO_DS.pubs2with replicate at SYDNEY_DS.pubs2

If the publication subscription is valid, Replication Server also checks whether the subscription is current. When you alter a publication after the subscription is created, the publication subscription is out of sync with the publication. To create subscriptions for new articles and make the subscription current, refresh the subscription using create subscription or define subscription.

• This example displays the subscription status of the article pubs2_art in the subscription pubs2_sub.

check subscription sub for article pubs2_artin pubs2_pubwith primary at TOKYO_DS.pubs2with replicate at SYDNEY_DS.pubs2List

Publication and Article Subscription Information

To display information about a publication subscription and article subscriptions, use the rs_helppubsub stored procedure at either the primary or replicate Replication Server’s RSSD.

Here are some examples of using rs_helppubsub:


359

• To list all publication subscriptions at a site, enter:

rs_helppubsub

For each publication subscription known to the site, the display includes the names of the subscription and its associated publication, the names of the primary and replicate databases and data servers, status information, and the date of the latest change to the publication subscription.

• To display information about a particular publication subscription, enter:

rs_helppubsub subscription_name

The output displays the information described in the above example for all publication subscriptions named subscription_name.

• To display information about a particular publication subscription and its article subscriptions, enter:

rs_helppub subscription_name, publication_name, primary_dataserver, primary_db, replicate_dataserver, replicate_db

The output displays the information described in the above examples for all publication subscriptions named subscription_name. For each article subscription, the output displays subscription and article name, status information for the primary and replicate Replication Servers, replication definition name, autocorrection status, and the date of the latest change to the article subscription.

See “rs_helppubsub” in the Replication Server Reference Manual for complete syntax and usage guidelines and sample output.


360

361

C H A P T E R 1 1 Verifying and Monitoring Replication Server

This chapter describes checking error logs, verifying that the components of a replication system are running, and monitoring the status of system components and processes.

The replication system includes data servers and Replication Servers. It may also include replication agents for heterogeneous data servers or Log Transfer Managers for SQL Server. The replication agent for Adaptive Server is RepAgent, an Adaptive Server thread.

Note If you are using a replication agent for a heterogeneous data server, refer to replication agent documentation for your data server for information about troubleshooting your replication agent.

In a fully operational replication system, all data servers, Replication Servers, replication agents, and their internal threads and other components are running. This chapter tells you how to perform basic troubleshooting tasks on the replication system, including:

1 Checking error logs for status and error messages.

2 Logging in to system servers and checking that all threads are functioning, routes and connections are in place, and the interfaces file information is correct.

This chapter also describes how you can monitor Replication Server and its threads and check partition threshold levels.

Refer to the Replication Server Troubleshooting Guide for detailed information about monitoring and troubleshooting Replication Server.

Checking Replication System Log Files for Errors

362

Checking Replication System Log Files for ErrorsThe Replication Server records status and error messages, including internal errors, in the Replication Server error log file. Use the admin log_name command to display the path to the current log file. The default name for the log file is repserver.log. You can change the default name by executing repserver with the -E option and specifying the new log file name.

You can check the repserver.log files for any error messages by using Sybase Central. You can also invoke shell scripts based on errors reported in those logs in Sybase Central.

See “Viewing the Error Log” in Replication Server’s online help for instructions on checking the information in the error logs in Sybase Central.

Internal errors are those where the only action available to Replication Server is to dump the stack and exit. For diagnostic purposes, Replication Server prints a trace of its execution stack in the log and leaves a record of its state when the error occurred.

Messages continue to accumulate in the error log files until you remove them. For this reason, you may choose to truncate the log files when the Replication Server is shut down. You can also close the Replication Server log file and begin a new log file by using the admin set_log_name command.

The Replication Server log file contains messages generated during the execution of asynchronous commands, such as create subscription and create route, which continue processing after the commands complete. While you are executing asynchronous commands, pay special attention to the log files for the Replication Servers affected by the procedure.

If a log file is unavailable, important error information is written to the standard error output file, which you can display on a terminal or redirect to a file.

Verifying a Replication SystemYou need to verify that the entire replication system is working when you are about to create replication definitions or subscriptions or when you are performing diagnostics on your system. If you encounter errors, verifying your system allows you to rule out the possibility that threads or components are not running or that routes and connections are not properly set up.

CHAPTER 11 Verifying and Monitoring Replication Server

363

See “Viewing the status of a server or folder” and the other topics in “Using the Topology View” in Replication Server’s online help for information about verifying a replication system using Sybase Central.

To make sure that Replication Server threads are running, you can execute admin who_is_down, which displays only those threads that are not running. Alternatively, execute admin who to display information about all threads. If no threads are down, you can confirm that the replication system is working by checking the following:

1 Verify that replication system servers and replication agents are running and available.

At the primary site, log in to these servers:

• Data server with the primary database and its replication agent

If you are using Adaptive Server, execute sp_help_rep_agent at Adaptive Server to display status information for RepAgent thread.

• Replication Server managing the primary database

• RSSD (and its replication agent) for the primary Replication Server


At replicate sites, log in to these servers:

• Data servers with replicate databases and, if request functions are executed at these databases, their replication agents


• Replication Servers managing replicate databases

• RSSDs (and their replication agents) for replicate Replication Servers


2 Use the admin show_connections command at Replication Server to verify that these routes and connections are in place:

• Routes from the primary Replication Server to each replicate Replication Server

• Database connection between the primary Replication Server and the primary database

Monitoring Replication Server

364

• Route from a replicate Replication Server to the primary Replication Server, if the replicate Replication Server manages a replicate database in which request functions are executed

• Database connections between each replicate Replication Server and its replicate database

3 Verify the accuracy of entries in the interfaces file.

When creating subscriptions, be sure an entry for the primary data server exists in the interfaces file for the replicate Replication Server. (If you are using atomic or non-atomic materialization, the replicate Replication Server retrieves initial rows through a direct connection to the primary data server.)

4 Use the admin who command to verify that these Replication Server threads are running:

• Data Server Interface (DSI)

• Replication Server Interface (RSI)

• Distributor (DIST)

• Stable Queue Manager (SQM)

• Stable Queue Transaction interface (SQT)

• RepAgent User

For detailed information about monitoring Replication Server threads, refer to “Displaying Replication System Thread Status” on page 366.

Monitoring Replication ServerWhile the replication system is in operation, you may need to monitor its components and processes. This section describes how to:

• Monitor replication system servers

• Monitor DSI, RSI, and other thread status

• Use system information commands to obtain information about various aspects of the Replication Server.


365

Verifying Server StatusYou can verify the status of your servers with these methods:

• Use Sybase Central.

See “Viewing the status of a server or folder” in Replication Server’s online help for instructions on verifying the status of your servers using Sybase Central.

• Use isql to log in to each server. If the login succeeds, you know that the server is running.

• Create a script that logs in to and displays the status of each Adaptive Server and its RepAgent thread, other replication agent (if any), and Replication Server. Make sure all servers in the script are included in the interfaces file.

If a login fails, it may be caused by one of the following problems:

Problem: You typed an incorrect name, or the interfaces file you are using does not have an entry for the server.

DB-LIBRARY error: Server name not found in interface file.

Problem: The server is running, but you specified an incorrect login name or password.

DB-LIBRARY error: Login incorrect.

Problem: The server is not running.

Operating-system error: Invalid argument DB-LIBRARY error: Unable to connect: SQL Server is unavailable or does not exist.

Problem: The interfaces file cannot be found.

Operating-system error: No such file or directory DB-LIBRARY error: Could not open interface file.

Problem: The interfaces file exists, but you do not have permission to access it.

Operating-system error: Permission denied DB-LIBRARY error:

RSM

Monitoring Replication Server

366

Could not open interface file

Displaying Replication System Thread StatusYou can monitor general information on current Replication Server threads. Table 11-1 describes threads that apply to database connections and routes and the admin who command you use to monitor them.

See “Viewing thread status” in Replication Server’s online help for Sybase Central instructions on monitoring threads.

Table 11-1: Monitoring Replication Server threads

Refer to “admin who” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for details on the admin who command. Refer to the Replication Server Troubleshooting Guide to interpret the command output for troubleshooting purposes.

Using System Information Commands

In addition to admin who, Replication Server offers other admin commands to assist you in monitoring Replication Server.

These commands are listed in Table 11-2. Refer to Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for details on each command.

Replication Server thread Command

Distributor (DIST) – uses SQT and SQM to read transactions from the inbound queue.

admin who, dist

Data Server Interface (DSI) – submits transactions to data server. admin who, dsi

REP AGENT or LTM USER – verifies that transactions from the data server are valid and writes them to the inbound queue.

admin who

Note Use sp_who or sp_help_rep_agent to display status of RepAgent thread at Adaptive Server.

Replication Server Interface (RSI) – logs in to each destination Replication Server and transfers commands from the stable queue to the destination server.

admin who, rsi

Stable Queue Manager (SQM) – manages Replication Server stable queues.admin who, sqm

Stable Queue Transaction interface (SQT) – reads transactions in a queue and passes them to the SQT reader.

admin who, sqt


367

In Sybase Central, you can find additional information about monitoring your replication system in “Monitoring a Replication System” in Replication Server’s online help.

Table 11-2: Overview of system information commands

Command Description

admin disk_space Displays utilization of disk partitions accessed by the Replication Server.

admin echo Determines if the local Replication Server is running.

admin get_generation Retrieves the generation number for a primary database, used in recovery operations.

admin health Displays the overall status of the Replication Server.

admin log_name Displays the path to the current log file.

admin logical_status Displays the status of logical database connections, used in warm standby applications.

admin pid Displays the process ID of the Replication Server.

admin quiesce_check Determines if the queues in the Replication Server have been quiesced.

admin quiesce_force_rsi Determines whether a Replication Server is quiescent. Also forces Replication Server to deliver outbound messages.

admin rssd_name Displays the names of the data server and database for the RSSD.

admin security_property Displays security features of network-based security systems supported by Replication Server.

admin security_setting Displays network-based security settings of a particular target server.

admin set_log_name Closes the existing Replication Server log file and opens a new log file.

admin show_connections Displays information about all connections and routes to and from Replication Server.

admin show_function_classes Displays the names of existing function-string classes and their parent classes and indicates the number of levels of inheritance.

admin show_route_version Displays the version number of routes that originate at Replication Server and routes that terminate at Replication Server.

admin show_site_version Displays the site version of Replication Server.

admin sqm_readers Displays information about threads that are reading the inbound queue.

admin statistics, md Displays statistics about message delivery.

admin statistics, mem Displays statistics about memory utilization.

admin statistics, reset Resets the message delivery statistics.

admin version Displays which version of the Replication Server you are running, representing the software version.

admin who Displays information about all threads in the Replication Server.

admin who, dsi Displays information about DSI threads that connect to a data server.

admin who, rsi Displays information about RSI threads that connect to other Replication Servers.

Setting and Using Threshold Levels

368

Setting and Using Threshold LevelsStable queue partitions fill up when a Replication Server is receiving more messages than it is sending. For example, if a network is down between a primary site and a replicate site, the Replication Server at the primary site queues up the undeliverable messages. When the network returns to service, the messages can be delivered, and then deleted from the primary Replication Server’s partitions.

If a partition becomes completely full, senders cannot deliver their messages to the Replication Server, and messages begin to back up in the partitions at previous sites and in the transaction logs for primary databases.

Warning! If the situation is not corrected, RepAgent is unable to update the secondary truncation point in the database log, and the transaction log fills. Clients are then unable to execute transactions at the primary database.

You can configure Replication Server to warn when partitions become too full by setting three rows in the rs_config system table: sqm_warning_thr1, sqm_warning_thr2, and sqm_warning_thr_ind. These parameters are described in Figure 14-2 on page 483.

See “Managing partition events” in Replication Server’s online help.

Monitoring Partition PercentagesReplication Server operates on 1MB partition segments. Whenever it allocates or deallocates a partition segment, it calculates these statistics:

• Percentage of total partition segments in use

• Percentage of total partition segments in use by the affected stable queue

admin who, sqm Displays information about all queues managed by the SQM.

admin who, sqt Displays information about all queues managed by the SQT.

admin who_is_down Displays the same information as admin who, but only about threads that are down.

admin who_is_up Displays the same information as admin who, but only about threads that are running.

Command Description


369

If the percentage of partition segments in use rises above the percentage specified by sqm_warning_thr1 or sqm_warning_thr2, a message like the following is written to the log file:

WARNING: Stable Storage Use is Above <threshold> percent

If you see this message often, you may need to add partitions to the Replication Server or correct a recurring failure that causes the queues to fill.

When the first percentage drops below the percentage specified by sqm_warning_thr1 or sqm_warning_thr2, a message like the following is written to the log file to note that the condition that caused the original warning no longer exists:

WARNING CANCEL: Stable Storage Use is Below <threshold> percent

The percentage of total partition segments in use by the affected stable queue triggers the following warning message when the percentage of the total space used by a single stable queue exceeds the percentage specified by sqm_warning_thr_ind:

WARNING: Stable Storage Use by <queue name> is Above <threshold> percent

This warning alerts you to problems that cause a particular stable queue to fill until it is using a disproportionate share of the total partition space. For example, if a route is suspended for a length of time, its stable queue may fill until it occupies enough partition space to trigger a warning.

When the percentage of the total partition space used by a stable queue drops below the sqm_warning_thr_ind percentage, Replication Server writes a cancel message like the following to the log file:

WARNING CANCEL: Stable Storage Use by <queue name> is Below <threshold> percent.

Setting and Using Threshold Levels

370

371

C H A P T E R 1 2 Customizing Database Operations

This chapter explains how you can create and alter functions, function strings, and function-string classes to allow replication definitions to work with database servers other than Adaptive Server.

OverviewReplication Server translates commands from the primary database into Replication Server functions that represent data server operations such as insert, delete, select, begin transaction, and so on. It distributes these functions to remote Replication Servers in the system, where they execute those operations in remote databases.

The primary Replication Server distributes functions in the same format regardless of the type of data server that actually updates the replicated data. Functions are not database-specific. They include all the data needed to perform the operation, but they do not specify the syntax needed to complete the operation at the destination data server.

The remote Replication Server converts functions to commands specific to the destination data servers where they are executed. A function string contains the database-specific instructions for executing a function. The replicate Replication Server managing a database uses an appropriate function string to map the function to a set of instructions for the data server. For example, the function string for the rs_insert function provides the actual language to be applied in a replicate database.

This separation between functions and data server commands lets you maintain replicated data among heterogeneous data servers. Replication Server allows you to customize function strings, specifying how Replication Server functions map to SQL commands. You can create function strings if you require customized data server operations. You customize replicated data applications by changing the way operations are performed at the destination database.

Working with Functions, Function Strings, and Classes

372

Function strings are grouped into function-string classes, so you can group mappings of functions to commands according to data server. Replication Server provides function-string classes for Adaptive Server Enterprise, Oracle, Informix, Microsoft SQL Server, Adaptive Server Anywhere, IMS, VSAM, and DB2 databases. You can create new derived function-string classes in which you customize certain function strings and inherit all others from these or other classes. You can also create entirely new classes in which you create all new function strings.

You may also need to create function strings for replicated functions, which allow you to execute stored procedures on remote databases. You must create a function string for any replicated function for which Replication Server does not automatically generate a function string in the function-string class used by the destination database.

Working with Functions, Function Strings, and ClassesYou can work with functions and function strings to customize database operations in any of these ways:

• Create a new function-string class for use with a specific type of database, and customize some or all of the function strings. See “Managing Function-String Classes” on page 385 for detailed information.

• Alter function strings for the system-provided function-string class, rs_sqlserver_function_class. See “Managing Function Strings” on page 391 for detailed information.

• Create a function-string class that inherits, either directly or indirectly, function strings from the system-provided function-string class rs_default_function_class.

• Use the system-provided function-string classes for non-Sybase data servers: rs_db2_function_class, rs_informix_function_class, rs_mss_function_class, or rs_oracle_function_class. See “Translating Datatypes Using HDS” on page 281 for detailed information on datatype translations using the heterogeneous datatype support (HDS) feature.

This section provides an overview of functions, function strings, and function-string classes. The following sections include a summary of the system functions, procedures, and guidelines for managing function strings and function-string classes. They also summarize commands for displaying information about the function strings and classes in the replication system.

CHAPTER 12 Customizing Database Operations

373

You can work with functions, function strings, and classes using Sybase Central or RCL commands. This chapter describes procedures and RCL commands that you enter at the command line using isql. For information about using Sybase Central, see Replication Server’s online help.

Refer to Chapter 4, “Replication Server System Functions,” in the Replication Server Reference Manual for more information about the system functions.

FunctionsReplication Server uses two major types of functions:

• System functions

• User-defined functions

You can create custom function strings for either type of function, depending on your needs.

See “Managing Function Strings” on page 391 for more information about when to customize function strings.

System Functions

System functions represent data server operations whose function strings are supplied by Replication Server or are available when you install a new database on the replication system. Unless your application requires it, you do not need to customize function strings for system functions. The system-provided class generates them for you.

System functions include:

• Functions that represent data-manipulation operations such as insert, update, delete, select, and select with holdlock.

These system functions have replication-definition scope. See “Function Scope” on page 374 for details.

• Functions that represent transaction-control directives. These functions include operations such as begin transaction and commit transaction.

These system functions have function-string-class scope. See “Function Scope” on page 374 for details.

See “Summary of System Functions” on page 375 for more information about each type of system function.


374

User-Defined Functions

User-defined functions allow you to use Replication Server to distribute replicated stored procedures between sites in the replication system. You must create function strings for user-defined functions unless you use a function-string class that directly or indirectly inherits function strings from rs_default_function_class. User-defined functions include:

• Functions that are used in replicating stored procedures associated with function replication definitions. Replication Server automatically creates a user-defined function of this type when you create a function-replication definition.

See Chapter 9, “Managing Replicated Functions” for details about function-replication definitions and replicated stored procedures.

• Functions that are used in replicating stored procedures associated with table-replication definitions. You create and maintain user-defined functions of this type yourself.

See Appendix A, “Asynchronous Stored Procedures” for details about replicated stored procedures that use table-replication definitions.

User-defined functions have replication-definition scope. See “Function Scope” on page 374 for details.

Any function string that you create for a user-defined function should be created at the primary Replication Server, where the replication definition was created. If you are using function replication definitions, see also “Implementing an Applied Function” on page 299 or “Implementing a Request Function” on page 302.

Function Scope

The scope of a function defines the object to which the function applies: either to a replication definition or to a function-string class. Knowing a function’s scope is important for determining where to customize a function string: at the primary or replicate Replication Server. Functions can have one of two scopes:

• Function-string-class scope

• Replication-definition scope


375

Function-String-Class Scope

A function with function-string-class scope is defined once for the class. Functions with function-string-class scope include system functions that represent transaction-control directives (such as rs_begin, rs_commit, or rs_marker) and do not perform data manipulation. Function strings for user-defined functions do not have class scope.

Function strings for functions with function-string-class scope must be customized at the primary Replication Server for the function-string class. See Table 12-1 on page 376 for a list of these functions. See “Primary Site for a Function-String Class” on page 388 for information on assigning a primary site.

Replication-Definition Scope

A function with replication-definition scope is defined once for a specific table-replication definition or function-replication definition—although the function may have multiple function strings.

Functions with replication-definition scope include:

• System functions that perform data-manipulation operations (such as rs_insert, rs_delete, rs_update, rs_select, rs_select_with_lock, and special functions used in replicating text and image data).

See Table 12-2 for a list of these functions.

• User-defined functions for table- or function-replication definitions.

System functions with replication-definition scope must be customized at the Replication Server where the replication definition was created. User-defined functions with replication-definition scope must be customized at the Replication Server where the replication definition was created.

Summary of System FunctionsThe following tables provide a summary of the available system functions. Refer to Chapter 4, “Replication Server System Functions,” in the Replication Server Reference Manual for complete documentation of all of the system functions.

System Functions with Function-String-Class Scope

Table 12-1 lists the system functions with function-string-class scope. Replication Server provides default generated function strings for each system-provided class when you install the replication system.


376

Some functions are required for every Replication Server application, while other functions only apply in particular cases, such as warm standby applications, parallel DSI threads, or coordinated dumps.

If you use a function-string class other than the default (rs_sqlserver_function_class), and you are not using function-string inheritance, you must create a function-string for each system function you use that has function-string class scope.

Customize function strings for system functions with class scope at the Replication Server that is the primary site for the function-string class. See “Changing the Primary Site for a Function-String Class” on page 389 for more information about assigning or changing the primary Replication Server for a function-string class.

Table 12-1: System functions with function-string-class scope

Function Name Description

rs_begin Begin a transaction.

rs_check_repl Check if a table is marked for replication.

rs_commit Commit a transaction.

rs_dumpdb Initiate a coordinated database dump.

rs_dumptran Initiate a coordinated transaction dump.

rs_get_charset Return the character set used by a data server.

Sample function strings for replication into DB2 databases via Net-Gateway are installed in the Sybase release directory in install/rs_db2_setup.sample (UNIX systems) and install\rs_2_db2.txt (NT systems).

rs_get_lastcommit Retrieve rows from the rs_lastcommit system table.

rs_get_sortorder Return the sort order used by a data server.

Sample function strings for replication into DB2 databases via Net-Gateway are installed in the Sybase release directory in install/rs_db2_setup.sample (UNIX systems) and install\rs_2_db2.txt (NT systems).

rs_get_thread_seq Return the current sequence number for the specified entry in the rs_threads system table. This function is executed only when you are using parallel DSI.

rs_get_thread_seq_noholdlock Return the current sequence number for the specified entry in the rs_threads system table, using the noholdlock option. This function is executed only when you are using parallel DSI with isolation level 3 locking.

rs_initialize_threads Set the sequence of each entry in the rs_threads system table to 0. This function is executed only when you are using parallel DSI.

rs_marker Help coordinate subscription materialization. The function passes its first parameter to Replication Server as an independent command.

rs_raw_object_serialization Replicate Java columns as serialized data.

rs_repl_off Set replication off in Adaptive Server for a standby database connection.


377

System Functions with Replication-Definition Scope

Table 12-2 lists the system functions with replication-definition scope. Replication Server provides default function strings for each system-provided class when you create a replication definition.

Some functions are required for every Replication Server application, while other functions only apply in particular cases, such as replication of text and image datatypes, parallel DSI threads, or performing subscription materialization or dematerialization.

Customize function strings for a system functions with replication-definition scope at the Replication Server where the replication definition was created.

Table 12-2: System functions with replication definition scope

rs_rollback Roll back a transaction.

rs_set_isolation_level3 Turn on transaction isolation level 3 locking in Adaptive Server. This function is executed only when you are using parallel DSI with isolation level 3 locking.

rs_set_proxy Assume the permissions, login name, and server user ID of the user.

rs_triggers_reset Set triggers off in Adaptive Server for a standby database connection.

rs_trunc_reset Reset the secondary truncation point in warm standby databases. This function is executed only when you create a warm standby database or when you switch to a standby database.

rs_trunc_set Set the secondary truncation point in warm standby databases. This function is executed only when you create a warm standby database or when you switch to a standby database.

rs_update_threads Update the sequence number for the specified entry in the rs_threads table. This function is executed only when you are using parallel DSI.

rs_usedb Change the database context.



rs_datarow_for_writetext Provide an image of the data row associated with a text or image column updated with a Transact-SQL writetext command or with CT-Library or DB-Library functions.

rs_delete Delete a row in a table.

rs_get_textptr Retrieve the text pointer for a text, image, or rawobject column.

rs_insert Insert a row into a table.

rs_select Retrieve rows from a table for subscription materialization or dematerialization.

rs_select_with_lock Retrieve subscription materialization or dematerialization rows using a holdlock.

rs_textptr_init Allocate a text pointer for a text, image, or rawobject column.

rs_truncate Truncate a table.


378

Function StringsFunction strings contain instructions for executing a function in a database. These instructions may differ according to database. For example, a non-Sybase database may require different instructions and have different function strings than an Adaptive Server database.

Functions strings come in two formats: language and RPC. A language-format function string contains a command, such as a SQL statement, that the data server parses. An RPC-format function string contains a remote procedure call that executes a registered procedure in an Open Server gateway application or in an Adaptive Server database. Both function-string formats can contain variables that get replaced with data values. What format a function string uses is determined by the type of data server and how you want Replication Server to interact with it. See “Using Output Templates” on page 393 for more information.

Function strings are grouped into function-string classes. Each database connection must be assigned a function-string class according to the type of destination database. Replication Server provides function-string classes that contain default function strings. Replication Server generates default function strings for Adaptive Server, SQL Server, DB2, Informix, Microsoft SQL Server, and Oracle function-string classes.

When you set up a replication system or add databases to the system, you should anticipate your function-string requirements and decide how you will use function-string classes and whether you need to customize function strings. See “Function-String Classes” on page 380 for more information.

See “Managing Function Strings” on page 391 for more information about customizing function strings.

Input and Output Templates

Every function string uses an output template to instruct the destination database in executing the function for a specific data server.

rs_update Update a row in a table.

rs_writetext Alter text, image, or rawobject data.



379

Function strings for the rs_select and rs_select_with_lock functions use both input templates and output templates, which together perform subscription materialization and dematerialization.

You customize function strings by altering their input and output templates. You customize function strings for functions other than rs_select and rs_select_with_lock by altering only the output template. How you alter a function string depends on the function string’s format-language or RPC.

See “Function-String Input and Output Templates” on page 392 for more information about input and output templates.

Applications for Customized Function Strings

You can customize function strings to:

• Perform operations in any native database language (including those other than Transact-SQL) by altering function-string output templates to format the commands sent to a data server.

• Materialize and dematerialize multiple subscriptions for the same replication definition with a single function string.

• Perform the following tasks by altering output templates for existing system function strings:

• Record auditing information.

• Execute remote procedure calls (RPCs).

• Replicate data into multiple replicate tables in the same database.

• Replicate data into a replicate table with a different name, column names, or column order than the primary table.

If the replicate Replication Server is of version 11.5 or later, you can perform the same tasks more easily by creating a customized replication definition that specifies the relevant information about the replicate table. See “Creating Multiple Replication Definitions Per Table” on page 234 for more information.

Function-String Classes

380

System Functions with Multiple Function StringsFor the class-scope system functions, each function maps to a function string within the class. Each replication-definition-scope rs_insert, rs_delete, and rs_update system function maps to a function string within the class for each replication definition.

You can create multiple function-string instances for the same replication definition for other system functions with replication-definition scope—rs_select, rs_select_with_lock, rs_datarow_for_writetext, rs_get_textptr, rs_textptr_init, and rs_writetext. In such cases, you must give each instance of a function string a different name. System functions that can take multiple function strings include:

• rs_select and rs_select_with_lock functions – used in subscription materialization and dematerialization when multiple subscriptions exist for the same replication definition. You can give each instance of the function string any name that is unique for the replication definition. Each instance of the function string corresponds to a where clause used in creating subscriptions for the replication definition.

• rs_datarow_for_writetext, rs_get_textptr, rs_textptr_init, and rs_writetext function each instance of the function string. You must name each instance of a function string for the text or image column specified in the replication definition.

Function-String ClassesEach function string belongs to a function-string class, which groups function strings intended to be used with databases of a similar type or with similar requirements. Replication Server assigns each database connection a function-string class according to the data server of the destination database.

Replication Server applies functions to the database using the function strings from its assigned function-string class. Function-string classes contain function strings for system functions and for any user-defined functions.

You can use a function-string class on multiple databases if the function strings can execute on all of the data servers. For example, a system with several databases managed by Adaptive Server can use rs_sqlserver_function_class for all the databases.


381

You can even use a single function-string class with heterogeneous data servers, provided that the gateways that provide access to the various data servers share a common interface.

System-Provided ClassesSeveral function-string classes are provided with Replication Server. These are called system-provided classes.

• rs_sqlserver_function_class – default Adaptive Server function strings are provided for this class. The default function strings in rs_sqlserver_function_class are identical to those in rs_default_function_class. rs_sqlserver_function_class is assigned by default to Adaptive Server databases you add to the replication system using rs_init.

You can customize function strings for this class. However, this class cannot participate in function-string class inheritance. In most cases, using derived classes that specify rs_default_function_class as a parent class is preferable to using rs_sqlserver_function_class directly.

• rs_default_function_class – default Adaptive Server function strings are provided for this class. The default function strings in rs_sqlserver_function_class are identical to those in rs_default_function_class.

You cannot customize function strings for this class. However, this class can participate in function-string class inheritance. In most cases, using derived classes that specify rs_default_function_class as a parent class is preferable to using rs_default_function_class directly.

Note The system-provided function-string classes rs_default_function_class and rs_sqlserver_function_class contain default function strings for all system functions except rs_dumpdb and rs_dumptran. If you need to use function strings for these functions you must create them yourself in a derived class or in rs_sqlserver_function_class.

• rs_db2_function_class – DB2-specific function strings are provided for this class. See “Creating Class-Level Translations” on page 284 for more information about using this class.


382

To allow rs_db2_function_class and other function-string classes to work, issue the following commands:

alter connection to dataserver.databaseset dsi_sql_data_style to ’db2’alter connection to dataserver.databaseset dsi_cmd_separator to ’;’

The rs_writetext function string of rs_db2_function_class was changed to “output none.” rs_db2_function_class does not support replication of text or image data. To achieve this functionality, customize the rs_writetext function string using the RPC method through a gateway.

You cannot customize function strings for this class. If you require DB2 function strings, using derived classes that specify rs_db2_function_class as a parent class is preferable, in most cases, to using this class directly.

• rs_informix_function_class – Informix function strings are provided for this class. You cannot customize function strings for this class. See “Creating Class-Level Translations” on page 284 for more information about using this class.

• rs_mss_function_class – Microsoft SQL Server function strings are provided for this class. You cannot customize function strings for this class. See “Creating Class-Level Translations” on page 284 for more information about using this class.

• rs_oracle_function_class – Oracle function strings are provided for this class. You cannot customize function strings for this class. See “Creating Class-Level Translations” on page 284 for more information about using this class.

Table 12-1 on page 384 illustrates function-string inheritance relationships for these and other classes.

Function-String InheritanceThe ability to share function-string definitions among classes by creating relationships between classes is called function-string inheritance.

Using function-string inheritance in general, and inheriting from system-provided classes in particular, provides both administrative and upgrade benefits to Replication System Administrators. Using classes that inherit from system-provided classes, you alter only the function strings you want to customize and inherit all others.


383

If you use classes that do not inherit from system-provided classes, you must create all function strings yourself, and add new function strings whenever you create a new table or function replication definition.

A class that inherits function strings from a parent class is called a derived class. A class from which a derived class inherits function strings is called the parent class of the derived class. Generally, you create a derived class in order to customize certain function strings and inherit all others from the parent class.

A class that does not inherit function strings from any parent class is called a base class. The system-provided classes rs_default_function_class and rs_db2_function_class, and any additional classes you create that do not inherit function strings from a parent class, are base classes. The system-provided classes rs_informix_function_class, rs_msss_function_class, rs_oracle_function_class are derived from rs_default_function_class.

A parent class can have multiple derived classes, while a derived class can have only one parent class. A derived class can also serve as the parent class for one or more derived classes. A set of derived classes of any number of levels stemming from the same base class is called a class tree.

The system-provided classes rs_default_function_class and rs_db2_function_class can serve as parent classes for derived classes. However, they cannot become derived classes of other parent classes.

The system-provided class rs_sqlserver_function_class cannot serve as a parent class or become a derived class.

A base class that you have created can be modified to become a derived class, or it can be designated as the parent class for a derived class. A derived class can be modified to inherit function strings from a different parent class, or it can be detached from a parent class and become a base class.

For every base class that you create, you must provide function strings for the functions that Replication Server invokes in each database to which the class is assigned. If you assign a function-string class to a database when some of the function strings for system functions are missing, the DSI reports an error when Replication Server tries to apply the function string, and suspends the database connection.

Circular function-string inheritance relationships are disallowed. That is, a parent class cannot be modified to inherit function strings from one of its own derived classes or from a derived class of one of these derived classes.

Function-string class relationships are illustrated in Figure 12-1.


384

Figure 12-1: Function-string class relationships

Restrictions in Mixed-Version SystemsIn a mixed-version system, only Replication Servers of version 11.5 or later can work with classes that participate in function-string inheritance.

rs_default_function_class Derived class for Adaptive Server/other

rs_db2_function_class

Derived class

rs_sqlserver_function_class

Cannot alter function strings

Can specify as parent class forAdaptive Server or other database

Cannot alter function strings

Can specify as parent class for DB2

Can alter function strings

Cannot specify as parent class

(Compatible with RS 11.0.x)

User-created base class

Must create/can alter function strings

Can specify as parent class

Derived class for DB2

System-provided class

User-created class

Inheritance by derived class








385

Any class whose primary site is Replication Server version 11.0.x cannot participate in function-string inheritance. If you want to alter such a class to become a derived class or use it as a parent class, you must move that class to a primary site that is Replication Server version 11.5 or later. Then you can alter the class relationships as desired and assign the class or its derived classes to connections managed by Replication Server version 11.5 or later.

A base class that you created in Replication Server version 11.5 or later and that does not participate in function-string inheritance can be assigned to connections managed by any Replication Server in the replication system. If it is not assigned to any databases managed by Replication Server version 11.5 or later, then you can use the move primary command to assign it to a primary site managed by Replication Server version 11.0.x.

Refer to the release bulletin for more information about compatibility between Replication Servers.

Note For compatibility with Replication Servers of version 11.0.x, you may need to continue to customize function strings in rs_sqlserver_function_class. However, for databases managed by Replication Servers version 11.5 or later, using function-string inheritance and customizing function strings only in derived classes is encouraged.

Managing Function-String ClassesWhen you create or customize a function string, you specify which class it belongs to. If you want to create and use customized function strings, you can:

• Create a derived function-string class that inherits function strings from rs_default_function_class, rs_db2_function_class,or another parent class. Then, in the derived class, create only the function strings that you are interested in overriding.

Note You cannot alter, add to, delete, or change any of the function-string classes for non-Sybase data servers.

• Create a new function-string class and create function strings for all functions.

• Customize function strings in rs_sqlserver_function_class. See “Managing Function Strings” on page 391 for information on this option.

Managing Function-String Classes

386

Before you create customized function strings, you should decide in advance which of these approaches to take and set up your classes accordingly. Generally, it is preferable to customize function strings in derived classes rather than to customize function strings in the class rs_sqlserver_function_class. You must be using Replication Server version 11.5 or later in order to create and deploy a derived function-string class that inherits function strings from other classes.

Creating a Function-String ClassIf function strings in an existing class do not serve your needs for particular database connections, and customizing function strings in an existing class is not feasible, you can create a new class in which to create the function strings you need. You can either:

• Create a derived class, one that inherits function strings from an existing parent class.

• Create a base class, one that does not inherit function strings from another class.

For instructions on creating a derived or base function-string class in Sybase Central, see “Creating function-string classes” in Replication Server’s online help.

To create a derived or base function-string class and begin using it for a database connection using RCL commands, follow these steps:

1 Create the function-string class with the create function string class command, using the syntax appropriate for your task. See:

• “Creating a Derived Class” on page 387, or

• “Creating a Base Class” on page 388.

The name of the new class must conform to the rules for identifiers provided in “Identifiers” in Chapter 2, “Topics,” in the Replication Server Reference Manual.

2 Create function strings for the new class with the create function string command, described in “Creating Function Strings” on page 398.

• If you are creating a derived class, you need create only the function strings that you want to override and inherit all others from the specified parent class.

RSM


387

• The class rs_default_function_class does not contain default function strings for the rs_dumpdb and rs_dumptran functions. If you require them in a derived class that inherits from rs_default_function_class, you must create them. See “System-Provided Classes” on page 381 for more information.

• If you are creating a base class, you must create all the necessary function strings for the class.

3 If you are preparing a new function-string class for an existing database connection, you must suspend the connection before you can use the new class. See “Suspending Database Connections” on page 151 for details.

4 Create or alter the database connection to use the new class. See “Assigning a Function-String Class to a Database” on page 390.

5 If you altered an existing database connection to use the new class, resume the connection. See “Suspending Database Connections” on page 151 for details.

Creating a Derived Class

To create a derived function-string class that inherits function strings from a parent class, enter a command like this at the primary site of the parent:

create function string class sqlserver_derived_class set parent to rs_default_function_class

In this example, the new class sqlserver_derived_class inherits function strings from the system-provided class rs_default_function_class. You can then create function strings that override some of the inherited function strings.

You can specify as the parent class any existing class whose primary site runs Replication Server version 11.5 or later. However, you cannot specify as a parent class the system-provided class rs_sqlserver_function_class. You also cannot specify a parent class that would result in circular inheritance. See “Function-String Inheritance” on page 382 for details.

If the parent class is rs_default_function_class or a function-string class for a non-Sybase data server, you can enter this command at any Replication Server with routes to the other Replication Servers where the new class will be used. This site is the primary site for the derived class and any new classes derived from it.


388

If the parent class is a user-created class, enter this command in the Replication Server that is the primary site for the parent class. This site is the primary site for all classes derived from the parent class.

Creating a Base Class

To create a base function-string class, one which does not inherit function strings from a parent class, enter a command like this:

create function string class base_class

In this example, the new class base_class does not inherit function strings from a parent class.

Enter this command at any Replication Server that has routes to the other Replication Servers where the new class will be used. This site then becomes the primary site for the class and for any derived classes for which this class serves as the parent class.

A base class can be used as a parent class for a derived class or can be modified to become a derived class.

For every base class that you create, you must provide function strings for the functions that Replication Server invokes in each database to which the class is assigned.

If you create a base class and then alter it so it becomes a derived class before actually using it with database connections, you do not have to create all the function strings.

Primary Site for a Function-String Class

Although most function strings are executed in replicate databases, you execute the create function string class command in a Replication Server, usually a primary Replication Server, that has routes to all sites where the function-string class is to be used. This command designates that Replication Server as the primary site for the class. Function-string classes are replicated via routes, along with other replication system data.

You can only create or alter function strings that have class scope at the primary site for a class. Function strings with replication-definition scope must be created or altered at the primary site for the replication definition.


389

By default, the class rs_sqlserver_function_class does not have a primary site. To alter class-scope function strings for this class, you must first designate a Replication Server as a primary site for the class. To specify a site for this function-string class, execute the following command at the Replication Server that is to be the primary site:

create function string class rs_sqlserver_function_class

After you have executed this command, you can use the move primary command to make further changes to the primary site for the function-string class.

Changing the Primary Site for a Function-String Class

Use the move primary command or Sybase Central to change the primary Replication Server for a function-string class. For example, you may need to change the primary site from one Replication Server to another so that function strings can be distributed through a new routing configuration. The new primary site must include routes to all Replication Servers where the function-string class will be used.

If you move a base class, all classes derived from that class move with it.

You cannot move the primary site for a derived class unless its parent class is a default function-string class.

For instructions on changing the primary site in Sybase Central, see “Moving a function-string class to a different primary site” in Replication Server’s online help.

Execute move primary at the Replication Server that you want to designate as the new primary site for the function-string class.

For example, the following command changes the primary site for the sqlserver2_function_class function-string class to the SYDNEY_RS Replication Server, where the command is entered:

move primary of function string class sqlserver2_function_class to SYDNEY_RS

If the class rs_sqlserver_function_class has not yet been assigned a primary site, you cannot use the move primary command to assign one. You must use the create function string class command to first designate a primary site for that class. See “Changing the Primary Site for a Function-String Class” on page 389 for details.


390

Assigning a Function-String Class to a DatabaseYou can assign a function-string class to a database connection in Sybase Central or with the create connection or alter connection commands, executed in the Replication Server that manages the database. When you add a database connection using the rs_init program, the class rs_sqlserver_function_class is assigned to the database by default.

For instructions on assigning a function-string class to a database in Sybase Central, see “Assigning function-string classes to database connections” in Replication Server’s online help.

You must suspend the connection to the database before you alter the function-string class that is assigned to the database. The set function string class clause of create connection and alter connection specifies the name of the function-string class to use with the database.

Before you can assign a function-string class to a database connection:

• The function-string class you specify must already exist and be available to the Replication Server. See “Creating a Function-String Class” on page 386 for more information.

• All necessary function strings must be created in the class. See “Creating Function Strings” on page 398 for details.

See “Creating Database Connections” on page 147 and “Altering Database Connections” on page 150 for more information about using the create connection and alter connection commands. Also refer to reference pages for these commands in the Replication Server Reference Manual.

Refer to the Replication Server installation and configuration guides for your platform for more information about rs_init.

Example for Creating New Connection

The following command creates a connection to the pubs2 database managed by the TOKYO_DS data server:

create connection to TOKYO_DS.pubs2 set error class tokyo_error_class set function string class tokyo_func_class set username pubs2_maint set password pubs2_maint_pw

This command assigns the tokyo_func_class function-string class to the database connection.

Example for Altering an Existing Connection

The following command alters an existing database connection to specify a different function-string class:

RSM


391

alter connection to TOKYO_DS.pubs2 set function string class tokyo_func_class2

Dropping a Function-String ClassIf you are sure that you will not need it again, you may want to drop a function-string class that you created from the replication system. You can drop any function-string class except the three system-provided classes and any user-created class that currently serves as a parent class. Before you can drop a function-string class, you must drop all database connections that use the function-string class, or you can alter the connections to use a different class.

Dropping a function-string class deletes all function strings defined for the class and removes all references to the class from the RSSD.

For instructions on dropping a function-string class in Sybase Central, see “Deleting function-string classes” in Replication Server’s online help.

To drop a function-string class from the isql command line, use the drop function string class command. For example, the following command drops the tokyo_func_class function-string class and all of its function strings:

drop function string class tokyo_func_class

Enter this command in the Replication Server that is the primary site for the class.

Refer to “drop function string class” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for more information.

Managing Function StringsEach destination Replication Server uses function strings to convert the functions to commands that are appropriate for the destination data server (such as Adaptive Server) before it submits these commands. See Chapter 2, “Replication Server Technical Overview” for more information about DSI threads, the components that perform this conversion at the replicate Replication Server.

The following sections describe elements of function strings and the commands for managing them. Refer to the Replication Server Reference Manual for complete command syntax and permissions.

RSM

Managing Function Strings

392

For instructions on managing function strings in Sybase Central, see “Function Strings” in Replication Server’s online help.

Function Strings and Function-String ClassesIf you do not require customized function strings, you can use one of the system-provided function-string classes to provide default function strings. If you require customized strings, you must use the system-provided class—rs_sqlserver_function_class—in which you can customize function strings or create a derived or base function-string class. See “Function-String Classes” on page 380 for details.

• If the connection for the database in which the function will be executed uses a system-provided function-string class or a derived class that inherits directly or indirectly from rs_default_function_class or a function-string class for a non-Sybase data server, default function strings are provided for every system function and user-defined function.

• If the connection uses a user-created base function-string class (which does not inherit function strings) or a derived class that inherits from such a class, you must create function strings for every system function and user-defined function. Create them in the base class if you want them to be available in all its derived classes.

Function-String Input and Output TemplatesTo customize function strings, you alter their input and/or output templates. Depending on the function, function strings may include both an input template and an output template, an output template, or neither template:

• For the rs_select and rs_select_with_lock functions, used in subscription materialization, Replication Server uses input templates to locate the function string that corresponds to a subscription’s where clause.

• For all functions Replication Server uses output templates to map functions to the language commands or to apply RPC invocations at the destination data server.

RSM


393

Requirements for Using Input and Output Templates

When you alter templates to customize function strings, you should keep in mind the following requirements:

• Function-string input and output templates are limited to 64K bytes. The result of substituting runtime values for embedded variables in function-string input or output templates must not exceed 64K.

• Function-string input and output templates are delimited with single quotation marks (').

• Function-string variables are enclosed within a pair of question marks (?).

• A variable name and its modifier are separated with an exclamation mark (!).

Language output templates involve additional related requirements. See “Using Output Templates” on page 393 for details.

Using Output TemplatesYou alter output templates to customize function strings. Replication Server uses output templates to determine the format of the command sent to a data server. Most output templates use one of two formats: language or RPC, corresponding to the format of the function string itself. (See “Function Strings” on page 378 for information on function-string formats.) An output template for an rs_writetext function string can use the RPC format or one of the additional formats writetext or none, but not a language output template. See “Using Function Strings with text, image, and rawobject Datatypes” on page 410 for details.

Language Output Templates

Language output templates contain text that the data server interprets as commands. Replication Server substitutes values for variables embedded in the output template and passes the resulting language command(s) to the data server to process.

See “Creating Function Strings” on page 398 for example output templates. See “Using Function-String Variables” on page 397 for details on embedded variables.

Within a language output template, Replication Server interprets certain characters in special ways:


394

• Two single quote characters ('') are interpreted as one single quote

• Two question marks (??) are interpreted as one single question mark

• Two semicolons (;;) are interpreted as one single semicolon

Other than the embedded variable substitutions and these special interpretations, Replication Server does not attempt to interpret the contents of language output templates.

See “Function-String Variable Formatting” on page 398 for information about how Replication Server formats function-string variables when it maps function strings to data server commands.

RPC Output Templates

Unlike language output templates, Replication Server interprets the contents of RPC output templates. They are written in the format of the Transact-SQL execute command. Replication Server parses the output template to construct a remote procedure call to send to the Adaptive Server, Open Server gateway, or Open Server application.

RPC output templates work well with gateways or Open Servers with no language parser. RPCs are usually more compact than language requests and, since they do not require parsing by the data server, may also be more efficient. Therefore, you might choose to use an RPC even when a data server supports language requests.

Output Templates for rs_writetext Function Strings

Replication Server supports three output formats for creating an rs_writetext function string: RPC, writetext, and none. The writetext and none output templates can only be used in rs_writetext function strings.

See “Using Function Strings with text, image, and rawobject Datatypes” on page 410 for more information about writetext and none.


395

Using Input TemplatesInput templates are used only for non-bulk materialization and for dematerialization with purge— those situations where Replication Server must select data to add or delete from selected tables. rs_select and rs_select_with_lock are the only function strings that can contain input templates. Replication Server determines which function string to use with a subscription during materialization or dematerialization by:

• Matching the subscription’s replication definition

• Matching the input template with the where clause used in the subscription

rs_select and rs_select_with_lock also contain output templates to specify the actual select statements or other operations that perform the desired materialization or dematerialization.

For the system-provided classes, Replication Server generates default function strings for the rs_select and rs_select_with_lock functions when you create a replication definition. Generally, you only need to customize these function strings if multiple subscriptions exist for your replication definition.

Function strings for the rs_select and rs_select_with_lock functions are most often used for materialization. If you plan multiple subscriptions to the same replication definition, create the function strings before you create the subscriptions. See “Subscription Materialization Methods” on page 310 for more information about subscription materialization.

Function strings for rs_select and rs_select_with_lock may also be used for subscription dematerialization, which uses the where clause of the command used to create the subscription. The function strings for these functions must exist before you drop the subscriptions. See “Using the drop subscription Command” on page 336 for more information about dematerialization.

An input template can contain user-defined variables whose values come from constants in the where clause of a subscription. No other types of function-string variables are allowed in input templates. An output template in the same function string can reference these user-defined variables.

If you need to customize an output template to select materialization data, you can omit the input template from an rs_select or rs_select_with_lock function string. Doing so creates a default function string that can match any select statement when no other function string’s input template matches the select command.


396

As with other functions with replication-definition scope, you create function strings for the rs_select and rs_select_with_lock functions in the primary Replication Server where the replication definition was created.

Class in Which to Create Function Strings

When you create rs_select and rs_select_with_lock function strings for materialization, you create them in the function-string class that is assigned to the connection to the primary database from which you are selecting materialization data. If you are using bulk materialization, you do not need to create rs_select and rs_select_with_lock function strings for materialization.

When you create rs_select and rs_select_with_lock function strings for dematerialization, you create them in the function-string class that is assigned to the connection to the replicate database for which you are selecting data to be dematerialized. If you drop a subscription using drop subscription with the without purge option, you do not need rs_select and rs_select_with_lock function strings for dematerialization.

Example for rs_select Function String

In the following example, a site subscribes to a specified publisher’s book titles through the replication definition titles_rep. There must be an rs_select function string with an input template that compares the publisher column in the pubs2 database’s titles table to a user-defined value that identifies the publisher.

The create function string command creates a function string with an input template that compares the publisher column pub_id to the user-defined variable ?pub_id!user?. For details on function-string variables, see “Using Function-String Variables” on page 397.

The input template matches any subscription with a where clause of the form where pub_id = constant. As a result, the output template, when it is used, includes the constant value. The output template selects materialization data from two different tables.

create function string titles_rep.rs_select;pub_idfor sqlserver2_function_class

scan ’select * from titles where pub_id =?pub_id!user?’

output language’select * from titles where pub_id =

?pub_id!user?unionselect * from titles.pending where pub_id =

?pub_id!user?’


397

See “Creating Function Strings” on page 398 for details. Refer to the Replication Server Reference Manual for complete syntax.

Using Function-String VariablesVariables embedded in function-string input or output templates are symbolic markers for various runtime values.

A variable can represent a column name, the name of a system-defined variable, the name of a parameter in a user-defined function, or a user-defined variable defined in an input template. The variable must refer to a value with the same datatype as anything to which it is assigned.

Function-string variables are enclosed inside of a pair of question marks (?), as shown:

?variable!modifier?

The modifier portion of a variable identifies the type of data the variable represents. The modifier is separated from the variable name with an exclamation point (!).

Replication Server recognizes the modifiers listed in Table 12-3:

Table 12-3: Function-string variable modifiers

Modifier Description

new, new_raw A reference to the new value of a column in a row that Replication Server is inserting or updating.

old, old_raw A reference to the old values of a column in a row that Replication Server is inserting or updating.

user, user_raw A reference to a variable that is defined in the input template of an rs_select or rs_select_with_lock function string.

sys, sys_raw A reference to a system-defined variable.

param, param_raw A reference to a stored-procedure parameter

text_status A reference to the text_status value for text or image data. Possible values are:

• 0x000 – Text field contains NULL value, and the text pointer has not been initialized.

• 0x0002 – Text pointer is initialized.

• 0x0004 – Real text data will follow.

• 0x0008 – No text data will follow because the text data is not replicated.

• 0x0010 – The text data is not replicated but it contains NULL values.


398

Note Function strings for user-defined functions may not use the new or old modifiers.

Refer to “create function string” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for a list of system-defined variables that you can use in function-string input or output templates.

See “Using the Default System Variable” on page 408 for information on applications for that system variable.

Function-String Variable Formatting

When Replication Server maps function-string output templates to data server commands, it formats the variables using the Adaptive Server format.

For most variables (except those special cases with modifiers ending in _raw), Replication Server formats data as follows:

• Adds an extra single-quote character to single-quote characters appearing in character and date/time values.

• Adds single-quote characters around character and date/time values, if they are missing.

• Adds the appropriate monetary symbol (for example, the dollar sign) to values of money datatypes.

• Adds the “0x” prefix to values of binary datatypes.

• Adds a combination of a backslash (\) and newline character between existing instances of a backslash and newline character in character values. Adaptive Server treats a backslash followed by a newline as a continuation character and, therefore, deletes the added pair of characters, leaving the original characters intact.

Replication Server does not alter datatypes in these ways for modifiers that end in _raw.

Creating Function StringsTo add a function string to a function-string class, use the create function string command. Enter function-string commands at the primary site of the function string:


399

• For function strings with replication-definition scope, the primary site is the Replication Server where the replication definition was created.

• For function strings with class scope, the primary site is the Replication Server that is the primary site for the class. The primary site for a derived class is the same as for its parent class, unless the parent class is one of the system-provided classes. See “Primary Site for a Function-String Class” on page 388 for more information.

If you are using a derived function-string class whose parent class is not provided by the system, you may choose to customize function strings in the parent class rather than in the derived class that is actually assigned to a particular database connection. Doing so would make the customized function strings available for any additional derived classes of that parent class.

Guidelines for Creating Function Strings

The following guidelines for creating function strings pertain to function-string classes:

• If you need to customize function strings, you can do so in any class other than the system-provided classes rs_default_function_class and rs_db2_function_class.

• You must assign a function-string class a primary site before you can create function strings for the class. The system-provided class rs_sqlserver_function_class has no primary site until you assign one using the create function string class command.

• If the function-string class is a new base class, you must create function strings for all the necessary system functions before you can use the class.

The following guidelines pertain to function strings themselves:

• You can specify an optional name for the function string. For the rs_select, rs_select_with_lock, rs_datarow_for_writetext, rs_get_textptr, rs_textptr_init, and rs_writetext functions, Replication Server uses the function-string name to uniquely identify the function strings. Function string names are unique when you qualify them fully.

• If the input template is omitted for an rs_select or rs_select_with_lock function string, Replication Server matches any subscriptions that do not have matching function strings.

• If you are customizing function strings for functions with replication-definition scope, you must create the function strings before you create the subscriptions.


400

• You can put several commands in a language output template, separating them with semicolons. See “Defining Multiple Commands in a Function String” on page 405 for details.

Make sure that the database connection batch parameter has been set to allow command batching. See “Configuration Parameters Affecting Connections” on page 154.

• You can use Adaptive Server syntax to specify a null value for a constant in a function string.

Refer to “create function string” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for the complete syntax for the create function string command.

Example for rs_begin Function String

The following example creates a function string for the rs_begin function that begins a transaction in the database by executing a stored procedure named begin_xact.

create function string rs_begin for gateway_func_class output rpc ’execute begin_xact’

Example for rs_insert Function String

The following example creates a function string for a rs_insert function that references the publishers_rep replication definition, which executes an RPC at the replicate database as a result of an insert in the primary table. The stored procedure insert_publisher is defined only at the replicate database.

create function string publishers_rep.rs_insertfor rs_sqlserver_function_classoutput rpc’execute insert_publisher

@pub_id = ?pub_id!new?,@pub_name = ?pub_name!new?,@city = ?city!new?,@state = ?state!new?’

Altering Function StringsThe alter function string command replaces an existing function string. alter function string acts essentially the same as create function string except that it executes the drop function string command first. The function string is dropped and re-created in a single transaction to prevent any errors from occurring as a result of missing function strings.


401

You can alter a function string using either the alter function string command or the create function string command. To alter a function string using the create function string command, you must include the optional clause with overwrite after the name of the function-string class. This command drops and re-creates an existing function string, the same as the alter function string command.

To alter a function string using the alter function string command, you must first create a function string.

In a derived class, first use the create function string command to override the function string that is inherited from the parent class. You cannot alter a function string in a derived class unless the function string has been explicitly created for the derived class.

You alter function strings at the Replication Server that is the primary site for the existing function string:

• For functions of replication-definition scope, alter the function string at the primary Replication Server where the replication definition was defined.

• For functions of class scope, alter the function string at the primary site for the function-string class. The primary site for a derived class is the same as for its parent class, unless the parent class is one of the system-provided classes. See “Primary Site for a Function-String Class” on page 388 for more information.

For system functions that allow multiple function-string mappings, such as rs_select and rs_select_with_lock, provide the complete function string name in the alter function string syntax. Replication Server uses the name to determine which function string to alter.

See “Creating Function Strings” on page 398 for example function strings.

Refer to “alter function string” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for the complete syntax for the alter function string command.

For instructions on altering function strings in Sybase Central, see “Changing function strings” in Replication Server’s online help.

RSM


402

Dropping Function StringsTo discard a customized function string in a derived class and restore the function string from the parent class, drop the function string. Use the drop function string command to remove one or more function strings in a function-string class.

Warning! If you want to drop and re-create a function string, use alter function string to replace an existing function string with a new one. Dropping and then re-creating a function string by other methods can lead to a state where the function string is temporarily missing. If a transaction that uses this function string occurs between the time the function string is dropped and the time it is re-created, Replication Server detects the function string as missing and fails the transaction.

When you drop the function string from a derived class, you restore the function string from the parent class.

For instructions on dropping function strings in Sybase Central, see “Deleting function strings” in Replication Server’s online help.

Refer to “drop function string” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for more information on this command.

You can also drop customized function strings from the system-provided class rs_sqlserver_function_class.

To restore a default function string for a function string with replication-definition scope that you have dropped, use the alter function string command to omit the output clause. See “Restoring Default Function Strings” on page 403 for details.

Examples The following command drops the rs_insert function string for the publishers_rep replication definition in the class sqlserver2_func_class:

drop function stringpublishers_rep.rs_insertfor sqlserver2_func_class

The following command drops the pub_id instance of a function string for the rs_select function for the publishers_rep replication definition in the class derived_class. Drop function strings for the rs_select_with_lock function in a similar way.

drop function stringpublishers_rep.rs_select;pub_id

RSM


403

for derived_class

The following command drops the rs_begin function string from the gateway_func_class function-string class:

drop function string rs_beginfor gateway_func_class

Dropping All Function Strings for a Function

In cases where there are multiple function strings for a specified function, you can drop all function strings for that function simultaneously.

The following command drops all function strings for the rs_select_with_lock function that references the publishers_rep replication definition in the class sqlserver2_func_class:

drop function stringpublishers_rep.rs_select_with_lock;allfor sqlserver2_func_class

System functions that can have multiple function string mappings include the rs_select, rs_select_with_lock, rs_get_textptr, rs_textptr_init, or rs_writetext functions.

Examples of Using the all Keyword As Shorthand

When dropping function strings for any system function for which you provided a lengthy name, you can use the all keyword as shorthand for the name of the function string instance. For example, the following command gives a long name for a function string:

create function stringpublishers_rep.rs_insert;my_insert_function_stringfor sqlserver2_func_class ...

In this case, the following command drops the function string without you having to enter the fully qualified name:

drop function stringpublishers_rep.rs_insert;allfor sqlserver2_func_class

Restoring Default Function StringsTo restore the Adaptive Server default function string for a system function with replication definition scope, omit the output clause in the create function string or alter function string command. You cannot omit an output template from a system function with function-string-class scope, although you can specify an empty template.


404

For instructions on restoring default function strings in Sybase Central, see “Reverting to original function strings” in Replication Server’s online help.

In all classes, even derived classes, executing the create function string or alter function string command without the output clause restores the same function string that is provided by default for the system-provided classes rs_sqlserver_function_class and rs_default_function_class.

The default function-string definition this method yields may or may not be appropriate for the databases to which you have assigned the class. This method may be most helpful when you are using a customized rs_sqlserver_function_class or when you are using other user-created base classes for Adaptive Server databases.

In a derived class, if you want to discard a customized function string and restore the function string from the parent class, drop the function string. See “Dropping Function Strings” on page 402 for details.

Example for alter function string

The following command replaces a customized rs_insert function string for the publishers_rep replication definition with the default function string:

alter function string publishers_rep.rs_insertfor rs_sqlserver_function_class

See “Altering Function Strings” on page 400 for details on using the alter function string command.

Example for create function string in a Derived Class

You can use this method in a derived function-string class to override an inherited function string with the Adaptive Server default function string. The following command replaces an inherited rs_insert function string for the publishers_rep replication definition with the default function string:

create function string publishers_rep.rs_insertfor derived_class

See “Creating Function Strings” on page 398 for details on using the create function string command.

Creating Empty Function Strings with the Output TemplateYou can create an empty function string—one that performs no action—by including the output language clause with an empty function string specified with two single quotes.

For example, the following command defines no action for the rs_insert function string for the publishers_rep replication definition:

RSM


405

alter function string publishers_rep.rs_insertfor derived_classoutput language ’’

See “Altering Function Strings” on page 400 for details on using the alter function string command.

Remapping Table and Column Names with Function StringsYou can use function strings to translate the table name and column names for a replicated table to names other than those specified in the replication definition. The function strings that Replication Server generates for the rs_sqlserver_function_class function-string class use the names specified by the replication definition for the table, but you can define your own function strings with any names you like.

This procedure is useful if a site has existing client applications that use different table and column names than those defined by the replication definition for the primary data. Customizing function strings allows Replication Server to maintain the data in the table and does not require that you alter the site’s applications.

To do this, you can use either language function strings or RPC function strings with Adaptive Server stored procedures at the remote site.

Defining Multiple Commands in a Function StringLanguage output templates can contain many commands. Adaptive Server permits multiple commands in a batch. Although most other data servers do not offer this feature, Replication Server allows you to batch commands in function strings for any data server by separating commands with a semicolon (;).

Use two consecutive semicolons (;;) to represent a semicolon that is not to be interpreted as a command separator.

If the data server supports command batches, Replication Server replaces the semicolons with the DSI command separator character (dsi_cmd_separator configuration parameter), as necessary, and submits the commands in a single batch.

If the data server does not support command batches, Replication Server submits each command in the function string separately.


406

For example, the output template in the following function string contains two commands:

create function string rs_commitfor sqlserver2_function_classoutput language’execute rs_update_lastcommit

@origin = ?rs_origin!sys?,@origin_qid = ?rs_origin_qid!sys?,@secondary_qid = ?rs_secondary_qid!sys?;commit transaction’

Support for batches is enabled or disabled in Replication Server with the alter connection command.

Set batch to “on” to allow command batching for a database, or set it to “off” to send individual commands to the data server. The default is “on.”

To set batching “on” for this example, enter:

alter connection to SYDNEY_DS.pubs2set batch to ’on’

To set batching “off,” enter:

alter connection to SYDNEY_DS.pubs2set batch to ’off’

Using Declare Statements in Language Output TemplatesTo include declare statements, used to define local variables, in the language output templates, make sure that the batch configuration parameter is set to “off” for the Replication Server connected to the database. When batch is set to “on” (the default), Replication Server can send multiple invocations of a function string to the data server as a single command batch, thereby putting multiple declarations of the same variable in that batch, which is unacceptable to Adaptive Server.

Performance is slower when batch mode is off because Replication Server must wait for a response to each command before the next one is sent. If your performance requirements are low, you can use declare statements in your function strings if you set batch to “off.” Alternatively, if you want to use batch mode for improved performance, create function-string language output templates that execute stored procedures, which can include declare statements and other commands.


407

Refer to “Setting and Changing Parameters Affecting Physical Connections” on page 152 for more information about batch.

Displaying Function-Related InformationYou can obtain information about existing function strings and classes in your replication system in two ways:

• Using Replication Server admin command

• Using Adaptive Server stored procedures

For instructions on viewing information about function strings and classes in Sybase Central, see “Viewing function string properties” in Replication Server’s online help.

Obtaining Information Using the admin CommandYou can display the names of the function-string classes used in your Replication Server system using one of Replication Server’s admin commands.

Use admin show_function_classes to display the names of existing function-string classes and their parent classes. It also indicates the inheritance level of the class. Level 0 is a base class such as rs_default_function_class or rs_db2_function_class, level 1 is a derived class that inherits from a base class, and so on.

For example:

admin show_function_classesClass ParentClass Level -------- ------------ -----sql_derived_class rs_default_function_class 1 rs_db2_derived_class rs_db2_function_class 1rs_db2_function_class 0...

Refer to Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for more information about this command.

RSM

Using the Default System Variable

408

Obtaining Information Using Stored ProceduresYou can obtain information about existing functions, function strings, and function-string classes in your system using stored procedures in a Replication Server’s RSSD.

Refer to Chapter 6, “Adaptive Server Stored Procedures,” in the Replication Server Reference Manual for more information about these stored procedures.

rs_helpfunc rs_helpfunc displays information about system functions and user-defined functions for a Replication Server or for a particular table or function replication definition. The syntax is:

rs_helpfunc [replication_definition [, function_name]]

rs_helpfstring rs_helpfstring displays the parameters and function-string text for functions associated with a replication definition. The syntax is:

rs_helpfstring replication_definition[, function_name]

rs_helpclass rs_helpclass lists all function-string classes and error classes and their primary Replication Servers. The syntax is:

rs_helpclass [class_name]

rs_helpclassfstring rs_helpclassfstring displays the function-string information for class-scope functions. The syntax is:

rs_helpclassfstring class_name [, function_name]

Using the Default System VariableThe rs_default_fs system variable allows you to perform the following tasks:

• Extend function strings with replication-definition scope to include additional commands (such as those for auditing or tracking)

• Customize rs_update and rs_delete function strings and still be able to use the replicate minimal columns option in your replication definitions

Note Function strings containing the rs_default_fs system variable may only be applied on Adaptive Servers or data servers that accept Adaptive Server syntax. Otherwise, errors will occur.


409

Refer to “create function string” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for a complete list of function string system variables.

Extending Default Function StringsYou can use the rs_default_fssystem variable with all function strings that have replication-definition scope (table or function) as a way to extend the default function-string behavior.

Using the rs_default_fs system variable reduces the amount of typing required when you want to keep the functionality of the default function string intact and include additional commands. For example, you can add commands to extend the capabilities of the default function string for auditing or tracking purposes.

Commands that you add to the output language template may either precede or follow the rs_default_fs system variable. They may or may not affect how the row is replicated into the replicate table.

The following example shows how you might use the rs_default_fs system variable in the create function string command (or the alter function string command) to verify that an update has occurred:

create function string replication_definition.rs_updatefor function_string_classoutput language ’?rs_default_fs!sys?;

if (@@rowcount = 0)beginraiserror 99999 "No rows updated!"end’

In this example, the rs_default_fs system variable, embedded in the language output template, maintains the functionality of the default rs_update function string while the output template then checks to see if any rows have been updated. If they have not been updated, Replication Server raises an error.

In this example, the commands that follow the system variable do not affect how the row is to be replicated at the replicate site. You can use the rs_default_fs system variable with similar additional commands for verification or auditing purposes.

Using Function Strings with text, image, and rawobject Datatypes

410

Using Replicate Minimal ColumnsIf you have specified replicate minimal columns for a replication definition, you normally cannot create non-default function strings for the rs_update, rs_delete, rs_get_textptr, rs_textptr_init, or rs_datarow_for_writetext system functions.

You can create non-default function strings for the rs_update and rs_delete functions by embedding the rs_default_fs system variable in the output language template of the create function string or alter function string commands and still use the minimal columns option.

You cannot use any variables, including the rs_default_fs system variable, that access non-key column values in rs_update or rs_delete function strings for replication definitions that use the minimal columns option. When you create such a function string, you may not know ahead of time which columns will be modified at the primary table. You may, however, include variables that access key column values.

See “create replication definition” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for more information about the replicate minimal columns option.


In an environment that supports text, image, and rawobject datatypes, you can customize function strings for the rs_writetext function using the output template formats writetext or none. The methods discussed in this section can only be used with rs_writetext function strings.

For instructions on using text, image, and rawobject datatypes in function strings in Sybase Central, see “Customizing function strings for text and image columns” in Replication Server’s online help.

For Replication Server version 11.5 or later, you can use multiple replication definitions instead of function strings. See Chapter , “Managing Replicated Tables,” for information about multiple replication definitions.

RSM


411

Using output writetext for rs_writetext Function StringsThe writetext output template option for rs_writetext function strings instructs Replication Server to use the Client-Library function ct_send_data to update a text, image, or rawobject column value. It specifies logging behavior for text, image, and rawobject columns in the replicate database.

writetext output templates support the following options:

• use primary log – logs the data in the replicate database, if the logging option was specified in the primary database.

• with log – logs the data in the replicate database transaction log.

• no log – does not log the data in the replicate database transaction log.

Using output none for rs_writetext Function StringsThe none output template option for rs_writetext function strings instructs Replication Server not to replicate a text or image column value. This option provides necessary flexibility for using text and image columns within a heterogeneous environment.

Heterogeneous Replication and text, image, and rawobject Data

To replicate text, image, and rawobject data from a foreign data server into an Adaptive Server database, you must include the text, image, and rawobject data in the replication definition so that a subscription can be created for the Adaptive Server database. However, you might not want to replicate the text, image, and rawobject data into other replicate data servers, whether they are other foreign data servers or other Adaptive Servers.

With the none output template option, you can customize rs_writetext function strings to map operations to a smaller table at a replicate site and to instruct the rs_writetext function string not to perform any text, image, or rawobject operation against the replicate site.

There is one rs_writetext function string for each text, image, and rawobject column in the replication definition. If you do not want to replicate a certain text, image, or rawobject column, customize the rs_writetext function string for that column. Specify the column name in the create or alter function string command, as shown in the example below. You may also need to customize the rs_insert function string.


412

Example Assume that a replication definition does not allow null values in a text, image, or rawobject column and that you do not require certain text, image, or rawobject columns at the replicate site.

If inserts occur in those columns at the primary site, you must customize the rs_writetext function strings for the text, image, or rawobject columns that are not needed at the replicate site. You must also customize the rs_insert function string for the replication definition.

For example, assume that you have primary table foo:

foo (int a, b text not null, c image not null)

and you perform the following insert:

insert foo values (1, "111111", 0x11111111)

By default, Replication Server translates rs_insert into the following form for application by the DSI thread into the replicate table foo:

insert foo (a, b, c) values (1, "", "")

The DSI thread calls:

• ct_send_data to insert text data into column b

• ct_send_data to insert image data into column c

Because null values are not allowed for the text column b and the image column c, the DSI thread shuts down if the replicate table does not contain either column b or column c.

If the replicate table only contains columns a and b, you need to customize the rs_writetext function for column c to use output none, as follows:

alter function string foo_repdef.rs_writetext;cfor rs_sqlserver_function_classoutput none

You must specify the column name (c in this example) as shown to alter the rs_writetext function string for that column.

If the replicate table only contains columns a and b, you also need to customize the rs_insert function string for the replication definition so that it will not attempt to insert into column c, as follows:

alter function string foo_repdef.rs_insertfor rs_sqlserver_function_classoutput language’insert foo (a, b) values (?a!new?, "")’


413

You do not have to customize rs_insert if the replication definition specifies that null values are allowed for column c. By default, rs_insert does not affect any text or image columns where null values are allowed.


414

415

C H A P T E R 1 3 Managing Warm Standby Applications

This chapter describes how to create and manage a warm standby application using Replication Server.

OverviewA warm standby application is a pair of Adaptive Server or SQL Server databases, one of which is a backup copy of the other. Client applications update the active database; Replication Server maintains the standby database as a copy of the active database.

If the active database fails, or if you need to perform maintenance on the active database or on the data server, a switch to the standby database allows client applications to resume work with little interruption.

To keep the standby database consistent with the active database, Replication Server reproduces transaction information retrieved from the active database’s transaction log. Although replication definitions facilitate replication into the standby database, they are not required. Subscriptions are not needed to replicate data into the standby database.

How a Warm Standby WorksFigure 13-1 illustrates the normal operation of an example warm standby application.

Overview

416

Figure 13-1: Warm standby application

In this warm standby application:

• Client applications execute transactions in the active database.

• The RepAgent for the active database retrieves transactions from the transaction log and forwards them to Replication Server.

• Replication Server executes the transactions in the standby database.

• Replication Server may also copy transactions to destination databases and remote Replication Servers.

See Figure 13-4 on page 441 for more details about the components and processes in a warm standby application.

Database Connections in a Warm Standby ApplicationIn a warm standby application, the active database and the standby database appear in the replication system as a connection from the Replication Server to a single logical database. The Replication System Administrator creates this logical connection to establish one symbolic name for both the active and standby databases.

Thus, a warm standby application involves three database connections from the Replication Server:

• A physical connection for the active database

ActiveDatabase

StandbyDatabase

Clients

Replication Server

to other Replication Serversor destination databases

CHAPTER 13 Managing Warm Standby Applications

417

• A physical connection for the standby database

• A logical connection for the active and standby databases

Replication Server maps the logical connection to the currently active database and copies transactions from the active to the standby database.

See “Setting Up Warm Standby Databases” on page 428 for details on creating the logical and physical database connections. See Chapter 6, “Managing Database Connections” for more information about physical database connections.

Primary and Replicate Databases and Warm Standby ApplicationsIn many Replication Server applications:

• A primary database is the source of data that is copied to other databases through the use of replication definitions and subscriptions.

• A destination database receives data from the primary (source) database.

Replication Server treats a logical database like any other database. Depending on your application, the logical database in a warm standby application may function as:

• A primary database, or

• A replicate database, or

• A database that does not participate in replication

See “Switching the Active and Standby Databases” on page 440 for more information about warm standby applications that do not participate in standard replication.

See “Warm Standby Applications Using Replication” on page 457 for more information about warm standby applications for primary or replicate databases.

Comparison of Database Relationships

In most of this book, databases are defined as “primary” or “replicate.” In discussing warm standby applications, however, databases are also defined as “active” or “standby.” Table 13-1 explains the difference.

Overview

418

Table 13-1: Active and standby vs. primary and destination databases

Warm Standby Requirements and RestrictionsThe following restrictions apply to all Replication Server warm standby applications:

• You must use a Sybase Adaptive Server or SQL Server that supports warm standby applications. Refer to your release bulletin for more information.

Active and Standby Databases Primary and Replicate Databases

The active and standby databases must be managed by the same Replication Server.

Primary and destination databases may be managed by the same or different Replication Servers.

The active and standby databases must be Adaptive Server (or SQL Server) databases.

Except where they participate in warm standby applications, primary and destination databases need not be Adaptive Server (or SQL Server) databases.

The active database has one standby database.

Information is always copied from the active to the standby database.

A primary database can have one or more destination databases.

Some databases contain both primary and copied data.

The use of replication definitions is optional. Subscriptions are not used.

Replication definitions and subscriptions are required for replication from a primary to a destination database.

The connection to the standby database uses the function-string class rs_default_function_class.

You cannot customize function strings for this class.

The connection to a replicate database can use a function-string class in which you can customize function strings. For example, it may use a derived class that inherits function strings from rs_default_function_class.

You can switch the roles of the active and standby databases.

You cannot switch the roles of primary and replicate databases.

Client applications generally connect to the active database. (However, you can perform read-only operations at the standby database.)

No mechanism is provided for switching client applications when you switch the Replication Server to the standby database.

Client applications can connect to either primary or destination database. Only primary data can be directly modified.

Generally, client applications do not need to switch between primary and destination databases.

The RepAgent for the active database submits all transactions on replicated tables, including maintenance user transactions, to the Replication Server, which reproduces them in the standby database.

In a warm standby application for a destination database, transactions in the active database are normally executed by the maintenance user.

In most applications, RepAgent does not submit maintenance user transactions to the Replication Server to be reproduced in destination databases.

The maintenance user does not generally execute transactions in primary databases.


419

• One Replication Server manages both the active and standby databases. Both the active and standby databases must be Adaptive Server or SQL Server databases.

• You cannot create a standby database for the RSSD or for the master database.

• Replication Server does not switch client applications to the standby database. See “Setting Up Clients to Work with the Active Data Server” on page 450 for more information.

• You should run Adaptive Server for the active and standby databases on different machines. Putting the active and standby databases on the same data server or hardware resources undermines the benefits of the warm standby feature.

• Although Adaptive Server allows tables that contain duplicate rows, tables in the active and standby databases should have unique values for the primary key columns in each row.

• Failover support is not a substitute for warm standby. While warm standby keeps a copy of a database, Failover support accesses the same database from a different machine. Failover support works the same for connections from Replication Server to warm standby databases.

For more detailed information about how Sybase Failover works in Adaptive Server, refer to Using Sybase Failover in a High Availability System, which is part of the Adaptive Server Enterprise version 12.0 documentation set.

For more detailed information about how Failover support works in Replication Server, see “Configuring the Replication System to Support Sybase Failover” in Chapter 16, “Replication System Recovery,” of the Replication Server Administration Guide.

Function Strings for Maintaining Standby DatabasesReplication Server uses the system-provided function-string class rs_default_function_class for the standby DSI, which is the connection to the standby database. Replication Server generates default function strings for this class. You cannot customize the function strings in the class rs_default_function_class.

What Information Is Replicated?

420

What Information Is Replicated?Replication Server supports different methods for enabling replication to the standby database. The level and type of information that Replication Server copies to the standby database depends on the method you choose.

You must choose one of these two methods:

• Use the sp_reptostandby system procedure to mark the entire database for replication to the standby database. sp_reptostandby enables replication of data manipulation language (DML) commands and a set of supported data definition language (DDL) commands and system procedures.

• DML commands, such as insert, update, delete, and truncate table, change the data in user tables.

• DDL commands and system procedures change the schema or structure of the database.

sp_reptostandby allows replication of DDL commands and procedures that make changes to system tables stored in the database. You can use DDL commands to create, alter, and drop database objects such as tables and views. Supported DDL system procedures affect information about database objects. They are executed at the standby database by the original user.

• If you use SQL Server version 11.0.x, or you choose not use sp_reptostandby, you can mark individual user tables for replication with sp_setreptable. This procedure enables replication of DML operations for the marked tables.

Optionally, you can also tell Replication Server which user stored procedures to replicate to the standby database:

• If you use Adaptive Server or SQL Server version 11.0.x, you can copy the execution of user stored procedures to the standby database by marking them with the sp_setrepproc system procedure. Normally, only stored procedures associated with function replication definitions are replicated to standby databases.

Refer to “Using sp_setrepproc to Copy User Stored Procedures” on page 425 for more information.


421

Comparing Replication MethodsTable 13-2 compares sp_reptostandby and sp_setreptable, detailing how each copies information to the standby database. Many of these issues are discussed in detail later in the chapter.

Table 13-2: Comparison of table replication methods

sp_reptostandby sp_setreptable

Copies all user tables to the standby database. Lets you choose which user tables are copied to the standby database.

Allows replication of DML commands and supported DDL commands and system procedures. Supported DDL operations are listed in Table 13-3.

Allows replication of DML commands executed on marked tables.

Note Supported DDL operations can be replicated for an isql sessions. Refer to “Forcing Replication of DDL Commands to the Standby Database” on page 427 for more information.

Does not copy DML and DDL operations to replicate databases.

If the warm standby application also copies data to a replicate database, you must mark tables to be copied to the replicate database with sp_setreptable.

Copies DML operations to standby and replicate databases.

Copies execution of the truncate table command to the standby database. No subscription is needed.

Note You can enable or disable replication of truncate table to standby databases with the alter logical connection command. See “Replicating truncate table to Standby Databases” on page 454 for more information.

• If you use Adaptive Server databases, copies execution of truncate table to standby databases. No subscription is needed.

• If you use SQL Server databases, does not copy execution of truncate table to standby or replicate databases.

Replication Server uses table name and table owner information to identify a table at the standby database.

If you include the owner_on keywords when you mark a table for replication to the warm standby, Replication Server uses table name and table owner information to identify a table at the standby database.

If you include the owner_off keywords when you mark a table for replication to the warm standby, Replication Server uses the table name and “dbo” to identify a table at the standby database.


422

Using sp_reptostandby to Enable ReplicationUse sp_reptostandby to copy DML and supported DDL commands for all user tables to the standby database.

Restrictions and Requirements When Using sp_reptostandbyConsider the following issues when you set up your warm standby application and enable replication with sp_reptostandby.

• Both the active and standby databases must be managed by Adaptive Servers and must support RepAgent. Both databases must have the same disk allocations, segment names, and roles. Refer to the Adaptive Server System Administration Guide for details.

• The active database name must exist in the standby server. Otherwise, replication of commands or procedures containing the name of that database will fail.

• Replication Server does not support replication of DDL commands containing local variables. You must explicitly define site-specific information for these commands.

• Login information is not replicated to the standby database. Refer to “Making the Server User’s IDs Match” on page 436 for information about adding login information to the destination Replication Server.

• Some commands not copied to the standby database include:

• select into

• update statistics

By default, text, image, and rawobject columns are copied to the standby database only if changed.

If you mark the database tables with sp_reptostandby and sp_setreptable, text, image, and rawobject data may be treated in a different way. Refer to “Replicating text, image, and rawobject Data” on page 426 for more information.

By default, text and image columns are always copied to the standby database.

If you set the replication status with sp_setrepcol, text, image, and rawobject columns are treated as marked: always_replicate, replicate_if_changed, or do_not_replicate.

The easiest method to use when the active and standby databases are identical. Replication definitions are not required, but can be used to optimize performance.

Replication definitions are not required, but can be used to optimize performance.

sp_reptostandby sp_setreptable


423

• Database or configuration options such as sp_dboption and sp_configure

Table 13-3 displays the DDL commands—Transact-SQL commands and Adaptive Server system procedures—that Replication Server reproduces at the standby database when you enable replication with sp_reptostandby.

Table 13-3: Supported commands and system procedures

To enable replication of DML and DDL commands, execute sp_reptostandby at the Adaptive Server that manages the active database. The syntax is:

sp_reptostandby dbname[, ’L1’ | ’all’ | ’none’ ]

where dbname is the name of the active database and the keywords L1, all, and none set the level of replication support.

L1 represents the level of replication supported by Adaptive Server version 12.0.

Note For Replication Server version 12.0, L1 is equivalent to all.

Transact-SQL Commands

alter tablecreate defaultcreate indexcreate procedurecreate rulecreate table

create triggercreate viewdrop defaultdrop indexdrop proceduredrop rule

drop tabledrop triggerdrop viewgrantinstalljavaremove javarevoke

Adaptive Server System Procedures

sp_addaliassp_addgroupsp_addmessagesp_addusersp_addtypesp_bindefaultsp_bindmsgsp_bindrulesp_changegroupsp_chgattribute

sp_commonkeysp_config_rep_agentsp_dropaliassp_dropgroupsp_dropkeysp_dropmessagesp_droptypesp_dropusersp_foreignkeysp_primarykey

sp_procxmodesp_recompilesp_renamesp_setrepcolsp_setreplicatesp_setrepprocsp_setreptablesp_unbindefaultsp_unbindmsgsp_unbindrule


424

Use the all keyword to make sure that schema replication support is always at the highest level available. For example, to set the schema replication support level to that of the latest Adaptive Server version, log in to Adaptive Server and execute this command at the isql prompt:

sp_reptostandby dbname, ’all’

Then, if the database is upgraded to a later Adaptive Server version with a higher level of replication support, all new features of that version are enabled automatically. Refer to “sp_reptostandby” in Chapter 5, “Adaptive Server Commands and System Procedures,” in the Replication Server Reference Manual for complete syntax and user information.

Disabling Replication

To turn off data and schema replication, log in to Adaptive Server and enter this command at the isql prompt:

sp_reptostandby dbname,’none’

When replication is turned off, Adaptive Server locks all user tables in exclusive mode and saves information about each of them. This process may take some time if there are a large number of user tables in the database.

Use this procedure only if you are disabling the warm standby application.

Note If you wish to turn off replication for the current isql session only, use the set replication command. See “Changing Replication for the Current isql Session” on page 427 for more information.

Using sp_setreptable to Enable ReplicationUse sp_setreptable to mark individual tables for replication to replicate or replicate and standby databases. Replication Server copies DML operations on those tables to the standby and replicate databases.

Use sp_setreptable to mark tables for replication to the standby database if:

• You use SQL Server databases, or

• You choose not to use sp_reptostandby.


425

Using sp_setreptable maintains data, but not schema, consistency between the active and standby databases. sp_setreptable normally does not copy supported DDL commands and procedures to the standby database. You can, however, use the set replication command to force replication of DDL commands for the current isql session. Refer to “Changing Replication for the Current isql Session” on page 427 for more information about set replication.

Using sp_setrepproc to Copy User Stored ProceduresTo copy the execution of a user stored procedure to the standby database, mark the stored procedure for replication with sp_setrepproc. Procedures marked with sp_setrepproc are also reproduced at replicate databases if subscriptions have been created for them.

There are two possible scenarios for stored procedure execution in warm standby applications:

• If you have marked the stored procedure for replication with sp_setrepproc, Replication Server copies execution of the procedure to the standby database. It does not copy the effects of the stored procedure to the standby database.

• If you have not marked the stored procedure for replication, Replication copies DML changes effected by the procedure to the standby database, if the affected tables have been marked for replication.

Refer to Chapter 9, “Managing Replicated Functions” for more information about the sp_setrepproc system procedure.

Replicating Tables with the Same Name but Different OwnersAdaptive Server and Replication Server allow you to replicate tables with the same name but different owners.

When you mark a database for replication with sp_reptostandby, updates are copied automatically to the table of the same name and owner in the standby database.

When you mark a table for replication using sp_setreptable, you can choose whether the table owner name is used to select the correct table in the standby database.


426

• If you set owner_on, Replication Server sends the table name and table owner name to the standby database.

• If you set owner_off, Replication Server sends the table name and “dbo” as the owner name to the standby database.

Note If you are copying information to a replicate database and have used sp_setreptable to set owner_off, Replication Server sends the table name to the replicate database. It does not send owner information.

Refer to “Enabling Replication with owner_on Status” on page 239 for syntax and other information about using sp_setreptable to set owner status.

Note If you mark a table with a non-unique name for replication and then create a replication definition for it, you must include owner information in the replication definition. Otherwise, Replication Server will be unable to find the correct table in the replicate or standby database.

Replicating text, image, and rawobject DataIf a database is marked with sp_reptostandby, the replication status is automatically replicate_if_changed, and Adaptive Server logs only text, image, and rawobject columns that have been changed. This ensures that the standby database stays in sync with the active database. You cannot change the replication status of such a table using sp_setrepcol.

If a table is marked for replication with sp_setreptable, the default replication status is always_replicate, and Adaptive Server logs all text, image, and rawobject column data. You can change the replication status of text, image, and rawobject columns in tables marked with sp_setreptable. Use sp_setrepcol to change the replication status to replicate_if_changed or do_not_replicate.

If you use replication definitions, make sure that replication status is the same at the Adaptive Server and the Replication Server. If the replication status differs, you must resolve the inconsistencies. Refer to “Resolving Inconsistencies in Replication Status” on page 251 for more information.


427

When Warm Standby Involves a Replicate Database

You can copy information from an active database to a standby database and also copy information from the active database to a replicate database. Replication Server must copy a table’s text, image, and rawobject columns to the standby and replicate databases with the same replication status.

Do not change the replication status for the table if you want to copy all text, image, and rawobject columns to the standby and replicate databases. By default, all text, image, and rawobject columns are copied to standby and replicate databases.

If you want to copy only text, image, and rawobject columns that have changed, use sp_setrepcol to set the replication status to replicate_if_changed.

Changing Replication for the Current isql SessionYou can use set replication to control replication of DML and/or DDL commands and procedures for an isql session.

Execute set replication at the Adaptive Server that manages the active database. The syntax is:

set replication [’on’ | ’force_ddl’ | ’default’ | ’off’]

The default setting is “on.” Default behavior depends on whether or not the database has been marked for replication with sp_reptostandby. Table 13-4 describes the default behavior of set replication.

Table 13-4: Default behavior of set replication

Some examples of set replication follow. Refer to “set replication” in Chapter 5, “Adaptive Server Commands and System Procedures” in the Replication Server Reference Manual for complete syntax and usage information.

Forcing Replication of DDL Commands to the Standby Database

To force replication of all supported DDL commands and system procedures for an isql session, enter:

If the database has been marked for replication with sp_reptostandby

If the database has not been marked for replication with sp_reptostandby

Replication Server copies DML and supported DDL commands to the standby database for all user tables.

Replication Server copies DML commands to standby and replicate databases for tables marked with sp_setreptable.

Setting Up Warm Standby Databases

428

set replication ’force_ddl’

This command enables replication of DDL commands and system procedures for tables marked with sp_setreptable.

To turn off force_ddl and return set replication to default status, enter:

set replication ’default’

Turning Off All Replication to the Standby Database

To turn off all replication to the standby database for an isql session, enter:

set replication ’off’

Setting Up Warm Standby DatabasesSetting up databases for a warm standby application involves three high-level tasks. Each of these tasks may include additional tasks.

1 Create a single logical connection that will be used by both the active and standby databases.

2 Use Sybase Central or rs_init to add the active database to the replication system. You do not need to add the active database if you have designated as the active database a database that was previously added to the replication system.

3 Use sp_reptostandby or sp_setreptable to enable replication for tables in the active database.

4 Use Sybase Central or rs_init to add the standby database to the replication system, then initialize the standby database.

Before You BeginBefore setting up the databases, note that:

• The Replication Server that manages the active and standby databases must be installed and running. A single Replication Server manages both the active and the standby database.


429

• The Adaptive Servers that contain the active and standby databases must be installed and running. Ideally, these databases should be managed by data servers running on different machines.

• Before you can add a database to the replication system as an active or standby database, it must already exist in the Adaptive Server.

See “Warm Standby Requirements and Restrictions” on page 418 for additional information.

Client Application Issues

Depending on your client applications and your method of initializing the standby database, you may be suspending transaction processing in the active database until you have initialized the standby database.

If you do not suspend transaction processing, ensure that Replication Server has sufficient stable queue space to hold the transactions that execute while you are loading data into the standby database.

Before you set up the warm standby databases, you should have decided on and implemented a mechanism for switching client applications to the new active database. See “Setting Up Clients to Work with the Active Data Server” on page 450 for more information.

Task One: Creating the Logical ConnectionThis section explains how to create the logical connection for the warm standby application. See “Database Connections in a Warm Standby Application” on page 416 for more information about logical connections.

This section also explains how to reconfigure RepAgent for the active database, which you must do if the active database was already part of the replication system.

For instructions on creating a logical connection in Sybase Central, see “Creating a logical connection” in Replication Server’s online help.

Naming the Logical Connection

When you create the logical connection, use the combination of logical data server name and logical database name, in the form data_server.database.

There are two methods for naming the logical connection:

RSM


430

• If the active database has not yet been added to the replication system – use a different name for the logical connection than for the active database. Using unique names for the logical and physical connections makes switching the active database more straightforward.

• If the active database has previously been added to the replication system – use the data_server and database names of the active database for the logical connection name. The logical connection inherits any existing replication definitions and subscriptions that reference this physical database.

When you create a replication definition or subscription for a warm standby application, specify the logical connection instead of a physical connection. Specifying the logical connection allows Replication Server to reference the currently active database.

See “Warm Standby Applications Using Replication” on page 457 for more information. Also see “Using Replication Definitions and Subscriptions” on page 464.

Procedure for Creating the Logical Connection

Follow these steps to create the logical connection:

1 Using a login name with sa permission, log in to the Replication Server that will manage the warm standby databases.

2 Execute the create logical connection command:

create logical connection to data_server.database

The data server name can be any valid Adaptive Server name, and the database name can be any valid database name.

Reconfiguring and Restarting RepAgent

If you designate as the active database a database that was previously added to the replication system, the RepAgent thread for the active database shuts down when you create the logical connection.

1 Reconfigure RepAgent with sp_config_rep_agent, setting the send_warm_standby_xacts configuration parameter.

2 Restart RepAgent.


431

For information about how to configure and start RepAgent, refer to “Setting Up RepAgent” on page 97. Refer to “sp_config_rep_agent” on page 5-10 in the Replication Server Reference Manual for more information about the sp_config_rep_agent system procedure.

If you are using an LTM as the replication agent, start the LTM using the -W command line flag. Refer to “ltm” in Chapter 7, “Programs,” in the Replication Server Reference Manual for information about the ltm program.

Task Two: Adding the Active DatabaseTo add a database to the replication system as the active database for a warm standby application, rs_init, as described in the Replication Server installation and configuration guides for your platform. Perform the steps described for adding a database to the replication system.

For instructions on adding an active database in Sybase Central, see “Adding the active database” in Replication Server’s online help.

Note Remember, you do not need to add the active database if you have designated a database that is already part of the replication system as the active database.

Task Three: Enabling Replication for Objects in the Active DatabaseYou can enable replication for tables in the active database in either of two ways:

• Use sp_reptostandby to mark the database for replication, enabling replication of data and supported schema changes.

• Use sp_setreptable to mark individual tables for replication of data changes.

Refer to “What Information Is Replicated?” on page 420 for more information about these commands.

1 Log in to the Adaptive Server as the System Administrator or as the Database Owner, and:

use active_database

2 Mark database tables for replication, using one of these methods:

RSM


432

• Mark all user tables by executing the sp_reptostandby system procedure:

sp_reptostandby dbname, [ ’L1’ | ’all’ ]

where dbname is the name of the active database, L1 sets the replication level to that of Adaptive Server version 11.5, and all sets the replication level to the current version of Adaptive Server. This method replicates both DML and DDL commands and procedures.

• Mark individual user tables by executing the sp_setreptable system procedure for each table that you want to replicate into the standby database:

sp_setreptable table_name, ’true’

where table_name is the name of the table. This method replicates DML commands.

3 If you are using the replicated functions feature described in Chapter 9, “Managing Replicated Functions” execute the following system procedure for every stored procedure whose executions you want to replicate into the standby database:

sp_setrepproc proc_name, ’function’

4 If you are using replicated stored procedures associated with table replication definitions, as described in Appendix A, “Asynchronous Stored Procedures” execute the following system procedure for every such stored procedure whose executions you want to replicate into the standby database:

sp_setrepproc proc_name, ’table’

Enabling Replication for Objects Added Later

Later on, you may add new tables and user stored procedures that you want to replicate to the standby database.

• If you marked the database for replication with sp_reptostandby, new tables are automatically marked for replication.

• If you marked database tables for replication to the standby database with sp_setreplicate, you must mark each new table that you want to replicate with sp_setreplicate.

• You must mark each new user stored procedure that you want to replicate with sp_setrepproc.


433

Task Four: Adding the Standby DatabaseUse rs_init to add the standby database and its RepAgent to the replication system, then you initialize it with data from the active database.

For instructions on adding the standby database in Sybase Central, see “Adding the standby database” in Replication Server’s online help.

This section explains how to add the standby database to the replication system and prepare it for operation.

This section also describes enabling replication for objects in the standby database and granting permissions to the maintenance user in the standby database. Whether or not you need to perform these steps depends on your method for initializing the standby database.

Before you add the standby database:

1 Create the standby database, if it does not already exist.

2 Determine how to initialize the standby database.

3 Add the standby database maintenance user—if you are using dump and load to initialize the standby database.

Creating the Standby Database

If it does not already exist, you must create the standby database in the appropriate Adaptive Server, according to your needs.

Refer to the Adaptive Server System Administration Guide for details on creating databases.

Determining How to Initialize the Standby Database

You initialize the standby database with data from the active database. To do this, you use the Adaptive Server dump and load commands or the Adaptive Server bcp utility program.

Replication Server writes an “enable replication” marker into the active database transaction log when you add the standby database using Sybase Central or rs_init. Adaptive Server writes a dump marker into the active database transaction log when you perform a dump operation.

If you do not suspend transaction processing during initialization:

• Choose the “dump marker” option in Sybase Central or rs_init, and use the dump and load commands.

RSM


434

If you suspend transaction processing during initialization:

• Do not choose the “dump marker” option in Sybase Central or rs_init, and use the dump and load commands, or

• Use bcp.

Table 13-5 summarizes each of the initialization methods and the role of these markers.

Table 13-5: Issues in initializing the standby database

If You Do Not Suspend Transaction Processing

If you do not suspend transaction processing for the active database while initializing the standby database, choose the “dump marker” option when you add the standby database. Then initialize the standby database by using the dump and load commands.

IssueUse dump and load with “dump marker”

Use dump and load without “dump marker” Use bcp

Working with client applications.

Use if you do not suspend transaction processing for client applications.

Use if you suspend transaction processing for client applications.

When does Replication Server begin replicating into the standby database?

Replication Server starts replicating into the standby database from the first dump marker after the enable replication marker.

Replication Server starts replicating into the standby database from the enable replication marker.

Creating maintenance user login names and making sure all user IDs match.

Add the login name for the standby database maintenance user in both the active Adaptive Server and the standby Adaptive Server, and ensure that the server user’s IDs match.

(You create login names in the active Adaptive Server because using dump and load to initialize the standby database with data from the active database overrides any previous contents of the standby database with the contents of the active database.)

When you add the standby database, Sybase Central or rs_init adds the maintenance user login name and user in the standby Adaptive Server and the standby database.

Initializing standby database.

Use dump and load to transfer data from the active database to the standby database.

You can use database dumps and/or transaction dumps.

Use bcp to copy each replicated table from the active database to the standby database.

Active database connection state.

The connection to the active database does not change.

Replication Server suspends the connection to the active database.

Resuming connections.

Resume connection to the standby database.

Resume connections to the active and standby databases; resume transaction processing in the active database.


435

Replication Server starts replicating into the standby database from the first dump marker after the enable replication marker in the transaction log of the active database.

In Figure 13-2, transaction T1, executed after you added the standby database, appears after the enable replication marker in the log. T1 is included in dumps, so it is present in the standby database after you have loaded the dumps. Replication Server does not need to replicate it into the standby database.

Figure 13-2: Using dump and load with dump marker

Transactions can be executed in the active database between the time the enable replication marker is written and the time the data in the active database is dumped.

You can load the last full database dump and any subsequent transaction dumps into the standby database until both markers have been received and the standby database is ready for operation. Then, optionally, you can use a final transaction dump of the active database to bring the standby database up to date. Any transactions not included in dumps will be replicated.

Replication Server does not replicate transactions from the active to the standby database until it has received both the enable replication marker and the first subsequent dump marker. After receiving both markers, Replication Server starts executing transactions in the standby database.

See Table 13-5 for more information about this method.

If You Suspend Transaction Processing

If you suspend transaction processing for the active database while initializing the standby database, do not choose the “dump marker” option when you add the standby database. You can initialize the standby database by using the dump and load commands or by using bcp.

LogGrows

Enable Marker

Dump Marker

Active DatabaseTransaction Log

T1

Included in Dumps,and Loaded in theStandby Database

Applied to theStandby Database


436

Replication Server starts replicating into the standby database from the enable replication marker in the transaction log of the active database. No transactions occur after the enable replication marker, because client applications are suspended.

Figure 13-3: Using dump and load without dump marker, or using bcp

As shown in Figure 13-3, no transactions are executed in the active database between the time the enable replication marker is written and the time the data in the active database is dumped using the dump command or copied using bcp.

You can load the last full database dump or the last set of replicated tables copied with bcp into the standby database until the standby database receives the enable replication marker.

After receiving this marker, Replication Server starts executing transactions in the standby database.

Adding the Standby Database Maintenance User

If you plan to initialize the standby database using the dump and load commands, with or without the “dump marker” option, you must create the maintenance user login name for the standby database in both the standby and the active data servers. Do this before you add the standby database.

Both Sybase Central and rs_init automatically add the active database maintenance user in the active data server when you add the active database.

Making the Server User’s IDs Match

Within each data server, the server user’s ID (suid) for each login name must be the same in the syslogins table in the master database and the sysusers table in each user database. This must be true for the active and standby databases in a warm standby application. The server user’s ID and role settings must also be the same in the syslogins and sysloginroles tables in the master database.

Included in Dumps,and Loaded in theStandby DatabaseLog

GrowsEnable Marker

Active DatabaseTransaction Log

Applied to theStandby Database


437

Use one of these three methods to make the server user’s IDs match:

• Add all login names, including maintenance user names, to both Adaptive Servers in the same order. Adaptive Server assigns server user’s IDs sequentially, so the server user’s IDs for all login names will match.

• After loading the dump into the standby, reconcile the sysusers table in the standby database with the syslogins table in the master database of the standby Adaptive Server.

• Maintain a master Adaptive Server with all of your login names and copy the syslogins table from the master database for the master Adaptive Server to all newly created Adaptive Servers.

Adding the Maintenance User

To add the maintenance user login name for the standby database to both the standby and the active data servers:

1 In the standby data server, execute the sp_addlogin system procedure to create the maintenance user login name.

Refer to the Adaptive Server System Administration Guide for more information about using sp_addlogin.

2 In the active data server, execute sp_addlogin to create the same maintenance user login name that you created in the standby data server.

When you set up the standby database using the dump and load commands, the sysusers table is loaded into the standby database along with the other data from the active database.

Adding the Standby Database to the Replication System

To add the standby database to the replication system:

1 Suspend transaction processing in the active database, if appropriate for your client applications and your method of initializing the standby database.

You must use dump and load with the “dump marker” method if you do not suspend transaction processing.

2 Use Sybase Central or rs_init to add the standby database to the replication system. Perform the steps described for adding a database to the replication system.

3 To monitor the status of the logical connection at any time, enter:

admin logical_status, logical_ds, logical_db


438

The Operation in Progress and State of Operation in Progress output columns indicate the standby creation status.

4 If you are initializing the standby database using dump and load, use the dump command to dump the contents of the active database, and load the standby database. For example:

dump database active_database to dump_deviceload database standby_database from dump_device

5 If you have already loaded a previous database dump and subsequent transaction dumps, you can just dump the transaction log and load it into the standby database. For example:

dump transaction active_database to dump_deviceload transaction standby_database from dump_device

6 After completing load operations, bring the standby database online:online database standby_database

Refer to the Adaptive Server Reference Manual for help with using the dump and load commands and the online database command.

7 To initialize the standby database using bcp, copy each of the replicated tables in the active database to the standby database.

You must copy the rs_lastcommit table, which was created when you added the active database to the replication system.

Refer to the Adaptive Server utility programs manual for help with using the bcp program.

8 If you initialized the standby database by using dump and load without the “dump marker” method, or by using bcp, Replication Server suspended the connection to the active database. Resume the connection by executing the following command in the Replication Server:

resume connection to active_ds.active_db

9 Regardless of your method for initializing the standby database, you must resume the connection to the standby database by executing the following command:

resume connection to standby_ds.standby_db

10 Resume transaction processing in the active database, if it was suspended.

Using a Blocking Command for Standby Creation

In Replication Server, the wait for create standby command is a blocking command. It tells Replication Server not to accept commands until the standby database is ready for operation. You can use this command in a script that creates a standby database. The syntax is:


439

wait for create standby for logical_ds.logical_db

Enabling Replication for Objects in the Standby Database

To be ready to switch to the standby database, replication must be enabled for the tables and stored procedures in the standby database that you want to replicate into the new standby database after the switch.

• If you initialized the standby database using the dump and load commands, the tables and stored procedures in the standby database will have the same replication settings as the active database.

• If you initialized the standby database using bcp, enable replication for these objects by using sp_setreptable or sp_reptostandby, and sp_setrepproc. To do this, adapt the procedure under “Task Three: Enabling Replication for Objects in the Active Database” on page 431 to enable replication for objects in the standby database.

Enabling Replication for Objects Added Later

Later on, you may add new tables and user stored procedures that you want to replicate to the new standby database.

• If you marked the standby database for replication with sp_reptostandby, any new tables are automatically marked for replication.

• If you marked individual database tables for replication to the new standby database with sp_setreplicate, you must mark each new table that you want to replicate with sp_setreplicate.

• You must mark each new user stored procedure that you want to replicate with sp_setrepproc.

Granting Permissions to the Maintenance User

After adding the standby database, you must grant the necessary permissions to the maintenance user.

To grant permissions:

1 Log in to the Adaptive Server as the System Administrator or as the Database Owner, and enter:

use standby_database

2 Grant replication_roleto the maintenance user. replication_role ensures that the maintenance user can execute truncate table at the standby database.

sp_role “grant”, replication_role, maintenance_user

Switching the Active and Standby Databases

440

3 Execute this command for each table:grant all on table_name to maintenance_user

Switching the Active and Standby DatabasesThis section contains information about switching to the standby database when the active database fails or when you want to perform maintenance on the active database.

Determining If a Switch Is NecessaryDetermining when it is necessary to switch from the active to the standby database depends on the requirements of your applications.

In general, you should not switch when the active data server experiences a transient failure. A transient failure is a failure from which the Adaptive Server recovers upon restarting with no need for additional recovery steps. You probably should switch if the active database will be unavailable for a long period of time.

Determining when to switch depends on issues such as how much recovery the active database requires, to what degree the active and standby databases are in sync, and how much downtime your users or applications can tolerate.

You may also want to switch the roles of the active and standby databases to perform planned maintenance on the active database or its data server.

Before Switching Active and Standby DatabasesFigure 13-4 illustrates a warm standby application for a database that does not participate in the replication system other than through the activities of the warm standby application itself. Figure 13-4 represents the warm standby application in normal operation, before you switch the active and standby databases.


441

Figure 13-4: Warm standby application example—before switching

Figure 13-4 adds internal detail to Figure 13-1, to show that:

• Replication Server writes transactions received from the active database into an inbound message queue.

See “Distributed Concurrency Control” on page 47 for more information about inbound and outbound queues.

• This inbound queue is read by the DSI thread for the standby database, which executes the transactions in the standby database.

Messages received from the active database cannot be truncated from the inbound queue until the standby DSI thread has read them and applied them to the standby database.

In this example, transactions are simply replicated from the active database into the standby database. The logical database itself does not:

• Contain primary data that is replicated to replicate databases or remote Replication Servers, or

• Receive replicated transactions from another Replication Server

See “Warm Standby Applications Using Replication” on page 457 for information about warm standby applications for a primary or replicate database.

StandbyDSI

Inbound Queue

StandbyDatabase

ActiveDatabase

Replication Server

Clients


442

Internal Switching StepsWhen you switch active and standby databases, here is what Replication Server does:

1 Suspends the connection to the active database and suspends the active database RepAgent.

2 Reads all messages left in the inbound queue and applies them to the standby database and, for subscription data or replicated stored procedures, to outbound queues.

All committed transactions in the inbound queue must be processed before the switch can complete.

3 Suspends the standby DSI.

4 Enables the secondary truncation point in the new active database.

5 Places a marker in the transaction log of the new active database. Replication Server uses this marker to determine which transactions to apply to the new standby database and to any replicate databases.

6 Updates data in the RSSD pertaining to the warm standby databases.

7 Resumes the connection for the new active database, and resumes log transfer for the new active database so that new messages can be received.

After Switching Active and Standby DatabasesAfter you have switched the roles of the active and standby databases, the replication system will have changed, as shown in Figure 13-5:


443

Figure 13-5: Warm standby application example—after switching

• The previous standby database is the new active database. Client applications will have switched to the new active database.

• The previous active database, in this example, becomes the new standby database. Messages for the previous active database are queued for application to the new active database.

Note RepAgent for the previous active database has shut down. RepAgent for the new active database has started.

Making the SwitchTo switch from the active to the standby database:

• Disconnect client applications from the active database if they are still using it

• In Replication Server, switch the active and standby databases

• Restart client applications with the new active database

• Start RepAgent for the new active database

• Determine whether to drop the old active database or use it as the new standby database

The following sections contain the procedures for these tasks.

StandbyDSI

Inbound Queue

StandbyDatabase

ActiveDatabase

Replication Server

Clients


444

For instructions about switching to the active database in Sybase Central, see “Switching the active and standby databases” in Replication Server’s online help.

Disconnect Client Applications from the Active Database

Before you switch to the standby database, you must stop clients from executing transactions in the active database. If the database failed, of course, clients cannot execute transactions. However, you may need to take steps to prevent them from updating that database after it is back online.

See “Setting Up Clients to Work with the Active Data Server” on page 450 for more information about client application issues.

Procedure for Switching the Active and Standby Databases

Before switching, you must implement a method for switching clients, as described in “Setting Up Clients to Work with the Active Data Server” on page 450.

Follow these steps to switch the active and standby databases for a logical connection:

1 At the Adaptive Server, use sp_stop_rep_agent to shut down RepAgent.

Step 1 is optional. If you do not shut down RepAgent, it will eventually shut itself down or be suspended after you enter the switch active command.

2 At the Replication Server, enter:

switch active for logical_ds.logical_dbto data_server.database

where data_server.database is the new active database.

See “Internal Switching Steps” on page 442 for information on what Replication Server does when you switch.

3 To monitor the progress of a switch, you can use the admin logical_status command:

admin logical_status, logical_ds, logical_db

The Operation in Progress and State of Operation in Progress output columns indicate the switch status.

RSM


445

4 When the active database switch is complete, you must restart RepAgent for the new active database:

sp_start_rep_agent_thread dbname

Note If Replication Server stops in the middle of switching, the switch resumes after you restart Replication Server.

Using a Blocking Command for Switch Active

In Replication Server, the wait for switch command is a blocking command. It tells Replication Server to wait until the standby database is ready for operation. You can use this command in a script that switches the active database. The syntax is:

wait for switch for logical_ds.logical_db

Monitoring the Switch

You can use admin logical_status to check for replication system problems that prevent the switch from proceeding. Such problems may include a full transaction log for the standby database or a suspended standby DSI. If you cannot resolve the problems, you can abort the switch using the abort switch command.

The Operation in Progress and State of Operation in Progress output columns indicate the switch status.

For example, suppose the admin logical_status command persistently returns one of the following messages in its State of Operation in Progress output column:

Standby has some transactions that have not been applied

or

Inbound Queue has not been completely read by Distributor

These messages may indicate a problem that you cannot resolve, in which case you may choose to abort the switch. You can use admin who commands to obtain more information about the state of the switching operation.

See “Commands for Monitoring Warm Standby Applications” on page 449 for more information.


446

Aborting a Switch

Unless Replication Server has proceeded too far in switching the active and standby databases, you can abort the process by using the abort switch command:

abort switch for logical_ds.logical_db

If the abort switch command cancels the switch active command successfully, you may have to restart the RepAgent for the active database.

You cannot cancel the switch active command after it reaches a certain point. If this is the case, you must wait for the switch active command to complete, then use it again to return to the original active database.

Restart Client Applications

When the admin logical_status command indicates that there is no operation in progress, or when the wait for switch command returns an isql prompt, you can restart client applications in the new active database.

Client applications must wait until Replication Server’s switch to the new active database is complete before they begin executing transactions in the new active database. You should provide an orderly method for moving clients from the old active database to the new active database. See “Setting Up Clients to Work with the Active Data Server” on page 450 for more information.

Resolving Paper-Trail Transactions

If the old active database failed, determine if any transactions were not transmitted to the new active database. Such transactions are called paper-trail transactions if there is an external record of their execution.

When you switch from an active to a standby database, all committed transactions in the inbound queue are applied to the new active database before the switch is complete. However, it is possible that some transactions that committed at the active database before the failure were not received by Replication Server and, therefore, were not applied to the standby database.

When you switch the active and standby databases, you can re-execute the paper-trail transactions in the new active database. If there are dependencies, you may need to re-execute the paper-trail transactions before you allow new transactions to execute. Be sure to execute the paper-trail transactions using the original client’s login name, not the maintenance user login name.


447

If you bring the old active database online as the new standby database, you must first reverse the paper-trail transactions so they will not be duplicated in the standby database.

Manage the Old Active Database

After you have switched to the new active database, you must decide what to do with the old active database. You can:

• Bring the database online as the new standby database and resume the connection so that Replication Server can apply new transactions, or

• Drop the database connection using the drop connection command, and add it again later as the new standby database. If you drop the database, any queued messages for the database are deleted. Refer to “drop connection” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual.

Bringing the Old Active Database Online As the New Standby

If the old active database is undamaged, you can bring it back online as the new standby database by entering:


where data_server.database is the physical database name of the old active database.

You may need to resolve paper-trail transactions in the database in order to avoid duplicate transactions. Depending on your applications, you may need to do this before you bring the old active database back online as the new standby database.

Because paper-trail transactions must be re-executed in the new active database, you must prepare the new standby database so that it can receive the transactions again when they are delivered through the replication system.

To resolve the conflicts, you can:

• Undo or reverse the duplicate transactions in the new standby database, or

• Ignore the duplicate transactions and deal with them later.

Monitoring a Warm Standby Application

448

Monitoring a Warm Standby ApplicationThis section describes methods you can use to monitor a warm standby application.

Replication Server Log FileYou can read the Replication Server log file for messages pertaining to warm standby operations. This section discusses log messages you will see when you add the standby database.

Standby Connection Created

These are examples of the messages that Replication Server writes while creating the physical connection for a standby database:

I. 95/11/01 17:47:50. Create starting : SYDNEY_DS.pubs2I. 95/11/01 17:47:58. Placing marker in TOKYO_DS.pubs2 logI. 95/11/01 17:47:59. Create completed : SYDNEY_DS.pubs2

In these examples, SYDNEY_DS is the standby data server and TOKYO_DS is the active data server.

When you create the physical connection for the standby database, Replication Server writes an “enable replication” marker in the active database transaction log. The standby DSI ignores all transactions until it has received this marker. If, however, you chose the “dump marker” option, the standby DSI continues to ignore messages until it encounters the next dump marker in the log.

When the appropriate marker arrives at the standby database from the active database RepAgent, the standby DSI writes a message in the Replication Server log file and then begins executing subsequent transactions in the standby database.

In the example messages above, Replication Server has created the connection for the standby database, SYDNEY_DS.pubs2, and suspended its DSI thread. At this point, the Database Administrator dumps the contents of the active database, TOKYO_DS.pubs2, and loads it into the standby database.


449

Standby Connection Resumed After Initialization

After the Database Administrator has loaded the dump into the standby database and resumed the connection to the standby database, the standby DSI begins processing messages from the active database. Replication Server writes in its log messages similar to this:

I. 95/11/01 18:50:34. The DSI thread for database ’SYDNEY_DS.pubs2’ is started.I. 95/11/01 18:50:41. Setting LTM truncation to ’ignore’ for SYDNEY_DS.pubs2 logI. 95/11/01 18:50:43. DSI for SYDNEY_DS.pubs2 received and processed Enable

Replication Marker. Waiting for Dump MarkerI. 95/11/01 18:50:43. DSI for SYDNEY_DS.pubs2 received and processed Dump

Marker. DSI is now applying commands to the Standby

When you see the final message in the log file, the warm standby database creation process has completed.

Commands for Monitoring Warm Standby ApplicationsUse the admin commands to monitor the status of a warm standby application. Refer to Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for more information about these commands.

admin logical_statusThe admin logical_status command tells you:

• How the addition of a standby database or the switching between active and standby databases is progressing.

• Whether the active or standby database connection is suspended.

• Whether the standby DSI is ignoring messages. The standby DSI ignores messages while it waits for a marker to arrive in the transaction stream from the active database.

admin who, dsiThe admin who, dsi command provides another method to check the status of the standby DSI. The IgnoringStatus output column contains either:

• “Applying” – if the DSI is applying messages to the standby database, or

• “Ignoring” – if the DSI is waiting for a marker.

Setting Up Clients to Work with the Active Data Server

450

admin who, sqmThe admin who, sqm command provides information about the state of stable queues. In a warm standby application, the inbound queue is read by the Distributor thread, if you have not disabled it, and by the standby DSI thread. Replication Server cannot delete messages from the inbound queue until both threads have read and delivered them.

If Replication Server is not deleting messages from the inbound queue, you can use the admin who, sqm command to investigate the problem. The command tells you how many threads are reading the queue and the minimum deletion point in the queue.

admin sqm_readersThe admin sqm_readers command monitors the read and delete points of the individual threads that are reading the inbound queue. If the inbound queue is not being deleted, admin sqm_readers will help you find the thread that is not reading the queue.

The admin sqm_readers command takes two parameters: the queue number and the queue type for the logical connection.

You can find the queue number and queue type in the Info column of the admin who, sqm command output: the queue number is the 3-digit number to the left of the colon, while the queue type is the digit to the right of the colon.

Queue type 1 is an inbound queue. Queue type 0 is an outbound queue. The inbound queue for a logical connection can be read by more than one thread. For example, to find out about the threads reading inbound queue number 102, execute admin sqm_readers as follows:

admin sqm_readers, 102, 1

Setting Up Clients to Work with the Active Data ServerWhen you switch the active and standby databases in Replication Server using the switch active command, Replication Server does not switch client applications to the new active data server and database automatically. You must devise a method to switch client applications. This section describes three sample methods for setting up client applications to connect to the currently active data server. You can create:

• Two interfaces files


451

• An interfaces file entry with a symbolic data server name for client applications

• A mechanism that automatically maps the client application data server connections to the currently active data server

You must implement your method before you set up the warm standby databases.

Regardless of your method for switching applications, do not modify the interfaces file entries used by Replication Server.

Two Interfaces FilesWith this method, you set up two interfaces files, one for the client applications and one for Replication Server. When you switch the clients, you can modify their interfaces file entry to use the host name and port number of the data server with the new active database.

Symbolic Data Server Name for Client ApplicationsWith this method, you create an interfaces file entry with a symbolic data server name for client applications.

The interfaces file might contain entries like these:

Table 13-6: Symbolic data server name in interfaces file

You could create an interfaces entry for a data server named CLIENT_DS. Client applications would always connect to CLIENT_DS. The CLIENT_DS entry would use the same host name and port number as the data server with the active database.

Replication Server connects to the same host name and port number as the client applications but uses a different data server name. In this example, Replication Server would switch between the TOKYO_DS_X and TOKYO_DS_Y data servers.

Data Server Name Host Name Port Number

Client applications CLIENT_DS machine_1 2800

Active database TOKYO_DS_X machine_1 2800

Standby database TOKYO_DS_Y machine_2 2802

Altering Warm Standby Database Connections

452

After switching the active database, you would change the CLIENT_DS interfaces entry to the host name and port number of the data server with the new active database—in this example, machine_2 and port number 2802.

Map Client Data Server to Currently Active Data ServerWith this method, you create a mechanism, such as an intermediate Open Server application, that automatically maps the client application data server connections to the currently active data server.

Refer to Open Server documentation, such as the Open Server Server-Library/C Reference Manual, for more information about how to create such an Open Server application.

Altering Warm Standby Database ConnectionsThis section describes options for reconfiguring or modifying the logical database connection and the physical database connections. Under ordinary circumstances, if you set up a warm standby application through the usual procedure, the default settings will work correctly.

Altering Logical ConnectionsUse the alter logical connection command to modify parameters that:

• Affect logical connections

• Enable or disable the Distributor thread

• Enable or disable the replication of truncate table to the standby database

Changing Parameters Affecting Logical Connections

To update parameters that affect logical connections, log in to the source Replication Server and, at the isql prompt, enter:

alter logical connection to logical_ds.logical_db set logical_database_param to ’value’


453

where logical_ds is the data server name for the logical connection, logical_db is the database name for the logical connection, logical_database_param is a logical database parameter, and value is a character string setting for the parameter.

New settings take effect immediately.

Warning! You should reset the logical connection parameters materialization_save_interval and save_interval only when there is a serious lack of stable queue space. Resetting them (from strict to a given number of minutes) may lead to message loss at the standby database.

Table 13-7 displays the configuration parameters that affect logical database connections.

Table 13-7: Configuration parameters affecting logical connections

Disabling the Distributor Thread

If you do not replicate data from the active database into databases other than the standby database, Replication Server does not need a Distributor thread for the logical connection. You can disable the Distributor thread to save Replication Server resources.

To disable the Distributor thread, you must first drop any subscriptions for the data in the logical database. Then execute alter logical connection at the Replication Server:

alter logical connection to logical_ds.logical_dbset distribution off

logical_database_param value

materialization_save_interval Materialization queue save interval. This parameter is only used for standby databases in a warm standby application.

Default: “strict” for standby databases

save_interval The number of minutes that the Replication Server saves messages after they have been successfully passed to the destination data server. See “Save Interval for Recovery” on page 523 for details.

Default: 0 minutes


454

If you decide later to replicate data out of the active database, you can use this command to reenable the Distributor thread.

Warning! If you disable the Distributor thread and then drop the standby database from the replication system, no Replication Server threads will be left to read the inbound queue from the active database. The inbound queue will continue to fill until you either add another standby database, set distribution to “on” for the logical connection, or drop the active database from the replication system.

Replicating truncate table to Standby Databases

Replication Server copies execution of truncate table to warm standby databases. The active and standby databases must be Adaptive Server version 11.5 or later to support this feature.

To enable or disable replication of truncate table, log in to the source Replication Server and enter:

alter logical connection to logical_ds.logical_db set send_truncate_table to {on | off}

If your warm standby application was created before you upgraded or installed Replication Server version 11.5 or later, Replication Server does not copy truncate table to the standby database unless you enable this feature with alter logical connection. To preserve compatibility with existing warm standby applications, the default setting is “off.”

If your warm standby application was created after you upgraded or installed Replication Server version 11.5 or later, Replication Server automatically copies truncate table to the standby database unless you disable this feature with alter logical connection. The default setting is “on.”

Altering Physical ConnectionsUse the alter connection command at the source Replication Server to modify parameters that affect physical connections for warm standby applications:

alter connection to data_server.databaseset database_param to ’value’


455

where data_server is the destination data server, database is the database the data server manages, database_param is a parameter that affects the connection and value is a setting for database_param.

You must suspend the connection before altering it; then, after executing alter connection, you resume the connection for new parameter settings to take effect. Refer to “Altering Database Connections” on page 150 for more information.

Configuring Triggers in the Standby Database

By default, the standby DSI thread executes a set triggers off Adaptive Server command when it logs in to a standby database. This prevents Adaptive Server from firing triggers for the replicated transactions, thereby preventing duplicate updates in the standby database.

You can alter the default behavior by using the alter connection command to configure a connection to fire or not fire triggers. To do this, set the dsi_keep_triggers configuration parameter to “on” or “off.” The default dsi_keep_triggers setting for all connections except standby databases is “on.”

Configuring Replication in the Standby Database

The dsi_replication configuration parameter specifies whether or not transactions applied by the DSI are marked in the transaction log as being replicated. It must be set to “on” for the active replicate database. By default, it is set to “off” for the standby database and set to “on” for all other databases.

When dsi_replication is set to “off,” the DSI executes set replication off in the database, preventing Adaptive Server from adding replication information to log records for transactions that the DSI executes. Since these transactions are executed by the maintenance user and, therefore, are not replicated further (except if there is a standby database), setting this parameter to “off” where appropriate writes less information into the transaction log.

Use admin who, dsi to see how this parameter is set for a connection.

Changing Configuration Parameters in the Standby Database

When you create the standby database, the following configuration parameters, if they are set for the active database, are copied from the active database to the standby database:


456

Table 13-8: Configuration parameters copied to standby database

You can change the setting of any of these configuration parameters. See Chapter 6, “Managing Database Connections” for more information.

Dropping Logical Database ConnectionsIf you are dismantling a warm standby application, you may need to remove a logical database from the replication system. To do this, drop the standby database, then execute the drop logical connection command. Before you execute the command, you must drop the standby database. See “Dropping Database Connections” on page 164 for information about dropping physical database connections.

The syntax for drop logical connection is:

drop logical connection to data_server.database

where data_server and database represent the logical data server and logical database.

For example, to drop the connection to the pubs2 logical database in the LDS logical data server, enter:

drop logical connection to LDS.pubs2

Dropping a Logical Database from the ID Server

When a warm standby application exists in the replication system, logical databases, along with physical databases, data servers, and Replication Servers, are listed in the rs_idnames system table in the RSSD for the ID Server. Occasionally, it may be necessary to remove the entry for a logical database from this system table.

batch batch_begin command_retry

db_packet_size dsi_charset_convert dsi_cmd_batch_size

dsi_cmd_separator dsi_fadeout_time dsi_keep_triggers

dsi_large_xact_size dsi_max_cmds_to_log dsi_max_text_to_log

dsi_num_large_xact_threads dsi_num_threads dsi_replication

dsi_serialization_method dsi_sql_data_style dsi_sqt_max_cache_size

dsi_xact_group_size dsi_xact_in_group dump_load

parallel_dsi


457

For example, if a drop logical connection command fails, you may have to force the ID Server to delete from the rs_idnames system table the row that corresponds to the logical database. Logical database connections show an “L” in the ltype column.

The sysadmin dropldb command logs in to the ID Server and deletes the entry for the specified logical database. The syntax is:

sysadmin dropldb, data_server, database

where data_server and database refer to the logical data server and the logical database names.

You must have sa permission to execute any sysadmin command.

Warm Standby Applications Using ReplicationThis section describes warm standby applications that involve replication, where the logical database serves as a primary or replicate database in the replication system.

Also see “Using Replication Definitions and Subscriptions” on page 464.

Warm Standby Application for a Primary DatabaseFigure 13-6 illustrates a warm standby application for a primary database. In this example, one Replication Server manages three databases:

• The active database for a logical primary database,

• The standby database for a logical primary database, and

• A replicate database that has subscriptions for the data in the logical primary database.

In this example, a single Replication Server manages both the primary and replicate databases. In other instances, different Replication Servers may manage the primary and replicate databases.

Warm Standby Applications Using Replication

458

Figure 13-6: Warm standby application for a primary database

The numbers in Figure 13-6 indicate the flow of transactions from client applications through the replication system in a warm standby application for a primary database.

From Client Applications to Inbound Queue

Numbers 1 through 3 trace transactions from clients to an inbound queue in the Replication Server:

1 Clients execute transactions in the active primary data server.

2 The active primary data server updates the active primary database.

3 The RepAgent thread for the active primary database reads transactions for replicated data in the database log. It forwards the transactions to the Replication Server, which writes them into an inbound queue.

All transactions for replicated data, including those executed by the maintenance user, are sent to the Replication Server for application in the standby database.

From Inbound Queue to Replicate Database

Numbers 1 through 5 trace transactions from the inbound queue to the replicate database:

1 The Distributor thread reads transactions from the inbound queue.


459

2 The Distributor thread processes transactions against subscriptions and writes replicated transactions into an outbound queue.

Transactions executed by the maintenance user, which are always replicated into the standby database (because you set the send_warm_standby_xacts parameter when you configure RepAgent with sp_config_rep_agent), are not replicated to replicate databases unless you also set the send_maint_xacts_to_replicate parameter for RepAgent.

3 A DSI thread reads transactions from the outbound queue.

4 The DSI thread executes the transactions in the replicate data server.

5 The replicate data server updates the replicate database.

If the transactions are to be replicated to a database managed by a different Replication Server, they are written into an RSI outbound queue managed by an RSI thread instead of a DSI thread. The RSI thread delivers the transactions to the other Replication Server.

From Inbound Queue to Standby Database

Numbers 1 through 3 trace transactions from the inbound queue to the standby database for the logical primary database:

1 The standby DSI thread reads transactions from the inbound queue.

2 The standby DSI thread executes transactions in the standby data server.

3 The standby data server updates the standby database.

The inbound queue is read by the standby DSI and the Distributor. The two threads do their work concurrently. Messages cannot be truncated from the inbound queue until both threads have read them and delivered them to their destination. The messages remain in the queue until the DSI has applied them to the standby database and, if there are subscriptions or replicated stored procedure executions, the Distributor has written them to the outbound queue.

Depending on your replication system, the transactions may be replicated into the standby database before the replicate database. However, Replication Server guarantees that the standby primary database and replicate databases will be kept in sync with the active primary database.

Warm Standby Application for a Replicate DatabaseFigure 13-7 illustrates a warm standby application for a replicate database. In this example, a single Replication Server manages three databases:


460

• A primary database,

• The active database for a logical replicate database, and

• The standby database for a logical replicate database.

The logical replicate database has subscriptions for the data in the primary database. Therefore, updates from the primary database are replicated to both the active and the standby databases.

In this example, a single Replication Server manages both the primary and replicate databases. In other instances, different Replication Servers may manage the primary and replicate databases.


461

Figure 13-7: Warm standby application for a replicate database

The numbers in Figure 13-7 indicate the flow of transactions from client applications through the replication system in a warm standby application for a replicate database.

From Client Applications to Primary and Active Databases

Numbers 1 through 8 trace transactions from clients to the primary database, and, via normal replication, to the active replicate database:

1 Clients execute transactions in the primary data server.

2 The primary data server updates the primary database.

StandbyDatabase

StandbyData Server

DSI

Inbound Queue

Inbound Queue

ActiveDatabase Standby

DSI

PrimaryData Server

Primary Database

2

8

9

12

7

4

11

10

Distributor

5

6

Outbound Queue

Clients

1

Replication Server

ActiveData Server

If Replication Server does not manage the primary database, replicated data is received from the primaryReplication Server and written directly into the out-bound queue, bypassing steps 1–5.

3


462

3 RepAgent for the primary database reads transactions for replicated data in the transaction log and forwards them to the Replication Server, which writes them into an inbound queue.

4 The Distributor thread reads transactions from the inbound queue.

5 The Distributor processes transactions against subscriptions and writes replicated transactions into an outbound queue.

If the Replication Server managing the warm standby application for the replicate database does not also manage the primary database, replicated data is received from the primary Replication Server and written directly to the outbound queue. Steps 1 through 5 are bypassed.

6 A DSI thread reads transactions from the outbound queue.

7 The DSI thread executes the transactions in the replicate data server, which is the active data server for the warm standby application.

8 The active data server updates the active database.

If the transactions originate in a primary database managed by a different Replication Server, the Distributor thread in the primary Replication Server writes them into an RSI outbound queue. Then they are replicated to a DSI outbound queue in the replicate Replication Server in order to be applied in the active database for the logical replicate database.

From Active Database to Standby Database

Numbers 1 through 4 trace transactions from the active database for the logical replicate database to its standby database:

1 RepAgent for the active database reads the transactions in the active database log and forwards them to the Replication Server, which writes them into an inbound queue.

All transactions for replicated data, including those executed by the maintenance user, are sent to the Replication Server for application in the standby database.

2 The standby DSI thread reads transactions from the inbound queue.

3 The standby DSI thread executes transactions in the standby data server.

4 The standby data server updates the standby database.


463

Configuring Logical Connection Save Intervals

This section describes some options for reconfiguring the save intervals for a logical replicate database. A save interval for a connection specifies how long messages will be retained in a stable queue before they can be deleted. If you set up a warm standby application through the usual procedure, the default settings will work correctly.

You can use the configure logical connection command to configure the DSI queue save interval and the materialization queue save interval for the logical connection.

Refer to “configure logical connection” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for the syntax of this command.

Warning! The DSI queue save interval and the materialization queue save interval settings for a logical connection should be reset only under serious conditions stemming from a lack of stable queue space. Resetting these save intervals (from strict to a given number of minutes) may lead to message loss at the standby database. Replication Server cannot detect this type of loss; you have to verify the integrity of the standby database yourself.

The DSI Queue Save Interval

By default, the DSI queue save interval for the logical connection is set to ’strict’ when you create a standby database. This causes Replication Server to retain DSI queue messages until they are delivered to the standby database. If you must change the DSI queue save interval for the logical connection, use the configure logical connection command.

For example, to force a replicate Replication Server to save messages destined for its logical replicate data server LDS for one hour (sixty minutes), enter the following command:

configure logical connection to LDS.logical_pubs2set save_interval to ’60’

To reset this save interval back to ’strict’, enter:

configure logical connection to LDS.logical_pubs2set save_interval to ’strict’

The Materialization Queue Save Interval

The materialization queue save interval for the logical connection is set to ’strict’ by default when you create a subscription. This causes Replication Server to retain materialization queue messages until they are delivered to the standby database. If you must change the materialization queue save interval for the logical connection, use the configure logical connection command.

Using Replication Definitions and Subscriptions

464

For example, to force a replicate Replication Server to save messages in the materialization queue for its logical replicate data server LDS for one hour (sixty minutes), enter the following command:

configure logical connection to LDS.logical_pubs2set materialization_save_interval to ’60’

To reset this save interval back to ’strict’, enter:

configure logical connection to LDS.logical_pubs2set materialization_save_interval to ’strict’

Using Replication Definitions and SubscriptionsThis section contains information about using warm standby databases with replication definitions and subscriptions. See “Warm Standby Applications Using Replication” on page 457 for more information about warm standby applications for a primary or replicate database.

Creating Replication Definitions for Warm Standby DatabasesReplication Server does not require replication definitions to maintain a standby database, although using replication definitions can improve performance when replicating into a standby database. You can create a replication definition for each table in the logical database. You can also use function replication definitions when replicating into a standby database.

Replication definitions can change how Replication Server replicates data into a standby database, allowing you to optimize your warm standby application or enable a non-default behavior that your application requires.

You can use replication definitions in a warm standby application in the following scenarios:

• To improve the performance of the replication system, as described under “Using Replication Definitions to Optimize Performance” on page 467.

• In normal replication into or out of the logical database, as described in “Warm Standby Applications Using Replication” on page 457.


465

alter table Support for Warm Standby

Adaptiver Server Enterprise version 12.0 allows users to alter existing tables— add non-nullable columns, drop columns, and modify column datatypes.

This section describes how Replication Server supports table changes resulting from the alter table command when the table has no subscriptions.

Note To support table changes that result from alter table when subscriptions exist for that table, you need to alter the table’s replication definition. See “Modifying Replication Definitions” on page 256 for instructions.

In previous releases, when a replication definition was defined for a table, Replication Server always used the column datatype defined in the warm standby replication definition. Beginning with Replication Server version 12.0, and depending on the situation, Replication Server may or may not use a table’s replication definition.

No Replication Definition

When you use alter table against a table without replication definitions, Replication Server sends warm standby databases the same information it receives from the primary server. All options of alter table are supported. When you execute alter table at the primary, the command is replicated to the warm standby, and replication to the standby continues—no action is required in the Replication Server.

See alter table in version 12.0 of the Adaptive Server Enterprise Transact-SQL User’s Guide for drop table syntax. for syntax and information.

Warm Standby with No send standby Clause

When there is no send standby clause associated with any replication definition, Replication Server sends whatever data it receives from the primary table without referring to the replication definitions.

Replication Server uses the original column names and datatypes to send data received from the RepAgent. The replication definition is used only to find the primary key. The primary keys are the union of primary keys in all replication definitions for the table.

If schema changes do not involve dropping all primary key columns in all replication definitions of the table, the scenario is the same as discussed in “No Replication Definition” on page 465. All options of alter table are supported, and no action is required in the Replication Server.


466

You can alter the replication definition at any point to drop all primary keys in the replication definitions, and add the new primary key columns to the replication definitions before you alter the primary table.

Drop the old primary keys only after all of the old data rows are out of the replication system. Otherwise, the Data Server Interface (DSI) shuts down. If this occurs, see for recovery instructions.

Warm Standby with send standby all columns Clause

When send standby all columns is associated with a replication definition, Replication Server sends whatever data it receives from the RepAgent using the original column names and datatypes. The replication definition is used only to find the primary key.

If schema changes do not involve dropping all primary key columns in the replication definition with the send standby all columns clause, the scenario is the same as “No Replication Definition” on page 465. All options of alter table are supported, and no action is required in the Replication Server.

You can alter the replication definition at any time to drop all primary keys in the replication definition with the send standby all columns clause, and add the new primary key columns to the replication definition before you alter the primary table.

Drop the old primary keys after all of the old data rows have left the replication system. Otherwise, the Data Server Interface (DSI) shuts down. If this occurs, see “Recovering from Inbound Queue Problems” on page 261 for recovery instructions.

Warm Standby with send standby replication definition columns Clause

When there is a send standby replication definition columns clause in the replication definition, the standby will continue to use the replicate table name and column names as well as the datatype defined in the table’s corresponding replication definition.

If you want the replication definition datatype to be used in the standby, always create a replication definition with a send standby replication definition columns clause.

Please note that:

• To add or alter columns in the primary database, follow the “Migration Procedure” on page 258.


467

• To drop columns in the primary database, you do not need to alter the replication definition of the table as long as you do not drop all primary key columns.

• To drop all primary key columns, alter the replication definition to add new primary key columns before you alter the primary table. You can drop the old primary keys when the old data rows have been removed from the replication system.

Using Replication Definitions to Optimize Performance

When you specify that you want to use a replication definition for replicating into a standby database:

• Replication Server optimizes updates and deletes by using the primary key defined in the replication definition to generate the where clause.

• You can specify whether Replication Server uses the replication definition’s replicate minimal columns setting for replicating into the standby database. This setting indicates whether updates replace the values for all columns or only the columns with changed values.

• You can specify whether Replication Server replicates all of a table’s columns or all of a stored procedure’s parameters to the standby database or only those columns or parameters listed in the table or function replication definition.

Creating a Replication Definition for Replicating into a Standby Database

To create a replication definition just for replicating into the standby database, use the send standby clause in the create replication definition command. The replication definition’s primary key and replicate minimal columns setting will be used in replicating into the standby database.

Refer to “create replication definition” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for detailed information about using this command.

Specifying a Primary Key

Replication Server generates a where clause to specify target rows for updates and deletes.

• If a replication definition for a table is marked with the send standby clause, the generated where clause contains only the columns listed in the primary key clause of the create replication definition command.

• If there are replication definitions for a table but none are marked with the send standby clause, the generated where clause contains the columns listed in the union of the primary key clauses of all of the replication definitions.


468

• If there is no replication definition for a table, the generated where clause includes all columns in the table except text, image, rawobject, rawobject in row, timestamp, and sensitivity columns.

Updating Minimal Columns

If you create a replication definition for replicating into a standby database, you can take advantage of another replication system performance optimization, the minimal columns setting.

When you use the replicate minimal columns clause, replicated update and delete transactions include only the required columns. Values for unchanged columns can be omitted from update commands. Omitting the unnecessary columns reduces the size of messages delivered through the replication system and requires Adaptive Server to do less work.

If you are not using replication definitions for replicating into the standby, you can still attain this performance benefit.

Minimal column replication occurs automatically if you have no replication definitions for a table or if you have replication definitions for a table but do not use one for replicating into the standby database.

Specifying Columns to Replicate into the Standby Database

If you create a replication definition for replicating into a standby database, you can specify which set of columns to replicate:

• Specify send standby or send standby all columns to replicate all the columns in the table into the standby database.

• Specify send standby replication definition columns to replicate only the replication definition’s columns into the standby database.

Refer to “create replication definition” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for more information about using the send standby clause with the create replication definition command.

Specifying Parameters to Replicate into the Standby Database

If you create a function replication definition, you can specify which set of parameters to replicate:

• Specify send standby all parameters (or omit the all parameters clause) to replicate all the parameters for the stored procedure into the standby database.

• Specify send standby replication definition parameters to replicate only the replication definition’s parameters into the standby database.


469

If a replicated stored procedure has no function replication definition, when the stored procedure is executed, Replication Server replicates all of its parameters from the active database into the standby database. You can create only one function replication definition per replicated stored procedure.

Refer to “create function replication definition” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for more information about using the send standby clause with the create function replication definition command.

Using Replication Definitions for Tables with More Than 128 Columns

Adaptive Server limits the number of expressions in the where clause to 128. For warm standby applications, you must use replication definitions to replicate into tables with more than 128 columns.

• If there are more than 128 columns in a table, the generated where clause causes an Adaptive Server error.

• Make sure that the primary key is not more than 128 columns.

See “Using Replication Definitions to Optimize Performance” on page 467 for more information about the primary key and replication into the standby database.

Using Replication Definitions to Copy Redundant Updates

Without a replication definition, Replication Server does not replicate redundant updates to the warm standby. That is, if an update merely changes the current value to the same value, and thus the before and after images are identical, Replication Server does not replicate the update.

However, if you want to replicate redundant updates, create a replication definition for the column that includes the send standby replication definition parameters option.

If you create a replication definition for a column, Replication Server always sends redundant updates, even when the replication definition is created with the replicate minimal columns option.

Using Subscriptions with Warm Standby ApplicationAlthough subscriptions are not used in replicating from the active to the standby database, you can:


470

• Create subscriptions for the data in a logical primary database, or

• Create subscriptions in order to replicate data from other databases into a logical replicate database.

The create subscription and define subscription commands use the logical database and data server names instead of the physical names.

See “Warm Standby Applications Using Replication” on page 457 for more information about warm standby applications for a primary or replicate database. Also see Chapter 10, “Managing Subscriptions” for more information about subscriptions and subscription materialization.

Restrictions on Using Subscriptions

Replication Server supports all forms of subscription materialization and dematerialization in warm standby applications. These restrictions apply to the creation of subscriptions that replicate data from or into warm standby databases:

• When there is a logical connection for a database, you cannot create a subscription for the physical active or standby database. You must create the subscription for the logical database in order to replicate subscription data into or from both the active and standby databases.

• You cannot create subscriptions while adding the standby database to the replication system. You must wait until the standby database has been properly initialized.

• You cannot add the standby database to the replication system while any subscriptions are being created.

• You cannot create new subscriptions while the switch active command is executing.

Subscription Materialization for Logical Primary Database

This section describes subscription materialization issues for a logical primary database. It also describes what happens if you execute the switch active command for a logical primary database during subscription materialization.

During subscription materialization, data is selected from the active primary database into a materialization queue.


471

When you execute the switch active command, the primary Replication Server replicates RSSD information to notify replicate sites that the active database has been changed. When a replicate Replication Server with a materializing subscription receives this information, the materialization queue is dropped. A new queue is built by reselecting the subscription data from the new active primary database.

Note The RepAgent thread for the RSSD of the primary Replication Server must be running for replicate Replication Servers to detect that the active database has been changed.

Subscription Materialization for Logical Replicate Database

This section describes subscription materialization issues for a logical replicate database. It also describes what happens if you execute the switch active command for a logical replicate database during subscription materialization.

The following sections discuss each subscription materialization method.

Atomic Materialization When you use atomic materialization, Replication Server sets the save interval for the materialization queue to ’strict’. Transactions are not deleted from the materialization queue until the data has been applied to the active database and replicated into the standby database.

Replication Server executes a marker in the active replicate database when the materialization queue has been applied. The marker marks the start of transactions that execute after the materialization queue is applied.

When the marker is executed at the active replicate database, Replication Server writes an informational message like this in its log:

I. 95/10/03 18:00:15. REPLICATE RS: Created atomic subscription <publishers_sub> for replication definition <publishers_rep> at active replicate for <LDS.pubs2>

When the marker arrives at the standby replicate database, Replication Server writes an informational message like this in its log:

I. 95/10/03 18:00:15. REPLICATE RS: Created atomic subscription <publishers_sub> for replication definition <publishers_rep> at standby replicate for <LDS.pubs2>

Materialization is now complete and Replication Server drops the materialization queue. The subscription is considered VALID at both the active and the standby replicate database.


472

If you execute the switch active command while the materialization queue is being processed, Replication Server reapplies the materialization queue to the new active database. If you used the incrementally option to create the subscription, only the batches of materialization rows that were not already replicated into the new active database are reexecuted.

Nonatomic Materialization

When you use nonatomic materialization, the save interval is set to 0, allowing Replication Server to delete rows from the materialization queue after they are applied to the active database.

If a subscription is materializing when you execute the switch active command, Replication Server finishes processing the materialization queue, but marks the subscription “suspect.” Use the check subscription command to find the subscription status in the active and replicate databases. You must drop and re-create suspect subscriptions.

Bulk Materialization If you use bulk materialization to create a subscription that replicates data into a warm standby application, you must ensure that the subscription data is loaded into the active and standby replicate databases.

If you load the data with a method that logs the inserted rows, such as logged bcp, Replication Server replicates the rows into the standby database. If you load the data with a non-logged method, you must also load it into the standby database because the active database log contains no insert records to replicate into the standby database.

During bulk materialization, you execute the activate subscription with suspension command before you load the subscription data into the replicate database. By default, activate subscription with suspension suspends the DSI threads for both the active database and the standby database. Suspending DSI threads allows you to load the data into both databases.

If you load the data using logged bcp or some other method that logs the rows, execute activate subscription with suspension at active replicate only so that Replication Server only suspends the DSI for the active database. This allows the inserted rows to be replicated from the active database into the standby database.

Checking Subscriptions

For a warm standby application for a logical replicate database, you can use the check subscription command to check subscription status. The Replication Server managing the warm standby application returns either one or two status messages, depending on whether or not the status is different for the active and the standby database.


473

For example, while you are creating a subscription, the materialization status may be VALID at the active database and ACTIVATING at the standby database.

Dropping Subscriptions

For a logical replicate database, you can drop a subscription using the drop subscription command with the with purge option. A drop subscription marker follows the dematerialization data from the DSI queue to the active database, and then travels to the standby database. After the marker has been received at both databases, subscription data is deleted from both databases.

While Executing switch active

You can execute the switch active command at the replicate Replication Server while you drop a subscription using the drop subscription command with the with purge option. Replication Server suspends DSI threads and temporarily suspends dematerialization. After switch active completes, the DSI threads are resumed and dematerialization restarts.

Suspect drop subscription

Dropping a subscription using the with purge option for a logical replicate database may lead to a suspect drop subscription if:

• The subscription is materializing in the active database, and

• You switch the active and standby databases, then

• You drop the subscription while it is materializing in the new active database.

Dematerialization restarts and proceeds normally for the new active database, but the new standby (old active) database may retain some subscription data that is not purged. To resolve the discrepancy, you can reconcile the active and the standby database using the rs_subcmp program, or you can drop and re-create the standby database.

For example, you may see a warning message like this when you try to execute drop subscription:

W. 95/10/02 20:59:15. WARNING #28171 DSI(111 SYDNEY_DS.pubs2) - /sub_dsi.c(1231) REPLICATE RS: Dropped subscription <publishers_sub> for replication definition <publishers_rep> at standby replicate for <SYDNEY_DS.pubs2> before it completed materialization at the Active Replicate. Standby replicate may have some subscription data rows left in the database

Loss Detection and Recovery

474

Missing Columns When You Create the Standby DatabaseWhen you create a standby database for an existing database that has replication definitions, missing columns may result under the following combination of circumstances:

• If the existing database has a replication definition that does not include all columns in the table, and

• An insert or update transaction that has not been committed is in the inbound queue, and

• You create a standby database for the existing database (now the active database), after which

• The transaction commits.

Although, by default, a standby database is supposed to receive all columns, at the time the transaction began, the standby database did not exist. Replication Server would have discarded values for columns not in the replication definition. If a column is not in the replication definition and the standby database allows a null value for the column, the row can be inserted into or updated in the standby database without the missing value. Otherwise, you must reconcile the databases yourself.

Loss Detection and RecoveryCreating a warm standby application introduces additional types of loss detection messages into a replication system. See Chapter 16, “Replication System Recovery” for general information on Replication Server recovery, and for recovery procedures.

If you rebuild queues in a Replication Server that participates in a warm standby application, the Replication Server may detect losses between any of the following databases:

Table 13-9: Loss detection in warm standby applications

Loss Detected From To

Logical replicate database Logical primary database

Logical primary database Physical replicate database

Physical primary database Logical replicate database

Physical active database Physical standby database

Logical primary database Replication Server


475

If you need to use the ignore loss command in database recovery operations where a warm standby application is involved, use the same logical or physical data server and database designations that appear in the loss detection messages you received.

Loss Detection and Recovery

476

477

C H A P T E R 1 4 Performance Tuning

To meet the needs and demands of your Replication Server system, you need to manage resources effectively and optimize the performance of individual Replication Servers. You can affect the performance of a Replication Server by changing the values of configuration parameters and by using parallel DSI threads. In order to manage these resources, you need to understand something about Replication Server’s internal processing.

Replication Server Internal ProcessingDuring the replication process, data operations are carried out by several Replication Server threads (or “light-weight processes”). In addition, Replication Server stores data in queues and relies on the Replication Server System Database (RSSD) for critical system information. This section describes how these internal operations support various processes within the primary and destination Replication Server.

Threads, Modules, and DaemonsReplication Server runs multiple threads concurrently. The total number of threads depends on the number of databases that a Replication Server manages and the number of Replication Servers to which it has direct routes. Each thread performs a specific function such as managing a user session, receiving messages from a RepAgent, receiving messages from another Replication Server, or applying transactions to databases.

Some threads call specific portions (or “modules”) of Replication Server to determine the destination of messages and transactions, and to determine what operations to replicate and how to replicate them.

Daemon threads, which run in the background and perform specified operations at predefined times or in response to certain events, run during such Replication Server activities as subscription materialization.

Replication Server Internal Processing

478

For details on Replication Server threads, modules, and daemons involved in processes specific to the primary Replication Server, see “Processing in the Primary Replication Server” on page 478.

When you troubleshoot the replication system, verify the status of Replication Server threads, modules, and daemons. See Chapter 11, “Verifying and Monitoring Replication Server” for details.

Processing in the Primary Replication ServerThis section describes how a transaction that originates in a primary Replication Server distributes replicated data to a destination Replication Server as illustrated in Figure 14-1.

Figure 14-1: Threads used for processing in the primary Replication Server

DISTSRE TD

MDDSI-S

Replication

DSI-E

RSI

Replicate 1Replication Server

Replicate 2Data Server

Stable Queue

Outbound

Stable Queue

Inbound

Primary Data Server

SQT

RepAgent User

Replicate 1Data Server

Server

SQM

SQM

SQM Stable Queue

Outbound

CHAPTER 14 Performance Tuning

479

RepAgent User Thread

RepAgent is the replication agent for Adaptive Server.

RepAgent logs in to Replication Server through an Open Client interface. It scans the transaction log, converts log records directly into LTL (Log Transfer Language) commands, and sends them to Replication Server as soon as they are logged—either in batches or one at a time. Replication Server then distributes the transaction information to subscribing replicate databases.

Replication Server has one RepAgent user thread for each primary database that it manages. Thus, Replication Server has one RepAgent user thread for each RepAgent thread. The RepAgent user thread verifies that RepAgent submissions are valid and writes them into the inbound stable queue for the database.

Stable Queue Manager Thread

There is one Stable Queue Manager (SQM) thread for each stable queue accessed by the primary Replication Server, whether inbound or outbound. Each RepAgent user thread works with a dedicated SQM thread that reclaims stable queue space after a transaction is forwarded to a data server or to another Replication Server.

Stable Queue Transaction Thread

Commands stored in transaction log records and in the inbound queue are ordered according to the sequence in which they were committed—although they are not necessarily grouped by transaction. It is the task of the Stable Queue Transaction (SQT) thread to reassemble transactions and place the transactions in commit order. Transactions are required to be in commit order for final application on the destination’s data servers and for materialization processing.

The SQT thread reassembles transactions as it reads commands from its stable queue and keeps a linked list of transactions. When it reads a commit record, the SQT thread makes that transaction available to the Distributor thread or to the DSI thread, depending on what process required the SQT ordering of the transaction.

When it reads a rollback record, the SQT thread tells the SQM thread to delete affected records from all stable queues. The SQT thread also notifies the DSI thread when a transaction exceeds the large transaction threshold. See “Using Parallel DSI Threads” on page 486 for more information on transaction thresholds.


480

Distributor Thread and Related Modules

For each primary database managed by a Replication Server, there is a Distributor (DIST) thread, which in turn uses SQT and SQM threads to read transactions from the inbound queue. For example, if there are three primary databases, then there are three inbound queues, and three DIST, SQM, and SQT threads.

In determining the destination of each transaction row, the DIST thread makes calls to the following modules:Subscription Resolution Engine, Transaction Delivery, and Message Delivery. All DIST threads share these modules. These modules, and the role they play in the replication system, are described in the following sections.

Subscription Resolution Engine

The Subscription Resolution Engine (SRE) matches transaction rows with subscriptions. When it finds a match, it attaches a destination-database ID to each row. It only marks rows required for subscriptions, thereby minimizing network traffic. If no subscriptions match, the DIST thread discards the row data.

For each row, the SRE determines whether subscription migration occurs.

• A row migrates into a subscription when its column values change so that the row matches the subscription and must be added to the replicate table.

• A row migrates out of a subscription when its column values change so that it no longer matches the subscription and must be deleted from the replicate table.

When the SRE detects subscription migration, it determines which operation to replicate (insert, delete, or update) to maintain consistency between the replicate and primary tables.

Transaction Delivery Module

The Transaction Delivery (TD) module is called by the DIST thread to package transaction rows for distribution to data servers and other Replication Servers.


481

Message Delivery Module

The Message Delivery (MD) module is called by the DIST thread to optimize routing of transactions to data servers or other Replication Servers. The DIST thread passes the transaction row and the destination ID to the MD module. Using this information and routing information in the RSSD, the module determines where to send the transaction:

• To a data server via a DSI thread, or

• To a Replication Server via an RSI thread.

After determining how to send the transaction, the MD module places the transaction into the appropriate outbound queue.

Data Server Interface Threads

Replication Server starts DSI threads to submit transactions to a replicate database to which it maintains a connection.

Each DSI thread is composed of a scheduler thread (DSI-S) and one or more executor threads (DSI-E). Each DSI executor thread opens an Open Client connection to a database.

In order to improve performance in sending transactions from a Replication Server to a replicate database it manages, you can configure a database connection so that transactions are applied using multiple DSI executor threads. See “Using Parallel DSI Threads” on page 486 for a description of this feature.

The DSI scheduler thread calls the SQT thread to perform the following tasks:

• Collect small transactions into groups by commit order

• Dispatch transaction groups to the next available DSI executor thread

The DSI executor threads perform the following tasks:

• Map functions using the function strings defined for the functions, according to the function-string class assigned to the database connection

• Execute the transactions in the replicate database

• Take action on any errors returned by the data server; depending on the assigned error actions, also record any failed transactions in the exceptions log


482

The DSI thread may apply a mixture of transactions from all data sources supported by the Replication Server. The transactions are processed in the single outbound stable queue for the destination data server.

Replication Server Interface Thread

RSI threads are asynchronous interfaces to send messages from one Replication Server to another. One RSI thread exists for each destination Replication Server to which the source database has a direct route.

The DIST thread in the primary Replication Server processes transactions, causing those destined for other Replication Servers to be written to RSI outbound queues. An RSI thread logs in to each destination Replication Server and transfers messages from the stable queue to the destination Replication Server.

When a direct route is created from one Replication Server to another, an RSI thread in the source Replication Server logs in to the destination Replication Server. When an indirect route is created, Replication Server does not create a new stable queue and RSI thread. Instead, messages for indirect routes are handled by the RSI thread for the direct route. For details, see Chapter 5, “Managing Routes”

Miscellaneous Threads and Daemons

The Replication Server threads and daemons shown in Table 14-1 perform miscellaneous tasks in the replication system.

Table 14-1: Additional Replication Server daemons and threads

Thread or Daemon Name Description

Alarm daemon (dALARM) The alarm daemon keeps track of alarms set by other threads, such as the fade-out time for connections and the interval for the subscription retry daemon.

Asynchronous I/O daemon (dAIO) The asynchronous I/O daemon manages asynchronous I/O to Replication Server stable queues.

Connection manager daemon (dCM) The connection manager daemon manages connections to data servers and other Replication Servers.

Subscription retry daemon (dSUB) The subscription retry daemon wakes up after a configurable time-out period (sub_daemon_sleep_time configuration parameter in the rs_config system table) and attempts to resume processing for subscriptions that may have failed.

Recovery daemon (dREC) The recovery daemon takes care of various operations in connection with warm standby applications, routing, and recovery procedures.


483

Processing in the Replicate Replication ServerThis section describes the processes involved when a replicate Replication Server receives incoming messages from a primary Replication Server.

“Processing in the Primary Replication Server” on page 478 describes processing for some of the threads (SQM, RSI, DSI) described in this section. Refer to Figure 14-2 on page 483.

Figure 14-2: Transaction processing in the replicate Replication Server

Version daemon (dVERSION) The version daemon activates briefly when the Replication Server is started for the first time after an upgrade. It communicates the Replication Server’s new version number to the ID Server.

RS user thread The RS user thread manages connections from replicate Replication Servers during the process of creating or dropping subscriptions.

See “Subscription Materialization Methods” on page 310 for the data flow involved in creating and dropping subscriptions.

USER thread A USER thread is created when a user logs in to a Replication Server to execute RCL commands.

Thread or Daemon Name Description

Primary

Replicate

Replication Server

Replication Server

RSI User

SQM

SQM DSI-S

MD

Other Replicate Replication Server

Replicate Data Server

DSI-E

RSI

RSI

DIST

Stable Queue

Outbound

Stable Queue

Outbound

Stable Queue

Outbound

Default Configuration Parameters Affecting Performance

484

RSI User Thread

The RSI user thread is a client connection thread for incoming messages from another Replication Server. It calls the Message Delivery (MD) module to determine whether to send the message to:

• A data server using the DSI thread, described in “Data Server Interface Threads” on page 481. The DSI thread is composed of a scheduler thread (DSI-S) and one or more executor threads (DSI-E).

• Another Replication Server using the RSI thread, described in “Replication Server Interface Thread” on page 482.

The RSI user thread writes commands destined for other Replication Servers or databases into outbound queues. See “Processing in the Primary Replication Server” on page 478 for details on how messages are processed after they are stored in the outbound queues.

Default Configuration Parameters Affecting Performance

Configuration parameters are set by rs_init when you first configure your Replication Server. Table 14-2 lists configuration parameters that affect performance. You can change the values of these parameters to improve the performance of the Replication Server. Refer to “Changing Replication Server Parameters” on page 95 for information on how to modify default configuration parameters.

Table 14-2: Default configuration parameters


cm_max_connections The maximum number of outgoing connections available to the connection manager. The value must be greater than 0.

Default: 64

fstr_cachesize Size of function-string cache, in bytes. The value must be greater than 0.


init_sqm_write_delay Write delay for the SQM if queue is being read.

Default: 1000 milliseconds

init_sqm_write_max_delay The maximum write delay for the stable queue manager if the queue is not being read.

Default: 10,000 milliseconds


485

memory_limit The maximum total memory the Replication Server can use.

Values for several other configuration parameters are directly related to the amount of memory available from the memory pool indicated by memory_limit. These include fstr_cachesize, md_source_memory_pool, queue_dump_buffer_size, sqt_max_cache_size, sre_reserve, and sts_cachesize.

Default: 20MB

num_client_connections The maximum number of incoming client connections allowed. If Open Server limits are exceeded, increase the maximum number. The value must be greater than or equal to 30.

Default: 30

num_concurrent_subs The maximum number of concurrent subscription materialization/dematerialization requests allowed. (Limit applies to atomic and nonatomic materialization only; does not apply to bulk materialization.) Requests over the maximum are fulfilled after other requests have been fulfilled. The minimum value is 1.

Default: 10

num_msgqueues The maximum number of Open Server message queues allowed. If Open Server limits are exceeded, increase the maximum number. The value must be greater than the num_threads setting.

Default: 178

num_msgs The maximum number of Open Server message queue messages allowed. If Open Server limits are exceeded, increase the maximum number.

Default: 45,568

num_mutexes The maximum number of Open Server mutexes allowed. If Open Server limits are exceeded, increase the maximum number. The value must be greater than the num_threads setting.

Default: 128

num_stable_queues The maximum number of stable queues allowed (HP9000 only). Each stable queue uses 32,768 bytes of shared memory. The minimum number of stable queues allowed is 32.

Each standby database connection uses an additional 16,384 bytes of shared memory. Every two standby database connections count as one additional stable queue.

Default: 32

num_threads The maximum number of Open Server threads allowed. If Open Server limits are exceeded, increase the maximum number. The value must be greater than or equal to 20.

Default: 50


Using Parallel DSI Threads

486

Using Parallel DSI ThreadsReplication Server enables you to configure a database connection so that transactions are applied to a replicate data server using parallel DSI threads rather than a single DSI thread. Applying transactions in parallel increases the speed of replication, yet maintains the serial order of the transactions that occurred at the primary site.

queue_dump_buffer_size The maximum command length, in bytes, used by the sysadmin dump_queue command. Commands larger than the specified length are truncated. The range is 1000 to 32,768.

Default: 800 bytes

rec_daemon_sleep_time Specifies the sleep time for the recovery daemon, which handles “strict” save interval messages in warm standby applications and certain other operations.

Default: 2 minutes

sqm_warning_thr1 Percent of partition segments (stable queue space) to generate a first warning. The range is 1 to 100.

Default: 75

sqm_warning_thr2 Percent of partition segments used to generate a second warning. The range is 1 to 100.

Default: 90

sqm_warning_thr_ind Percent of total partition space that a single stable queue uses to generate a warning. The range is 51 to 100.

Default: 70

sqt_max_cache_size Maximum SQT cache memory, in bytes.


sre_reserve The amount of additional space to allocate for resolving new subscriptions. For example, 100 (100%) means double the current space. The range is 0 to 500.

Default: 0

sts_cachesize The total number of rows that are cached for each cached RSSD system table. Increasing this number to the number of active replication definitions prevents Replication Server from executing expensive table lookups.

Default: 100

sub_daemon_sleep_time Number of seconds the subscription daemon sleeps before waking up to recover subscriptions. The range is 1 to 31,536,000.

Default: 120 seconds



487

When parallel DSI threads are active, Replication Server starts processing a transaction before the preceding transaction has committed and after the DSI has seen the commit record for the next transaction. The commit is delayed until it is determined that all preceding transactions have committed. Replication Server uses a system table, rs_threads, to control the order in which transactions are committed and to detect conflicting updates in transactions that are executing simultaneously.

Replication Server achieves additional parallelism in the way it processes large transactions with parallel DSI threads. Large transactions begin processing before the DSI has seen the commit record. While this means a large transaction can be processed sooner, it also means that Replication Server might start processing a transaction that is ultimately rolled back.

Using parallel DSI threads is expected to produce an overall increase in system throughput. At times, however, this feature may produce an increase in overhead. An example of this is when there are a large number of conflicting updates between transactions, and Replication Server’s attempt to apply the transactions in parallel results in their being rolled back due to deadlocks.

Parallel DSI ParametersYou define parallel DSI threads in the configure connection command with the following configuration parameters:

• dsi_num_threads – specifies the number of parallel DSI threads to be used. The default value is 1. The maximum value is 20.

• dsi_large_xact_size – specifies the number of statements allowed in a transaction before it is considered to be a large transaction. The default value is 100. The minimum value is 4.

• dsi_sqt_max_cache_size – specifies the maximum SQT cache size for the database connection. The default, 0, means the current setting of the sqt_max_cache_size parameter is used as the maximum cache size for the connection.

• dsi_num_large_xact_threads – specifies the number of parallel DSI threads to be reserved for use with large transactions. The default value is 0. The maximum value is one less than the value of dsi_num_threads.

• dsi_serialization_method – specifies the method used to maintain serial consistency between parallel DSI threads. Refer to “Transaction Serialization Methods” on page 490 for a description of these methods.


488

• parallel_dsi – provides a shorthand method for configuring parallel DSI. A setting of “on” sets dsi_num_threads to 5, dsi_num_large_xact_threads to 2, dsi_serialization_method to “wait_for_commit,” and dsi_sqt_max_cache_size to 1 million bytes. A setting of “off” sets the parallel DSI values to their defaults. The default for this parameter is “off.”

You can set the parallel_dsi parameter to “on” and then set individual parallel DSI configuration parameters to fine-tune your configuration. For example, enter the following command to set this parameter on for the connection to the pubs2 database in the SYDNEY_DS data server:

configure connection to SYDNEY_DS.pubs2 set parallel_dsi to ’on’

See “Configuring Parallel DSI for Optimal Performance” on page 494 for guidelines on configuring the parameters.

Components of Parallel DSIFigure 14-3 shows the components of parallel DSI.

Figure 14-3: Parallel DSI components

DSI Scheduler

The DSI scheduler thread (shown as DSI-S in Figure 14-3) collects small transactions into groups by commit order. Once transactions are grouped, the DSI scheduler dispatches the groups to the next available DSI executor thread. The DSI scheduler attempts to dispatch groups for different origins in parallel, because they can commit in parallel.

Replicate


Replication Server

Stable Queue

Outbound DSI-S

DSI-E

DSI-E

DSI-E

DSI-E


489

DSI Executor Threads

The DSI executor threads (shown as DSI-E in Figure 14-3) map functions to function strings and execute the transactions on the replicate database. The DSI executor threads also take action on any errors the replicate data server returns.

Processing Transactions with Parallel DSI ThreadsYou can define large and small transactions with the dsi_large_xact_size database connection configuration parameter, which specifies the number of commands allowed in a transaction before the transaction is considered to be large. Replication Server processes small and large transactions differently.

Small Transactions

Groups of small transactions are submitted to the first available DSI executor thread when a transaction commit is read. The DSI executor thread prepares the transaction group for execution and submits it to the replicate data server. It does not, however, submit the update of the rs_lastcommit table or the commit statement for a transaction.

Once the DSI executor thread receives confirmation that processing of the transactions is successful and all transactions scheduled to commit prior to this group have committed, it submits the update of the rs_lastcommit table and the commit statement for each transaction.

Large Transactions

Large transactions are submitted to the next available DSI executor thread that is reserved for a large transaction. The DSI executor thread sends the transaction to the replicate data server without waiting to see the commit record. If the transaction was rolled back at the primary data server, the DSI executor thread rolls it back at the replicate data server.

If Replication Server encounters a large transaction, and a dedicated large transaction thread is not available, the transaction is processed in the same way as a group of small transactions.


490

Transaction Serialization MethodsReplication Server maintains transaction serialization in parallel DSI by committing transactions at the replicate database in the same order they were committed at the primary database. When using multiple DSI threads to process transactions, Replication Server can execute updates in a different order at the replicate database, as long as the order of processing does not result in conflicting updates. If conflicting updates are detected, all current transactions are rolled back and then applied one at a time. Note that the commit order at the primary and replicate databases always match, and that the execution or processing order at the replicate database may not match.

Replication Server provides four methods for minimizing update conflicts between transactions that are processing with parallel DSI threads. These methods are described in the following sections.

isolation_level_3 This method specifies that transaction isolation level 3 locking be used in the replicate data server. This type of locking prevents “non-repeatable reads” and “phantoms” from occurring by applying an index page or table lock until the end of the transaction.

If you are using triggers to enforce referential integrity of data across a database, this serialization method should be used. It prevents phantom rows from occurring in a table while a trigger is being executed.

Refer to the Adaptive Server System Administration Guide for more information on transaction isolation levels and triggers.

Replication Server uses the rs_set_isolation_level3 system function to turn on transaction isolation level 3, which is supported by SQL Server version 10.0 and later. This system function is executed every time the DSI connects to the replicate data server.

Note Replication Server automatically creates a function string for the rs_set_isolation_level3 function in function-string classes in which Replication Server generates default function strings. For other function-string classes, you must create rs_set_isolation_level3 function strings before you can use the parallel DSI feature.

single_transaction_per_origin

This method prevents conflicts by allowing only a single active transaction from a primary data server. This means that transactions are applied in a single stream in replication systems. In systems with multiple primary databases, updates from each primary are treated as separate transaction streams and are applied in parallel.


491

wait_for_commit This method (the default) maintains transaction serialization by instructing the DSI to wait until one transaction is ready to commit before initiating the next transaction. This improves the speed of replication because the next transaction can be submitted to the replicate data server while the first transaction is in the process of committing, since the first transaction already holds the locks that it requires.

none This method assumes that your application is designed to avoid conflicting updates, or that lock protection is built into your database system. For example, SQL Server version 4.9.2 holds update locks for the duration of the transaction when an update references a nonexistent row. Thus, conflicting updates between transactions are detected by parallel DSI threads as deadlocks. However, SQL Server version 10.0 and later does not hold these locks unless transaction isolation level 3 has been set.

For replication to non-Sybase databases, transaction serialization cannot be guaranteed if you choose either the “none” (no coordination) or the “isolation_level_3” method, which may not be supported by non-Sybase databases.

Detecting Conflicting Updates with the rs_threads TableReplication Server uses a system table, rs_threads, to control the order in which transactions are committed and to detect conflicting updates between parallel DSI threads.

The rs_threads table contains a row for each DSI executor thread. To simulate row-level locking, it has two columns, id and seq, and enough dummy columns so that only one row fits on a page. The id column is used as a unique clustered index.

At the beginning of a transaction, the DSI executor thread updates its row in the rs_threads table with the next available sequence number. When it is ready to commit the transaction, the thread sends a select statement to the replicate data server to select, from the rs_threads table, the sequence number of the transaction that should have committed prior to the transaction.

Because the preceding transaction holds a lock on this row in rs_threads, this thread will be blocked until the preceding transaction commits.


492

If the sequence number that is returned is less than the expected value, the thread determines whether it should roll back the transaction or retry the select operation. Because the DSI formats many commands into a single batch before submitting it to the Adaptive Server, it is possible that a thread may be ready to commit before the preceding transaction has submitted any commands to the Adaptive Server. In this case, the select in the rs_threads table may be submitted several times.

If the sequence number that is returned matches the expected value, the transaction can commit.

After a certain number of rows (specified by the dsi_large_xact_size parameter), the user thread attempts to select the row for the next thread to commit in order to surface conflicting updates.

Figure 14-4 shows a deadlock occurring between three parallel DSI executor threads. The vertical lines represent the statements being executed by each thread. The statements show a cycle between the three threads resulting in a deadlock. The cycle is also detected if the third thread is a large transaction executing only the select statement against rs_threads where id = 2.


493

Figure 14-4: Deadlock detection in parallel DSI

Function Strings for rs_threadsReplication Server manipulates the rs_threads system table with the system functions listed below. These functions have function-string-class scope. These functions are executed only when more than one DSI thread is defined for a connection.

S4

S2

S3

update twhere k = 1

S1

commit transaction

update uwhere k = 2

update twhere k = 1

update uwhere k = 2

if 201 == (select seq fromrs_threads where id = 1)then commit transaction

if 99 == (select seq fromrs_threads where id = 2)then commit transaction

Thread Threeupdaters_threadsset seq = 87where id = 3

Thread Twoupdaters_threadsset seq = 99where id = 2

Thread Oneupdaters_threadsset seq = 201where id = 1


494

Table 14-3: System functions that modify the rs_threads system table

Note Replication Server automatically creates function strings for the above functions in function-string classes in which Replication Server generates default function strings. For other function-string classes, you must create these function strings before you can use the parallel DSI features.

Configuring Parallel DSI for Optimal PerformanceThe following guidelines will help you configure parallel DSI parameters to achieve optimal performance. When setting the parameters, you need to consider whether or not you have a large number of conflicting updates between transactions. You also need to determine the number of transactions you will be processing with parallel DSI threads, and the number of statements within the transactions.

Frequent Conflicting Updates

If your transactions conflict with each other frequently, set the parallel DSI configuration parameters as follows:

• dsi_serialization_method – set this parameter to “wait_for_commit.”

• dsi_num_large_xact_threads – set this parameter to “2”. If you are configuring parallel DSI in a warm standby application, set the dsi_num_larg_xact_threads parameter for the standby database to one more than the number of simultaneous large transactions executed at the active database.

Function Description

rs_initialize_threads Sets the sequence of each entry in the rs_threads system table to 0. This function is executed during the initialization of a connection.

rs_update_threads Updates the sequence number for the specified entry in the rs_threads system table.

rs_get_thread_seq Returns the current sequence number for the specified entry in the rs_threads system table.

rs_get_thread_seq_noholdlock Returns the current sequence number for the specified entry in the rs_threads system table, using the noholdlock option. This thread is used when the serialization method is “isolation_level_3.”


495

• dsi_num_threads – set this parameter to “3” plus the value of the dsi_num_large_xact_threads parameter. If your transactions are usually small, such as one or two statements, set dsi_num_threads to “1” plus the value of dsi_num_large_xact_threads.

Setting the parallel_dsi configuration parameter to “on” provides a shorthand method for configuring parallel DSI as described above. It also sets the sqt_max_cache_size parameter to 1 million bytes.

Infrequent Conflicting Updates

If your transactions conflict with each other only occasionally, set the parallel DSI configuration parameters as follows:

• dsi_serialization_method – set this parameter to “isolation_level_3” if you have Adaptive Server or SQL Server version 10.0.x or later. If you have SQL Server version 4.9.x, you can ignore this parameter.

• dsi_num_large_xact_threads – set this parameter to “2”. If you are configuring parallel DSI in a warm standby application, set the dsi_num_larg_xact_threads parameter for the standby database to one more than the number of simultaneous large transactions executed at the active database.

• dsi_num_threads – set this parameter to “3” plus the value of the dsi_num_large_xact_threads parameter.

Transaction Size and SQT Cache

The sqt_max_cache_size configuration parameter determines the maximum SQT cache memory, in bytes. You set its value based on the number of transactions you are processing and the number of statements within the transactions.

The following formula gives the upper bound, or worst case, estimate for SQT cache size. A good default value for the SQT cache when you are using parallel DSI is 2MB.

The SQT cache formula is:

sqt_max_cache_size = T * (O + (S * N) )

The factors included in the formula are as follows:

• T is the number of transactions to cache for a DSI. It should be 20 times 1 plus the number of ordinary DSI threads:


496

20 * (1 + dsi_num_threads - dsi_num_large_xact_threads)

• O is the SQT cache’s per transaction overhead, including the begin and commit statements. This is 3K bytes.

• S is the statement size within the SQT cache. This is 1K when the modified data is less than 100 bytes, 2K when the modified data is between 100 and 300 bytes, and 5K when the modified data is greater than 300 bytes.

• N is the number of statements modified by a transaction. It is determined by the application.

You can confirm the value of sqt_max_cache_size with the rs_configure stored procedure. When a steady stream of transactions is flowing to the DSI, the SQT should be full and the number of closed transactions should be about 20. More closed transactions indicates that the cache is larger than required, and fewer indicates that the cache is not large enough.

Number of Statements and SQT Cache

The dsi_large_xact_size parameter setting should be larger than the number of statements modified by an ordinary transaction and larger than the number given by the formula below. If the number below is smaller than the number of statements in an ordinary transaction, the sqt_max_cache_size parameter should be increased. The formula is:

dsi_large_xact_size =( (sqt_max_cache_size/ dsi_num_large_xact_threads) - O) / S

Parallel DSI and the rs_origin_commit_time System VariableThe value of the rs_origin_commit_time system variable depends on whether you are using the parallel DSI feature.

• If you are not using parallel DSI to process large transactions, the value of the rs_origin_commit_time system variable contains the time when the last transaction in the transaction group committed at the primary site.

• If you are using parallel DSI to process large transactions (before their commit has been read from the DSI queue), when the DSI threads start processing one of these transactions, the value of the rs_origin_commit_time system variable is set to the value of the rs_origin_begin_time system variable.


497

When the commit statement for the transaction is read, the value of rs_origin_commit_time is set to the actual commit time. Therefore, when the configuration parameter dsi_num_large_xact_threads is set to a value greater than zero, the value for rs_origin_commit_time is not reliable for any system function other than rs_commit.


498

499

C H A P T E R 1 5 Handling Errors and Exceptions

This chapter describes various error handing methods for Replication Server.

Refer to the Replication Server Troubleshooting Guide for information about resolving specific errors.

General Error HandlingReplication Server passes messages to data servers and other Replication Servers while they are accessible and queues messages when connections are down. Using Sybase Central, you can monitor the status of the replication system and troubleshoot problems as they arise.

Normally, short-term failures of networks and data servers do not require special error handling or intervention. When the failure is corrected, replication system components resume their work automatically. Lengthier failures may require intervention if there is not enough disk space to queue up messages or if it is necessary to reconfigure the replication system to work around the failure.

Failures of some system components, such as Replication Server partitions or primary databases, also require user intervention. Refer to Chapter 16, “Replication System Recovery” for more information about recovery procedures.

A Replication Server’s response to errors depends on the kind of error, source of the error, and how the Replication Server is configured. Replication Server handles errors in these ways:

• Logs errors in its error log file.

• Responds to data server errors based on configuration settings.

• If transactions fail to commit in a database, writes the transactions to the exceptions log for manual resolution.

• Detects duplicate transactions after system restart.

Error Log Files

500

Error Log FilesThis section describes error log files in the replication system. You can access log files to help you troubleshoot Replication Server and RepAgent. To view skipped transactions that are written to system tables, you can access the Adaptive Server for the Replication Server managing a specified database. Refer to the Replication Server Troubleshooting Guide for details on troubleshooting errors.

Replication Server allows user-definable error processing in response to data server errors. For details, see “Data Server Error Handling” on page 504.

For instructions on viewing and refreshing the error log in Sybase Central, see “Viewing the Error Log” in Replication Server’s online help.

Replication Server Error LogThe Replication Server error log is a text file where Replication Server writes informational and error messages.

By default, the Replication Server error log file name is repserver.log, and resides in the directory where you started the Replication Server. You can specify the name and location of the error log file by using the -E command line flag when you start the Replication Server or in a Replication Server run file

Each log message begins with a letter to indicate the message type. Table 15-1 lists the possible message types.

Table 15-1: Message types in the Replication Server error log

RSM

Error Code Description

I An informational message.

W A warning about a condition that has not yet caused an error, but may require attention. An example is running out of a resource.

E An error that does not prevent further processing, such as a site that is unavailable.

H A Replication Server thread has died. An example is a lost network connection.

F Fatal. A serious error caused Replication Server to exit. An example is starting the Replication Server with an incorrect configuration.

N Internal error. These errors are caused by anomalies in the Replication Server software. Report these errors to Sybase Technical Support.

CHAPTER 15 Handling Errors and Exceptions

501

Informational Messages

For informational messages in the error log, the format is as follows:

I. date: message

The letter “I” at the beginning of a message means that the message is provided for information. It does not mean that an error occurred. For example, Replication Server outputs the following messages as it drops a subscription:

I. 95/11/01 05:41:54. REPLICATE RS: Dropping subscription <authors_sub> for replication definition <authors> with replicate at <SYDNEY_DS.pubs2>I. 95/11/01 05:42:02. SQM starting: 104:-2147483527 authors.authors_subI. 95/11/01 05:42:12. SQM Stopping: 104:-2147483527 authors.authors_subI. 95/11/01 05:42:20. REPLICATE RS: Dropped subscription <authors_sub> for replication definition <authors> with replicate at <SYDNEY_DS.pubs2>

Error and Warning Messages

For messages other than informational messages, the format is as follows:

severity, date. ERROR #error_number thread_name(context) - source_file(line) message

If the message is a warning, “ERROR” in the above format becomes “WARNING.”

The severity is either W, E, H, F, or N, as listed in Table 15-1. The date is the date and time that the error occurred. The error_number is the Replication Server error number.

The thread_name is the name of the Replication Server thread that received the error. See Chapter 2, “Replication Server Technical Overview” and Chapter 14, “Performance Tuning” for details about Replication Server threads. The context provides some information about the thread’s context at the time the error occurred.

The source_file and line point to the program file and line number in the Replication Server source code where the error was reported.

Error Log Files

502

The message is the full text of a message from a Replication Server. It is in the language specified in the RS_language configuration parameter. Some messages also include a message from a data server, or one of the component libraries that Replication Server uses.

Note Replication Server puts question marks (?) in messages where more specific information is not available. For example, if an error occurs during initialization, Replication Server may not yet have completed some internal structures, so it prints question marks in place of information it has not yet collected.

The following example shows the Replication Server error log entry for a data server:

E. 95/11/01 05:30:52. ERROR #1028 DSI(SYDNEY_DS.pubs2) - dsiqmint.c(3522)Message from server: Message: 2812, State: 4, Severity: 16 -- ’Stored procedure ’upd_authors’ not found.H. 95/11/01 05:30:53. THREAD FATAL ERROR #5049 DSI(SYDNEY_DS.pubs2) - dsiqmint.c(3529) The DSI thread for database ’SYDNEY_DS.pubs2’ is being shutdown because of error action mapped from data server error ’2812’. The error was caused by output command ’1’ mapped from source command ’2’ of the transaction.

The messages indicate that Adaptive Server returned error number 2812, causing Replication Server to take the stop_replication action. See “Assigning Actions to Data Server Errors” on page 508.

Finding the Name of the Replication Server Error Log

Use the admin log_name command to find the name of the current Replication Server error log file. Replication Server displays the path to the log file, as the following UNIX example shows:

Log File Name ----------------------------- /work/sybase/SYDNEY_RS/SYDNEY_RS.log

Changing to a New Replication Server Log File

To begin a new error log file, use the admin set_log_name command. This command closes the current log file and opens a new one. Subsequent messages are written in the new log file.


503

Following is an example of the admin set_log_name command for UNIX:

admin set_log_name, ’/work/sybase/SYDNEY_RS/951101.log’

The previous log remains active if Replication Server fails to create and open the new log file.

RepAgent Error Log MessagesAll RepAgent error, trace, and information messages are logged in the Adaptive Server error log file. Each message identifies the RepAgent that logged the error in the string “RepAgent (dbid)”, which appears in the first line of the message. dbid is the database identification number of the RepAgent that logged the error.

Here is an example of an information message:

RepAgent(dbid): Recovery of transaction log is complete. Please load the next transaction log dump and then start up the Rep Agent Thread with sp_start_rep_agent, with ‘for recovery’ specified.

The Adaptive Server error log is a text file. The messages are printed in the language specified at Adaptive Server. RepAgent records errors and informational messages that occur when transferring replicated objects from the Adaptive Server transaction log and converting them into commands. RepAgent errors are generally in the 9200 to 9299 range.

Adaptive Server performs actions based on the severity and recoverability of an error. Some errors are for information only, others cause Adaptive Server to retry the operation that caused the error until it succeeds, and still others indicate an error too severe to continue and RepAgent shuts down. For more information about the Adaptive Server error log file, refer to the Adaptive Server System Administration Guide.

If you are using the LTM as your replication agent, refer to Appendix B, “LTM for SQL Server” for information about LTM error messages.

Sample Error Messages

This section describes some common RepAgent error messages and possible solutions.

Data Server Error Handling

504

• In this example, the RepAgent login name is not present on the Replication Server.

RepAgent(6): Failed to connect to Replication Server. Please check the Replication Server, username, and password specified to sp_config_rep_agent. RepSvr = repserver_name, user = RepAgent_usernameRepAgent(6): This Rep Agent Thread is aborting due to an unrecoverable communications or Replication Server error.

You must either add RepAgent’s login name to Replication Server or change RepAgent’s login name.

• In this example, RepAgent cannot connect to Replication Server.

RepAgent(7): The Rep Agent Thread will retry the connection to the Replication Server every 60 second(s). (RepSvr = repserver_name.)

Check Replication Server status. If Replication Server is down, resolve the problem and restart. Otherwise, wait for possible network problem to resolve.

Data Server Error HandlingReplication Server allows user-definable error processing for data server errors. This is accomplished by creating an error class for a database and specifying responses for each error that the data server returns when the error is encountered in the database. The data server returns the defined errors to Replication Server. Table 15-2 lists the RCL commands and Adaptive Server system procedures that manage errors and error classes.

Table 15-2: RCL commands and system procedures for error processing

Command Description

rs_helpclass Adaptive Server system procedure that displays the name of each existing error class, function-string class, and their primary Replication Server

create error class Creates a new error class

drop error class Drops an existing error class

assign action Specifies an error processing action for one or more data server errors

create connection Associates an error class with a new database connection

alter connection Associates an error class with an existing database connection


505

A default error class, rs_sqlserver_error_class, is provided for Adaptive Server databases.

Creating an Error ClassYou can define a single error class to use with all databases managed by the same type of data server. For example, you can use the default Adaptive Server error class, rs_sqlserver_error_class, with any Adaptive Server database. There is no need to create another error class unless a database has special error-handling requirements.

An error class is a name used to group error action assignments. The syntax for the create error class command is:

create error class error_class

For example, to create an error class named pubs2_error_class, use this command:

create error class pubs2_error_class

Initially, rs_sqlserver_error_class, the default error class that is predefined to work with Adaptive Server databases, does not have a primary site. Since you can only create server-wide error classes at a primary site for a class, you need to designate one of the Replication Servers as a primary site for a Adaptive Server error class.

To do this, make sure all other Replication Servers have direct or indirect routes from this primary site. You can designate a site as primary by executing the create error class command for a Adaptive Server error class at that site.

The default error action for all errors returned by a data server is stop_replication. This is also the most serious action: it suspends replication for the database, as if you entered the suspend connection command. To assign less severe actions to errors you want to handle differently, use the assign action command. See “Assigning Actions to Data Server Errors” on page 508 for more information.

Initializing a New Error ClassAfter you have created a new error class, you can initialize it with error actions from an error class such as the system-provided rs_sqlserver_error_class. To do this, use the rs_init_erroractions stored procedure:


506

rs_init_erroractions new_error_class, template_class

For example, to create the error class pubs2_error_class, based on the template error class rs_sqlserver_error_class, enter:

rs_init_erroractions pubs2_error_class, rs_sqlserver_error_class

Then use the assign action command to change the actions for individual errors.

Dropping an Error ClassThe drop error class command drops an error class and all actions associated with it. The error class must not be in use with an active database connection when you drop it. The syntax for drop error class is:

drop error class error_class

For example, to drop the pubs2_error_class error class, use this command:

drop error class pubs2_error_class

You cannot drop the rs_sqlserver_error_class error class.

Changing the Primary Replication Server for an Error ClassUse the move primary command to change the primary site for an error class. This is necessary when you are changing the primary site from one Replication Server to another so that error actions can be distributed through new routes. For example, you must use this command if you are dropping from the replication system the Replication Server that is the current primary site for an error class.

Before you execute move primary, make sure that a route exists from:

• The new primary site to each Replication Server that will use the error class

• The current primary to the new primary site

• The new primary to the current primary site

The syntax for the move primary command, for error classes, is:

move primary of error class class_nameto replication_server


507

Execute the move primary command at the Replication Server that you want to designate as the new primary site for the error class.

• class_ name – the name of the error class whose primary Replication Server is to be changed.

• replication_server – specifies the new primary Replication Server for the error class.

The following command changes the primary site for the pubs2_error_class error class to the TOKYO_RS Replication Server where the command is entered:

move primary of error class pubs2_error_class to TOKYO_RS

For the default error class, rs_sqlserver_error_class, no Replication Server is the primary site until you assign one as the primary site. You must specify a primary site before you can use the assign action command to change default error actions.

To specify a primary site for the default error class, execute the following command in that Replication Server:

create error class rs_sqlserver_error_class

After you have executed this command, you can use the move primary command to change the primary site for the error class.

Displaying Error Class InformationThe Adaptive Server rs_helpclass stored procedure displays the names of existing error classes and function-string classes in the replication system and their primary Replication Servers. For example:

rs_helpclass error_classError Class(es) PRS for class -------------- --------- my_error_class TOKYO_RS rs_sqlserver_error_class Not Yet Defined

Refer to “rs_helpclass” in Chapter 6, “Adaptive Server Stored Procedures,” in the Replication Server Reference Manual for more information.


508

Assigning Actions to Data Server ErrorsThe assign action command specifies the action to take for errors that a data server can return to Replication Server. The syntax for the assign action command is:

assign action {ignore | warn | retry_log | log | retry_stop | stop_replication} for error_classto data_server_error [, data_server_error]...

For example, to instruct Replication Server to ignore Adaptive Server errors 5701 and 5703:

assign action ignore for rs_sqlserver_error_class to 5701, 5703

The default error class provided for Adaptive Server databases is rs_sqlserver_error_class. You must create this error class at a primary site before you can use the assign action command to change default error actions. The data_server_error parameter is the data server error number.

Enter one of the six possible error actions at the Replication Server where the error class was created. These actions are listed in Table 15-3, in order of severity: ignore is the least severe action and stop_replication is the most severe.

When a transaction causes multiple errors, Replication Server chooses just one action—the most severe action assigned to any of the errors that occurred. To return an error to the default error action, stop_replication, you must reassign it explicitly.

Table 15-3: Replication Server actions for data server errors

Action Description

ignore Assume that the command succeeded and that there is no error or warning condition to process. This action can be used for a return status that indicates successful execution.

warn Log a warning message, but do not roll back the transaction or interrupt execution.

retry_log Roll back the transaction and retry it. The number of retry attempts is set with the configure connection command. If the error continues after retrying, write the transaction into the exceptions log, and continue, executing the next transaction.

log Roll back the current transaction and log it in the exceptions log; then continue, executing the next transaction.

retry_stop Roll back the transaction and retry it. The number of retry attempts is set with the configure connection command. If the error recurs after retrying, suspend replication for the database.


509

Displaying Assigned Actions for Error NumbersExecute the rs_helperror stored procedure to display the action assigned for an error number. The syntax for the rs_helperror stored procedure is:

rs_helperror server_error_number [, v]

where server_error_number parameter is the data server error number of the error you want information for. The v parameter specifies “verbose” reporting. When you supply this option, rs_helperror also displays the Adaptive Server error message text, if available. Refer to “rs_helperror” in Chapter 6, “Adaptive Server Stored Procedures,” in the Replication Server Reference Manual for more details.

Exceptions HandlingWhen a transaction submitted by Replication Server fails, Replication Server records the transaction in the exceptions log in the RSSD. The Replication System Administrator at the site must resolve the transactions in the exceptions log. See “Accessing the Exceptions Log” on page 511.

Transactions can fail due to errors such as duplicate keys, column value checks, and insufficient disk space. They may also be rejected for reasons such as insufficient permissions, version control conflicts, and invalid object references.

Because skipping a transaction causes inconsistency and can have an adverse affect on the system, you should review on a regular basis any transactions that have been recorded in the exceptions log and resolve them. The best resolution for a transaction may depend on the client application that originated it. For example, if a failed transaction corresponds to a real-world event, such as a cash withdrawal, the transaction must somehow be applied.

Refer to the Replication Server Troubleshooting Guide for more information on the implications of skipping a transaction.

stop_replication Roll back the current transaction and suspend replication for the database. This is equivalent to using the suspend connection command. This action is the default.

Since this action stops all replication activity for the database, it is important to identify the data server errors that can be handled without shutting down the database connection, and assign them to another action.

Action Description

Exceptions Handling

510

For information about exceptions handling, correcting transactions, and purging the exceptions log in Sybase Central, see “Managing the Exceptions Log” in Replication Server’s online help.

Handling Failed TransactionsThis section outlines the recommended process for handling failed transactions that require manual intervention.

Suspend Database Connection

When a data server begins rejecting transactions because of a temporary failure, such as lack of space in a database or log file, you can suspend the database connection until the error is corrected.

If the database connection is not suspended, Replication Server writes the transactions into the exceptions log for the database. Since these transactions must then be resolved manually, you can save time by shutting down the connection until the error condition is corrected.

While a database connection is suspended, Replication Server stores transactions in a stable queue. When the connection is resumed, the stored transactions are sent to the data server.

To stop the flow of transactions from a Replication Server to a database, use the suspend connection command:


The command requires sa permission and must be entered at the Replication Server that manages the database.

Analyze and Resolve the Problem

You then need to determine why the transaction failed, make corrections or adjustments, and resubmit the transaction. For example, if a transaction failed because the maintenance user had insufficient permissions, grant the maintenance user the needed permissions and retry the transaction.

If you are resolving transactions in the exceptions log:

1 Retrieve a list of the transactions from the exceptions log. See “Accessing the Exceptions Log” on page 511.

RSM


511

2 Investigate the transactions to determine the cause of failure and the best method for resolution.

3 Resolve the transactions according to your plan. For example, you might correct a permissions problem and then resubmit a transaction.

4 Delete resolved transactions from the exceptions log. See “Deleting Transactions from the Exceptions Log” on page 514.

Resume the Connection

Restart the flow of transactions for a suspended database connection with the resume connection command. The same command is used whether you suspended the connection intentionally, using the suspend connection command, or whether it was suspended by Replication Server as the result of an error action. The syntax for resume connection is:

resume connection to data_server.database[skip transaction]

The command requires sa permission and must be entered at the Replication Server that manages the database.

Use the skip transaction clause to instruct Replication Server to ignore the first transaction in the queue. You may need to do this if a transaction continues to fail each time you resume the connection.

Accessing the Exceptions LogThe exceptions log is implemented in three system tables in the RSSD: rs_exceptshdr, rs_exceptscmd, and rs_systext.

• rs_exceptshdr stores general information about a transaction in the exceptions log, such as the transaction ID, the database where the transaction originated, and the data server where the error occurred.

• rs_exceptscmd stores information needed to retrieve the source and output command text from rs_systext. The source is the text of the transaction that Replication Server receives from RepAgent. The output command is the result of Replication Server function string mapping. There is one row for each source and output command.

• rs_systext holds the text of the source and output commands. Each command may have multiple rows in rs_systext, indexed by the sequence column.

Exceptions Handling

512

Refer to Chapter 8, “Replication Server System Tables,” in the Replication Server Reference Manual for a description of each of the columns in these system tables.

Displaying Transactions in the Exceptions Log

You can display a summary list of all transactions in the exceptions log using the rs_helpexception stored procedure. The syntax for the rs_helpexception stored procedure is:

rs_helpexception [transaction_id, [, v]]

If you supply a valid transaction_id and v for “verbose” reporting, rs_helpexception displays a detailed description of a transaction. Use rs_helpexception with no parameters to obtain transaction_id numbers for all transactions in the exceptions log.

Querying the Exceptions Log System Tables

You can join the rs_exceptshdr and rs_exceptscmd system tables on the sys_trans_id column.

You can also join the rs_exceptscmd and rs_systext system tables to retrieve the text of a transaction. To do this, join the cmd_id column in rs_exceptscmd to the parentid column in rs_systext.

Figure 15-1 illustrates the exceptions log system tables.


513

Figure 15-1: Exceptions log system tables

The rs_exceptshdr system table contains descriptive information about the transactions in the exceptions log, including the following:

• User-assigned transaction name

• Site and database where the transaction originated

• User at the origin site who submitted the transaction

• Information about the error that caused the transaction to be recorded in the exceptions log

sys_trans_id rs_id

src_cmd_line int

output_cmd_index int

cmd_type char

cmd_id rs_id

sys_trans_id rs_id

rs_trans_id binary

app_trans_name

varchar

orig_siteid int

orig_site varchar

orig_db varchar

orig_time datetime

orig_user varchar

error_siteid int

error_site varchar

error_db varchar

log_time datetime

ds_error int

ds_errmsg varchar

error_src_line int

error_proc int

err_output_line int

log_reason char

trans_status smallint

retry_status smallint

app_usr varchar

app_pwd varchar

prsid int

parentid rs_id

texttype char

sequence int

textval varchar

rs_exceptshdr

rs_exceptscmdrs_systex

DSI Duplicate Detection

514

To retrieve a list of the excepted transactions for a given database, use, for example, the following query:

select * from rs_exceptshdr where error_site = ’data_server’ and error_db = ’database’ order by log_time

To retrieve the source and output text for a transaction with a given system transaction ID, use:

select t.texttype, t.sequence, t.textval from rs_systext t, rs_exceptscmd e where e.sys_trans_id = sys_trans_idand t.parentid = e.cmd_id order by e.src_cmd_line, e.output_cmd_index, t.sequence

Refer to Chapter 8, “Replication Server System Tables,” in the Replication Server Reference Manual for a list of all of the columns in these Replication Server system tables.

Deleting Transactions from the Exceptions LogTo delete a transaction from the exceptions log, use the rs_delexception stored procedure.

rs_delexception [transaction_id]

With no parameters, rs_delexception displays a summary of transactions in the exceptions log. If you supply a valid transaction_id, rs_delexception deletes a transaction. You can find the transaction_id for a transaction by using either rs_helpexception or rs_delexception with no parameters.

DSI Duplicate DetectionThe DSI records the last transaction committed or written into the exceptions log so that it can detect duplicates after a system restart. Each transaction is identified by a unique origin database ID and an origin queue ID that increases for each transaction.


515

The last transaction committed from each origin database is recorded at a data server by executing the function strings defined for the data server’s function-string class. For the system-defined classes, this is done in the function string for a commit command, that is, the rs_commit function. Every function-string class supports the rs_get_lastcommit function, which returns the origin_qid and secondary_qid for each origin database. The secondary_qid is the ID of the queue used for subscription materialization or dematerialization.

The origin_qid and secondary_qid for the last transaction written into the exceptions log from each origin is recorded into the rs_exceptslast system table. However, transactions logged explicitly by the sysadmin log_first_tran command are not recorded in this system table. These transactions are logged, but they are not skipped.

When a DSI is started or restarted, it gets the origin_qid returned by the rs_get_lastcommit function and the one stored in the rs_exceptslast system table. It assumes that any transaction in the queue with an origin_qid less than the larger of these two values is a duplicate and ignores it.

If the origin_qid values stored in a data server or the rs_exceptslast system table are modified by mistake, non-duplicate transactions may be ignored or duplicate transactions may be reapplied. If you suspect that this is happening in your system, check the values stored and compare them with the transactions in the database’s stable queue to determine the validity of the values. If the values are wrong, you must modify them directly.

Refer to the Replication Server Troubleshooting Guide for details on how to dump transactions in a queue.

Duplicate Detection for System Transactionstruncate table and certain supported DDL commands are not logged, although they can be replicated to standby and replicate databases. Refer to Table 13-3 on page 423 for a list of DDL commands supported for replication. Refer to the Adaptive Server Reference Manual for information about each DDL command.

Replication Server copies these commands as system transactions, in which Replication Server “sandwiches” the truncate table or similar command between two complete transactions. Execution of the first transaction is recorded in the replicate database in the secondary_qid column of the rs_lastcommit table and in the origin_qid column of that table. If Replication Server records the second transaction, the system transaction has completed, and Replication Server clears the secondary_qid column.

Duplicate Detection for System Transactions

516

If there is a system failure, and you see the following error message when the system restarts:

5152 DSI_SYSTRAN_SHUTDOWN,“There is a system transaction whose state is not known. DSI will be shutdown.”

a system command has not completed, and the connection shuts down. You must verify whether the command within the system transaction has executed at the replicate database.

• If the command has executed, or if you choose to execute the command yourself, you can skip the first transaction in the queue and continue with the second transaction when you resume the connection. At the replicate Replication Server, enter:

resume connection to data_server.databaseskip transaction

• If the command has not executed, you can fix the problem and then execute the first command in the queue. At the replicate Replication Server, enter:

resume connection to data_server.databaseexecute transaction

You must include the skip transaction or execute transaction clause with resume connection. Otherwise, Replication Server does not reset the secondary_qid correctly, and the error message reappears.

517

C H A P T E R 1 6 Replication System Recovery

This chapter describes how to prevent or recover from certain kinds of system failures in a replication system.

While Replication Server tolerates most failure conditions and recovers from them automatically, some failures require user intervention. This chapter identifies those failures and provides procedures for recovery. These procedures are designed to maintain the integrity of the replication system by recovering lost and corrupted data and restoring that data to its previous state.

You should design, install, and administer your replication system with backup and recovery in mind. We assume that dumps are performed on a regular basis and that appropriate tools and settings for handling recovery are in place. See “Creating Coordinated Dumps” on page 526 for details on performing dumps.

In this chapter, the current Replication Server refers to the one with a database (for example, RSSD) that you are recovering. An upstream Replication Server has a direct or indirect route to the current Replication Server. A downstream Replication Server is one to which the current Replication Server has a direct or indirect route.

How to Use Recovery ProceduresWhen using recovery procedures in this chapter, always write down or check off recovery steps as you perform them. Such information can help Sybase Technical Support determine where you are in the recovery procedure, if necessary.

Table 16-1 lists failure conditions described in this chapter, and indicates where to find information on corresponding failure symptoms and recovery procedures.

Table 16-1: Overview of available recovery procedures

Failure Condition For Symptoms and Recovery Procedures

Replication Server partition loss or failure “Recovering from Partition Loss or Failure” on page 527

Configuring the Replication System to Support Sybase Failover

518

Recovery procedures are only intended for the specific situations noted in this chapter. Do not use recovery procedures for replication system problems such as failure to replicate data.

Warning! Use recovery procedures in this chapter only for the failure condition specific to the procedure. Attempting to use recovery procedures on conditions other than those specified can complicate your problem and require more drastic recovery actions.

Refer to the Replication Server Troubleshooting Guide for help in diagnosing and correcting problems.


This section describes how Replication Server version 12.0 supports Sybase Failover available in Adaptive Server Enterprise version 12.0.

OverviewSybase Failover allows you to configure two version 12.0 Adaptive Servers as companions. If the primary companion Adaptive Server fails, that server’s devices, databases, and connections can be taken over by the secondary companion Adaptive Server.

You can configure a high availability system either asymmetrically or symmetrically.

An asymmetric configuration includes two Adaptive Servers that are physically located on different machines, but share the same system devices, system/master databases, user databases, and user logins. These two servers are connected so that if one of the servers is brought down, the other assumes its workload. The secondary Adaptive Server acts as a “hot standby” and does not perform any work until failover occurs.

Truncated primary database logs “Recovering from Truncated Primary Database Logs” on page 532

Primary database failure “Recovering from Primary Database Failures” on page 536

RSSD failure “Recovering from RSSD Failure” on page 540

Failure Condition For Symptoms and Recovery Procedures

CHAPTER 16 Replication System Recovery

519

A symmetric configuration also includes two Adaptive Servers running on separate machines, but each Adaptive Server is fully functional with its own system devices, system/master databases, user databases, and user logins. If failover occurs, either Adaptive Server can act as a primary or secondary companion for the other Adaptive Server.

In either setup, the two machines are configured for dual access, which makes the disks visible and accessible to both servers.

In a replication system, where Replication Server makes many connections to Adaptive Servers, you can enable or disable Failover support of the database connections initiated by a Replication Server to Adaptive Servers. When you enable Failover support, Replication Servers connected to an Adaptive Server that fails are automatically switched to the second companion machine, reestablishing network connections.

Note There is no Failover support of Replication Server itself.

Refer to the Adaptive Server Enterprise Version 12.0 Feature Overview for more detailed information about how Sybase Failover works in Adaptive Server.

Enabling Failover Support in Replication ServerYou enable Failover support for each Replication Server in your system; once for the RSSD connection, and once for all other database connections from the specified Replication Server to Adaptive Servers.

You cannot enable Failover support for individual connections, except the RSSD connection.

The default for Failover support in Replication Server is “off” for all connections from a Replication Server to Adaptive Servers.

For continuing replication, you should enable Failover support for all connections. However, in some cases you may want to disable connection Failover when the secondary server’s workload exceeds its capacity.


520

How Sybase Failover Works with Replication Server

To configure Sybase Failover from Replication Server to Adaptive Server, the Adaptive Server must be configured to allow connection failover. You can configure Sybase Failover for a Replication Server from RSM using the Server Configuration dialog box.

When Adaptive Servers are in failover companion mode and the primary companion fails, the secondary companion takes over the workload. Incomplete transactions or operations that require updates to the RSSD fail. Replication Server retries existing connections, but new connections are failed over.

For Data Server Interface (DSI) connections, the DSI retries failed transactions after a brief sleep.

For RSSD connections, user commands that are executed during failover do not succeed. Internal operations (such as updates to locator, disk segment, and so on) should not fail. Replication of RSSD objects should be covered by the DSI.

Asynchronous commands (for example, subscription, routing, and standby commands) may be rejected or encounter errors and require recovery if the commands have been accepted but not completed. For example, a create subscription command may have been accepted, but the subscription may still be being created.

Note Failover support is not a substitute for warm standby. While warm standby keeps a copy of a database, Failover support accesses the same database from a different machine. Failover support works the same for connections from Replication Server to warm standby databases.

Requirements

• To enable Failover support, a Replication Server must connect to Adaptive Servers that are version 12.0 or later and configured for Failover.

• Failover of Replication Server System Databases (RSSDs) and user databases is configured directly through the Adaptive Server.

• Failover support responds only to failover of the Adaptive Servers; that is, failover of Replication Servers is not supported.

• LTMs do not support Failover; that is, RepAgents are required.


521

• Adaptive Server is responsible for the RepAgent thread failover and its reconnection to Replication Server after failover/failback.

• Each Replication Server configures its own connections.

Enabling Failover Support for an RSSD Connection

To enable Failover support for an RSSD connection, use either of the following methods:

• Use rs_init when you install a new Replication Server.

For instructions, see Chapter 2, “Configuring Replication Server and Adding New Databases,” in the Replication Server Configuration Guide for your platform.

• Edit the Replication Server’s configuration file after you have installed the Replication Server.

a Use a text editor to open the Replication Server’s configuration file. The default file name is the Replication Server name with a “.cfg” extension.

The configuration file contains one line per entry.

b Find the line “RSSD_ha_failover=no” and change it to:

RSSD_ha_failover=yes

c To disable Failover support for an RSSD connection, change the “RSSD_ha_failover=yes” to:

RSSD_ha_failover=no

These changes take affect immediately; that is, you do not have to restart Replication Server to enable Failover support.

Enabling Failover Support for Non-RSSD Database Connections

You can enable Failover support for new database connections from the Replication Server or RSM Server to Adaptive Servers using either of the procedures in this section.

For more information about Sybase Failover, refer to the Adaptive Server Enterprise book Using Sybase Failover in a High Availability System.


522

❖ To enable Failover support using the Replication Server Manager (RSM) plug-in for Sybase Central:

1 Right-click the Replication Server or the RSM Server icon in the Sybase Central view for which you want to configure Sybase Failover.

2 Select Configure from the drop-down menu. The Server Configuration dialog box opens.

3 Choose General from the Categories drop-down list.

4 Select HA_failover from the list of configuration parameters.You may need to scroll down through the list to find the Sybase Failover parameter.

5 Enter the correct value in the Pending Value column.

For Replication Server:

• Enter “on” to turn on Sybase Failover.

• Enter “off” to turn off Sybase Failover.

For RSM Server:

• Enter “1” to turn on Sybase Failover.

• Enter “0” to turn off Sybase Failover.

6 Click OK. The Server Configuration dialog box closes.

7 Restart Replication Server or RSM Server, respectively, to have the new parameter value take effect.

See “Starting Replication Server” in Chapter 4 of the Replication Server Administration Guide for instructions.

❖ To enable Failover support using configure replication server:

1 If necessary, start the Replication Server, as described in the section “Starting Replication Server” in Chapter 4 of the Replication Server Administration Guide.

2 Log in to the Replication Server:

isql -Uuser_name -Ppassword -Sserver_name

where user_name must have Administrator privileges. Specify the name of the Replication Server using the -S flag.

When your login is accepted, isql displays a prompt:

1>

3 Enter the following RCL command:


523


Configuring the Replication System to Prevent Data Loss

This section contains recommended measures for preventing data loss in the event of an irrecoverable database error. If used properly, these measures allow you to restore replicated data using the system recovery procedures.

Save Interval for RecoveryReplication Servers are designed to store messages from their source and forward them to their destinations. To increase the chances of recovering online messages after rebuilding stable queues, you can set save intervals, measured in minutes, for routes between Replication Servers. A save interval is the amount of time that a message is stored after it has been forwarded. You can also set save intervals for a physical or logical database connection from a Replication Server, allowing Replication Server to save messages in a DSI outbound queue.

To find the current save interval for a route or connection, use the admin who, sqm command. The Save_Int:Seg column holds two values. The value preceding the colon is the save interval. The value after the colon is the first saved segment in the stable queue.

Details on setting save intervals for routes and connections are described in the following sections.

Routes Between Replication Servers

If the Replication Server has suspended routes, or if a network or data server connection is down, a backlog of messages may accumulate in the Replication Server’s stable queues. The chance of recovering these messages decreases with time. Source Replication Servers may already have deleted messages from their stable queues and database logs may already have been truncated.


524

When you set the save_interval for each route between Replication Servers, you allow each Replication Server to retain messages for a minimum period of time after the next site in the route acknowledges that it has received the messages. The availability of these messages increases the chance of recovering online messages after queues are rebuilt.

For example, in Figure 16-1 on page 524, Replication Server TOKYO_RS maintains a direct route to MANILA_RS, and MANILA_RS maintains a direct route to SYDNEY_RS.

TOKYO_RS retains messages for a period of time after MANILA_RS has received them. If MANILA_RS experiences a partition failure, it requires that TOKYO_RS to resend the backlogged messages. MANILA_RS can also retain messages to allow SYDNEY_RS to recover from failures.

When all of the messages stored on a stable queue segment are at least as old as the save_interval setting, Replication Server deletes the segment so it can be reused.

Figure 16-1: Save interval example

Setting the Save Interval for Routes

To set the save_interval for a route, execute the alter route command at the source Replication Server. Using as an example the replication system in Figure 16-1, here is the command to set Replication Server TOKYO_RS to save for one hour any messages destined for MANILA_RS:

alter route to MANILA_RSset save_interval to ’60’

TOKYO_RS SYDNEY_RS

TOKYO_RS SYDNEY_RS

MANILA_RS

MANILA_RS

PrimaryData Server


TOKYO_DS SYDNEY_DS

RSSDRSSD RSSD


525

By default, the save_interval is set to 0 (minutes). For systems with low volume, this may be an acceptable setting for recovery, since Replication Server does not delete messages immediately after receiving acknowledgment from destination servers. Rather, messages are deleted periodically in large chunks.

However, to accommodate the volume and activity of sites that receive distributions from the Replication Server and to increase the chance of full recovery from database or partition failures, you may want to change the save_interval setting.

In case of a partition failure on the stable queues, be sure your setting allows adequate time to restore your system. Consider also the size of the partitions that are allocated for backlogged messages. Partitions must be large enough to hold the extra messages.

Refer to the Replication Server Design Guide capacity planning guidelines for help in determining queue space requirements.

Connections Between Replication Servers and Data Servers

When you set the save_interval for a physical or logical connection between a Replication Server and a data server and database, you allow Replication Server to save transactions in the DSI queue. You can restore the backlogged transactions using the sysadmin restore_dsi_saved_segments command. Refer to the Replication Server Reference Manual for more information.

You can use these saved transactions to resynchronize a database after it has been loaded to a previous state from transaction dumps and database dumps.

For example, in Figure 16-1, if the replicate data server SYDNEY_DS that is connected to Replication Server SYDNEY_RS experiences a failure, it can obtain the messages saved in the DSI queue at SYDNEY_RS to resynchronize the replicate database after it has been restored.

You can also use the save_interval for setting up a warm standby of a database that holds some replicate data or one that receives applied functions.

Setting the Save Interval for Connections

To set the save_interval for a database connection, execute the alter connection command at the Replication Server. For example, here is the command to set Replication Server SYDNEY_RS to save for one hour any messages destined for its replicate data server SYDNEY_DS.

alter connection to SYDNEY_DS.pubs2


526

set save_interval to ’60’

By default, the save_interval is set to 0 (minutes).

You can also configure the save intervals for the DSI queue and the materialization queue for a logical connection. See “Configuring Logical Connection Save Intervals” on page 463 for details.

Backing Up the RSSDsIf you cannot recover an RSSD’s most recent state, RSSD recovery can be complex. The procedure you use depends on how much RSSD activity there has been since the last dump. See Table 16-3 on page 541 for a list of possible recovery procedures.

You should perform a dump of your RSSDs following any replication DDL, such as changing routes or adding subscriptions.

Creating Coordinated DumpsWhen you must recover a primary database by restoring backups, you must also make sure that replicate data in the affected databases at other sites is consistent with the primary data. To provide for consistency after a restore on multiple data servers, Replication Server provides a method for coordinating database dumps and transaction dumps at all sites in a replication system.

You initiate a database dump or transaction dump from the primary database. RepAgent retrieves the dump record from the log and submits it to Replication Server so that the dump request can be distributed to the replicate sites. The method ensures that all of the data can be restored to a known point of consistency.

You can only use a coordinated dump with databases that store either primary data or replicated data but not both. You initiate a coordinated dump from within a primary database.

The process for coordinating dumps works as follows:


527

• In each function-string class assigned to the databases involved, the Replication System Administrator at each site creates function strings for the rs_dumpdb and rs_dumptran system functions. The function strings should call stored procedures that execute the dump database and dump transaction or equivalent commands and update the rs_lastcommit system table. Refer to the Replication Server Reference Manual for examples.

• You must be using a function-string class, such as a derived class, in which you can create and modify function strings. See “Managing Function-String Classes” on page 385 for more information.

• Using the alter connection command, the Replication System Administrator at each replicate site configures the Replication Servers to enable a coordinated dump.

• When a dump is started in a primary database, the RepAgent transfers the dump database or dump transaction log record to the Replication Server.

• Replication Server distributes an rs_dumpdb or rs_dumptran function call to sites that have subscriptions for the replicated tables in the database.

• The rs_dumpdb and rs_dumptran function strings at the replicate sites execute the customized stored procedures at each replicate site.

Recovering from Partition Loss or FailureWhen a Replication Server detects a failed or missing partition, it shuts down the stable queues that are using the partition and logs messages about the failure. Restarting Replication Server does not correct the problem. You must drop the damaged partition and rebuild the stable queues.

Complete recovery depends on the volume of messages cleared from the queue and on how soon you apply the recovery procedure after the failure occurs. If a Replication Server maintains minimal latency in the replication system, only the most recent messages are lost when its queues are rebuilt.

If a partition fails in a primary Replication Server, you can usually resend lost messages from their source using an off-line database log. If partitions fail in a replicate Replication Server, you need to recover from the stable queue of the upstream Replication Server.

Recovering from Partition Loss or Failure

528

In some cases, using an off-line log may be the only way you can recover your messages. If the Replication Server has suspended routes or connections, or if a network or data server connection goes down, a backlog may have accumulated in the Replication Server’s stable queues. Unless you have specified a save interval setting that can cover the backlog, your chance of recovering these messages decreases with time. Source Replication Servers may have already deleted messages from their stable queues and may have truncated the database logs.

Note For details on setting and displaying the save interval for recovery purposes, see “Recovering from Partition Loss or Failure” on page 527.

Table 16-2 summarizes when to use and where to locate the appropriate recovery procedure for partition loss or failure.

Table 16-2: Overview of symptoms and procedures

Procedure for Recovering from Partition Loss or FailureTo recover from Replication Server partition loss or failure, perform the following steps:

1 Log in to the Replication Server and drop the failed partition:

drop partition logical_name

Replication Server does not immediately drop a partition that was in use. If the partition is undamaged, Replication Server drops it only after all of the messages it holds are delivered and deleted.

Refer to “drop partition” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for more information.

Symptom Use This Procedure

Replication Server detects lost, damaged, or failed stable queue.

“Procedure for Recovering from Partition Loss or Failure” on page 528.

Message loss occurred because a backlog existed in the failed Replication Server and there were insufficient messages saved at the previous site.

“Message Recovery from Off-line Database Logs” on page 530.

In addition to message loss, database logs have been truncated. Either the secondary truncation point is invalid or the dbcc settrunc(’ltm’, ’ignore’) command, was executed to truncate log records that have not been transferred by RepAgent to the Replication Server.

Use “Truncated Message Recovery from the Database Log” on page 533 to recover the database log. Then use “Message Recovery from Off-line Database Logs” on page 530 to rebuild the stable queues and recover lost messages.


529

2 If the failed partition was the only one available to the Replication Server, add another one to replace it:

add partition logical_nameon ’physical_name’ with size size[starting at vstart]

Refer to “add partition” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for more information.

3 Since the partition is damaged, you must rebuild the stable queues:

rebuild queues

See “Rebuilding Queues Online” on page 556 for a description of this process.

When all stable queues on the partition are removed, Replication Server drops the failed partition from the system and rebuilds the queues using the remaining partitions.

4 After rebuilding the queues, check the Replication Server logs for loss detection messages.

See “Loss Detection After Rebuilding Stable Queues” on page 558 for background and details.

5 If Replication Server detected message loss, you can:

• Perform “Message Recovery from Off-line Database Logs” on page 530, or

• Request that Replication Server ignore the loss by executing the ignore loss command for the database on the Replication Server where the loss was detected.

Note If you specify that Replication Server ignore message losses and you have rebuilt the queues of a Replication Server that is part a route, you must re-create subscriptions at the destination or use the rs_subcmp program with the -r flag to reconcile primary and replicate data.

Recovering from Partition Loss or Failure

530

Message Recovery from Off-line Database LogsIf the online log does not contain all the data needed to recover, you must load an older version of the primary database into a separate database and start RepAgent for the database. Although RepAgent is accessing a different database, it submits messages as if they were from the database whose messages you are recovering.

To recover messages from off-line logs after a partition failure:

1 Restart Replication Server in standalone mode, using the -M flag.

2 Log in to the Replication Server, and enter:

rebuild queues


3 Inspect the Replication Server logs at each site for “Checking Loss” messages.

See “Determining Which Dumps to Load” on page 564 for background and details on examining these messages.

4 Use the date and time in the error log messages to determine which dumps to load.

5 Enable RepAgent for a temporary recovery database, using the sp_config_rep_agent system procedure.

sp_config_rep_agent temp_dbname, ’enable’, \ ’rs_name’, ’rs_user_name’, ’rs_password’

See“Setting Replication Server Configuration Parameters” on page 92 for information about configuring RepAgent.

6 Load the database dump and the first transaction log dump in to a temporary recovery database.

7 Start RepAgent in recovery mode for the temporary database:

sp_start_rep_agent temp_dbname, ’for_recovery’, \ ’connect_dataserver’, ’connect_database’, \ ’rs_name’, ’rs_user_name’, ’rs_password’

where “connect_dataserver” and “connect_database” specify the original primary data server and database.


531

RepAgent transfers data in the transaction log of the temporary recovery database to the original primary database. When RepAgent completes scanning the transaction log, it shuts down.

8 Verify that RepAgent has replayed the transaction log of the temporary database.

a Check the Adaptive Server log for a message similar to the following:

Recovery of transaction log is complete. Please load the next transaction log dump and then start up the Rep Agent Thread with sp_start_rep_agent, with ‘for_recovery’ specified.

and perform the appropriate actions, or

b From Adaptive Server, execute the sp_help_rep_agent system procedure for recovery:

sp_help_rep_agent dbname, 'recovery'

This procedure displays RepAgent’s recovery status. If the recovery status is “not running” or “end of log,” then recovery is complete. You can load the next transaction log dump. If the recovery status is “initial” or “scanning,” either the log has not been replayed, or the replay is not complete.

9 If you have performed another recovery procedure since you performed the last database dump, you may need to change the database generation number after loading a transaction log dump. See “Determining Database Generation Numbers” on page 565.

10 If there are more transaction log dumps to load, repeat the following three steps for each dump:

a Load the next transaction log dump. (Be sure to load the dumps in the correct order.)

b Restart RepAgent in recovery mode.

c Watch the Adaptive Server log for the completion message or use sp_help_rep_agent.

11 Check the Replication Server logs for loss detection messages.

No losses should be detected unless you failed to load the database to a state old enough to retrieve all of the messages.

See “Loss Detection After Rebuilding Stable Queues” on page 558 for background and details.

Recovering from Truncated Primary Database Logs

532

12 Restart the Replication Server in normal mode.

13 Restart RepAgent for the original primary data server and database in normal mode.

Message Recovery from the Online Database LogTo recover messages that are still in the online log at the primary database, perform the following steps:

1 Stop all client activity.

2 Restart RepAgent for the primary database in recovery mode.

This process causes RepAgent to scan the log from the beginning so that it retrieves all messages.

Recovering from Truncated Primary Database LogsThis section describes how to recover from failures caused by truncating a primary transaction log before Replication Server has received the messages.

This situation typically occurs if RepAgent, a Replication Server (managing a primary database), or a network between them is down for a long time and RepAgent or Replication Server is unable to read records from the transaction log. The secondary truncation point cannot be moved, which prevents Adaptive Server from truncating the log and causes the transaction log of the primary database to fill up. You must then disable RepAgent by executing sp_config_rep_agent with the disable option turned on.

When a failed component returns to service, messages are missing at the Replication Server. Depending on the status of the lost messages, use one of the following procedures:

• If messages are still in the online log at the primary database (which is unlikely), see “Message Recovery from the Online Database Log” on page 532.

• If messages have been truncated from the online database log, see “Truncated Message Recovery from the Database Log” on page 533.


533

Truncated Message Recovery from the Database LogIn this procedure, you must load a previous database dump and transaction log dumps into a temporary recovery database. Then connect a RepAgent to that database to transmit the truncated log to the Replication Server. After the missing log records are recovered, you can restart the system using the regular primary database.

Using a temporary recovery database permits transaction recovery from clients that continued to use the primary database after its log was truncated.

Note Use the temporary database exclusively for recovering messages. Any modification to the database prevents you from loading the next transaction log dump. Also limit the activity on the original primary database so that the recovery can be completed before the transaction log on the original primary database must be dumped and truncated again.

To replay off-line transaction logs, follow these steps:

1 Start the Replication Server in standalone mode, using the -M flag.

2 Log in to the Replication Server and execute the set log recovery command for each primary database you are recovering.

See “Setting Log Recovery for Databases” on page 562.

This command puts the Replication Server into loss detection mode for the databases. Replication Server logs a message similar to the following:

Checking Loss for DS1.PDB from DS1.PDBdate=Nov-01-1995 10:35amqid=0x01234567890123456789

3 Review the “Checking Loss” messages for the date and time, to determine which database dumps and transaction log dumps to load.

See “Determining Which Dumps to Load” on page 564.

Recovering from Truncated Primary Database Logs

534

4 Execute the allow connections command to allow Replication Server to accept connections only from other Replication Servers and from RepAgents in recovery mode.

Note If you attempt to connect to this Replication Server by automatically restarting RepAgent in normal mode with scripts, the Replication Server rejects the connection. You must restart RepAgent in recovery mode while pointing to the correct off-line log. This step allows you to resend old transaction logs before current transactions are processed.

5 Enable RepAgent for a temporary recovery database, using the sp_config_rep_agent system procedure.

sp_config_rep_agent temp_dbname, ’enable’, ’rs_name’, ’rs_user_name’, ’rs_password’

See “Setting Replication Server Configuration Parameters” on page 92 for more information about configuring RepAgent.

6 Load the database dump and the first transaction log dump into a temporary recovery database.

7 Start RepAgent in recovery mode for the temporary database:

sp_start_rep_agent temp_dbname, ’for_recovery’, ’connect_dataserver’, ’connect_database’, ’repserver_name’, ’repserver_username’, ’repserver_password’

where connect_dataserver and connect_database specify the original primary data server and database.

RepAgent transfers data in the transaction log of the temporary recovery database to the original primary database. When RepAgent completes scanning the current transaction log, it shuts down.

8 Verify that RepAgent has replayed the transaction log of the temporary database.

a Check the Adaptive Server log for the following message:




535

b From the Adaptive Server, execute the sp_help_rep_agent system procedure for recovery:



9 If you have performed another recovery procedure since you performed the last database dump, you may need to change the database generation number after loading a transaction log dump. See “Determining Database Generation Numbers” on page 565.

10 If there are more transaction log dumps to load, repeat the following three steps for each dump:

a Load the next transaction log dump. (Be sure to load the dumps in the correct order.)

b Restart RepAgent in recovery mode.

c Watch the Adaptive Server log for the completion message or execute sp_help_rep_agent.

11 Check the Replication Server logs for loss detection messages.

No losses should be detected unless you failed to load the database to a state old enough to retrieve all of the messages.

See “Loss Detection After Setting Log Recovery” on page 563 for background and details.

12 Perform one of the following actions, depending on whether loss was detected:

• If no loss was detected, complete recovery by restarting the Replication Server and RepAgent in normal mode, or

• If loss was detected, you started the replay from the incorrect log. Decide whether to ignore the losses by executing the ignore loss command, or repeat the recovery procedure from the beginning.

13 If you need to repeat the recovery procedure, be sure to start from earlier logs for a successful outcome.

Recovering from Primary Database Failures

536

Recovering from Primary Database FailuresMost database failures are recovered without losing any committed transactions. No special Replication Server recovery procedure is needed if the database recovers on restart—Replication Server performs a handshake with the database, ensuring that no transactions are lost or duplicated in the replication system.

If a primary database fails and you are unable to recover all committed transactions, you must load the database to a previous state and follow a recovery procedure designed to restore consistency at the replicate sites.

Here are two possible scenarios for recovering from primary database failures:

• Recovering with coordinated dumps

If you have coordinated dumps of primary and replicate databases, you can use them to load all databases in the replication system to a consistent state.

See “Loading from Coordinated Dumps” on page 536 for details.

• Recovering with primary dumps only

If you do not have coordinated dumps, you can load the failed primary database and then verify the consistency of the replicate databases with the restored primary database.

See “Loading a Primary Database from Dumps” on page 537 for details.

Loading from Coordinated DumpsUse this procedure only if you have coordinated dumps of both primary and replicate databases. To load a primary database and all replicate databases to the same state, follow this procedure:

1 Perform steps 1 through 15 from “Loading a Primary Database from Dumps” on page 537.

2 Suspend connections to the replicate databases that must be restored.

3 For each replicate database, log in to its managing Replication Server and execute the suspend connection command:


4 Load the replicate databases from the coordinated dumps that correspond to the restored primary database state.


537

5 For each replicate database, log in to its managing Replication Server and execute a sysadmin set_dsi_generation command to set the generation number for the database to the same generation number used in step 1:

sysadmin set_dsi_generation, 101,primary_data_server, primary_database,replicate_data_server, replicate_database

The parameters primary_data_server and primary_database specify the primary database for loading. The parameters replicate_data_server and replicate_database specify the replicate database for loading.

Setting the generation numbers in this manner prevents Replication Servers from applying to the replicate databases any old messages that may be in the queues.

6 For each replicate database, log in to its managing Replication Server and execute the resume connection command to restart the DSI for the database:


7 Restart the primary Replication Server in normal mode.

8 Restart RepAgent for the primary database in normal mode.

Note If any subscriptions were materializing when the failure occurred, drop them and re-create them.

Loading a Primary Database from DumpsUse this procedure if you are loading only a primary database in a replication system. To load the database to a previous state and resolve any inconsistencies with replicate databases, follow this procedure:

1 Shut down the RepAgent for the primary database. To do this, execute the sp_stop_rep_agent system procedure from Adaptive Server.

If you want to apply commands currently in transition within the replication system, you must quiesce the system. Otherwise, commands arriving at replicate sites are rejected. The rejected commands are immaterial when you are loading the replicate databases.

2 Suspend the DSI connection to the primary database (for exclusive use).

3 Load the database to the most recent or previous state.

Recovering from Primary Database Failures

538

This step entails loading the most recent database dump and all subsequent transaction log dumps.

Refer to the Adaptive Server Administration Guide for instructions.

4 Resume the DSI connection.

5 Restart the primary Replication Server in standalone mode, using the -M flag.

6 Log in to the primary Replication Server and use the admin get_generation command to get the database generation number for the primary database:

admin get_generation, data_server, database

Write down the generation number so you have it for step 15.

7 In the Replication Server, execute the set log recovery command for the database:

set log recovery for data_server.database

This command tells the Replication Server to only accept a connection from RepAgent for the specified database. Other RepAgents are rejected.

8 Execute the allow connections command in the Replication Server:

allow connections

The Replication Server is now in recovery mode.

9 Log in to the Adaptive Server and execute a checkpoint in the loaded database to record the state of the rollbacks. This action permits Replication Server to truncate its inbound queues faster.

10 Start RepAgent for the primary database in recovery mode, using the for_recovery option.

11 Verify that RepAgent has replayed the transaction log of the database.

a Check the Adaptive Server log for a message similar to the following:



b From the Adaptive Server, execute the sp_help_rep_agent system procedure for recovery:


539



12 Check the Replication Server error logs for loss detection messages.

See “Loss Detection After Setting Log Recovery” on page 563 for background and details.

13 If a loss was detected, it must be a “false loss,” so you can ignore it. Log in to the Replication Server and execute the ignore loss command:

ignore loss from data_server.databaseto data_server.database

The “from” and “to” databases are the same for losses detected from RepAgents for primary databases. See “SQM Loss Between Two Replication Servers” on page 559 for more information about false losses.

14 Shut down RepAgent for the primary database.

15 Log in to the data server, access the primary database, and execute the dbcc settrunc command in the restored primary database to set the generation number to the next higher number. For example, if the admin get_generation command in step 6 returned 100, enter the following commands:

use databasegodbcc settrunc(’ltm’, ’gen_id’, 101)go

database is the name of the restored primary database.

See “Determining Database Generation Numbers” on page 565 for background information.

16 Restart the primary Replication Server in normal mode.

17 Start RepAgent for the primary database in normal mode.

18 Run the rs_subcmp program for each subscription at the replicate sites. Use the -r flag to reconcile the replicate data with the restored primary data, or

Drop all of the subscriptions and re-create them.

Recovering from RSSD Failure

540

See Chapter 10, “Managing Subscriptions” for more information on using rs_subcmp. Also refer to “rs_subcmp” in Chapter 7, “Programs,” in the Replication Server Reference Manual.

Recovering from RSSD FailureIf you cannot recover the RSSD’s most recent database state, recovering from an RSSD failure is a complex process. In this case, you must load the RSSD from old database dumps and transaction log dumps.

The procedure for recovering an RSSD is similar to that for recovering a primary database. However, it requires more steps, since the RSSD holds information about the replication system itself. RSSD system tables are closely associated with the state of the stable queues and of other RSSDs in the replication system.

If a Replication Server’s RSSD has failed, you first need to determine the extent of recovery required. To do this, perform one or more of the following actions:

• When the RSSD becomes available, log in to the Replication Server and execute admin who_is_down. Some Replication Server threads may have shut down during the RSSD’s period of inactivity.

• If an SQM thread for an inbound or outbound queue or an RSI outbound queue is down, restart the Replication Server.

• If a DSI thread is down, resume the connection to the associated database.

• If an RSI thread is down, resume the route to the destination database.

For instructions on viewing thread status in Sybase Central, see “Viewing thread status” in Replication Server’s online help.

• Check all connecting RepAgents to see if they are running with the sp_help_rep_agent system procedure. (RepAgents may have shut down in response to errors resulting from RSSD shutdown.) Restart them if necessary.

• If you cannot recover the RSSD’s most recent database state, you must load it from old database dumps and transaction log dumps. See “Recovering an RSSD from Dumps” on page 541.

RSM


541

Recovering an RSSD from DumpsThe procedure you use to recover an RSSD depends on how much RSSD activity there has been since the last RSSD dump. There are four increasingly severe levels of RSSD failure, with corresponding recovery requirements. Use Table 16-3 to locate the RSSD recovery procedure you need.

Table 16-3: Recovering from RSSD failures

Basic RSSD Recovery ProcedureUse the basic RSSD recovery procedure to restore the RSSD if you have executed no DDL commands since the last RSSD dump. DDL commands in RCL include those for creating, altering, or deleting routes, replication definitions, subscriptions, function strings, functions, function-string classes, or error classes.

Certain steps in this procedure are also referenced by other RSSD recovery procedures in this chapter.

Warning! Do not execute any DDL commands until you have completed this recovery procedure.

To perform basic RSSD recovery, follow these steps:

1 Shut down all RepAgents that connect to the current Replication Server.

Activity Since Last RSSD Dump Use This Procedure

No DDL activity “Basic RSSD Recovery Procedure” on page 541

DDL activity, but no new routes or subscriptions created

“Subscription Comparison Procedure” on page 544

DDL activity, but no new routes created “Subscription Re-Creation Procedure” on page 551

New routes created “Deintegration/Reintegration Procedure” on page 554


542

2 Since its RSSD has failed, the current Replication Server is down. If for some reason it is not down, log in to it and use the shutdown command to shut it down.

Note Some messages may still be in the Replication Server stable queues. Data in those queues may be lost when you rebuild these queues in later steps.

3 Restore the RSSD by loading the most recent RSSD database dump and all transaction dumps.

4 Restart the Replication Server in standalone mode, using the -M flag.

You must start the Replication Server in standalone mode, because the stable queues are now inconsistent with the RSSD state. When the Replication Server starts in standalone mode, reading of the stable queues is not automatically activated.

5 Log in to the Replication Server, and get the generation number for the RSSD, using the admin get_generation command:

admin get_generation, data_server, rssd_name

For example, the Replication Server may return a generation number of 100.

6 In the Replication Server, rebuild the queues with the following command:

rebuild queues


7 Start all RepAgents (except the RSSD RepAgent) that connect to the current Replication Server in recovery mode.

Wait until each RepAgent logs a message in the Adaptive Server log that it is finished with the current log.

8 Check the loss messages in the Replication Server log, and in the logs of all the Replication Servers with direct routes from the current Replication Server.

• If all your routes were active at the time of failure, you probably will not experience any real data loss.


543

• However, loss detection may indicate real loss. Real data loss may be detected if the database logs were truncated at the primary databases, so that the rebuild process did not have enough information to recover. If you have real data loss, reload database logs from old dumps. See “Recovering from Truncated Primary Database Logs” on page 532.

• See “Loss Detection After Rebuilding Stable Queues” on page 558 for background and details on loss detection.

9 Shut down RepAgents for all primary databases managed by the current Replication Server.

10 Execute the dbcc settrunc command at the Adaptive Server for the restored RSSD. Move up the secondary truncation point.

> use rssd_name> go> dump tran rssd_name with truncate_only> go> begin tran commit tran> go 40

Note The begin tran commit tran go 40 command moves the Adaptive Server log onto the next page.

After completing step 10 and before continuing with step 11, run the following command to clear the locator information.

> rs_zeroltm rssd_server, rssd_name > go

11 Execute the dbcc settrunc command at the Adaptive Server for the restored RSSD to set the generation number to one higher than the number returned by admin get_generation in step 5.

> use rssd_name> go> dbcc settrunc(’ltm’, ’gen_id’, 101)> go

Make a record of this generation number and of the current time, so that you can return to this RSSD recovery procedure, if necessary. Or, you can dump the database after setting the generation number.

12 Restart the Replication Server in normal mode.


544

If you performed this procedure as part of the subscription comparison or subscription re-creation procedure, the upstream RSI outbound queue may contain transactions, bound for the RSSD of the current Replication Server, that have already been applied using rs_subcmp. If this is the case, after starting the Replication Server, the error log may contain warnings referring to duplicate inserts. You can safely ignore these warnings.

13 Restart RepAgents for the RSSD and for user databases in normal mode.

If you performed this procedure as part of the subscription comparison or subscription re-creation RSSD recovery procedure, you should expect to see messages regarding RSSD losses being detected in all Replication Servers that have routes from the current Replication Server.

Subscription Comparison ProcedureFollow this RSSD recovery procedure if you have executed some DDL commands since the last transaction dump but you have not created any new subscriptions or routes. DDL commands in RCL include those for creating, altering, or deleting routes, replication definitions, subscriptions, function strings, functions, function-string classes, or error classes.

Warning! Do not execute any DDL commands until you have completed this recovery procedure.

Following this procedure makes the failed RSSD consistent with upstream RSSDs or consistent with the most recent database and transaction dumps (if there is no upstream Replication Server). It then makes downstream RSSDs consistent with the recovered RSSD.

If DDL commands have been executed at the current Replication Server since the last transaction dump, you may have to re-execute them.

Warning! This procedure may fail if you are operating in a mixed-version environment; that is, the Replication Servers in your replication system are not all at the same version level.

To restore an RSSD with subscription comparison, follow these steps:

1 To prepare the failed RSSD for recovery, perform steps 1 through 4 of “Basic RSSD Recovery Procedure” on page 541.


545

2 To prepare all upstream RSSDs for recovery, execute the admin quiesce_force_rsi command at each upstream Replication Server.

• This step ensures that all committed transactions from the current Replication Server have been applied before you execute the rs_subcmp program.

• Execute this command sequentially, starting with the Replication Server that is furthest upstream from the current Replication Server.

• Make sure that RSSD changes have been applied, that is, that the RSSD DSI outbound queues are empty.

• The Replication Server that is directly upstream from the current Replication Server cannot be quiesced.

3 To prepare all downstream RSSDs for recovery, execute the admin quiesce_force_rsi command at each downstream Replication Server.

• This step ensures that all committed transactions bound for the current Replication Server have been applied before you execute the rs_subcmp program.

• Execute this command sequentially, starting with Replication Servers that are immediately downstream from the current Replication Server.

• Make sure that RSSD changes have been applied, that is, that the RSSD DSI outbound queues are empty.

4 Reconcile the failed RSSD with all upstream RSSDs, using the rs_subcmp program.

• First execute rs_subcmp without reconciliation to get an idea of what operations it will perform. When you are ready to reconcile, use the -r flag to reconcile the replicate data with the primary data.

• You must execute rs_subcmp as the maintenance user. See Chapter 7, “Managing Replication Server Security” for more information on the maintenance user.

• In each instance, specify the failed RSSD as the replicate database.

• In each instance, specify the RSSD of each upstream Replication Server as the primary database.

• Start with the furthest upstream Replication Server, and proceed downstream for all other Replication Servers with routes (direct or indirect) to the current Replication Server.


546

• Reconcile each of the following RSSD system tables: rs_articles, rs_classes, rs_columns, rs_databases, rs_erroractions, rs_functions, rs_funcstrings, rs_objects, rs_publications, rs_systext, and rs_whereclauses.

• When you execute rs_subcmp on replicated RSSD tables, the where and order by clauses of the select statement must include all rows to be replicated. See “Using rs_subcmp on Replicated RSSD System Tables” on page 547 for more information.

The failed RSSD should now be recovered.

5 Reconcile all downstream RSSDs with the RSSD for the current Replication Server, which was recovered in the previous step, using the rs_subcmp program.

• First execute rs_subcmp without reconciliation to get an idea of what operations it will perform. When you are ready to reconcile, use the -r flag to reconcile the replicate data with the primary data.

• You must execute rs_subcmp as the maintenance user. See Chapter 7, “Managing Replication Server Security” for more information on the maintenance user.

• In each instance, specify as the primary database the recovered RSSD.

• In each instance, specify as the replicate database the RSSD of each downstream Replication Server.

• Start with the Replication Servers that are immediately downstream, then proceed downstream for all other Replication Servers with routes (direct or indirect) from the current Replication Server.

• Reconcile each of the following RSSD system tables: rs_articles, rs_classes, rs_columns, rs_databases, rs_erroractions, rs_functions, rs_funcstrings, rs_objects, rs_publications, rs_systext, and rs_whereclauses.

• When you execute rs_subcmp on replicated RSSD tables, the where and order by clauses of the select statement must select all rows to be replicated. See “Using rs_subcmp on Replicated RSSD System Tables” on page 547 for more information.

All downstream RSSDs should now be fully recovered.

6 If the recovering Replication Server is an ID Server, you must restore the Replication Server and database IDs in its RSSD.


547

a For every Replication Server, check the rs_databases and rs_sites system tables for their IDs.

b Insert the appropriate rows in the recovering RSSD’s rs_idnames system table if they are missing.

c Delete from the recovering RSSD’s rs_idnames system table any IDs of databases or Replication Servers that are no longer part of the replication system.

d To ensure that the rs_ids system table is consistent, execute the following stored procedure in the RSSD of the current Replication Server:

rs_mk_rsids_consistent

7 If the recovering Replication Server is not an ID Server, and a database connection was created at the recovering Replication Server after the last transaction dump, delete the row corresponding to that database connection from the rs_idnames system table in the ID Server’s RSSD.

8 Perform steps 5 through 13 of “Basic RSSD Recovery Procedure” on page 541.

9 To complete RSSD recovery, re-execute any DDL commands executed at the current Replication Server since the last transaction dump.

Using rs_subcmp on Replicated RSSD System Tables

When executing rs_subcmp on replicated RSSD tables during RSSD recovery procedures, formulate the where and order by clauses of the select statement to select all rows that must be replicated for each system table.

Table 16-4 illustrates the general form of these select statements.

Note You may need to adjust these select statements in a mixed-version environment.

Table 16-4: select statements for rs_subcmp procedure

RSSD Table Name select Statement

rs_articles select * from rs_articles where prsid in sub_select order by primary_key

rs_classes select * from rs_classes where prsid in sub_select order by primary_keys

rs_columns select * from rs_columns where prsid in sub_select and rowtype = 1 order by primary_keys

rs_databases select * from rs_databases where prsid in sub_select and rowtype = 1 order by primary_keys


548

In the select statements in Table 16-4, sub_select represents the following sub-selection statement, which selects all site IDs that are the source Replication Servers for the current Replication Server:

(select source_rsid from rs_routeswhere

(through_rsid = PRS_site_IDor through_rsid = RRS_site_ID)

anddest_rsid = RRS_site_ID)

where PRS_site_ID is the site ID of the Replication Server managing the primary RSSD, and RRS_site_ID is the site ID of the Replication Server managing the replicate RSSD for the rs_subcmp operation.

For the rs_columns, rs_databases, rs_funcstrings, rs_functions, and rs_objects system tables, if rowtype = 1, then the row is a replicated row. Only replicated rows need be compared using rs_subcmp.

For each system table, the primary_keys are its unique indexes.

Classes and System Tables

The system-provided function-string classes and error class do not initially have a designated primary site, that is, their site ID = 0. The classes rs_default_function_class and rs_db2_function_class cannot be modified, and thus can never have a designated primary site. The classes rs_sqlserver_function_class and rs_sqlserver_error_class may be assigned a primary site and modified. The primary site of a derived function-string class is the same as its parent class.

rs_erroractions select * from rs_erroractions where prsid in sub_select order by primary_keys

rs_funcstrings select * from rs_funcstrings where prsid in sub_select and rowtype = 1 order by primary_keys

rs_functions select * from rs_functions where prsid in sub_select and rowtype = 1 order by primary_keys

rs_objects select * from rs_objects where prsid in sub_select and rowtype = 1 order by primary_keys

rs_publications select * from rs_publications where prsid in sub_select order by primary_key

rs_systext select * from rs_systext where prsid in sub_select and texttype in (’O’, ’S’) order by primary_keys

rs_whereclauses select * from rs_whereclauses where prsid in sub_select order by primary_key

RSSD Table Name select Statement


549

If the recovering Replication Server was made the primary site for a function-string class or error class since the last transaction dump, the rs_subcmp procedure described earlier in this section would find orphaned rows in downstream RSSDs.

In that event, run rs_subcmp again on the rs_classes, rs_erroractions, rs_funcstrings, and rs_systext system tables. Set prsid = 0 in order to repopulate these tables with the necessary default settings. For example, use the following select statement for the rs_classes table:

select * from rs_classes where prsid = 0order by primary_keys

Example

Suppose you have the following Replication Server sites in your replication system, where an arrow (→) indicates a route. Site B is the failed site, and there are no indirect routes.

A→B C→B C→D B→E

These Replication Servers have the following site IDs:

A = 1 B = 2 C = 3 D = 4 E = 5

In this example, to bring the RSSDs to a consistent state, you would perform the following tasks, in the order presented, on the rs_classes, rs_columns, rs_databases, rs_erroractions, rs_funcstrings, rs_functions, rs_objects, and rs_systext system tables.

Reconciling with Upstream RSSDs

1 Run rs_subcmp against the above tables, specifying site B as the replicate and site A as the primary, with prsid = 1 in the where clauses. For example, the select statement for rs_columns should look like the following:

select * from rs_columns where prsid in(select source_rsid from rs_routes where


550

(through_rsid = 1 or through_rsid = 2) and dest_rsid = 2)and rowtype = 1order by objid, colname

2 Run rs_subcmp against the above tables, specifying site B as the replicate and site C as the primary, with prsid = 3 in the where clauses. For example, the select statement for rs_columns should look like the following:


(through_rsid = 3 or through_rsid = 2) and dest_rsid = 2)

and rowtype = 1 order by objid, colname

Reconciling Downstream RSSDs

1 Run rs_subcmp against the above tables, specifying site B as the primary and site E as the replicate, with prsid = 2 in the where clauses. For example, the select statement for rs_columns should look like the following:


(through_rsid = 2 or through_rsid = 5) and dest_rsid = 5)

and rowtype = 1 order by objid, colname

Refer to “rs_subcmp” in Chapter 7, “Programs,” in the Replication Server Reference Manual for more information on rs_subcmp. Refer to Chapter 8, “Replication Server System Tables,” in the Replication Server Reference Manual for more information on the RSSD system tables.


551

Subscription Re-Creation ProcedureFollow this RSSD recovery procedure if you have created new subscriptions or other DDL since the last transaction dump, and you have not created new routes. DDL commands in RCL include those for creating, altering, or deleting routes, replication definitions, subscriptions, function strings, functions, function-string classes, or error classes.

Warning! Do not execute any DDL commands until you have completed the subscription re-creation recovery procedure.

As with the subscription-comparison RSSD recovery procedure, following this procedure makes the failed RSSD consistent with upstream RSSDs or with the most recent database and transaction dumps (if there is no upstream Replication Server). It then makes downstream RSSDs consistent with the recovered RSSD.

In this procedure, however, you also either delete or re-create subscriptions that are in limbo due to the loss of the RSSD.

If DDL commands have been executed at the current Replication Server since the last transaction dump, you may have to reexecute them.

To restore an RSSD that requires that lost subscriptions be re-created, follow these steps:

1 To prepare the failed RSSD for recovery, perform steps 1 through 4 of “Basic RSSD Recovery Procedure” on page 541.

2 To prepare the RSSDs of all upstream and downstream Replication Servers for recovery, perform step 2 through 3 of “Subscription Comparison Procedure” on page 544.

3 Shut down all upstream and downstream Replication Servers affected by the previous step. Use the shutdown command.

4 Restart all upstream and downstream Replication Servers in standalone mode, using the -M flag.

All RepAgents connecting to these Replication Servers shut down automatically when you restart the Replication Servers in standalone mode.

5 To reconcile the failed RSSD with all upstream RSSDs, perform step 4 of “Subscription Comparison Procedure” on page 544.

The failed RSSD should now be recovered.


552

6 To reconcile all downstream RSSDs with the RSSD for the current Replication Server, perform step 5 of “Subscription Comparison Procedure” on page 544.

7 If the recovering Replication Server is an ID Server, to restore the IDs in its RSSD, perform step 6 of “Subscription Comparison Procedure” on page 544.

8 If the recovering Replication Server is not an ID Server and a database connection was created at the recovering Replication Server after the last transaction dump, perform step 7 of “Subscription Comparison Procedure” on page 544.

9 Query the rs_subscriptions system table of the current Replication Server for the names of subscriptions and replication definitions or publications and their associated databases.

• Also query all Replication Servers with subscriptions to primary data managed by the current Replication Server, or with primary data to which the current Replication Server has subscriptions.

• You can query the rs_subscriptions system table by using the rs_helpsub stored procedure.

10 For each user subscription in the rs_subscriptions system table, execute the check subscription command using the information obtained in step 9.

• Execute this command at the current Replication Server and at all Replication Servers with subscriptions to primary data managed by the current Replication Server, or with primary data to which the current Replication Server has subscriptions.

• Subscriptions with a status other than VALID must be deleted or re-created, as described below.

11 For each Replication Server that has a non-VALID subscription with the current Replication Server as the primary:

• Note its subid, and delete the appropriate row from the primary rs_subscriptions system table.

• Use the subid from rs_subscriptions to find corresponding rows in the rs_rules system table, and also delete those rows.

For each system table, rs_subscriptions and rs_rules:


553

• If a subscription is in the primary table and not in the replicate table (because it was dropped), delete the subscription row from the primary table.

• If a subscription is in the replicate table and not in the primary table, delete the subscription row from the replicate table. After completing the rest of this procedure, re-create the subscription, as described in steps 17 through 19.

• If a subscription is in both the primary and replicate tables but is not VALID at one of the sites, delete the rows from both tables. After completing the rest of this procedure, re-create the subscription, as described in steps 17 through 19.

12 For each primary Replication Server for which the current Replication Server has a non-VALID user subscription:

• Note its subid, and delete the appropriate row from the primary rs_subscriptions system table.

• Use the subid from rs_subscriptions to find corresponding rows in the rs_rules system table, and also delete those rows.

For each system table, rs_subscriptions and rs_rules:

• If a subscription is in the primary table and not in the replicate table, delete the subscription row from the primary table. After completing the rest of this procedure, re-create the subscription, as described in steps 17 through 19.

• If a subscription is in the replicate table and not in the primary table (because it was dropped), delete the subscription row from the replicate table.

• If a subscription is in both the primary and replicate tables, but not VALID at one of the sites, delete the rows from both tables. After completing the rest of this procedure, re-create the subscription, as described in steps 17 through 19.

13 At both the primary and replicate Replication Server, execute the sysadmin drop_queue command for all existing materialization queues for subscriptions deleted in steps 17 through 19.

14 Restart in normal mode all Replication Servers, and their RepAgents, that had subscriptions to primary data managed by the current Replication Server or with primary data to which the current Replication Server had subscriptions.


554

15 Perform steps 5 through 13 of “Basic RSSD Recovery Procedure” on page 541.

16 Reexecute any DDL commands that executed at the current Replication Server since the last transaction dump.

17 Enable autocorrection for each replication definition.

18 Re-create the missing subscriptions using either the bulk materialization method or no materialization.

Use the define subscription, activate subscription, validate subscription, and check subscription commands for bulk materialization.

19 For each re-created subscription, restore consistency between the primary and replicate data in either of two ways:

• Drop a subscription using the drop subscription command and the with purge option. Then re-create the subscription.

• Use the rs_subcmp program with the -r flag to reconcile replicate and primary subscription data.

Refer to “rs_subcmp” in Chapter 7, “Programs,” in the Replication Server Reference Manual for more information on the rs_subcmp program. Refer to Chapter 8, “Replication Server System Tables,” in the Replication Server Reference Manual for more information on the RSSD system tables.

Deintegration/Reintegration ProcedureIf you created routes since the last time the RSSD was dumped, you are required to perform the following tasks:

1 Remove the current Replication Server from the replication system.

See “Removing a Replication Server” on page 110 for details.

2 Reinstall the Replication Server.

Refer to the Replication Server installation and configuration guides for your platform for complete information on re-installing Replication Server.

3 Re-create Replication Server routes and subscriptions.

See Chapter 5, “Managing Routes” and Chapter 10, “Managing Subscriptions” for details.


555

Recovery Support TasksThis section describes standard recovery tasks that are required in performing the recovery procedures described in this chapter. Use recovery tasks only for the procedure to which they apply. These tasks support recovery by letting you manipulate and identify critical data in the replication system.

Refer to this section for background in performing the recovery procedures in this chapter.

Table 16-5 lists the recovery support tasks.

Table 16-5: Overview of recovery support tasks

Rebuilding Stable QueuesThe rebuild queues command removes all existing queues and rebuilds them. It cannot rebuild individual stable queues.

You can rebuild queues online or off-line, depending on your situation. Generally, you rebuild queues online first to detect if there are lost stable queue messages. If there are lost messages, you can retrieve them by first putting the Replication Server in standalone mode and recovering the data from an off-line log.

Both methods for rebuilding queues are described in more detail in the following sections. Refer to “rebuild queues” in Chapter 3, “Replication Server Commands,” in the Replication Server Reference Manual for more information.

Recovery Support Task See

Rebuild stable queues “Rebuilding Stable Queues” on page 555

Check for Replication Server loss detection messages after rebuilding stable queues

“Loss Detection After Rebuilding Stable Queues” on page 558

Put Replication Server in log recovery mode “Setting Log Recovery for Databases” on page 562

Check for Replication Server loss detection messages after setting log recovery for databases

“Loss Detection After Setting Log Recovery” on page 563

Determine which dumps and logs to load “Determining Which Dumps to Load” on page 564

Adjust database generation numbers “Adjusting Database Generation Numbers” on page 565

Recovery Support Tasks

556

Rebuilding Queues Online

During the online rebuild process, the Replication Server is in normal mode. All RepAgents and other Replication Servers are automatically disconnected from the Replication Server. Connection attempts are rejected with the following message:

Replication Server is Rebuilding

Replication Servers and RepAgents retry connections periodically until rebuild queues has completed. At this time, the connections are successful.

When the queues are cleared, the rebuild is complete. The Replication Server then attempts to retrieve the cleared messages from the following sources:

• Other Replication Servers that have direct routes to the rebuilt Replication Server. If you have set a save interval from other Replication Servers, you have a greater likelihood of recovery.

• Database transaction logs for primary databases the Replication Server manages.

If there are loss detection messages, you need to check the status of these messages. Depending on the failure condition, if these messages are no longer available at their source, you may need to rebuild the queues using off-line logs. Or, you can request that Replication Server ignore the lost messages. See “Rebuilding Queues from Off-line Database Logs” on page 556 and “Loss Detection After Rebuilding Stable Queues” on page 558.

Rebuilding Queues from Off-line Database Logs

This task is used to recover data from off-line database logs. You use the rebuild queues command only after you have restarted the Replication Server in standalone mode. For details on standalone mode, see “Using Standalone Mode” on page 557. Executing rebuild queues in standalone mode puts Replication Server in recovery mode.

In recovery mode, the Replication Server allows only RepAgents in recovery mode to connect. If a RepAgent that is not in recovery mode attempts to connect, Replication Server rejects it with following error message:

Rep Agent not in recovery mode

If you use a script that automatically restarts RepAgent and connects it to the Replication Server, you must start RepAgent using the for_recovery option. RepAgents are not allowed to connect in normal mode.


557

Figure 16-2 illustrates the progression from normal mode to standalone mode to recovery mode using the rebuild queues command.

Figure 16-2: Entering recovery mode with the rebuild queues command

Using Standalone Mode

To start Replication Server in standalone mode, use the -M flag. Standalone mode is useful for looking at the state of Replication Server because the state is static. Standalone mode allows you to review the contents of the stable queues because no messages are being written to or read from the queues.

Standalone mode differs from Replication Server’s normal mode in the following ways:

• No incoming connections are accepted. If any RepAgent or Replication Server attempts to connect to a Replication Server in standalone mode, the message “Replication Server is in Standalone Mode” is raised.

• No outgoing connections are started. A Replication Server in standalone mode does not attempt to connect to other Replication Servers.

Standalone Mode

Normal Mode

Reject“Not in Recovery”RepAgent connect attempt

rebuild queues

Restart

Restart -M

Restart -M

Restart -M

Recovery ModeLog recovery set for all databases


558

• No DSI threads are started, even if there are messages in the DSI queues that have not been applied.

• No Distributor (DIST) threads are started. A DIST thread reads messages from the inbound queues, performs subscription resolution, and writes messages to the outbound queues.

Loss Detection After Rebuilding Stable Queues

To determine if any messages could not be recovered after the stable queues were rebuilt, the Replication Server performs loss detection. By checking Replication Server loss-detection messages, you can determine what kind of user intervention, if any, is necessary to restore all data to the system.

Replication Server detects two types of losses after rebuilding stable queues:

• SQM loss, which refers to data lost between two Replication Servers, detected at the next downstream site

• DSI loss, which refers to data lost between a Replication Server and a replicate database that the Replication Server manages

Both kinds of loss detection are addressed in the following sections.

If all data is available, no intervention is necessary and the replication system can return to normal operations. For example, if you know that the save interval for the route or connection is set for a longer length of time than the failure, you can recover all messages with no intervention. However, if the save interval is not set or is set too low, some messages may be lost.

Note A Replication Server that has detected a loss does not accept messages from the source. Loss detection prevents the source from truncating its stable queues. For example, if Replication Server RS2 detects that replicate data server DS2.RDB has lost data from primary data server DS1.PDB, Replication Server RS1 cannot truncate its queues until you decide how to handle the loss.

As a result, RS1 may run out of stable storage. Before a loss is detected (that is, after the “Checking Loss” message is reported), you can choose to ignore losses for a source and destination pair.


559

SQM Loss Between Two Replication Servers

Every time you rebuild stable queues during a recovery procedure, Replication Server requests backlogged messages from sites that send its distributions. If the Replication Server manages primary databases, it instructs their RepAgents to send messages from the beginning of the online transaction logs. The backlogged messages repopulate the emptied stable queues.

Replication Server enables loss detection mode at those sites you are rebuilding that have a direct route from the Replication Server. In Figure 16-3, Replication Server RS3 detects losses if you rebuild the queues of Replication Server RS2. Similarly, RS2 detects losses if you rebuild the queues of Replication Server RS1.

Figure 16-3: Replication system loss detection example

When you execute the rebuild queues command at RS2, RS3 performs loss detection for all primary databases whose updates are routed to RS3 through RS2. RS3 logs messages for each of these databases. If you rebuild queues at RS3, no SQM loss detection is performed, because there are no routes originating from RS3.

Replication Server detects loss by looking for duplicate messages. If RS3 receives a message that it had received before the rebuild queues command, then no messages were lost. If the first message RS3 receives after rebuild queues has not been seen before, then either messages were lost, or no messages were in the stable queue.

Even if there are no messages in the stable queue from a specific source, RS3 identifies them as lost because it has no duplicate messages to use for a comparison. You can prevent this false loss detection by creating a heartbeat with an interval that is less than the save interval. This guarantees that there will always be at least one message in the stable queue.

PrimaryDatabase

RS1 RS2 RS3

RS1 RSSD RS2 RSSD RS3 RSSD

ReplicateDatabase


560

For instructions on using heartbeats in Sybase Central, see “Concepts for using heartbeats to monitor latency” in Replication Server’s online help.

SQM Example When RS3 performs SQM loss detection for the rebuilt RS2, it logs in to its log file messages similar to the following “Checking Loss” message examples. These messages mark the beginning of the loss detection process. Subsequent messages are logged with the results. Each message contains a source and destination pair.

The first example message indicates that RS3 is checking loss for the RSSD at RS3 from the RSSD at RS2:

Checking Loss for DS3.RS3_RSSD from DS2.RS2_RSSDdate=Nov-01-95 10:15 amqid=0x01234567890123456789

The second example message indicates that RS3 is checking loss for the replicate database RDB at RS3, from the primary database PDB at RS1:

Checking Loss for DS3.RDB from DS1.PDBdate=Nov-01-95 11:00amqid=0x01234567890123456789

The third example message indicates that RS3 is checking loss for the RSSD at RS3 from the RSSD at RS1:

Checking Loss for DS3.RS3_RSSD from DS1.RS1_RSSDdate=Nov-01-95 10:00amqid=0x01234567890123456789

RS3 reports whether it detects a loss. For example, the results of such loss-detection tests might read as follows:

No Loss for DS3.RS3_RSSD from DS2.RS2_RSSDLoss Detected for DS3.RDB from DS1.PDBNo Loss for DS3.RS3_RSSD from DS1.RS1_RSSD

DSI Loss Between a Replication Server and Its Databases

Some messages in Replication Server queues are destined for databases, rather than for other Replication Servers. The DSI performs loss detection in a way that is similar to stable queue loss detection.

If you rebuild queues at a Replication Server that has no originating routes, no SQM loss detection is performed, but the Replication Server performs DSI loss detection for its messages.

DSI Example The DSI at Replication Server RS2 generates the following message for the RSSD at RS2:

RSM


561

DSI: detecting loss for database DS2.RS2_RSSD from origin DS1.RS1_RSSDdate=Nov-01-95 10:58pmqid=0x01234567890123456789

When retained messages begin arriving from previous sites, the DSI detects a loss, depending on whether the first message from the origin has already been seen by the DSI. If it detects no loss, a message similar to the following one is generated:

DSI: no loss for database DS2.RS2_RSSD from origin DS1.RS1_RSSD

If the DSI does detect a loss, a message like the following one is generated:

DSI: loss detected for database DS2.RS2_RSSD from origin DS1.RS1_RSSD

Handling Losses

When Replication Server detects a loss, no further messages are accepted on the connection to the SQM or the DSI.

For example, when RS3 detects an SQM message loss for the RDB database from the PDB database, it rejects all subsequent messages from the PDB database to the RDB database.

Recovering a Loss To recover the loss, you need to choose one of the following options:

• Ignore the loss and continue, even though some messages may be lost. You can use the rs_subcmp program with the -r flag to reconcile primary and replicate data.

To run rs_subcmp, see “Subscription Comparison Procedure” on page 544. See also Chapter 10, “Managing Subscriptions” and refer to “rs_subcmp” in Chapter 7, “Programs,” in the Replication Server Reference Manual.

• Ignore the loss, then drop and re-create the subscriptions.

• Recover by replaying transactions from off-line logs (primary Replication Server loss only). In this case, you are not ignoring the loss.

Ignoring a Loss You must execute an ignore loss command in the following situations:

• If you choose to recover the lost messages by re-creating subscriptions or replaying logs.


562

• For an SQM loss, at the Replication Server that reported that loss, to force the Replication Server to begin accepting messages again. For example, to ignore a loss RS3 detected from DS1.PDB, enter the following command at RS3:

ignore loss from DS1.PDB to DS3.RDB

• For a DSI loss, at the database on the Replication Server where the loss was detected. For example, to ignore a loss reported in DS2.RS2_RSSD from origin DS1.RS1_RSSD, enter the following command at RS2:

ignore loss from DS1.RS1_RSSD to DS2.RS2_RSSD

• For both an SQM and a DSI loss that is detected by a Replication Server at the destination of the route when you rebuild two Replication Servers in succession.

In this case, you need to execute ignore loss twice, once for SQM losses and once for DSI losses. The ignore loss command that you execute to ignore DSI loss at the destination Replication Server is the same command you use to ignore SQM loss from the previous site.

Setting Log Recovery for Databases

Setting log recovery manually is part of the procedure for recovering from truncated primary database logs off-line or restoring primary and replicate databases from dumps. While the procedure to rebuild queues off-line automatically sets log recovery for all databases, setting log recovery manually allows you to recover each database without reconstructing the stable queue.

The set log recovery command places Replication Server in log recovery mode for a database. You execute this command after placing Replication Server in standalone mode. To connect the RepAgents only to those databases that have been set for log recovery mode, execute the allow connections command. This puts the Replication Server in recovery mode.

Figure 16-4 illustrates the progression from normal mode to standalone mode to recovery mode using the set log recovery and allow connections commands.

For databases specified with the set log recovery command, Replication Server only accepts connections from other Replication Servers and from RepAgents that are in recovery mode. You then recover the transaction dumps into a temporary recovery database.


563

Figure 16-4: Entering recovery mode with the allow connections command

Loss Detection After Setting Log Recovery

While you are applying the temporary recovery database to the primary database, Replication Server may detect SQM loss between a primary database and the Replication Server that manages that primary database.

If all data is available, no intervention is necessary and the replication system can return to normal operations. The Replication Server logs a message such as:

No Loss Detected for DS1.PDB from DS1.PDB

If there were not enough messages, Replication Server logs a loss detection message similar such as:

Standalone Mode

Normal Mode

DS1.DB1 Repagentconnect attempt in

normal mode

DS1.DB1 RepAgent connectattempt in recovery mode

set log recovery for DS1.DB1

allow connections

Restart

Restart -M

Restart -M

Restart -M

Accept DS2.DB1connect attempt

Accept

Reject

Recovery ModeLog recovery set

for DS1.DB1


564

Loss Detected for DS1.PDB from DS1.PDB

You must decide whether to ignore the losses by executing the ignore loss command, or repeat the recovery procedure from the beginning. To ignore the loss, enter the following command at the primary Replication Server:

ignore loss for DS1.PDB from DS1.PDB

If you received loss detection messages, you failed to reload the database to a state old enough to retrieve all of the messages. See “Determining Which Dumps to Load” on page 564.

Determining Which Dumps to Load

When loading transaction log dumps, always examine the “Checking Loss” message that is displayed during loss detection. If there is more than one message, choose the earliest date and time to determine which dumps to load.

For example, if the following message is generated by a Replication Server, you would load the dumps taken just before November 1, 1995 at 10:58 p.m.:

Checking Loss for DS3.RDB from DS1.PDBdate=Nov-01-1995 10:58pmqid=0x01234567890123456789

The date in the message is the date and time of the oldest open transaction in the log when the last message received by the Replication Server was generated by the origin queue. Locate the most recent transaction dump with a timestamp before the date and time in the message. Then find the full database dump taken before that transaction dump.

The origin queue ID, or qid, is formed by the RepAgent and identifies a log record in the transaction log. The date is embedded in the qid as a timestamp. Replication Server converts the timestamp to a date for RepAgents for Adaptive Server.

Replication agents for non-Sybase data servers may also embed the timestamp in the qid. Replication Server converts the timestamp for non-Sybase data servers in bytes 20–27. The use of these bytes depends on the replication agent.

Note If the data server is not an Adaptive Server, the date in the message may appear nonsensical. You may need to decode the qid in bytes 20–27 to identify the dumps to load.


565

Adjusting Database Generation Numbers

Each primary database in a replication system includes a database generation number. This number is stored both in the database and in the RSSD of the Replication Server that manages the database.

Any time you load a database for recovery, you may be required to change the database generation number, as instructed in the recovery procedure you are using. This section explains this step.

Determining Database Generation Numbers

RepAgent for a primary database places the database generation number in the high-order 2 bytes of the qid that it constructs for each log record it passes to the Replication Server.

The remainder of the qid is constructed from other information that gives the location of the record in the log and also ensures that the qid increases for each record passed to Replication Server.

The requirement for increasing qid values allows Replication Server to detect duplicate records. For example, when a RepAgent restarts, it may resend some log records that Replication Server has already processed. If Replication Server receives a record with a lower qid than the last record it processed, it treats the record as a duplicate and ignores it.

If you are restoring a primary database to an earlier state, increment the database generation number so that the Replication Server does not ignore log records submitted after the database is reloaded. This step applies only if you are using the procedures described in “Loading a Primary Database from Dumps” on page 537 or in “Loading from Coordinated Dumps” on page 536.

If you are replaying log records, increment the database generation number only if RepAgent previously sent the reloaded log records with the higher generation number. This situation arises only if you have to restore the database and log to a previous state for the first failure and then later replay the log due to a second failure.

Warning! Only change the database generation number as part of a recovery procedure. Changing the number at any other time can result in duplicate or missing data at replicate databases.


566

Dumps and Database Generation Numbers

When you reload a database dump, the database generation number is included in the restored database. Since the database generation number is also stored in the RSSD of the Replication Server that manages the database, you may need to update that number so that it matches the one in the restored database.

However, when you reload a transaction log, the database generation number is not included in the restored log. For example, assume the following operations have occurred in a database:

Table 16-6: Dumps and database generation numbers

If you reload database dump D1, database generation number 100 is restored with it. If you reload transaction dump T1, the generation number remains at 100. After transaction dump T2, the generation number remains at 100, because reloading transaction dumps does not alter the database generation number. In this case, you need to change the database generation number to 101 using the dbcc settrunc command before having RepAgent scan transaction dump T2.

However, if you load database dump D2 before resuming replication, you do not have to alter the database generation number, since the number 101 is restored.

Operation Database Generation Number

database dump D1 100

transaction dump T1 100

dbcc settrunc(’ltm’, ’gen_id’, 101) 101

transaction dump T2 101

database dump D2 101

567

A P P E N D I X A Asynchronous Stored Procedures

This appendix describes asynchronous stored procedures.

This appendix describes the method for replicating stored procedures that are associated with table replication definitions. This method is supported for applications that require it.

See Chapter 9, “Managing Replicated Functions” for information about replicated stored procedures that are associated with function replication definitions. The method described in that chapter is the recommended method for replicating stored procedures.

Refer to Replication Server Design Guide for more information on replication system design issues relating to replicated stored procedures.

OverviewAsynchronous procedure delivery allows you to execute SQL stored procedures that are designated for replication at primary or replicate databases. Because these stored procedures are marked for replication using the sp_setreplicate or sp_setrepproc system procedures, they are called replicated stored procedures.

To satisfy the requirements of distributed applications, Replication Server provides two types of asynchronous stored procedure delivery: applied stored procedures and request stored procedures. Each type is described in this appendix.

Logging Replicated Stored ProceduresAdaptive Server uses the following method to determine in which database a replicated stored procedure execution will be logged:

Applied Stored Procedures

568

The procedure gets logged in the database in which the enclosing transaction was started.

• If the user does not begin a transaction explicitly, Adaptive Server will begin one in the user’s current database before the stored procedure execution.

• If the user begins the transaction in one database, and then executes a replicated stored procedure in another database, the execution will still be logged in the database where the user began the transaction.

If the execution of a table-style replicated stored procedure (marked for replication by using either sp_setreplicateproc_name, ’true’ or sp_setrepprocproc_name, ’table’) is logged in one database and changes replicated tables in another database, the table’s changes and the procedure execution are logged in different databases. Therefore, the effects of the stored procedure execution can be replicated twice. The first time the stored procedure execution itself is replicated. The second time table changes that have been logged in the other database are replicated.

Logging Replicated Stored RestrictionsNote that replicated Adaptive Server stored procedures may not contain parameters with the text and image datatypes. Refer to the Adaptive Server Reference Manual for more information.

Mixed-Mode TransactionsIf a single transaction that invokes one or more request stored procedures is a mixed-mode transaction that also executes applied stored procedures or contains data modification language, Replication Server processes the request stored procedures after all the other operations. All request operations are processed together in a single separate transaction. This situation may arise where a single Replication Server manages both primary and replicate data.

Applied Stored ProceduresReplicated stored procedures that Replication Server delivers from a primary database to a replicate database are called applied stored procedures.

APPENDIX A Asynchronous Stored Procedures

569

You use applied stored procedure delivery to replicate transactions first performed on primary data to replicate databases. Data changes are applied at a primary database and then distributed at a later time to replicate databases that subscribe to replication definitions for the data. Replication Server executes the replicated stored procedure in the replicate database as the maintenance user, which is consistent with normal data replication.

You can use applied stored procedures to realize important performance benefits. For example, if your organization has a large amount of row changes, you can create an applied stored procedure which changes many rows, rather than replicating the rows individually. You can also use applied stored procedures to replicate data set changes which are difficult to express using normal subscriptions. Refer to the Replication Server Design Guide for more information.

You set up applied stored procedures by making the first statement in the stored procedure update a table. You must also make sure that the destination databases have subscriptions to the before and after images of that updated row. The applied stored procedure must update only one row in a replicated table. Replication Server uses the first row updated by the stored procedure to determine where to send the user-defined function for the procedure.

If the rules in setting up the applied stored procedure are not met, Replication Server fails to distribute the stored procedure to replicate databases. See “Warning Conditions” on page 574 for a list of actions that Replication Server takes if it fails to deliver the applied stored procedure.

Request Stored ProceduresReplicated stored procedures that Replication Server delivers from a replicate database to a primary database are called request stored procedures. You use a request stored procedure to deliver a transaction from a replicate database back to the primary database.

For example, a client application at a remote location may need to make changes to primary data. In this case, the application at the remote location executes a request stored procedure locally to change the primary data. Replication Server delivers this request stored procedure to the primary database by executing, in the replicate database, a stored procedure that has the same name as the stored procedure in the primary database. The stored procedure in the primary database updates the primary data that the transaction changes.

Asynchronous Stored Procedure Prerequisites

570

Replication Server executes the replicated stored procedure in the primary database as the user who executed the stored procedure in the replicate database. This ensures that only authorized users may change primary data.

In an application, Replication Server may replicate some or all of the data that is changed in the primary database. The changes are propagated to replicate databases managed by Replication Servers with subscriptions for the related data, either as data rows (insert, delete, or update operation) or as stored procedures. Using this mechanism, the effect of a transaction quickly arrives at both the primary and replicate databases.

Warning! Do not execute a request stored procedure in a primary database. This can lead to looping behavior, in which replicate Replication Servers cause the same procedure to execute in the primary database.

Using request stored procedures ensures that all updates are made at the primary database, preserving Replication Server’s basic primary copy data model while keeping the replication system invulnerable to network failures and excess traffic. Even when there is primary database failure, or network failure from the replicate database to the primary database, Replication Server remains fault tolerant. It queues any undelivered request stored procedure invocations until the failed components come back online. When the components are again in service, Replication Server completes delivery.

By using Replication Server’s guaranteed request stored procedure delivery feature, you can obtain all the benefits of having a single, definitive copy of your data that includes all the latest changes. At the same time, Replication Server provides the availability and performance benefits of de-coupling applications at replicate databases from the primary database.

Refer to the Replication Server Design Guide for more information on replication system design issues relating to asynchronous procedure delivery.

Asynchronous Stored Procedure PrerequisitesBefore implementing applied or request stored procedures on your system, be sure you:

• Understand how you will use asynchronous procedure delivery to meet your application needs. Refer to the Replication Server Design Guide for more information.


571

• Set up a RepAgent or LTM for the stored procedure, even if the database contains no primary data (such as when using request functions). Refer to the Replication Server installation and configuration guides for your platform for details.

• Create a function string for user-defined functions for function-string classes for which Replication Server does not generate default function strings. You can use the alter function string command to replace a default function string with one that performs the action your application requires.

See “Function Strings and Function-String Classes” on page 392 for more information.

• Follow the step-by step instructions provided in this chapter for setting up applied or request stored procedures.

Note For function-string classes for which default generated function strings are provided, Replication Server creates a default function string that executes a stored procedure with the same name as the user-defined function. The procedures in this chapter assume that Replication Server processes applied or request stored procedures for such classes. For all other classes, you must create function strings for the user-defined function string.

Steps for Implementing an Applied Stored ProcedureTo implement an applied stored procedure, perform the following steps:

1 Review the requirements described in “Asynchronous Stored Procedure Prerequisites” on page 570.

2 Set up replicate databases that contain replicate tables. These tables may or may not match the replication definition for the primary table.

3 As necessary, set up routes from the primary Replication Server to the replicate Replication Servers that have subscriptions to replication definitions for the primary table.

See Chapter 5, “Managing Routes” for details on setting up routes.

4 Locate or create a replication definition on the primary Replication Server that identifies the table to be modified.

Steps for Implementing an Applied Stored Procedure

572

See Chapter 8, “Managing Replicated Tables” for information on creating replication definitions.

5 In the primary database, use the sp_setreplicate system procedure or the sp_setreptable system procedure to mark the table for replication. For example, for a table named employee:

sp_setreplicate employee, ’true’

or

sp_setreptable employee, ’true’

For sp_setreptable, the single quotes are optional.

See “Specifying Stored Procedures and Tables for Replication” on page 577 for details on using sp_setreplicate. See “Using the sp_setreptable System Procedure” on page 239 for details on using sp_setreptable.

6 Create the stored procedure on the primary database. The first statement in the stored procedure must contain an update command for the first row of the primary table. For example:

create proc upd_emp @emp_id int, @salary float as update employee set salary = salary * @salary where emp_id = @emp_id

Warning! If the first statement in the stored procedure contains an operation other than update, Replication Server cannot distribute the stored procedure to replicate databases. See “Warning Conditions” on page 574 for more information. Never include dump transaction or dump database commands in the stored procedure. If the stored procedure contains commands with statement level errors, the error may occur at the replicate DSI. Depending on the error actions, the DSI may shut down.

7 In the primary database, use the sp_setreplicate system procedure or the sp_setrepproc system procedure to mark the stored procedure for replication. For example:

sp_setreplicate upd_emp, ’true’

or

sp_setrepproc upd_emp, ’table’


573

See “Specifying Stored Procedures and Tables for Replication” on page 577 for details on using sp_setreplicate. See “Marking Stored Procedures for Replication” on page 305 for details on using sp_setrepproc.

8 At the replicate Replication Servers, create subscriptions to a replication definition for the table that the stored procedure at the primary database updates.

See Chapter 10, “Managing Subscriptions” for details on creating subscriptions.

Warning! Be sure the replicate database subscribes to both the before image and after image of the updated row. If it does not, Replication Server cannot distribute the stored procedure to the replicate database. See “Warning Conditions” on page 574 for more information.

9 Create a stored procedure on the replicate database with the same name and parameters as the stored procedure on the primary database, but do not mark the procedure as replicated. For example:


10 Grant execute permission on the stored procedure to the maintenance user. For example:

grant execute on upd_emp to maint_user

11 Create a user-defined function on the primary Replication Server that associates the stored procedure to the name of a replication definition for the table it updates. For example:

create function employee_rep.upd_emp (@emp_id int, @salary float)

Only one user-defined function are shared by all replication definitions for the same table. You can specify the name of any of these replication definitions.

12 Verify that all Replication Server and database objects in steps 1 through 11 exist at the appropriate locations.

Steps for Implementing an Applied Stored Procedure

574

Refer to Chapter 6, “Adaptive Server Stored Procedures,” in the Replication Server Reference Manual for information about stored procedures used to query the RSSD for system information.

Warning ConditionsIf the first statement in the applied stored procedure is an operation other than update, or the replicate database does not subscribe to the before image and after image of the updated row, Replication Server fails to deliver the applied stored procedure to the replicate database. Instead, Replication Server performs other actions that you can interpret as warnings.

The actions Replication Server takes is based on:

• The first operation (other than update) contained in the applied stored procedure at the primary database

• Whether the row modification stays in the subscription for the replicate database, and whether it matches the subscription’s before image or after image

Conditions and Actions

This section identifies the warning conditions that prevent Replication Server from delivering an applied stored procedure at a replicate database.

Condition: The first row operation is an insert operation.

Action: Replication Server distributes the insert operation instead of the applied stored procedure.

Condition: The first row operation is a delete operation.

Action: Replication Server distributes the delete operation instead of the applied stored procedure.

Condition: Replicate Replication Servers have subscriptions that match the before image, but not the after image, of the modified row.

Action: Replication Server distributes a delete operation (rs_delete system function) to replicate databases with subscriptions to the before image but not the after image of the row modification.

Example: Assume there is a table T1 that has a column named C1 with a value of 1. A replicate database has a subscription to a replication definition for table T1 where C1 = 1.


575

If the associated stored procedure is executed with the parameters= 1 (before image) and = 2 (after image), the replicate database does not subscribe to the after image value of 2. Therefore, Replication Server distributes the delete operation to the replicate database.

Condition: Replicate Replication Servers have subscriptions that match the after image, but not the before image of the modified row.

Action: Replication Server distributes an insert operation (rs_insert system function) to replicate databases with subscriptions to the after image but not the before image of the row modification.

Example: Assume there is a table T1 that has a column named C1 with a value of 1. A replicate database has a subscription to a replication definition for table T1 where C1 = 2.

If the associated stored procedure is executed with the parameters = 1 (before image) and = 2 (after image), the replicate database does not subscribe to the before image value of 1. Therefore, Replication Server distributes the insert operation to the replicate database.

Condition: Replicate Replication Servers have subscriptions that match neither the before image nor the after image of the row modification.

Action: Replication Server does not distribute any operation or stored procedure to the replicate databases.

Example: Assume there is a table T1 that has a column named C1 with a value of 1. A replicate database has a subscription to a replication definition for table T1 where C1 > 2.

If the associated stored procedure is executed with the parameters = 1 (before image) and = 2 (after image), the replicate Replication Server does not subscribe to either the before image value of 1 or the after image value of 2. Therefore, Replication Server performs no distribution to the replicate database.

Steps for Implementing a Request Stored ProcedureTo implement a request stored procedure, perform the following steps:

1 Review the requirements described in “Asynchronous Stored Procedure Prerequisites” on page 570.

Steps for Implementing a Request Stored Procedure

576

2 As necessary, set up a route from the replicate Replication Server to the primary Replication Server where the data is updated, and from the primary Replication Server to the replicate Replication Server that sends the update.

See Chapter 5, “Managing Routes” for details on setting up routes.

3 Create a login name and password at the primary Replication Server for the user at the replicate Replication Server.


4 At the replicate Replication Server, create the necessary permissions for this user to execute the stored procedure at the primary Replication Server.


5 At the primary Replication Server, locate or create a replication definition that identifies the table to be modified.

See Chapter 8, “Managing Replicated Tables” for information on creating replication definitions.

The replicate Replication Server may have subscriptions on the replication definition.

6 Create the stored procedure, which does not perform any updates, on the replicate database. For example:

create proc upd_emp @emp_id int, @salary float as print "Transaction accepted."

If you want the stored procedure to have the same name as those in different replicate databases, see “Specifying a Non-Unique Name for a User-Defined Function” on page 583 for details.

7 In the replicate database, use the sp_setreplicate system procedure or the sp_setrepproc system procedure to mark the stored procedure for replication. For example:

sp_setreplicate upd_emp, ’true’

or

sp_setrepproc upd_emp, ’table’



577

8 Create a stored procedure on the primary database with the same name as the stored procedure on the replicate database, but do not mark the procedure as replicated. This stored procedure modifies a primary table. For example:


Note The stored procedure names on the primary and replicate databases can differ if you alter the function string for the function to execute a stored procedure with a different name. See “Mapping to a Different Stored Procedure Name” on page 581 for more information.

9 Grant permission on the stored procedure to the replicate Replication Server users who will execute this stored procedure. For example:

grant all on upd_emp to public

10 Create a user-defined function on the primary Replication Server that associates the stored procedure to the name of a replication definition for the table it updates. For example:

create function employee_rep.upd_emp (@emp_id int, @salary float)

11 Verify that all Replication Server and database objects in steps 1 through 10 exist at the appropriate locations.

Refer to Chapter 6, “Adaptive Server Stored Procedures,” in the Replication Server Reference Manual for information about stored procedures used to query the RSSD for system information.

Specifying Stored Procedures and Tables for Replication

You can use the sp_setreplicate system procedure in Adaptive Server to mark database tables and stored procedures for replication.

Managing User-Defined Functions

578

You can also use the sp_setreptable system procedure to mark tables for replication and the sp_setrepproc system procedure to mark stored procedures for replication. These system procedures extend the capabilities of sp_setreplicate and are intended to replace it.

See “Using the sp_setreptable System Procedure” on page 239 and “Marking Stored Procedures for Replication” on page 305 for details.

The syntax for the sp_setreplicate system procedure is:

sp_setreplicate [object_name [, {’true’ | ’false’}]]

object_name can be either a table name or a stored procedure name.

The ’true’ or ’false’ parameters are used to change the replication status of a specified object. (The single quotes are optional.)

• Use sp_setreplicate with no parameters to list all replicated objects in the database.

• Use sp_setreplicate with just the object name to check the replication status of the object. Adaptive Server reports ’true’ if replication is enabled for the object, or ’false’ if it is not.

• Use sp_setreplicate with the object name and either ’true’ or ’false’ to enable or disable replication for the object. You must be the Adaptive Server System Administrator or the Database Owner to use sp_setreplicate to change the replication status of an object.

Warning! A replicated stored procedure should only modify data in the database in which it is executed. If it modifies data in another database, Replication Server replicates the updated data and the stored procedure.

Managing User-Defined FunctionsThis section describes commands for managing user-defined functions. See Chapter 7, “Managing Replication Server Security” for a list of permissions that are required to use the commands. See Chapter 12, “Customizing Database Operations” for details on altering function strings for user-defined functions and displaying function-related information.


579

Creating a User-Defined FunctionUse the create function command to register a replicated stored procedure with Replication Server. When a stored procedure is executed, Replication Server maps it to a replication definition. The replication definition contains a user-defined function name that matches the name of the stored procedure.

Replication Server delivers the function to the Replication Server that is primary for the replication definition. When the destination Replication Server that owns the replication definition receives the function, it maps the stored procedure parameters into the commands for the user-defined function.

The syntax for the create function command is:

create function replication_definition.function([@parameter datatype [, @parameter datatype]...])

The replication_definition must be an existing replication definition.

Observe these guidelines when using this command:

• Execute this command at the Replication Server where the replication definition was created.

• Do not use the names of system functions. See Chapter 12, “Customizing Database Operations” for the list of reserved system-function names.

• Include the parentheses surrounding the listed parameters, even when you are defining functions with no parameters.

• If you are not using a function-string class for which default generated function strings are provided, after you have created a user-defined function, use the create function string command to add a function string. See Chapter 12, “Customizing Database Operations” for details.

The following example creates a user-defined function named Stock_receipt. The function is associated with the Items_rd replication definition:

create function Items_rd.Stock_receipt (@Location int, @Recpt_num int, @Item_no char(15), @Qty_recd int)

When a user executes the replicated stored procedure, Replication Server now delivers it.


580

Adding Parameters to a User-Defined FunctionWhen you add a parameter to a replicated stored procedure, use the alter function command to tell Replication Server about the new parameters. To add the parameters:

1 Alter the stored procedure at the primary or replicate data server and provide defaults for new parameters.

2 As a precaution, quiesce the system. Altering functions while updates are in process can have unpredictable results.

See “Quiescing Replication Server” on page 109 for details on quiescing the system.

3 Alter the function using the alter function command.

4 If you are not using a function-string class for which default generated function strings are provided, alter function strings to use the new parameters. See Chapter 12, “Customizing Database Operations” for details.

The syntax for the alter function command is:

alter function replication_definition.functionadd parameters @parameter datatype[, @parameter datatype]...

The replication_definition is the name of the replication definition for the function. A function can have up to 255 parameters.

The following example adds an int parameter named Volume to the New_issue function for the Tokyo_quotes replication definition:

alter function Tokyo_quotes.New_issue add parameters @Volume int

Dropping a User-Defined FunctionUse the drop function command to drop a user-defined function. This command drops a function name and any function strings that have been created for it. You cannot drop system functions.

Before you drop the user-defined function, be sure to:


581

1 Drop the stored procedure at the primary database using the drop procedure Adaptive Server command, or use the sp_setreplicate or sp_setrepproc system procedure and specify ’false’ to disable replication for the stored procedure.


2 As a precaution, quiesce the system before executing the drop function command. Dropping functions while updates are in process can have unpredictable results.

See “Quiescing a Replication System” on page 109 for details on quiescing the system.

The syntax for the drop function command is:

drop function replication_definition.function

Execute the command on the Replication Server where the replication definition was created.

The following command drops the Stock_receipt user-defined function created in the previous section:

drop function Items_rd.Stock_receipt

Mapping to a Different Stored Procedure NameWhen you create a user-defined function in a database that uses the a function-string class for which default generated function strings are provided, Replication Server generates a default function string. The default generated function string executes a stored procedure with the same name and parameters as the user-defined function.

For example, if you are using a default function string, you can set up a request stored procedure to execute in the replicate database by creating a stored procedure in the primary database with the same name and parameters as the user-defined function.

If you want to map the user-defined function to a different stored procedure name, use the alter function string command to configure Replication Server to deliver the stored procedure by executing a stored procedure with a different name. You can also do so in function-string classes that allow you to customize function strings.


582

Example This example illustrates how to map a user-defined function to a different stored procedure name.

1 Assume the stored procedure upd_sales exists on the primary Adaptive Server, and that it performs an update on the Adaptive Server sales table:

create proc upd_sales @stor_id varchar(10), @ord_num varchar(10), @date datetime as update sales set date = @date where stor_id = @stor_id and ord_num = @ord_num

2 To register the upd_sales stored procedure with the Replication Server, create the following function, whose name includes in its name the sales_def replication definition on the sales table and the upd_sales replicated stored procedure:

create function sales_def.upd_sales (@stor_id varchar(10), @date datetime)

3 On the replicate Adaptive Server, a version of the stored procedure upd_sales that performs no work is created with the same name:

create proc upd_sales @stor_id varchar(10), @ord_num varchar(10), @date datetime as print "Attempting to Update Sales Table" print "Processing Update Asynchronously"

4 To execute the upd_sales stored procedure with the name real_update instead of upd_sales:

• The default generated function string is altered:

alter function string sales_def.upd_sales for rs_sqlserver_function_class output rpc ’execute real_update @stor_id = ?stor_id!param?, @date = ?date!param?’

• A stored procedure in the primary database is created with the name real_update. It accepts two parameters.


583

Specifying a Non-Unique Name for a User-Defined FunctionThe name of a user-defined function must be globally unique in the replication system so that Replication Server can locate the particular replication definition for which the user-defined function is defined. If you create more than one replication definition for the same primary table, there is only one user-defined function for all of that table’s replication definitions.

If the user-defined function name is not unique, the first parameter of the stored procedure must be @rs_repdef, and the name of the replication definition must be passed in this parameter when the stored procedure is executed.

Do not define the @rs_repdef parameter in the create function command for the user-defined function. The replication agent extracts the replication definition name and sends it with the LTL commands. This convention works with RepAgent for Adaptive Server or LTM for SQL Server, but may not be supported by replication agents for other data servers.

Example This example assumes that the user-defined function is not unique and the replication definition name is passed to the @rs_repdef parameter when the following stored procedure is executed:

create proc upd_sales @rs_repdef varchar(30), @stor_id varchar(10), @date datetime as print "Attempting to Update Sales Table" print "Processing Update Asynchronously"


584

585

A P P E N D I X B LTM for SQL Server

This appendix describes the Log Transfer Manager (LTM), which is the replication agent for SQL Server databases.

This appendix describes the LTM and its function in the replication system. It describes how to configure and maintain it and provides procedures for changing the status of a database from primary to replicate and vice versa. It describes how the LTM logs errors.

Refer to the Replication Server Administration Guide for version 11.0 for detailed information about these topics and for information about warm standby applications and recovery operations when your replication system includes LTMs.

Overview

LTM is the replication agent for SQL Server databases. LTM notifies Replication Server of actions in a database that must be replicated to other databases. LTM reads the database transaction log and transfers log records for replicated tables and stored procedures to the Replication Server managing the database. The Replication Server distributes the modifications to sites with subscriptions for the data.

An LTM is needed for every database that contains primary data and for every database where asynchronous procedures are executed. A database that contains only copies of replicated data and contains no asynchronous procedures does not require an LTM.

See “LTM Processing Data Flow” on page 587 for a description of how LTM reads transaction information in the SQL Server, formats it, and submits it to Replication Server.

Data Flow for Replication Systems with LTMs

586

Data Flow for Replication Systems with LTMsThis section assumes a typical scenario where a Replication Server exists at both primary and replicate sites, as shown in Figure B-1. Each time a client requests a transaction that changes database content, the following actions occur:

1 The LTM reads the log of the primary database for transactions that are marked for replication.

2 The LTM forwards the transactions, through the Log Transfer Language (LTL), to the primary Replication Server (PRS in the figure), where they are stored in a stable queue.

3 The primary Replication Server determines, for each transaction, which of the following actions to take:

• Discard the transaction if no subscriptions exist for the data.

• Forward the transaction to each replicate Replication Server (RRS in the figure), where it is stored in a stable queue.

4 The replicate Replication Server determines, for each transaction, which of the following actions to take:

• Route the transaction to another Replication Server.

• Applies the transaction to replicate databases that it manages.

APPENDIX B LTM for SQL Server

587

Figure B-1: Replication Server overview

LTM ProcessingThe LTM for SQL Server is an Open Server application. It connects to a primary database as a client, retrieves the data for replicated objects from the SQL Server log, and converts the log record information into LTL commands. These commands are then sent to the primary Replication Server for distribution and replication.

LTM Processing Data FlowThe following describes the flow of data in LTM processing. The LTM performs the following actions, as shown in Figure B-2.

1 Scans the primary database log and forwards transaction log records to the primary Replication Server (PRS in the figure) involving tables that are marked for replication.

2 Filters out records written by the database maintenance user.

Primary Data Server Replicate Data Server

Stable Queues Stable Queues

LTM

Log

LTL

Transactions

Transactions

Other RRSs

RRSPRS

Data Flow for Replication Systems with LTMs

588

This step prevents transactions that are replicated to the primary database from being re-replicated out of the database to other sites.

Note For applications designed using the redistributed corporate rollup model, LTM must be started with the -A flag, which allows replicated transactions to be redistributed as primary data. See “Redistributed Corporate Rollup” on page 14 for more information.

3 Marks the transaction log so the primary data server (PDS in the figure) does not truncate log records that have not yet been passed for replication. For details, see “Data Server Log Truncation” on page 588

Figure B-2: LTM processing

Data Server Log Truncation

The LTM retrieves transactions from the SQL Server log and sends them to the primary Replication Server. As long as there is space in the database log, the data server can continue to process updates. To prevent the log from filling up, you need to truncate it using the SQL Server dump transaction command.

SQL Server and the LTM cooperate to ensure that only transactions already processed by the LTM and passed to Replication Server are truncated.

The LTM maintains a secondary truncation point in the SQL Server log. The secondary truncation point is the log page that contains the begin transaction command for the oldest transaction not yet fully received by Replication Server. The LTM resets the truncation point when SQL Server returns an end-of-scan message. Two conditions cause SQL Server to return an end-of-scan message:

• When the number of log records returned to the LTM has reached the number specified with the batch_sz configuration parameter

• When the time interval specified by the scan_retry configuration parameter has expired

LTM

Log Request

Open Server

OpenClient

Log RecordsLTL

PDS PRSOpenClient


589

See “LTM Configuration File” on page 594 for information about setting these parameters in the LTM configuration file.

The batch_sz Condition

The batch_sz configuration parameter is the number of log records to request from the SQL Server in each batch before moving the LTM truncation point. The following events result in the LTM setting the truncation point, as shown in Figure B-3 on page 589:

1 When the primary data server (PDS in the figure) reaches the batch_sz limit, it sends an end-of-scan message to the LTM.

2 When the LTM receives an end-of-scan message, it requests a new truncation point from the primary Replication Server (PRS in the figure).

3 The primary Replication Server returns the latest truncation point to the LTM and writes it to the rs_locater system table.

4 The LTM executes the dbcc settrunc command in the primary data server to set the LTM truncation point.

Figure B-3: Data server log truncation

The scan_retry Condition

When there are no log records, the data server log scan thread sleeps. New log activity awakens the log scan thread. The scan_retry configuration parameter limits the length of time to sleep. When the data server reaches the maximum scan retry time, and there is still no new log activity, it sends an end-of-scan message to the LTM. Processing occurs as in steps 2 through 4 in the preceding section.

PDS

LTM

PRS1. End-of-scan

3. Truncation point sent to rs_locater system table

Dump tran

-----------------------------

-----------------------------

3. New4. New

2. Request for newtruncation point

truncationtruncation

Prior secondary truncation pt.

Active secondary truncation pt.

Open Server

OpenClient

OpenClient

SQL Server LTM Executable Program

590

When new records are added to the end of the log, the log scan thread wakes up and sends the new records. If batch_sz is not reached yet, it goes back to sleep. The time remaining in scan_retry is added to the next sleep interval, for a maximum time of scan_retry*2 seconds. When the log scan thread sleep interval has expired, the thread returns an end-of-scan message to the LTM, and a new log scan request is initiated.

Note If you restart an LTM while the log scan thread is sleeping, the SQL Server rejects the LTM connection because the sleeping log scan thread has not released the previous LTM connection. When the thread wakes up, the SQL Server releases the previous connection and can then accept a new LTM connection. If you create a script to automatically restart an LTM, you should have the script sleep for scan_retry * 2 seconds before it restarts the LTM.

LTM User Thread

There is one LTM user thread for each primary database that the Replication Server manages. The LTM user thread manages an LTM connection. It verifies that LTM submissions are valid and writes them into the inbound stable queue for the database.

If the connection between an LTM and a Replication Server is broken, the LTM user thread shuts down.

You can monitor general information on current Replication Server threads by using the command admin who. On the display output, the LTM user thread appears as “LTM USER”.

SQL Server LTM Executable ProgramIf the Replication Server has an LTM for a SQL Server database, use the ltm operating system command to start the LTM. Do this after the RSSD SQL Server and the Replication Server are already running. Here is the syntax for ltm:

ltm [-C config_file] [-S ltm_name][-I interfaces_file] [-E errorlog_file][-M] [-A] [-W] [-v]

Refer to “ltm” in Chapter 7, “Programs,” in the Replication Server Reference Manual for complete information about each of the parameters of the ltm command.


591

The rs_init program creates the run file “RUN_name”, where name is the name of the LTM. The run file specifies the ltm command with parameters set for the installed LTM. Normally, you start LTM by executing this file.

The ltm executable program and the LTM run file are located in the bin subdirectory of the Sybase release directory. Refer to the Replication Server installation and configuration guides for your platform for more information.

Warning! If you are running more than one LTM, either execute them in separate directories, or use the -E flag to specify different error log file names. Otherwise, the LTMs will try to record their messages in the same file.

Shutting Down an LTMTo shut down an LTM, log in to it and enter this at the isql prompt:

shutdown

When you shut down an LTM, it refuses additional connections, terminates threads, and exits.

Checking Log Files for ErrorsLike the Replication Server, the LTM displays status and error messages in its log file. The default name for the log file is ltm.log. You can change this default by restarting ltm with the -E option and specifying the error log file name to use.

You can check the ltm.log files for any error messages. One way to do this is by using Sybase Central, which also lets you invoke shell scripts based on errors reported in those logs.

In Sybase Central, see the topics under “Viewing the Error Log” in Replication Server’s online help.

Messages continue to accumulate in the error log files until you remove them. For this reason, you may choose to truncate the log files when the LTM is shut down.

If a log file is unavailable, important error information is written to the standard error output file, which you can display on a terminal or redirect to a file.

RSM

Configuring and Maintaining the LTM

592

Configuring and Maintaining the LTMAn LTM for the RSSD is installed with the Replication Server if the Replication Server is the source site for any route. In addition, a database in a replication system requires an LTM if:

• The database holds primary data, or

• Replicated stored procedures are executed in the database

The following sections describe how to maintain LTMs for the RSSD and the databases in your system.

The only task you may need to perform for the RSSD LTM is modifying the configuration file. An LTM configuration file contains information the LTM needs to find the database log it is transferring and the Replication Server it is transferring the log to.

This section describes the components and resources that must be present or assembled before you can run LTM. See the Replication Server Design Guide for component requirements for different replication topologies and performance considerations when constructing topologies.

Adding a Replication ServerTo add a Replication Server, use the rs_init installation program, as described in the Replication Server Installation Guide for your platform. When connecting a new Replication Server to an existing system, always conduct a careful review and analysis of how the server will fit into your system. Determine what other processes are required for the server and designate required names and accounts for these processes.

When you install each Replication Server, rs_init performs the following tasks:

• Creates configuration files for the Replication Server and the RSSD LTM

• Creates executable files to start the Replication Server and the RSSD LTM

• Sets up the RSSD

• Starts the Replication Server and the RSSD LTM


593

Preparing Databases for ReplicationSQL Server databases are prepared for use with Replication Server using the rs_init program described in the Replication Server installation and configuration guides for your platform.

rs_init Installation Program

The rs_init program prepares a database for replication. If the database has primary data, rs_init:

• Creates an LTM configuration file

• Creates a run file, an executable script to start the LTM

• Starts the LTM

• Sets the secondary truncation point to “valid” in the SQL Server database, preventing SQL Server from truncating database log records before the LTM has retrieved them

Refer to the Replication Server installation and configuration guides for your platform for details on each step.

If you are adding a database that requires an LTM, you specify the following information in rs_init:

• LTM name

• Replication Server user and password

• LTM Administrator user and password

• LTM error log file name

• LTM configuration file name

• LTM password encryption

• LTM character set

• LTM language

• LTM sort order

• LTM interfaces file information


594

Interfaces FileThe interfaces file contains network definitions for servers in the replication system, including Replication Servers, data servers, and LTMs. Server programs are registered in an interfaces file so that client applications and other server programs can locate them.

Generally, one interfaces file at each site contains entries for all local and remote Replication Servers and data servers. The interfaces file at a site requires entries for these LTM components:

• RSSD LTM for this Replication Server

• LTMs for databases managed by this Replication Server

You can use the default interfaces file or you can specify an alternative interfaces file at the command line when you start Replication Server or LTM. The interfaces file is usually located in the SYBASE release directory. Use ds_edit to modify the interfaces file. See the Replication Server installation guide for your platform for more information.

Note With Replication Server 11.5 and later, if you are using network-based security,we recommended that you use the directory services of your network security mechanism to register Replication Servers, Adaptive Servers, and gateway software. Refer to the documentation that comes with your network security mechanism for details.

LTM Configuration FileThe configuration file for an LTM for a primary database or an RSSD is created during the installation process. If you are modifying a primary database, you may need to modify the configuration file for the LTM for the database. Refer to the Replication Server installation and configuration guides for your platform.

LTM finds the start-up information it needs in a configuration file. The format of the LTM configuration file is the same as the Replication Server configuration file, which is described in “Setting Replication Server Configuration Parameters” on page 92.


595

The file is created by the rs_init program, but it can be edited with a text editor. If it contains encrypted passwords, however, you must modify them using rs_init. Refer to the Replication Server installation and configuration guides for your platform for more information about working with encrypted passwords. The default name for the LTM configuration file is the LTM name with “ .cfg” appended.

Note If a password is stored in encrypted form, you cannot edit the password in the LTM configuration file. To change an encrypted password in this file, use the rs_init installation program. See the Replication Server installation guide for your platform for more information.

Refer to the reference page for “ltm” in Chapter 7, “Programs,” in the Replication Server Reference Manual for detailed descriptions of LTM configuration file parameters.

Replication Server Login Name and Password for the LTMThe LTM retrieves information about changes to the replicated system tables from the database transaction logs and submits them to the Replication Server for distribution.

Replication Server needs a login name for LTM use. The rs_init program uses the create user command to add this Replication Server user.

Observe these guidelines when you change the Replication Server login name and/or password for the LTM. See the Replication Server Reference Manual for command syntax details.

• To change the login name and/or password (encrypted or clear text), use the alter user command with the set password clause.

This updates the login and/or password in the rs_users system table.

• To change both the login name and password (encrypted or clear text), use the drop user command to drop the old user login name and the create user command to create the new login and password. Then grant the user connect source permission.

• Update the LTM configuration file with the new login name and/or password.

• For the updates to take effect, restart the LTM.


596

LTM Login Name and PasswordThe LTM configuration file contains the login name and password for the System Administrator LTM user. Use this login name and password to log in to and shut down the LTM. The configuration parameters that hold the login name and password are LTM_admin_user and either LTM_admin_pw or LTM_admin_pw_enc.

By default, the System Administrator LTM user’s login name is “sa” and the password is “null.” If the login name or password is changed, edit the LTM configuration file to match the changes and restart the LTM.

SQL Server Login Name and PasswordLTMs log in to SQL Server to read the transaction log by using either the “sa” login name or the “dbo” role, depending on the values you supply when you use rs_init. If you change the password for the “sa” login name or the “dbo” role, you must also change it in the LTM configuration file. Be sure to shut down and restart the LTM so that the new values can take effect.

Enabling and Disabling Password EncryptionWhen you use the rs_init program to install or upgrade the replication system, you can enable password encryption. This allows rs_init to encrypt passwords throughout sensitive areas of the replication system. After the replication system is installed or upgraded, you can use rs_init at any time to enable encryption.

If encryption is enabled for a Replication Server, rs_init encrypts new passwords, passwords contained in the Replication Server configuration file, and passwords stored in the RSSD. If encryption is enabled for an LTM, rs_init encrypts new passwords and passwords contained in the LTM configuration file.

For details on enabling password encryption using the rs_init program, see the Replication Server Installation Guide.

Disabling Encryption on New and Existing LTM Passwords

Once LTM password encryption is enabled through rs_init, use this procedure to decrypt LTM passwords:


597

1 Disable encryption on new passwords that are entered for LTM.

To do this, specify 0 as the value of the pwd_encrypt configuration parameter in the LTM configuration file.

2 Restart the LTM to pick up the new pw_encrypt configuration parameter.

Suspending and Resuming Log TransferIf you are performing recovery, troubleshooting, or diagnostic tasks, you may need to suspend and resume log transfer. This is described in the following section. See Chapter 14, “Replication System Recovery,” in the Replication Server Administration Guide for version 11.0 for procedures to start the LTM in recovery mode so that it can replay database and transaction dumps.

Suspending LTMsTo disconnect an LTM and prevent an LTM from connecting to the Replication Server, execute the suspend log transfer command. The LTM remains suspended until you restart the LTM and execute the resume log transfer command.

Note Suspending LTMs is the first step in quiescing the replication system. See “Quiescing Replication Server” on page 109.

The syntax for the suspend log transfer command is:

suspend log transfer from {data_server.database | all}

data_server – the data server with the database whose LTM is to be suspended.

database – the database whose LTM is to be suspended and whose connections are to be disallowed.

all – instructs Replication Server to suspend all LTMs and disallow future connections for all LTMs.

The suspend log transfer command records information in the RSSD, so suspended LTMs remain suspended after the Replication Server is restarted.

Examples The following examples demonstrate the use of the suspend log transfer command.

Modifying Replication Systems with LTMs

598

1 The following command disconnects the LTM for the database named NY_ACCOUNTS_DB:

suspend log tranfer from NY_DS.NY_ACCOUNTS_DB

2 The following command suspends all LTM connections to this Replication Server:


In both examples, after the command is executed, the LTM process shuts down.

Resuming LTMsThis command allows an LTM to connect to a Replication Server. However, resume log transfer does not restart the LTM. The LTM must also be restarted manually.

The syntax for the resume log transfer command is:

resume log transfer from {data_server.database | all}

data_server – the data server with the database whose LTM is to be resumed.

database – the database whose LTM is to be resumed.

all – allow all LTMs to connect to this Replication Server.

Examples These examples demonstrate the use of the resume log transfer command.

1 The following command allows the LTM for NY_ACCOUNTS_DB to connect to the Replication Server:

resume log transfer from NY_DS.NY_ACCOUNTS_DB

2 The following command allows all LTMs to connect to the Replication Server:


In both examples, the appropriate LTMs must then be restarted.

Modifying Replication Systems with LTMsThe following sections describe how you can:

• Configure Replication Servers to manage primary tables


599

• Change replicate to primary databases

• Change primary to replicate databases

when your system uses LTMs as replication agents.

Configuring Replication Servers to Manage Primary TablesIf you want to add a route from a Replication Server that used to be configured as a replicate-only Replication Server, the RSSD for that Replication Server requires an LTM.

To add an LTM for the RSSD, perform the following steps:

1 To set the LTM truncation point for the RSSD to “valid,” log in to the SQL Server as “sa” and execute the following commands:

> use RSSD_database> go> dbcc settrunc(’ltm,’ ’valid’)> go

2 To allow the Replication Server to receive messages from the LTM, execute the following command at the Replication Server:

alter connection to RSSD_data_server.RSSD_databaseset log transfer on

3 Add an interfaces file entry for the LTM.

Use ds_edit to modify the interfaces file. See the Replication Server Installation Guide for more information.

4 Create an LTM configuration file.

5 Run the LTM for the configuration file.

Changing Replicate Databases to Primary DatabasesThis section describes how to change a database that is designated as “replicate only” to be a source of asynchronous transactions or to contain primary data.

1 A the Replication Server managing the database, create RS_user so that the LTM can log in to the Replication Server.

Use the create user command:

Modifying Replication Systems with LTMs

600

create user RS_user_name set password {RS_password | null}

where RS_user_name and RS_password are the name and password the LTM uses to connect to Replication Server.


grant connect source to RS_user_name


2 At the SQL Server, create SQL_user so that the LTM can log in to the SQL Server. Grant SQL_user dbo permission or replication_role.

See the SYBASE SQL Server System Administration Guide for information about creating users and granting permissions in SQL Server.

3 At the Replication Server that manages the database, execute the alter connection command using the log transfer on option:

alter connection to data_server.databaseset log transfer on

4 At the SQL Server, set the LTM truncation point for the database to “valid”:

> use database> go> dbcc settrunc(’ltm’, ’valid’)> go

5 Add an interfaces file entry for the LTM that will read the SQL Server log of this new primary database.

Use ds_edit to modify the interfaces file. See the Replication Server Installation Guide for more information.

6 In the SQL Server, create the rs_marker stored procedure and set its replicate status to “true,” using the sp_setrepproc system procedure. You can find the rs_marker stored procedure in the file rs_install_primary.sql or rsinssys.sql in the scripts directory of the SYBASE release directory.

7 Create an LTM configuration file and start the LTM.


601

Changing Primary Databases to Replicate DatabasesUse the following procedure to change a primary database to a replicate database:

1 Drop all subscriptions to the replication definitions in this database.

2 Drop all replication definitions and functions defined for this database.

3 Shut down the LTM.

4 Log in to the Replication Server that manages the database and execute the alter connection command using the log transfer off option:

alter connection to data_server.databaseset log transfer off

5 Log in to the SQL Server and set the LTM truncation point for the database to “ignore”:

> use database> go> dbcc settrunc(’ltm’, ’ignore’)> go

6 Set the status of rs_marker to “false” using the sp_setrepproc system procedure.

sp_setrepproc rs_marker, ’false’

7 Set the replicate status of all replicated objects to “false”. To do this:

a Execute sp_setreptable and sp_setrepproc without any arguments to generate a list of all replicated tables and stored procedures in the database.

b One by one, set the replicate status of each table and stored procedure to “false,” using sp_setreptable and sp_setrepproc.

LTM Error Log InformationThe SQL Server LTM error log is a text file. The LTM records errors and informational messages that occur when transferring replicated objects from the SQL Server log and converting them into LTL commands. These commands are sent to the Replication Server for distribution and replication. Errors include those from the SQL Server, the Replication Server, or internally from the LTM.

LTM Error Log Information

602

By default, the LTM error log file name is ltm.log and resides in the directory where you started the LTM. You can specify the name and location of the error log file by using the -E command line flag when you start the LTM or in an LTM run file

For solutions to common LTM errors, refer to the Replication Server Troubleshooting Guide for Replication Server 11.0.x.

The LTM performs actions based on the severity and recoverability of an error. The actions are listed in Table B-1.

Table B-1: Action for LTM errors

Note Unlike Replication Server, LTM error actions are not user-configurable.

The format of LTM messages is identical to the format for Replication Server messages. For details, see “Error and Warning Messages” on page 501.

LTM Message TypesTable B-2 describes the kinds of errors you can expect to find in the LTM error log. For specific errors and how to resolve them, see the Replication Server Troubleshooting Guide for Replication Server 11.0.x.

Action Description

Log the error as a warning and continue processing.

This action is taken if the LTM can continue its normal operation, and the error condition does not affect the general integrity of the system. For warning message examples, see the Replication Server Troubleshooting Guide for Replication Server 11.0.x.

Retry the operation that caused the error until it succeeds.

The LTM retries the operation that caused the error, as in the case where the connection to the Replication Server is down, LTM source is already connected, and SQL Server is out of system alarms, or is in the middle of recovery.

Retrying an operation that caused an error temporarily prevents the LTM from continuing. The operation should eventually succeed.

Abort and disconnect from the SQL Server and Replication Server.

The action is taken for fatal errors that are too severe to continue. The error cannot be recovered until some corrective action has been taken. The LTM is shut down.


603

Table B-2: Types of LTM Error messages

LTM Warning Messages from SQL Server

The following SQL Server errors from the 9100 and 9199 error range are logged as warnings; processing continues. The messages are printed in the language specified in the LTM_language configuration parameter (assuming SQL Server has that language installed).

9102 - Failed to convert the log record into row format for database ’tokyo_ds.pubs2’, XACT ID 0x10ab RID 0x04. Information associated with the log record is not replicated.9103 - Failed to send the log record for database 'xxx’, XACT ID 0x10ab, RID 0x04. Information associated with

Component Description of Error Messages

SQL Server Commonly identified by error numbers 9100 through 9199. The LTM can also obtain SQL Server errors outside this range.

Error numbers 9100 through 9199 are usually related to scanning the log and are not recorded in the SQL Server log because they are not considered severe to the SQL Server. They are only sent to the client. Look at the LTM error log for errors or conditions that occur during the log scan. The LTM logs the errors and performs some action based on the error. For a list of warning errors in this range, see Table B-2 on page 603. It describes the kinds of errors you can expect to find in the LTM error log. For specific errors and how to resolve them, see the Replication Server Troubleshooting Guide for Replication Server 11.0.x.

Replication Server

These include Replication Server normalization errors (numbers 32000 through 32999), rebuild or restart errors (numbers 14034 through 14036, and 14069), Open Server errors, and ct_lib and cs_lib errors from libraries the LTM uses.

If the LTM is in recovery mode and the error number is 14048, the LTM rebuilds the messages from the SQL Server log.

The LTM treats normalization errors as recoverable errors. The LTM logs the error and continues processing. For Open Server and library errors, responses to errors are based on the severity of the error and are handled in a manner similar to the way Replication Server handles library errors. Replication Server shuts down the LTM if the error is fatal.

Normalization errors result from transient inconsistencies in the setup of replicated objects. For example, if a table has been marked replicated with the sp_setreptable system procedure, but no replication definitions have yet been created for the table, the LTM will retrieve log records for an object that is not yet known to the Replication Server.

LTM General LTM errors include running out of memory and other software errors.

If the LTM encounters other errors sending the distribute commands (SQL-like statements), it turns off the batch_ltl_cmds configuration option and sends the distribute commands one at a time. If the skip_ltl_cmd_err configuration option is “on,” the LTM skips the command. Otherwise, the LTM shuts down. See “ltm” in Chapter 7, “Programs,” of the Replication Server Reference Manual for details on the configuration settings.

LTM Error Log Information

604

the log record is not replicated.9105 - A missing log record indicates a prematurely truncated log or a corrupt log. The log record in database ’tokyo_ds.pubs2’, XACT ID 0x10ab, is not replicated.9106 - The deferred insert (INOOP) log record referenced by the insert indirect (INSIND) log record was not found as expected at RID 0x04.9107 - Unexpected function return value while processing the log record of database ’tokyo_ds.pubs2’, XACT ID 0x10ab, RID 0x04. The log record may not be replicated.9110 - Found an ENDXACT log record before finding an expected INSERT log record in database ’tokyo_ds.pubs2’, XACT ID 0x10ab, RID 0x04.9141 - The stored proc. ’a’ associated with the log record in database ’tokyo_ds.pubs2’, XACT ID 0x10ab, RID 0x04, was dropped after the log record was written. The log record is not replicated.

605

A P P E N D I X C HDS Datatype Translation Mapping

This appendix lists default datatype mapping for the non-Sybase databases supported for HDS.

For each supported non-Sybase database, HDS provides default datatype mapping (class-level translations) for:

• Non-Sybase datatypes that do not correspond directly to Adaptive Server datatypes

• Adaptive Server datatypes that do not correspond directly to non-Sybase datatypes

• Non-Sybase datatypes that do not correspond directly to datatypes of other supported non-Sybase databases

Note Class-level translations are not provided for datatypes that correspond directly to datatypes in another database.

See “Translating Datatypes Using HDS” on page 281 for a complete discussion of HDS.

DB2 Class-Level TranslationsThe following sections list the class-level translations for Adaptive Server datatypes to DB2 datatypes, DB2 datatypes to Adaptive Server datatypes, and DB2 datatypes to datatypes of other supported databases:

• “Adaptive Server to DB2 Datatypes”

• “DB2 to Adaptive Server Datatypes”

• “DB2 to Informix Datatypes”

• “DB2 to Microsoft SQL Server Datatypes”

DB2 Class-Level Translations

606

• “DB2 to Oracle Datatypes”

Adaptive Server to DB2 Datatypes

Table C-1 lists class-level translations for Adaptive Server datatypes to DB2 datatypes.

Table C-1: Class-level translation from Adaptive Server to DB2 datatypes

DB2 to Adaptive Server Datatypes

Table C-2 lists class-level translations for DB2 datatypes to Adaptive Server datatypes.

Table C-2: Class-level translation from DB2 to Adaptive Server datatypes

DB2 to Informix Datatypes

Table C-3 lists class-level translations for DB2 datatypes to Informix datatypes.

Adaptive Server datatype DB2 datatype

binary CHAR FOR BIT DATA

bit TINYINT

datetime TIMESTAMP

decimal DECIMAL

money NUMERIC

numeric NUMERIC

smalldatetime TIMESTAMP

smallmoney NUMERIC

varbinary VARCHAR FOR BIT DATA

DB2 datatype Adaptive Server datatype

CHAR FOR BIT DATA binary

DATE datetime

TIME datetime

TIMESTAMP datetime

VARCHAR FOR BIT DATA varbinary

APPENDIX C HDS Datatype Translation Mapping

607

Table C-3: Class-level translation from DB2 to Informix datatypes

DB2 to Microsoft SQL Server Datatypes

Table C-4 lists class-level translations for DB2 datatypes to Microsoft SQL Server datatypes.

Table C-4: Class-level translation from DB2 to Microsoft SQL Server datatypes

DB2 to Oracle Datatypes

Table C-5 lists class-level translations for DB2 datatypes to Oracle datatypes.

Table C-5: Class-level translation from DB2 to Oracle datatypes

Informix Class-Level TranslationsThe following sections list class-level translations for Adaptive Server datatypes to Informix datatypes, Informix datatypes to Adaptive Server datatypes, and Informix datatypes to datatypes of other supported databases:

• “Adaptive Server to Informix Datatypes”

• “Informix to Adaptive Server Datatypes”

• “Informix to DB2 Datatypes”

DB2 datatype Informix datatype


DATE date

TIME datetime (time only)

TIMESTAMP datetime fraction(5)

VARCHAR FOR BIT DATA binary

DB2 datatype Microsoft SQL Server datatype


DATE datetime

TIME datetime

TIMESTAMP datetime

VARCHAR FOR BIT DATA varbinary

DB2 datatype Oracle datatype

CHAR FOR BIT DATA RAW

DATE DATE

TIME DATE (with time)

TIMESTAMP DATE (with time)

VARCHAR FOR BIT DATA RAW

Informix Class-Level Translations

608

• “Informix to Microsoft SQL Server Datatypes”

• “Informix to Oracle Datatypes”

Adaptive Server to Informix Datatypes

Table C-6 lists class-level translations for Adaptive Server datatypes to Informix datatypes.

Table C-6: Class-level translation from Adaptive Server to Informix datatypes

Informix to Adaptive Server Datatypes

Table C-6 lists class-level translations for Informix datatypes to Adaptive Server datatypes.

Table C-7: Class-level translation from Informix to Adaptive Server datatypes

Informix to DB2 Datatypes

Table C-8 lists class-level translations for Informix datatypes to DB2 datatypes.

Adaptive Server datatype Informix datatype

binary binary

datetime datetime fraction(3)

smalldatetime datetime fraction(0)

varbinary binary

Informix datatype Adaptive Server datatype

binary binary

date datetime

datetime fraction(0) datetime






datetime (time only) datetime


609

Table C-8: Class-level translation from Informix to DB2 datatypes

Informix to Microsoft SQL Server Datatypes

Table C-9 lists class-level translations for Informix datatypes to Microsoft SQL Server datatypes.

Table C-9: Class-level translation from Informix to Microsoft SQL Server datatypes

Informix to Oracle Datatypes

Table C-10 lists class-level translations for Informix datatypes to Oracle datatypes.

Informix datatype DB2 datatype


date DATE

datetime fraction(0) TIMESTAMP






datetime (time only) TIME

Informix datatype Microsoft SQL Server datatype

binary binary

date datetime







datetime (time only) datetime

Microsoft SQL Server Class-Level Translations

610

Table C-10: Class-level translation from Informix to Oracle datatypes

Microsoft SQL Server Class-Level TranslationsThe following sections list class-level translations for Microsoft SQL Server datatypes to datatypes of other supported databases:

• “Microsoft SQL Server to DB2 Datatypes”

• “Microsoft SQL Server to Informix Datatypes”

• “Microsoft SQL Server to Oracle Datatypes”

Note Class-level translations are not supplied for Adaptive Server datatypes to Microsoft SQL Server datatypes (or Microsoft SQL Server datatypes to Adaptive Server datatypes) because Microsoft SQL Server datatypes are directly compatible with Adaptive Server datatypes and require no translation.

Microsoft SQL Server to DB2 Datatypes

Table C-11 lists class-level translations for Microsoft SQL Server datatypes to DB2 datatypes.

Informix datatype Oracle datatype

binary RAW

date DATE

datetime fraction(0) DATE (with time)






datetime (time only) DATE (with time)


611

Table C-11: Class-level translation from Microsoft SQL Server to DB2 datatypes

Microsoft SQL Server to Informix Datatypes

Table C-12 lists class-level translations for Microsoft SQL Server datatypes to Informix datatypes.

Table C-12: Class-level translation from Microsoft SQL Server to Informix datatypes

Microsoft SQL Server to Oracle Datatypes

Table C-13 lists class-level translations for Microsoft SQL Server datatypes to Oracle datatypes.

Microsoft SQL Server datatype DB2 datatype


bit TINYINT

datetime TIMESTAMP

decimal DECIMAL

money NUMERIC

numeric NUMERIC

smalldatetime TIMESTAMP

smallmoney NUMERIC

varbinary VARCHAR FOR BIT DATA

Microsoft SQL Server datatype Informix datatype

binary binary

datetime datetime fraction(3)

smalldatetime datetime fraction(0)

varbinary binary

Oracle Class-Level Translations

612

Table C-13: Class-level translation from Microsoft SQL Server to Oracle datatypes

Oracle Class-Level TranslationsThe following sections list class-level translations for Adaptive Server datatypes to Oracle datatypes, Oracle datatypes to Adaptive Server datatypes, and Oracle datatypes to datatypes of other supported databases:

• “Adaptive Server to Oracle Datatypes”

• “Oracle to Adaptive Server Datatypes”

• “Oracle to DB2 Datatypes”

• “Oracle to Informix Datatypes”

• “Oracle to Microsoft SQL Server Datatypes”

Adaptive Server to Oracle Datatypes

Table C-14 lists class-level translations for Adaptive Server datatypes to Oracle datatypes.

Table C-14: Class-level translation from Adaptive Server to Oracle datatypes

Oracle to Adaptive Server Datatypes

Table C-15 lists class-level translations for Oracle datatypes to Adaptive Server datatypes.

Microsoft SQL Server datatype Oracle datatype

binary RAW

datetime DATE (with time)

money DECIMAL

smalldatetime DATE

smallmoney DECIMAL

varbinary RAW

Adaptive Server datatype Oracle datatype

binary RAW

datetime DATE (with time)

money DECIMAL

smalldatetime DATE

smallmoney DECIMAL

varbinary RAW


613

Table C-15: Class-level translation from Oracle to Adaptive Server datatypes

Oracle to DB2 Datatypes

Table C-16 lists class-level translations for Oracle datatypes to DB2 datatypes.

Table C-16: Class-level translation from Oracle to DB2 datatypes

Oracle to Informix Datatypes

Table C-17 lists class-level translations for Oracle datatypes to Informix datatypes.

Table C-17: Class-level translation from Oracle to Informix datatypes

Oracle to Microsoft SQL Server Datatypes

Table C-18 lists class-level translations for Oracle datatypes to Microsoft SQL Server datatypes.

Table C-18: Class-level translation from Oracle to Microsoft SQL Server datatypes

Oracle datatype Adaptive Server datatype

RAW varbinary

DATE datetime

Oracle datatype DB2 datatype

RAW CHAR FOR BIT DATA

DATE DATE

DATE (with time) TIMESTAMP

Oracle datatype Informix datatype

RAW binary

DATE date

DATE (with time) datetime fraction(0)

Oracle datatype Microsoft SQL Server datatype

RAW varbinary

DATE datetime

Oracle Class-Level Translations

614

615

Glossary

active database In a warm standby application, a database that is replicated to a standby database. See also warm standby application.

Adaptive Server The Sybase version 11.5 and later relational database server. At least one Adaptive Server is required for each Replication Server, to manage the RSSD and any other Adaptive Server databases.

application programming interface (API)

A predefined interface through which users or programs communicate with each other. Open Client and Open Server are examples of APIs that communicate in a client/server architecture. RCL, the Replication Command Language, is the Replication Server API.

applied function A replicated function, associated with a function replication definition, that Replication Server delivers from a primary database to a subscribing replicate database. The function passes parameter values to a stored procedure that is executed at the replicate database. See also replicated function delivery, request function, and function replication definition.

article A replication definition extension for tables or stored procedures that can be an element of a publication. Articles may or may not contain where clauses, which specify a subset of rows that the replicate database receives.

asynchronous procedure delivery

A method of replicating, from a source to a destination database, a stored procedure that is associated with a table replication definition.

asynchronous command A command that a client submits where the client is not prevented from proceeding with other operations before the completion status is received. Many Replication Server commands function as asynchronous commands within the replication system.

616

atomic materialization

A materialization method that copies subscription data from a primary to a replicate database through the network in a single atomic operation, using a select operation with a holdlock. No changes to primary data are allowed until data transfer is complete. Replicate data may be applied either as a single transaction or in increments of ten rows per transaction, which ensures that the replicate database transaction log does not fill. Atomic materialization is the default method for the create subscription command. See also nonatomic materialization, bulk materialization and no materialization.

autocorrection Autocorrection is a setting applied to replication definitions, using the set autocorrection command, to prevent failures caused by missing or duplicate rows in a copy of a replicated table. When autocorrection is enabled, Replication Server converts each update or insert operation into a delete followed by an insert. Autocorrection should only be enabled for replication definitions whose subscriptions use nonatomic materialization.

base class A function-string class that does not inherit function strings from a parent class. See also function-string class.

bitmap subscription A type of subscription that replicates rows based on bitmap comparisons. Create columns using the int datatype, and identify them as the rs_address datatype when you create a replication definition. When you create a subscription, compare each rs_address column to a bitmask using a bitmap comparison operator (&) in the where clause. Rows matching the subscription’s bitmap are replicated.

bulk materialization A materialization method whereby subscription data in a replicate database is initialized outside of the replication system. For example, data may be transferred from a primary database using media such as magnetic tape, diskette, CD-ROM, or optical storage disk. Bulk materialization involves a series of commands, starting with define subscription. You can use bulk materialization for subscriptions to table replication definitions or function replication definitions. See also atomic materialization, nonatomic materialization, and no materialization.

centralized database system

A database system where data is managed by a single database management system at a centralized location.

class See error class and function-string class.

class tree A set of function-string classes, consisting of two or more levels of derived and parent classes, that derive from the same base class. See also function-string class.

Glossary

617

client A program connected to a server in a client/server architecture. It may be a front-end application program executed by a user or a utility program that executes as an extension of the system.

Client/Server Interfaces (C/SI)

The Sybase interface standard for programs executing in a client/server architecture.

concurrency The ability of multiple clients to share data or resources. Concurrency in a database management system depends upon the system protecting clients from conflicts that arise when data in use by one client is modified by another client.

connection A connection from a Replication Server to a database. See also Data Server Interface (DSI) and logical connection.

coordinated dump A set of database dumps or transaction dumps that is synchronized across multiple sites by distributing an rs_dumpdb or rs_dumptran function through the replication system.

database A set of related data tables and other objects that is organized and presented to serve a specific purpose.

database generation number

Stored in both the database and the RSSD of the Replication Server that manages the database, the database generation number is the first part of the origin queue ID (qid) of each log record. The origin queue ID ensures that the Replication Server does not process duplicate records. During recovery operations, you may need to increment the database generation number so that Replication Server does not ignore records submitted after the database is reloaded.

database server A server program, such as Sybase Adaptive Server, that provides database management services to clients.

data definition language (DDL)

The set of commands in a query language, such as Transact-SQL, that describes data and their relationships in a database. DDL commands in Transact-SQL include those using the create, drop, and alter keywords.

data manipulation language (DML)

The set of commands in a query language, such as Transact-SQL, that operates on data. DML commands in Transact-SQL include select, insert, update, and delete.

data server A server whose client interface conforms to the Sybase Client/Server Interfaces and provides the functionality necessary to maintain the physical representation of a replicated table in a database. Data servers are usually database servers, but they can also be any data repository with the interface and functionality Replication Server requires.

618

Data Server Interface (DSI)

Replication Server threads corresponding to a connection between a Replication Server and a database. DSI threads submit transactions from the DSI outbound queue to a replicate data server. They consist of a scheduler thread and one or more executor threads. The scheduler thread groups the transactions by commit order and dispatches them to the executor threads. The executor threads map functions to function strings and execute the transactions in the replicate database. DSI threads use an Open Client connection to a database. See also outbound queue and connection.

data source A specific combination of a database management system (DBMS) product such as a relational or non-relational data server, a database residing in that DBMS, and the communications method used to access that DBMS from other parts of a replication system. See also database and data server.

decision support application

A database client application characterized by ad hoc queries, reports, and calculations and few data update transactions.

declared datatype The datatype of the value delivered to the Replication Server from the replication agent:

• If the replication agent delivers a base Replication Server datatype, such as datetime, to the Replication Server, the declared datatype is the base datatype.

• Otherwise, the declared datatype must be the UDD for the original datatype at the primary database.

default function string

The function string that is provided by default for the system-provided classes rs_sqlserver_function_class and rs_default_function_class and classes that inherit function strings from these classes, either directly or indirectly. See also function string.

dematerialization The optional process, when a subscription is dropped, whereby specific rows that are not used by other subscriptions are removed from the replicate database.

derived class A function-string class that inherits function strings from a parent class. See also function-string class and parent class.

direct route A route used to send messages directly from a source to a destination Replication Server, with no intermediate Replication Servers. See also indirect route and route.

disk partition See partition.

Glossary

619

distributed database system

A database system where data is stored in multiple databases on a network. The databases may be managed by data servers of the same type (for example, Adaptive Server) or by heterogeneous data servers.

Distributor A Replication Server thread (DIST) that helps to determine the destination of each transaction in the inbound queue.

dump marker A message written by Adaptive Server in a database transaction log when a dump is performed. In a warm standby application, when you are initializing the standby database with data from the active database, you can specify that Replication Server use the dump marker to determine where in the transaction stream to begin applying transactions in the standby database. See also warm standby application.

error action A Replication Server response to a data server error. Possible Replication Server error actions are ignore, warn, retry_log, log, retry_stop, and stop_replication. Error actions are assigned to specific data server errors.

error class A name for a collection of data server error actions that are used with a specified database.

exceptions log A set of three Replication Server system tables that holds information about transactions that failed on a data server. The transactions in the log must be resolved by a user or by an intelligent application. You can use the rs_helpexception stored procedure to query the exceptions log.

Failover Sybase Failover allows you to configure two version 12.0 Adaptive Servers as companions. If the primary companion fails, that server’s devices, databases, and connections can be taken over by the secondary companion.

For more detailed information about how Sybase Failover works in Adaptive Server, refer to Using Sybase Failover in a High Availability System, which is part of the Adaptive Server Enterprise version 12.0 documentation set.

For instructions on how to enable Failover support for non-RSSD Replication Server connections to Adaptive Server, see “Configuring the Replication System to Support Sybase Failover” in Chapter 16, “Replication System Recovery,” of the Replication Server Administration Guide.

fault tolerance The ability of a system to continue to operate correctly even though one or more of its component parts is malfunctioning.

620

function A Replication Server object that represents a data server operation such as insert, delete, select, or begin transaction. Replication Server distributes such operations to other Replication Servers as functions. Each function consists of a function name and a set of data parameters. In order to execute the function in a destination database, Replication Server uses function strings to convert a function to a command or set of commands for a type of database. See also user-defined function, and replicated function delivery.

function replication definition

A description of a replicated function used in replicated function delivery. The function replication definition, maintained by Replication Server, includes information about the parameters to be replicated and the location of the primary version of the affected data. See also replicated function delivery.

function scope The range of a function’s effect. Functions have replication definition scope or function-string class scope. A function with replication definition scope is defined for a specific replication definition, and cannot be applied to other replication definitions. A function with function-string class scope is defined once for a function-string class and is available only within that class.

function string A string that Replication Server uses to map a database command to a data server API. For the rs_select and rs_select_with_lock functions only, the string contains an input template, used to match function strings with the database command. For all functions, the string also contains an output template, used to format the database command for the destination data server.

function-string class A named collection of function strings used with a specified database connection. Function-string classes include those provided with Replication Server and those you have created. Function-string classes can share function string definitions through function-string inheritance. The three system-provided function-string classes are rs_sqlserver_function_class, rs_default_function_class, and rs_db2_function_class. See also base class, class tree, derived class, function-string inheritance, and parent class.

function-string inheritance

The ability to share function string definitions between classes, whereby a derived class inherits function strings from a parent class. See also derived class, function-string class, and parent class.

function-string variable

An identifier used in a function string to represent a value that is to be substituted at run time. Variables in function strings are enclosed in question marks (?). They represent column values, function parameters, system-defined variables, or user-defined variables.

function subscription

A subscription to a function replication definition (used in applied function delivery).

Glossary

621

generation number See database generation number.

heterogeneous data servers

Multi-vendor data servers used together in a distributed database system.

hibernation mode A Replication Server state in which all DDL commands, except admin and sysadmin commands, are rejected; all routes and connections are suspended; most service threads, such as DSI and RSI, are suspended; and RSI and RepAgent (or LTM) users are logged off and not allowed to log on. Used during route upgrades, and may be turned on for a Replication Server to debug problems.

hot standby application

A database application in which the standby database can be placed into service without interrupting client applications and without losing any transactions. See also warm standby application.

ID Server One Replication Server in a replication system is the ID Server. In addition to performing the usual Replication Server tasks, the ID Server assigns unique ID numbers to every Replication Server and database in the replication system, and maintains version information for the replication system.

inbound queue A stable queue used to spool messages from a Replication Agent to a Replication Server.

indirect route A route used to send messages from a source to a destination Replication Server, through one or more intermediate Replication Servers. See also direct route and route.

interfaces file A file containing entries that define network access information for server programs in a Sybase client/server architecture. Server programs may include Adaptive Servers, SQL Servers, gateways, Replication Servers, and Replication Agents such as LTM for SQL Server. The interfaces file entries enable clients and servers to connect to each other in a network.

latency The measure of the time it takes to distribute to a replicate database a data modification operation first applied in a primary database. The time includes Replication Agent processing, Replication Server processing, and network overhead.

local-area network (LAN)

A system of computers and devices, such as printers and terminals, connected by cabling for the purpose of sharing data and devices.

locator value The value stored in the rs_locater table of the Replication Server’s RSSD that identifies the latest log transaction record received and acknowledged by the Replication Server from each previous site during replication.

622

logical connection A database connection that Replication Server maps to the connections for the active and standby databases in a warm standby application. See also connection and warm standby application.

login name The name that a user or a system component such as Replication Server uses to log in to a data server, Replication Server, or Replication Agent.

Log Transfer Language (LTL)

A subset of the Replication Command Language (RCL). A Replication Agent such as RepAgent or LTM for SQL Server uses LTL commands to submit to Replication Server the information it retrieves from primary database transaction logs.

Log Transfer Manager (LTM)

The Replication Agent program for Sybase SQL Server. See also replication agent and RepAgent thread.

maintenance user A data server login name that Replication Server uses to maintain replicate data. In most applications, maintenance user transactions are not replicated.

materialization The process of copying data specified by a subscription from a primary database to a replicate database, thereby initializing the replicate table. Replicate data can be transferred over a network, or, for subscriptions involving large amounts of data, loaded initially from media. See also atomic materialization, bulk materialization, no materialization, and nonatomic materialization.

materialization queue

A stable queue used to spool messages related to a subscription being materialized or dematerialized.

missing row A row missing from a replicated copy of a table but present in the primary table.

mixed-version system

A replication system containing Replication Servers of different software versions that have different capabilities based on their different software versions and site versions. Mixed-version support is available only if the system version is 11.0.2 or greater.

For example, a replication system containing Replication Servers version 11.5 or later and version 11.0.2 is a mixed-version system. A replication system containing Replication Servers of releases earlier than release 11.0.2 is not a mixed-version system, because any newer Replication Servers are restricted by the system version from using certain new features. See also site version and system version.

name space The scope within which an object name must be unique.

Glossary

623

nonatomic materialization

A materialization method that copies subscription data from a primary to a replicate database through the network in a single operation, without a holdlock. Changes to the primary table are allowed during data transfer, which may cause temporary inconsistencies between replicate and primary databases. Data is applied in increments of ten rows per transaction, which ensures that the replicate database transaction log does not fill. Nonatomic materialization is an optional method for the create subscription command. See also autocorrection, atomic materialization, no materialization, and bulk materialization.

network-based security

Secure transmission of data across a network. Replication Server supports third-party security mechanisms that provide user authentication, unified login, and secure message transmission between Replication Servers.

no materialization A materialization method that lets you create a subscription when the subscription data already exists at the replicate site. Use the create subscription command with the without materialization clause. You can use this method to create subscriptions to table replication definitions and function replication definitions. See also atomic materialization and bulk materialization.

online transaction processing (OLTP) application

A database client application characterized by frequent transactions involving data modification (inserts, deletes, and updates).

Origin Queue ID (qid)

Formed by the RepAgent, the qid uniquely identifies each log record passed to the Replication Server. It includes the date and timestamp and the database generation number. See also database generation number.

orphaned row A row in a replicated copy of a table that does not match an active subscription.

outbound queue A stable queue used to spool messages. The DSI outbound queue spools messages to a replicate database. The RSI outbound queue spools messages to a replicate Replication Server.

parallel DSI Configuring a database connection so that transactions are applied to a replicate data server using multiple DSI threads operating in parallel, rather than a single DSI thread. See also connection and Data Server Interface (DSI).

parameter An identifier representing a value that is provided when a procedure executes. Parameter names are prefixed with an @ character in function strings. When a procedure is called from a function string, Replication Server passes the parameter values, unaltered, to the data server. See also searchable parameter.

parent class A function-string class from which a derived class inherits function strings. See also function-string class and derived class.

624

partition A raw disk partition or operating system file that Replication Server uses for stable queue storage. Only use operating system files in a test environment.

physical connection See connection.

primary data The definitive version of a set of data in a replication system. The primary data is maintained on a data server that is known to all of the Replication Servers with subscriptions for the data.

primary database Any database that contains data that is replicated to another database via the replication system.

primary fragment A horizontal segment of a table that holds the primary version of a set of rows.

primary key A set of table columns that uniquely identifies each row.

primary site A Replication Server where a function-string class or error class is defined. See error class and function-string class.

principal user The user who starts an application. When using network-based security, Replication Server logs in to remote servers as the principal user.

projection A vertical slice of a table, representing a subset of the table’s columns.

publication A group of articles from the same primary database. A publication lets you collect replication definitions for related tables and/or stored procedures and then subscribe to them as a group. You collect replication definitions as articles in a publication at the source Replication Server and subscribe to them with a publication subscription at the destination Replication Server. See also article and publication subscription.

publication subscription

A subscription to a publication. See also article and publication.

published datatype The datatype of the column after the column-level translation (and before a class-level translation, if any) at the replicate data server. The published datatype must be either a Replication Server base datatype or a UDD for the datatype in the target data server. If the published datatype is omitted from the replication definition, it defaults to the declared datatype

query In a database management system, a query is a request to retrieve data that meets a given set of criteria. The SQL database language includes the select command for queries.

quiescent A quiescent replication system is one in which all updates have been propagated to their destinations. Some Replication Server commands or procedures require that you first quiesce the replication system.

Glossary

625

remote procedure call (RPC)

A request to execute a procedure that resides in a remote server. The server that executes the procedure could be a Adaptive Server, a Replication Server, or a server created using Open Server. The request can originate from any of these servers or from a client application. The RPC request format is a part of the Sybase Client/Server Interfaces.

RepAgent thread The replication agent for Adaptive Server databases. RepAgent is an Adaptive Server thread; it transfers transaction log information from the primary database to a Replication Server for distribution to other databases.

replicate database Any database that contains data that is replicated from another database via the replication system.

replicated function delivery

A method of replicating, from a source to a destination database, a stored procedure that is associated with a function replication definition. See also applied function, request function, and function replication definition.

replicated stored procedure

An Adaptive Server stored procedure that is marked as replicated using the sp_setrepproc or the sp_setreplicate system procedure. Replicated stored procedures can be associated with function replication definitions or table replication definitions. See also replicated function delivery and asynchronous procedure delivery.

replicated table A table that is maintained by Replication Server, in part or in whole, in databases at multiple locations. There is one primary version of the table, which is marked as replicated using the sp_setreptable or the sp_setreplicate system procedure; all other versions are replicated copies.

replication agent A program or module that transfers transaction log information representing modifications made to primary data from a database server to a Replication Server for distribution to other databases. RepAgent is the replication agent for Adaptive Server databases. LTM (Log Transfer Manager) is the replication agent for SQL Server databases.

Replication Command Language (RCL)

The commands used to manage information in Replication Server.

replication definition Usually, a description of a table for which subscriptions can be created. The replication definition, maintained by Replication Server, includes information about the columns to be replicated and the location of the primary version of the table.

You can also create function replication definitions; sometimes the term “table replication definition” is used to distinguish between table and function replication definitions. See also function replication definition.

626

Replication Server The Sybase server program that maintains replicated data, typically on a LAN, and processes data transactions received from other Replication Servers on the same LAN or on a WAN.

Replication Server Interface (RSI)

A thread that logs in to a destination Replication Server and transfers commands from the RSI outbound stable queue to the destination Replication Server. There is one RSI thread for each destination Replication Server that is a recipient of commands from a primary or intermediate Replication Server. See also outbound queue and route.

Replication Server Manager (RSM)

An application for managing and monitoring a replication system and its components. Includes status and monitoring functions, diagnostics and troubleshooting functions, asynchronous notification of user-defined events, and operational control over many aspects of the system.

Replication System Administrator

The System Administrator that manages routine operations in the Replication Server.

Replication Server System Database (RSSD)

The Adaptive Server database containing a Replication Server’s system tables.

Replication Server system Adaptive Server

The Adaptive Server with the database containing a Replication Server’s system tables (the RSSD).

replication system A data processing system where data is replicated in multiple databases to provide remote users with the benefits of local data access. Specifically, a replication system that is based upon Replication Server and includes other components such as Replication Agents and data servers.

replication system domain

All replication system components that use the same ID Server.

request function A replicated function, associated with a function replication definition, that Replication Server delivers from a replicate database to a primary database. The function passes parameter values to a stored procedure that is executed at the primary database. See also replicated function delivery, request function, and function replication definition.

route A one-way message stream from a source Replication Server to a destination Replication Server. Routes carry data modification commands (including those for RSSDs) and replicated functions or stored procedures between Replication Servers. See also direct route and indirect route.

Glossary

627

route version The lower of the site version numbers of the route’s source and destination Replication Servers. Replication Server version 11.5 and later use the route version number to determine which data to send to the replicate site. See also site version.

row migration The process whereby column value changes in rows in a primary version of a table cause corresponding rows in a replicate version of the table to be inserted or deleted, based on comparison with values in a subscription’s where clause.

SQL Server The Sybase relational database pre-11.5 server.

schema The structure of the database. DDL commands and system procedures change system tables stored in the database. Supported DDL commands and system procedures can be replicated to standby databases when you use Replication Server version 11.5 or later and Adaptive Server version 11.5 or later.

searchable column A column in a replicated table that can be specified in the where clause of a subscription or article to restrict the rows replicated at a site.

searchable parameter

A parameter in a replicated stored procedure that can be specified in the where clause of a subscription to help determine whether or not the stored procedure should be replicated. See also parameter.

secondary truncation point

See truncation point.

site An installation consisting of, at minimum, a Replication Server, data server, and database, and possibly a Replication Agent, usually at a discrete geographic location. The components at each site are connected over a WAN to those at other sites in a replication system. See also primary site.

site version The version number for an individual Replication Server. Once the site version has been set to a particular level, the Replication Server enables features specific to that level, and downgrades are not allowed. See also software version, route version, and system version.

software version The version number of the software release for an individual Replication Server. See also site version and system version.

Stable Queue Manager (SQM)

A thread that manages the stable queues. There is one Stable Queue Manager (SQM) thread for each stable queue accessed by the Replication Server, whether inbound or outbound.

628

Stable Queue Transaction (SQT) interface

A thread that reassembles transaction commands in commit order. A Stable Queue Transaction (SQT) interface thread reads from inbound stable queues, puts transactions in commit order, then sends them to the Distributor (DIST) thread or a DSI thread, depending on which thread required the SQT ordering of the transaction.

stable queues Store-and-forward queues where Replication Server stores messages destined for a route or database connection. Messages written into a stable queue remain there until they can be delivered to the destination Replication Server or database. Replication Server builds stable queues using its disk partitions. See also inbound queue, outbound queue, and materialization queue.

standalone mode A special Replication Server mode used for initiating recovery operations.

standby database In a warm standby application, a database that receives data modifications from the active database and serves as a backup of that database. See also warm standby application.

stored procedure A collection of SQL statements and optional control-of-flow statements stored under a name in a Adaptive Server database. Stored procedures supplied with Adaptive Server are called system procedures. Some stored procedures for querying the RSSD are included with the Replication Server software.

subscription A request for Replication Server to maintain a replicated copy of a table, or a set of rows from a table, in a replicate database at a specified location. You can also subscribe to a function replication definition, for replicating stored procedures.

subscription dematerialization

See dematerialization.

subscription materialization

See materialization.

subscription migration

See row migration.

Sybase Central A graphical tool that provides a common interface for managing Sybase and Powersoft products. Replication Server uses Replication Server Manager as a Sybase Central plug-in. See also Replication Server Manager (RSM).

synchronous command

A command that a client considers complete only after the completion status is received.

Glossary

629

system function A function that is predefined and part of the Replication Server product. Different system functions coordinate replication activities, such as rs_begin, or perform data manipulation operations, such as rs_insert, rs_delete, and rs_update.

system-provided classes

Replication Server provides the error class rs_sqlserver_error_class and the function-string classes rs_sqlserver_function_class, rs_default_function_class, and rs_db2_function_class. Function strings are generated automatically for the system-provided function-string classes and for any derived classes that inherit from these classes, directly or indirectly. See also error class and function-string class.

system version The version number for a replication system that represents the version for which new features are enabled, for Replication Servers of release 11.0.2 or earlier, and below which no Replication Server can be downgraded or installed. For a Replication Server version 11.5, your use of certain new features requires a site version of 1150 and a system version of at least 1102. See also mixed-version system, site version, and software version.

table replication definition

See replication definition.

table subscription A subscription to a table replication definition.

thread A process running within Replication Server. Built upon Sybase Open Server, Replication Server has a multi-threaded architecture. Each thread performs a certain function such as managing a user session, receiving messages from a Replication Agent or another Replication Server, or applying messages to a database. See also Data Server Interface (DSI), Distributor, and Replication Server Interface (RSI).

transaction A mechanism for grouping statements so that they are treated as a unit: either all statements in the group are executed or no statements in the group are executed.

Transact-SQL The relational database language used with Adaptive Server. It is based on standard SQL (Structured Query Language), with Sybase extensions.

truncation point An Adaptive Server database that holds primary data has an active truncation point, marking the transaction log location where Adaptive Server has completed processing. This is the primary truncation point.

630

The RepAgent for an Adaptive Server database maintains a secondary truncation point, marking the transaction log location separating the portion of the log successfully submitted to the Replication Server from the portion not yet submitted. The secondary truncation point ensures that each operation enters the replication system before its portion of the log is truncated.

user-defined function

A function that allows you to create custom applications that use Replication Server to distribute replicated functions or asynchronous stored procedures between sites in a replication system. In replicated function delivery, a user-defined function is automatically created by Replication Server when you create a function replication definition.

variable See function-string variable.

version See mixed-version system, site version, software version, and system version.

warm standby application

An application that employs Replication Server to maintain a standby database for a database known as the active database. If the active database fails, Replication Server and client applications can switch to the standby database.

wide-area network (WAN)

A system of local-area networks (LANs) connected together with data communication lines.

Index

631

Aabort switch command 445, 446Accounts. See Login names xxvactivate subscription command 327, 351, 355

for publications 351publication subscription example 355with suspension at replicate only clause 472with suspension clause 472

Active databaseSee also Warm standby applications xxv

active database 415managing old active after switching 447restarting clients on new active after switching

446Adaptive Server xxv

See also SQL Server xxvdescribed 28error handling 508login name for Replication Server access 171

Data serverSee also Primary data server xxv

Adaptive Server to DB2 datatypes 606Adaptive Server to Informix datatypes 608Adaptive Server to Oracle Adaptive Server to Oracle

612add partition command 46Adding

ID server domains 90primary keys 264Replication Servers to existing systems 89RSSD LTM 128, 599searchable columns to the searchable columns list

266admin commands described 366admin log_name command 502admin logical_status command 444, 449admin security_property command 210admin security_setting command 211admin set_log_name command 362, 502, 591

admin show_connections command 166admin show_route_versions command 140admin sqm_readers command 450admin translate command 292admin who command 324, 590admin who, dsi command 449admin who, sqm command 450

finding current save interval 523admin who_is_down command 363Alarm daemon (dAlarm) 482allow connections command 562alter connection command 146, 152, 200, 212, 286

assigning databases to function-string classes 390changing maintenance user password 171disabling password encryption 176

alter function command 580alter function replication definition command 221,

261, 297, 306alter function string command 400

mapping user-defined function to a different stored procedure name 581

replacing default function string 571alter logical connection command 453alter replication definition command 287alter route command 94, 112

changing passwords 171disabling password encryption 176

Alter table supportfor warm standby 465

alter user commandchanging passwords 174disabling password encryption 176

Altering. See Changing xxvapplication models

consolidated replicate 12redistributed corporate rollup 14replicated consolidated replicate 14

Applied functionsdescribed 298prerequisites for implementing 294

Index

632

setting up 299Request stored procedures xxvApplied stored procedures xxv, 568

See also Replicated stored procedures xxvprerequisites for implementing 570setting up 571

Article subscriptions, creating 352Articles

adding to publication 279definition 271displaying information about 278dropping 280

assign action command 508Asynchronous I/O daemon (dAIO) 482Asynchronous stored procedures

adding parameters 580applied stored procedures 568executing 567request stored procedures 569specifying a non-unique user-defined function name

583user-defined functions 579

Atomic materializationcreate subscription command 330described 310, 311example 313text and image columns 342in warm standby applications 471

Autocorrectionbulk materialization 319enabling for nonatomic materialization 314, 325

BBackups. See DumpsBars

displaying 63hiding 63

Batch commands in function strings 405batch configuration parameter 154batch_begin configuration parameter 154batch_sz LTM configuration parameter 588bcp utility program 433

logged 472Binaries. See Replication Server programs xxv

Bitmap subscriptions 344Bulk materialization xxv

autocorrection 319define subscription command 333described 311, 315methods 316publication subscriptions 354refreshing publication subscriptions 356for replicated functions 305simulating atomic materialization 318simulating nonatomic materialization 319stopping primary updates and taking snapshot 316in warm standby applications 472

Nonatomic materialization xxvButtons

tab 67toolbar 63

CC/SI. See Client/Server Interfaces xxvCase, in RCL commands xxiiChanging

database connections 150existing replication system 89, 92function strings 375ID Server login name and password 170replication definitions 256Replication Server login names for the RSSD LTM

595Replication Server login names for the RSSD

RepAgent 169routes 136RSSD primary or maintenance user 169searchable columns 270user passwords 174

Character setsconversion 154

check publication command 274, 277check subscription command 327, 335, 351

after executing switch active command 472example 358for articles 351for publication subscriptions and articles 358for publications 351

Index

633

Class-level translations 284existing connections 286new connections 284system-defined variables 286with column-level translations 292

Client applicationdescribed 31restarting after active switch 446

Client/Server Interfaces (C/SI)client applications 31

cm_max_connections configuration parameter 484Column-level translations 287

creating 287multiple replication definitions 291

columnschanging in replicated tables 265, 270deleting from primary or replicate table 269IDENTITY 255rs_address datatype 344specifying for replication definition 225

command_retry configuration parameter 154Commands

batch for function strings 405See also RCL commands xxv

Transact-SQL commands xxvConcurrency control

described 47Configuration file 89

LTM 592, 594Replication Server 89rs_subcmp program 348

Configuration parameterschanging 99for replication server 92rs_config system table 484, 486viewing 105

configuration star 120Configuration variables. See Configuration parameters

xxvconfigure connection command

setting save interval 525configure logical connection command 463

setting DSI queue save interval 463setting materialization queue save interval 464

configure replication server command 93, 94, 191, 196, 203

configure route commandsetting save interval 524

Configuring 193connect source permission 177Connecting to Replication Server

using network-based security 205, 207Connection manager daemon (dCM) 482Connections

defined 39network-based security for 199setting save interval 525

ConsistencySee also Inconsistencies xxvmaintaining for replicate databases 526verifying for subscriptions 347

Consolidated replicate application model 12context-sensitive menus

shortcut 63conventions

document style xxexamples xxicons xxivsyntax statements xxi

Coordinated dumpscreating 526loading primary and replicate databases 536recovering databases 536

create article command 274example 275

create connection command 146, 148, 390create error class command 505create function command 579create function replication definition command 297,

300create function string class command 386, 388create function string command 322, 398create logical connection command 430create object permission 177create publication command 273, 274

example 274create replication definition command 220, 223, 287create route command 125create subscription command 327, 351, 353

and atomic materialization 331example for publications 353for publications 276, 351

Index

634

and nonatomic materialization 332create user command 174

adding Replication Server login name for RSSD LTM 595

adding Replication Server login name for RSSD RepAgent 169

Creatingdatabase connections 147function replication definitions 300, 304function strings 398function-string classes 386multiple ID Server domains 91replicate tables 338replication definitions 213, 221Replication Server login names 174subscriptions 172, 324user-defined functions 579

current_rssd_version configuration parameter 93

DDaemons

alarm (dAlarm) 482asynchronous I/O (dAIO) 482connection manager (dCM) 482described 477recovery (dREC) 482subscription retry (dSUB) 482version (dVERSION) 483

dAIO. See Asynchronous I/O daemon xxvdAlarm. See Alarm daemon xxvData availability

fault tolerance 3local access 2

Data serverSee also Primary data server xxvand C/SI support 17error handling 504, 509ID numbers 91log truncation 588maintenance user login names 21support for heterogeneous 16, 29suspending access to 151

Data Server Interface. See DSI threads xxvDatabase Administrator, role of 22

Database connectionsattributes 147changing attributes of 150configuring for parallel DSI 487creating 147displaying 165dropping 164information for 148managing 143, 160monitoring 165resuming 151suspending 151for warm standby applications 416

Database generation numbersadjusting during database recovery 565and dumps 566qid 565

Database logsdetermining for reload 564recovering messages off-line 530recovering messages online 532reloading 566truncated primary recovery 532, 535truncation 49

Database schemareplication definitions 261

Databasesactive 416assigning function-string classes 390customizing operations 371, 408failures 536logical 416managed by Replication Server 166preparing for replication 143, 593See also Primary databases xxvsetting log recovery 562standby 416

Replicate databases xxvDatatype classes

rs_db2_dt_class 287rs_informix_dt_class 287rs_msss_dt_class 287rs_oracle_dt_class 287rs_sqlserver_dt_class 287

Datatype definitions 289for DB2 datatypes 290

Index

635

for Informix datatypes 291for Microsoft SQL Server datatypes 290for Oracle datatypes 291

datatype translation mapping in HDS 605datatypes

See also individual datatypes xxvAdaptive Server to DB2 606Adaptive Server to Informix 608DB2 to Adaptive Server 606DB2 to Informix 606DB2 to Microsoft SQL Server 607DB2 to Oracle 607IDENTITY columns 255Informix to Adaptive Server 608Informix to DB2 608Informix to Microsoft SQL Server 609Informix to Oracle 609Microsoft SQL Server to DB2 610Microsoft SQL Server to Informix 611Microsoft SQL Server to Oracle 611Oracle to Adaptive Server 612Oracle to DB2 613Oracle to Informix 613Oracle to Microsoft SQL Server 613rs_address 255, 344text and image 422

db_packet_size configuration parameter 154DB2 databases, function-string class 18, 372DB2 to Adaptive Server datatypes 606DB2 to Informix datatypes 606DB2 to Microsoft SQL Server datatypes 607DB2 to Oracle datatypes 607db2_function_class

described 381DBA. See Database Administrator xxvdbcc settrunc Transact-SQL command 532dCM. See Connection manager daemon xxvdeadlock detection, parallel dsi 491Declared datatypes 288Default function strings, restoring 403define subscription command 327, 351, 354

and bulk materialization 333creating publication subscriptions 354for publications 351publications subscription example 354using with replicated functions 302

DeletingSee also Dropping xxvtransactions in the exceptions log 514

Dematerialization. See Subscription dematerialization xxv

Derived function-string classdescribed 385

dialog boxesobject 66refreshing 65tabs 67

Direct routes 120Directory services 594Display

synchronizing windows 65updating 65

Displayingassigned actions for error numbers 509bars 63database connections 165databases with subscriptions to replication

definitions 347DSI thread status 166error class information 507function-related information 407icons 63replication definitions 261RSI thread status 141subscription information 347transactions in the exceptions log 512users of replication system 182users’ permissions 183

DIST thread. See Distributor thread xxvdistributed data models 9

corporate rollup 9distributed primary fragments 9redistributed corporate rollup 9

distributed database systemand replication server 3

Distributed primary fragmentsconsolidated replicate application model 14

Distributor thread (DIST)described 480disabling 453

Domain. See ID Server xxvdREC. See Recovery daemon xxv

Index

636

drop article command 274, 280example 280, 281

drop connection command 112, 164, 447drop error class command 506drop function command 580drop function replication definition command 297, 307drop function string class command 391drop function string command 402drop logical connection command 456drop publication command 274, 279

example 280drop replication definition command 221, 267drop route command 112, 113drop subscription command 111, 327, 351, 356

example 357for articles 352for publications 351function replication definitions 336table replication definitions 336

drop user commanddropping login names 175

drop_repdef clause 280, 281Dropping

See also Deleting xxvdatabase connections 164databases from the ID Server 165function replication definitions 307function string class 391function strings 402logical database connections 456logical databases from the ID Server 456primary keys 264replication definitions 267Replication Server login names 175Replication Servers from existing system 110, 115routes 138searchable columns from the searchable columns list

263, 270subscriptions 172user-defined functions 580

DSI threadsdescribed 45, 481detecting duplicate transactions 514detecting losses 560displaying 166executor 481, 489

handling losses 561parallel 486, 496scheduler 45, 481, 488for standby database 441suspending to load bulk materialization data 472

dsi_charset_convert configuration parameter 154dsi_cmd_batch_size configuration parameter 154dsi_cmd_separator configuration parameter 155dsi_fadeout_time configuration parameter 155dsi_keep_triggers configuration parameter 155dsi_large_xact_size configuration parameter 155, 487dsi_max_cmds_to_log configuration parameter 155dsi_max_text_to_log configuration parameter 155dsi_num_large_xact_threads configuration parameter

155, 487dsi_num_threads configuration parameter 155, 487dsi_replication configuration parameter 156dsi_serialization_method configuration parameter

156, 487dsi_sql_data_style configuration parameter 157dsi_sqt_max_cache_size configuration parameter 157,

487dsi_xact_group_size configuration parameter 157dSUB. See Subscription retry daemon xxvdump database command 438, 527Dump marker option

for rs_init program 434, 448dump transaction command 438, 527dump_load configuration parameter 157Dumps

creating 526database generation numbers 566determining for reload 564initializing warm standby databases 433, 438transaction timestamp 564

EEmpty function strings, creating 404Enable replication marker 433Encryption

disabling for Replication Server 176, 596enabling for Replication Server 175, 596

Error classeschanging primary Replication Server 506

Index

637

creating 505dropping 506initializing 505Open Server gateway 17rs_sqlserver_error_class 505

Error handlingassigning actions 508data server 504, 509general 499LTM 602Replication Server 500, 602system transactions 515

Error log files xxvbeginning a new Replication Server log file 502described 500displaying current log file name 502LTM 503, 591Replication Server 362, 500

Error messages xxvformat 501Replication Server login name 365severity levels 501system transactions 516

Errorlogslog file for LTM 591

Error messages xxvErrors

log file for Replication Server 362See also Error handling xxvstandard error output 362, 591

Examplesassigning domain ID numbers 91atomic materialization 313DSI loss detection 560replication definition 223routing 127rs_subcmp configuration file 348SQM loss detection 560style conventions xxwarm standby application 440

Exceptions logaccessing 511deleting transactions 514displaying transactions 512exceptions handling 509transactions written to 48

Executable programs. See Replication Server programs xxv

ExecutingRCL commands 84scripts with isql 86

FFailed transactions

handling 510, 514process for resolving 510

Failover, support for in Replication Server 518Failure

data server 499network 499

Fault tolerance, achieving 2File menu 63Files

See also Error log files xxvinterfaces 38, 594LTM configuration 594LTM error log 591Replication Server configuration 89Replication Server error log 362Replication Server run file 87RSM.Servers 171standard error output 362, 591

for new articles clause 354Formatting, RCL commands xxiifstr_cachesize configuration parameter 484function replication definitions

commands for managing 296sending parameters to standby database 468subscribing to 305

Function scope, described 374Function strings

changing 375changing replication definitions 262creating 398creating empty 404defined 41defining multiple commands 405described 378dropping 402examples 400

Index

638

generated for standby databases 419input templates 392managing 391, 406none 411output templates 392remapping table and column names 405restoring default 403restoring defaults with output template 403updating 400variables 42, 397writetext 411

Functionsdescribed 373See also System functions xxv

User-defined functions xxvFunction-string classes 284

assigning to databases 390changing the primary Replication Server 389creating 386defined 42described 380dropping 391for Adaptive Server databases 18for DB2 databases 18, 372managing 385, 389open architecture 17rs_default_function_class 419rs_informix_function_class 284rs_msss_function_class 285rs_oracle_function_class 285rs_sqlserver_function_class 284

Function-string inheritance 385

GGeneration numbers. See Database generation numbers

xxvgrant command 145, 176, 181, 440graphic icons xxiv

Hha_failover configuration parameter 96, 108, 157, 521HDS, datatype translation mapping 605

HDS. See Heterogeneous datatype support 281Help

menu 63toolbar buttons 64

Heterogeneous datatype support 281–292class-level translations 284column-level translations 287data servers 281function-string classes for 284overview 282procedure for 283

Hidingbars 63icons 63

Iicons xxiv

displaying 63hiding 63object 59

ID numbersdata servers 91Replication Server 91

ID Server xxv, 89adding server domains 90dropping a database from 165dropping a logical database from 456guidelines 91ID numbers 92login name 28login name and password 170network-based security for 203requirements 27specifying domain ID numbers 91

id_msg_confidentiality parameter 203id_security_mechanism parameter 203id_server configuration parameter 93Identifiers

case sensitivity xxiiiignore loss command

handling losses 561ignoring SQM and DSI losses 562ignoring SQM loss after setting log recovery 563and warm standby applications 475

Index

639

image datatypechanging replication for 251LTM shutdown and 251overview of replication 246

Inbound queuedefined 44displaying reader threads 450multiple reader threads 454

Inconsistenciescorrecting 348locating 348occurring in tables 347resulting from skip transaction clause 160

Indirect routes 120Informational messages xxv

format 501Informix to Adaptive Server datatypes 608Informix to DB2 datatypes 608Informix to Microsoft SQL Server datatypes 609Informix to Oracle datatypes 609init_sqm_write_delay configuration parameter 484init_sqm_write_max_delay configuration parameter

484Input templates, example 396Installation procedure. See Installation Guide xxvInterfaces file 38, 594

checking for accuracy 364defined 38modifying for warm standby application 451network-based security 189requirements 38, 593, 594

Intermediate routes. See Indirect routes xxvisolation_level_3

transaction serialization method 490isql interactive SQL utility 85

executing RCL commands 84executing scripts 86verifying server status 365

Issuing. See Executing xxv

KKeytab file 205Key-table file 192

LLanguage

function string output templates 393libtcl.cfg file 187load database command 438load transaction command 438Loading

primary database from dumps 537Log recovery

detecting losses 563setting for databases 562

Log transfersuspending 106

Log Transfer Language (LTL) 29Log Transfer Manager. See LTM xxvLog truncation, Adaptive Server 49Logical connection

See also Warm standby applications xxvconfiguring materialization queue save interval

463configuring save interval 463creating 429

Logical database connectionsdropping 456

Logical view in Sybase Central 75Login names

See also Maintenance user xxvapplied functions 173applied stored procedures 173creating for maintenance user 145creating for Replication Server 174data server 20dependencies 168, 173displaying maintenance user 146dropping Replication Server 175for SQL Server use 596ID Server 28, 170list of commands for managing 173for LTM users 596Replication Server 20Replication Server for RSSD LTM use 595Replication Server for RSSD RepAgent use 169for Replication Server use 171request functions 173request stored procedures 173RSM.Servers file 171

Index

640

RSSD maintenance user 168RSSD primary user 168for subscriptions 172, 326

Logins. See Login names xxvLoss detection

after setting log recovery 563checking messages 560DSI loss 558, 560handling losses 561preventing false losses in stable queue 559rebuilding stable queues 558SQM loss 558with warm standby applications 474

LTMadding for RSSD 599checking for errors 591configuration file 594data flow 587described 29, 585error handling 602error log file 601errors from SQL Server 603login name and password 596login names to access SQL Server 596normalization errors and 603origin queue ID (qid) 565replicate databases 592requirements 592resuming 598for RSSD 595shutting down 591starting 590suspending 597transaction timestamp 564truncation point 588

LTM command 590LTM truncation point

described 588, 589

MMaintenance user

changing passwords 171described 171displaying list of 146

granting database access 146login names 21, 145required permissions 145RSSD 169for standby database 439

Mapping security-system login 211master database

and warm standby applications 419materialization methods

for function replication definitions 353for publication subscriptions 353

Materialization queue save intervalsetting for logical connections 463strict setting 463

Materialization. See Subscription materialization xxvmaterialization_save_interval configuration parameter

for logical connections 453MD. See Message Delivery module xxvmd_source_memory_pool configuration parameter

158memory_limit configuration parameter 485memory_max configuration parameter 159menus

shortcut 63standard 62

menus and toolbars 62Message Delivery module (MD) 481Informational messages xxvMessages

handling loss in stable queues 561recovering from off-line database logs 530recovering from online database logs 532See also Error messages xxvSQM loss detection 563

Microsoft SQL Server to DB2 datatypes 610Microsoft SQL Server to Informix datatypes 611Microsoft SQL Server to Oracle datatypes 611minimal columns

specifying for replication 222, 230minimum_rssd_version configuration parameter 93Mixed versions

replication system 18Modifiers

in function string variables 397Modifying. See Changing xxvModules

Index

641

described 477Message Delivery 481Transaction Delivery 480

Monitoringdatabase connections 165errors 362, 591partition percentages 368Replication Server 364routes 141

move primary command 111, 389, 506routing requirements 119

msg_confidentiality parameter 195msg_integrity 196msg_origin_check 196msg_replay_detection 196msg_sequence_check 196Multiple replication definitions

and function strings 379column-level translations 291

mutual_auth 196

NName space, replication definition 223Naming replicated tables 268Network-based security 183–212, 594

activiating 191altering 209configuring services 193credential 184disabling 208environment variables for 189global settings 197how it works 184logging in 205mapping login 211message protection 185parameters 195pathways 193, 194planning for 196potential security breech 212requirements 186restrictions 186setting up 186using multiple security mechanisms 211

viewing information about 210network-based security

requirements and restrictions 185No materialization method

described 311describing 314requirements for using 314

Nonatomic materialization xxvautocorrection 325described 311, 313text and image columns 342in warm standby applications 472

Nonetransaction serialization method 491

none function string output templates 411Normalization errors

LTM and 603num_client_connections configuration parameter 485num_concurrent_subs configuration parameter 485num_msgqueues configuration parameter 485num_msgs configuration parameter 485num_mutexes configuration parameter 485num_stable_queues configuration parameter 485num_threads configuration parameter 159, 485

OObject icons 59objectid.dat file 187, 188Objects

dialog boxes 66online database command 438online help 54Open Client Client-Library 84Open Server gateway

creating for Replication Server 17Oracle to Adaptive Server datatypes 612Oracle to DB2 datatypes 613Oracle to Informix datatypes 613Oracle to Microsoft SQL Server datatypes 613Origin queue ID (qid) 564

determining database generation numbers 565oserver configuration parameter 93Outbound queue, defined 44output templates

Index

642

creating empty function strings 404language 393none 411restoring default function strings 403rpc 394writetext 411

PParallel DSI

described 486, 496parallel_dsi configuration parameter 158, 487Parameters

RepAgent configuration 89, 99Parameters, configuration

See Configuration parameters xxvParameters, stored procedure

adding to replicated functions 306adding to user-defined functions 580

Parent function-string class 385Partition failure

recovering 527, 532Partitions

See also Stable queues xxvguidelines for choosing 46monitoring percentages 368recovering from loss or failure 527, 532space requirements 525

Password encryptionreplication system 21

password_encryption configuration parameter 176password_encryption LTM configuration parameter 597Passwords

alter user command 174applied functions 173applied stored procedures 173changing 174changing for maintenance user 171changing for Replication Server in RSSD LTM 595changing for Replication Server in RSSD RepAgent

169changing for RSSD primary user 169dependencies 171, 173enabling encryption 175, 596encrypted 176

for LTM use 595for SQL Server use 596ID Server 170for LTM use 596for RepAgent use 170for Replication Server use 171request functions 173request stored procedures 173requirements for Replication Server 174RSM.Servers file 172subscriptions 172

Performancereplicating local data 2routing 123

Permissionscreating subscriptions 325displaying for users 183dropping subscriptions 336granting 181granting database access for maintenance user 146maintenance user 145managing for Replication Server 176, 183revoking 181subscription requirements 326summary of commands for 179system for 21

Warm standby applications xxvPhysical connections. See Database connections xxvPhysical view in Sybase Central 77prev_min_rssd_version configuration parameter 93prev_rssd_version configuration parameter 93Primary data 47

failure to update 48Primary data server xxv

subscription requirements 326Primary databases

See also Primary tables xxvloading from dumps 537LTM configuration file 594recovering from failure 536recovering truncated logs 532, 535required permissions 147subscription requirements 326upgrading from replicate only 599

Primary dumpsrecovering primary databases 536

Index

643

Primary keyadding or dropping 264defined 33, 222requirement for unique 215for tables in a warm standby database 467

primary key clause 228Primary key columns

restrictions on updating 215Primary Replication Server xxv

changing for an error class 506changing function-string class to another

Replication Server 389processing in 478, 483

primary subscribe permission 177Primary tables

subscription requirements 324upgrading Replication Server to manage 599

Primary userRSSD 168

Principal user 191Principal user principle 190Privileges. See Permissions xxvProcedures. See Stored procedures xxvRequest stored procedures xxvProcesses. See Threads xxvPrograms. See Replication Server programs xxvProperty sheets 66Publication subscriptions 349, 358

activating 355bulk materialization method 354creating 352defining 354definition 271dropping 356refreshing 353, 356restrictions 350specifying materialization methods 353status information 358validating 355

publication subscriptionsmonitoring 358

Publications 281adding articles 279altering 279creating at the command line 274definition 271

displaying information about 278dropping 279dropping replication defintions 280for stored procedures 308from Sybase Central 272isql script 272procedure for creating 271procedure for Sybase Central 272RCL commands for 273viewing information about 277

Published datatype 288

Qqid. See Origin queue ID xxvQueries

for exceptions log system tables 513queue_dump_buffer_size configuration parameter

486Queues. See Stable queues xxvquiescing

procedure for replication server 109Replication system 109

RRCL commands

abort switch 445, 446activate subscription 327admin log_name 502admin logical_status 444, 449admin set_log_name 362, 502admin show_connections 166admin sqm_readers 450admin who, dsi 449admin who, sqm 450, 523admin who_is_down 363allow connections 562alter connection 146, 152, 390alter function 580alter function replication definition 297alter function string 308, 400alter replication definition 221, 262assign action 508

Index

644

check subscription 327, 335configure connection 406, 455, 527create connection 148, 390create error class 505create function 579create function replication definition 297, 300, 304create function string 400create function string class 388create logical connection 430create replication definition 220, 223create route 125create subscription 327, 331, 332create user 595define subscription 327, 333drop connection 164, 447drop error class 506drop function replication definition 297, 307drop function string 402drop function string class 391drop replication definition 221drop route 138drop subscription 327, 336drop user 175executing 84formatting xxiigrant 181ignore loss 561, 564move primary 389, 506rebuild queues 555resume connection 160, 438, 511resume log transfer 598resume route 130revoke 181set autocorrection 325set log recovery 562shutdown 89suspend connection 151, 510suspend log transfer 106, 597suspend route 130sysadmin dropdb 165sysadmin dropldb 457sysadmin purge_route_at_replicate 139sysadmin restore_dsi_saved_segments 525table of permissions 179, 181validate subscription 327wait for create standby 438

wait for switch 445rebuild queues command 555rec_daemon_sleep_time configuration parameter 486Recovery

of messages from off-line database logs 530overview 540partition loss or failure 527, 532from primary database failures 536from RSSD failure 540, 554of RSSD from dumps 541setting save intervals 523support tasks 555, 566from truncated primary database logs 532, 535using procedures 517

Recovery daemon (dREC) 482Recovery mode

Replication Server 538, 556, 562Redistributed corporate rollup application model 14refreshing windows and dialog boxes 65Related documents xixRemote procedure calls. See RPCs xxvRepAgent 97

configuration parameters 99configuring 98described 29disabling 102enabling for databases 98enabling on Adaptive Sever 97error log messages 503error messages 103network-based security for 204parameters 89for RSSD 169secondary truncation point 49setting up 96starting 101status information 104stopping 102suspending 106thread status 105thread user status 105truncation point 49

RepAgent user thread 479Replicate data server xxvReplicate databases xxv

preventing data loss 523

Index

645

upgrading to primary databases 161, 599replicate minimal columns

and non-default function strings 410and rs_default_fs system variable 410

Replicate Replication xxvReplicate Replication Server xxv

processing in 483subscription requirements 326

Replicate tablesrequirements for subscriptions 325

replicated consolidated replicate application model 14

Replicated functionsadding parameters 306adding searchable parameters 306described 35, 297dropping 306modifying 306subscribing to 301

Replicated stored procedures xxvenabling for replication 305, 578login and password dependencies 173replicated function delivery 297

Replicated tables xxvchanging 267changing searchable columns 270commands required for modification 220dropping 268enabling for replication 239failed updates 48procedures for changing 268renaming primary and replicate copies 268requirements 33subscribing to 309

TablesSee also Primary tables xxv

Replicationconfiguring in standby databases 455

xxvReplication Agent

described 29open architecture 17requirements 31See also RepAgent xxv

Replication Command Language. See RCL commands xxv

Replication definitionsfor distributed primary fragments 9, 12changing 256commands for managing 220creating 221datatypes 225defined 33described 222dropping 267dropping from articles 281dropping from publications 280examples 223functions 297name space 223primary key 228required for warm standby 464requirements for creating subscriptions 324rs_address datatype 344searchable columns 229sending columns to standby database 468text or image columns 246using 221, 267

Replication Server xxvSee also ID Server xxvadding to an existing system 89, 592advantages 2checking for errors 362, 591configuration file 89, 199configuring rs_config system table 92connections 38described 1, 27distributed data models 9dropping from existing system 110, 115error log 448, 500executable program 88general description 1handling lost messages 561and heterogeneous data servers 16ID numbers 91informational messages 501internals 477, 484introduction 1list of databases managed by 166log recovery mode 562login name for Adaptive Server use 171login name for LTM use 595

Index

646

login name for RSSD use 171managing 81, 110managing login names 173monitoring 364partitions 368permissions 176, 182primary copy model 5processing in primary 478, 483processing in replicate 483quiescing 109rebuilding stable queues 555recovery mode 538, 556, 562role in a distributed database system 3run file for 87security 183shutting down 89standalone mode 530, 555standard errors 362, 591starting 87subscription requirements 326system data flow 7, 586technical overview 25, 47transaction handling 43upgrading to manage primary tables 599verifying a working system 362verifying status 365

Replication Server Interface. See RSI threads xxvReplication Server Manager. See RSM xxvReplication Server programs xxv

ltm 590repserver 88rs_init 89, 592rs_subcmp 348, 561

Transact-SQL commands xxvReplication Server System Database

managing 107Replication Server System Database (RSSD)

See also System tables xxvdescribed 30login names 168LTM for 592maintaining 92recovering from failure 540RepAgent for 169requirements 31rs_helpdb stored procedure 166

rs_maintusers 183rs_users 183system tables 30updating database generation numbers 566users 168

Replication systemcomponents 25, 32creating multiple domains 91domains 90error log files 500open architecture 17preventing data loss 523quiescing 109roles and responsibilities 22, 24security 167setting up 81

Replication System Administratorrole of xvii, 22

Replication system domains. See ID Server xxvReplication system Server xxvrepserver command 88repsrvr command. See repserver command xxvRequest functions

defined 35described 298login names and passwords 173permissions needed at primary 147prerequisites for implementing 294setting up 302

Request stored procedures 569See also Replicated stored procedures xxvlogin names and passwords 173prerequisites for implementing 570primary copy model 6setting up 575

RequirementsReplication Server 25, 592

RestoringSee also Loading xxvdumps 526primary and replicate databases 536RSSD 541

Restrictionson replicated data 215warm standby applications 418

Index

647

resume connection command 160, 201, 320, 438, 511

resume log transfer command 106, 598resume route command 130Resuming

log transfer 107RepAgent 107routes 129

revoke command 176, 181Roll-up

Consolidated replicate application model 12Consolidated replicate as primary application

model 14Route version

between Replication Servers 140Routes

See also Routingchanging 130, 136creating 124creating login names 125defined 39determining 118direct 120dropping 138indirect 120managing 117, 138monitoring creation of 141network-based security for 201purging 114requirements 118resuming 129RSSD recovery 554setting save interval 523subscriptions 122suspending 129unsupported 123upgrading 140

RoutingSee also Routes xxvexamples 127overlapping subscriptions 122schemes 119

Row migrationtext and image columns 342

RPC function string output templates 394RS user thread 483

rs_address datatype 255rs_begin system function 376rs_check_repl system function 376rs_commit system function 376rs_config system table 94

configuration parameters 484, 486rs_databases system table 166rs_datarow_for_writetext system function 377rs_default_function_class 419

described 381rs_delete system function 377rs_delexception stored procedure 514rs_dumpdb system function 376, 527rs_dumptran system function 376, 527rs_exceptscmd system table 511rs_exceptshdr system table 511rs_get_charset system function 376rs_get_lastcommit system function 376rs_get_sortorder system function 376rs_get_textptr system function 377rs_get_thread_seq system function 376, 494rs_get_thread_seq_noholdlock system function 376,

494rs_helpclass stored procedure 408rs_helpdb stored procedure 111, 166rs_helperror stored procedure 509rs_helpexception stored procedure 512rs_helpfstring stored procedure 408rs_helpfunc stored procedure 408rs_helppub stored procedure 274, 278, 358rs_helprepdb stored procedure 347rs_helproute stored procedure 141rs_helpuser stored procedure 182rs_idnames system table

dropping database from 165dropping logical database from 457

rs_init program 93adding a standby database 437adding Replication Servers to existing system 592adding warm standby databases 431enabling password encryption 596preparing databases for replication 593

rs_init_erroractions stored procedure 505rs_initialize_threads system function 376, 494rs_insert system function 377rs_lastcommit system table 160

Index

648

permissions 146rs_maintusers system table 183rs_marker stored procedure 147rs_marker system function 376rs_mk_rsids_consistent stored procedure 547rs_repl_off system function 376rs_rollback system function 377rs_select system function 377

updating function strings 401rs_select_with_lock system function 377

updating function strings 401rs_set_isolation_level3 system function 377, 490rs_setproxy function string 208rs_sqlserver_error_class error class 505rs_sqlserver_function_class 389, 405

described 381rs_subcmp program 348, 473, 561rs_subscriptions system table 354rs_systext system table 511rs_textptr_init system function 377rs_threads system table 491rs_triggers_reset system function 377rs_trunc_reset system function 377rs_trunc_set system function 377rs_update system function 378rs_update_lastcommit stored procedure 147rs_update_threads system function 377, 494rs_usedb system function 377rs_users system table 183rs_writetext system function 378RSA. See Replication System Administrator xxvRSI threads

described 45, 482displaying 141

RSI user thread 484rsi_batch_size configuration parameter 126rsi_fadeout_time configuration parameter 126rsi_packet_size configuration parameter 127rsi_sync_interval configuration parameter 127RSM

login name and password dependencies 171monitoring errors 362Sybase Central plug-in 51verifying server status 365

RSM Client 53RSM Server 53

connecting to 71disconnecting from 73

RSM Server domain 53RSSD

network-based security for 199RSSD failure

recovering 540, 554RSSD. See Replication Server System Database xxvrssd_error_class configuration parameter 93Run file, Replication Server 87

Ssa permission xvii, 177, 179Save interval

described 523setting for connections 525setting for logical connections 463setting for routes 524strict setting 463, 471

save_interval configuration parameter 523for database connection 158for logical connection 453for route 127

scan_retry LTM configuration parameter 588Schema. See Database schema xxvscope, of functions 374Scripts

executing in isql 86replication definition examples 338verifying server status 365

Searchable columnsadding to the searchable columns list 266dropping from the searchable columns list 263,

270searchable columns clause 222Searchable parameters

adding to replicated functions 306Secondary truncation point

and disabling RepAgent 103described 49, 50

Securitynetwork-based 183Replication Server 167, 183replication system 20

Index

649

Security mechanismDCE 187

Security mechanismsCyberSafe Kerberos 186Transarc DCE 186

Security, network-based 173–212security_mechanism 196select with holdlock clause 353send standby clause

for columns 468for parameters 468

Server user’s IDfor warm standby databases 436

ServersSee also Data server xxvverifying operation 365

SQL Server xxvset autocorrection command 325set function string class clause 390set log recovery command 562set proxy command 190, 208set replication off Transact-SQL command 455set replication Transact-SQL command 427set triggers off Transact-SQL command 455Setting up network-based security 186Severity levels

data server errors 508error messages 501LTM 602Replication Server 508

shortcut menus 63shutdown RCL command 89Shutting down

LTM 591Replication Server 89

single_transaction_per_origintransaction serialization method 490

skip transaction clause 160, 511sp_config_rep_agent system procedure 204sp_reptostandby 439sp_reptostandby system procedure 422sp_role system procedure 145sp_setreplicate system procedure

marking rs_marker for replication 163marking stored procedures for replication 578

sp_setrepproc system procedure 300, 425

marking stored procedures for replication 305marking stored procedures in a warm standby active

database 439using for applied function 300using for request function 303

sp_setreptable system proceduremarking tables in a warm standby active database

439sp_stop_rep_agent command 102, 112SQL Server

See also Adaptive Server xxvlogin names for LTM access 596truncation point 588

SQM. See Stable Queue Manager thread xxvsqm_warning_thr_ind configuration parameter 486sqm_warning_thr1 configuration parameter 486sqm_warning_thr2 configuration parameter 486SQT. See Stable Queue Transaction thread xxvsqt_max_cache_size configuration parameter 486,

487SRE. See Subscription Resolution Engine xxvStable Queue Manager thread (SQM) 479

detecting loss during stable queue rebuild 559handling losses 561loss detection after log recovery 563

Stable Queue Transaction thread (SQT) 479Stable queues

See also Partitions xxvatomic materialization 312described 44detecting losses 558disk files 47DSI loss 558handling partition failure 525off-line rebuild from database logs 556online rebuild 556rebuilding 555requirements 46for routes 124

Standalone modeReplication Server 530, 555

Standard menus 62Standard toolbar 63Standby database 415

See also Warm standby applications xxvadding 433

Index

650

monitoring status of add 448switching to 440

Star configurationdescribed 120

StartingLTM 590replication server 87

Statusverifying data servers 365verifying RepAgents 365verifying Replication Servers 365

status bar 64Stored procedures

dropping 581marking for replication using sp_setreplicate 577marking for replication using sp_setrepproc 305publications 308rs_delexception 514rs_helpclass 408rs_helpdb 166rs_helperror 509rs_helpexception 512rs_helpfstring 408rs_helprep 261rs_helprepdb 347rs_helproute 141rs_helpsub 347rs_helpuser 182rs_init_erroractions 505rs_mk_rsids_consistent 547rs_update_lastcommit 147

sts_cachesize configuration parameter 486sub_daemon_sleep_time configuration parameter 486subcmp program. See rs_subcmp program xxvsubscribe to truncate table clause 352Subscribing

See also Subscriptions xxvto data in warm standby databases 469to function replication definitions 305to replicated tables 309

Subscriptionsprimary fragments 9, 12

Subscription dematerializationmethods 336phases 323processing 321

with purge 322Nonatomic materialization xxvSubscription materialization

defined 34methods 325phases 323See also Atomic materialization xxvtext and image columns 341

Subscription materialization queuedefined 44

Subscription migrationdescribed 480rs_address columns 346

Subscription Resolution Engine (SRE) 480Subscription retry daemon (dSUB) 482Subscriptions

adding to a publication subscriptions 354bitmap 344commands for managing 327comparing after restoring backups 544defined 309displaying 347dropping 172, 336login names and password dependencies 172overlapping 122permissions for creating 177preparations for creating 324re-creating after backups 551removing rows manually 337requirements 324restrictions in warm standby applications 470user permission requirements 178verifying consistency 347

Suspect subscriptions 472suspend connection command 151, 201, 510, 511suspend log transfer command 106, 597suspend route command 130Suspending

database connections 151log transfer 106LTMs 106routes 129

switch active commandduring atomic materialization 472during subscription dematerialization 473during subscription materialization 470

Index

651

Sybase Central 51, 84, 85creating an object in 65navigating in 57online help 54pop-up menus 63Replication Server views 75standard menus 62stopping 57using publications 272

syntax statementsconventions xxi

sysadmin dropdb command 113, 114, 165sysadmin dropldb command 457sysadmin droprs command 112sysadmin purge_route_at_replicate command 139sysadmin restore_dsi_saved_segments command

525System functions

rs_dumpdb 526rs_dumptran 527

System functions, list ofwith function-string class scope 375with replication definition scope 377

Request stored procedures xxvSystem procedures xxv

sp_setreplicate 246, 578sp_setrepproc 305, 439sp_setreptable 239, 439

System tables xxvdescribed 30rs_config 92rs_databases 166rs_exceptscmd 511rs_exceptshdr 511rs_idnames 165, 456rs_lastcommit 160rs_systext 511rs_threads 491

TablesSee also Primary tables xxv

System transactions 515

TTable Properties tab 67

TablesSee also Primary tables xxvcreating for replication 213procedure for replicating 216subscription requirements 326

Tabsbuttons 67dialog boxes 67

TD. See Transaction Delivery module xxvTesting

Replication Server components 363Replication Server connections 363

text datatypechanging replication for 251LTM shutdown and 251overview of replication 246

Threadsdescribed 477displaying for replication system 366distributor (dist) 480DSI executor 481, 488DSI scheduler 45, 481, 488in primary Replication Server described 483in primary replication server described 478RS user 483RSI 45, 482RSI user 484Stable Queue Manager (SQM) 479Stable Queue Transaction (SQT) 479USER 483for parallel DSI 486

Threshold levelssetting and using for partitions 368

Timestampand foreign LTMs 564qid 564

Toolbarbuttons 63standard 63

Toolbarshiding 63

Tools menu 63ToolTip 64Topology view in Sybase Central 79Transaction Delivery module (TD) 480Transaction logs. See Database logs xxv

Index

652

Transactionsexceptions handling 509handling suspended 151handling with Replication Server 43large 489loading log dumps 564modifying data in multiple data servers 47processing with parallel DSI threads 486, 496reasons for failure 509serialization methods 490skip transaction clause 160small 489timestamp 564

Transact-SQL commands xxvdump database 527dump transaction 527set replication off 455set triggers off 455

Triggersconfiguring in standby databases 455

truncate table command 515enabling replication of 354

truncate table RCL command 421truncate table Transact-SQL command 352Truncated database logs

recovering 532, 535Truncation

Adaptive Server database logs 49Truncation point. See LTM truncation point xxv

Uunified_login 196Updating

function strings 400Upgrading

routes 140User names. See Login names xxvUSER thread 483User-defined functions xxv

adding parameters 580associating replicated stored procedures with 579described 374dropping 580managing 578

mapping to a different stored procedure name 581specifying a non-unique function name 583

Login namesSee also Maintenance user xxv

Users xxvdisplaying replication system 182

Utilities. See Replication Server programs xxv

Vvalidate publication command 274, 275

example 276, 277validate subscription command 327, 351, 355

for publications 351publication subscription example 356

Variable modifier 397Variables

See also Configuration parameters xxvfunction strings 42, 397modifiers 397system-defined 397

verify password clause 175Verifying translations 292Version daemon (dVERSION) 483Version number

for route 140Versions

replication system 18Viewing. See Displaying xxv

Wwait for create standby command 438wait for switch command 445wait_for_commit

transaction serialization method 490Warm standby

alter table support 465Warm standby applications xxv

comparing methods 420database connections 416databases 416effects of switching to the standby database 442forcing replication of DDL commands 427

Index

653

logical connections 417monitoring 448physical connections 416for a primary database 457for a replicate database 459restrictions 418setting up databases 428, 454switching to the standby database 440tables with the same name 425turning off replication 428

where clausealtering 279operators 277syntax 276used in articles 276

where clause for create subscription command 328Windows

status bar 64with nowait clause 151with primary table named clause 224with purge clause 357with replicate table named clause 224without holdlock clause 332without purge clause 357Wizards 65writetext function string output templates 411

Index

654